diff --git a/doc/DeterministicTesting.en.md b/doc/DeterministicTesting.en.md
new file mode 100644
index 0000000..836d238
--- /dev/null
+++ b/doc/DeterministicTesting.en.md
@@ -0,0 +1,205 @@
+# Deterministic Error Tests
+
+🌍 **Languages:**  
+🇬🇧 English (this file) | 🇫🇷 [Français](./DeterministicTesting.fr.md)
+
+Every error occurrence records two values that should vary in production:
+
+- `OccurredAt`, the UTC instant at which the error was created;
+- `InstanceId`, a unique identifier for that occurrence.
+
+Those values improve observability, but they make whole-object assertions and snapshots (tests comparing a serialized object against an approved reference file) unstable. `FirstClassErrors.Testing` lets you temporarily replace the two generators behind them — the clock and the instance-id source — only within the scope of a test that deliberately needs deterministic values.
+
+For fluent assertions on outcomes and errors, start with [Testing Outcomes and Errors](Testing.en.md).
+
+## Shared setup for the examples
+
+Every example below tells the same small story — looking up a missing order — through one factory and two stubs, so each snippet stays short:
+
+```csharp
+// The documented error every example reports.
+private static DomainError MakeError() =>
+    DomainError
+        .Create(ErrorCode.Create("ORDER_NOT_FOUND"), "Order 42 was not found.")
+        .WithPublicMessage("The order does not exist.");
+
+private static readonly DateTimeOffset start = new(2026, 7, 8, 10, 30, 0, TimeSpan.Zero);
+
+// A repository whose lookup fails for missingOrderId, returning a failed Outcome<Order>.
+private readonly IOrderRepository orders = /* test double */;
+private readonly OrderId missingOrderId  = /* an id with no match */;
+```
+
+`MakeError()` returns the concrete `DomainError`. When an example instead pulls the error out of a failed outcome with `ShouldFail().Subject`, it comes back typed as the base `Error` — that is why some snippets below say `DomainError` and others `Error`. It is the same object seen at two levels of its type hierarchy, not two interchangeable types.
+
+## Freeze `OccurredAt`
+
+Testing against the real clock usually requires an imprecise time window:
+
+```csharp
+DateTimeOffset before = DateTimeOffset.UtcNow;
+DomainError error = MakeError();
+DateTimeOffset after = DateTimeOffset.UtcNow;
+
+Check.That(error.OccurredAt >= before && error.OccurredAt <= after).IsTrue();
+```
+
+`Clock.UseFixed(...)` makes the expected instant explicit:
+
+```csharp
+[Fact]
+public void An_error_records_the_fixed_occurrence_time() {
+    var instant = new DateTimeOffset(2026, 7, 8, 10, 30, 0, TimeSpan.Zero);
+
+    using (Clock.UseFixed(instant)) {
+        DomainError error = MakeError();
+
+        Check.That(error.OccurredAt).IsEqualTo(instant);
+    }
+}
+```
+
+The override applies only inside the `using` scope. Disposing the scope restores the previous clock.
+
+## Use a custom clock
+
+When a test needs several controlled instants, implement `IClock` and pass it to `Clock.Use(...)`:
+
+```csharp
+sealed class StepClock : IClock {
+    private DateTimeOffset _now;
+
+    public StepClock(DateTimeOffset start) => _now = start;
+
+    public DateTimeOffset UtcNow {
+        get {
+            DateTimeOffset current = _now;
+            _now = _now.AddSeconds(1);
+            return current;
+        }
+    }
+}
+```
+
+```csharp
+using (Clock.Use(new StepClock(start))) {
+    DomainError first = MakeError();
+    DomainError second = MakeError();
+
+    Check.That(first.OccurredAt).IsEqualTo(start);
+    Check.That(second.OccurredAt).IsEqualTo(start.AddSeconds(1));
+}
+```
+
+Use a custom clock only when progression itself matters. A fixed clock is simpler for most tests.
+
+## Freeze `InstanceId`
+
+A random `Guid` is correct in production but unstable in a snapshot:
+
+```csharp
+[Fact]
+public void A_missing_order_error_has_a_stable_instance_id() {
+    var id = new Guid("11111111-1111-1111-1111-111111111111");
+
+    using (InstanceIds.UseFixed(id)) {
+        Error error = orders.Find(missingOrderId).ShouldFail().Subject;
+
+        Check.That(error.InstanceId).IsEqualTo(id);
+    }
+}
+```
+
+As with the clock, the override ends when the scope is disposed.
+
+## Generate several stable identifiers
+
+When one test creates several errors, provide a deterministic source:
+
+```csharp
+static Func<Guid> SequentialIds() {
+    int value = 0;
+    return () => new Guid(++value, 0, 0, new byte[8]);
+}
+```
+
+```csharp
+using (InstanceIds.Use(SequentialIds())) {
+    DomainError first = MakeError();
+    DomainError second = MakeError();
+
+    Check.That(first.InstanceId.ToString()).IsEqualTo("00000001-0000-0000-0000-000000000000");
+    Check.That(second.InstanceId.ToString()).IsEqualTo("00000002-0000-0000-0000-000000000000");
+}
+```
+
+Prefer identifiers that are visibly synthetic so they cannot be confused with production values.
+
+## Freeze `OccurredAt` and `InstanceId` together
+
+```csharp
+[Fact]
+public void A_missing_order_error_is_fully_deterministic() {
+    var instant = new DateTimeOffset(2026, 7, 8, 10, 30, 0, TimeSpan.Zero);
+    var id = new Guid("11111111-1111-1111-1111-111111111111");
+
+    using (Clock.UseFixed(instant)) {
+        using (InstanceIds.UseFixed(id)) {
+            Error error = orders.Find(missingOrderId)
+                                .ShouldFail()
+                                .WithCode("ORDER_NOT_FOUND")
+                                .WithContextEntry("OrderId", missingOrderId)
+                                .Subject;
+
+            Check.That(error.OccurredAt).IsEqualTo(instant);
+            Check.That(error.InstanceId).IsEqualTo(id);
+        }
+    }
+}
+```
+
+## Scope and parallel tests
+
+An override takes effect when its `using` opens and is undone when the `using` is disposed. Outside that block, the clock and instance ids are back to their real behavior.
+
+The override is not a shared global: it follows the test's own execution flow (internally it is stored in an `AsyncLocal`). So a value frozen inside one test is invisible to any code running outside that test — including other tests running at the same time. Two tests can each freeze the clock to a different instant and run in parallel without disturbing each other.
+
+Because of that, keep the `using` as tight as possible around the code that creates the errors: the frozen values then cover exactly what the test asserts, and nothing else.
+
+## Common mistakes
+
+### Forgetting to dispose the override
+
+Always use `using`. Manual lifetime management makes tests harder to reason about.
+
+### Freezing values in every test
+
+Most tests should assert stable semantics through `ShouldSucceed()` and `ShouldFail()`. Freeze occurrence data only when occurrence data is part of the assertion.
+
+### Treating test overrides as production configuration
+
+`Clock` and `InstanceIds` overrides are test aids. Production should keep the real UTC clock and unique identifiers.
+
+### Using the same fixed id for several errors when identity matters
+
+If the test verifies distinct occurrences, use a deterministic sequence rather than one repeated identifier.
+
+## Review checklist
+
+Before approving a deterministic error test, verify that:
+
+- the timestamp or instance id is genuinely relevant to the test;
+- every override is enclosed in `using`;
+- the scope is narrow;
+- a fixed value is used when progression is unnecessary;
+- a deterministic sequence is used when several distinct errors are created;
+- synthetic values are obvious in snapshots;
+- the test does not rely on real time or random identifiers accidentally.
+
+---
+
+<div align="center">
+<a href="Testing.en.md">← Testing Outcomes and Errors</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="OperationalIntegration.en.md">Generating and Publishing the Catalog →</a>
+</div>
+
+---
\ No newline at end of file
diff --git a/doc/DeterministicTesting.fr.md b/doc/DeterministicTesting.fr.md
new file mode 100644
index 0000000..f2081c3
--- /dev/null
+++ b/doc/DeterministicTesting.fr.md
@@ -0,0 +1,205 @@
+# Tests d’erreur déterministes
+
+🌍 **Langues :**  
+🇫🇷 Français (ce fichier) | 🇬🇧 [English](./DeterministicTesting.en.md)
+
+Chaque occurrence d’erreur enregistre deux valeurs qui doivent varier en production :
+
+- `OccurredAt`, l’instant UTC de création de l’erreur ;
+- `InstanceId`, un identifiant unique de cette occurrence.
+
+Ces valeurs améliorent l’observabilité, mais rendent instables les assertions sur l’objet complet et les snapshots (tests qui comparent un objet sérialisé à un fichier de référence approuvé). `FirstClassErrors.Testing` permet de remplacer temporairement les deux générateurs qui les produisent — l’horloge et la source d’identifiants — uniquement dans la portée d’un test qui a délibérément besoin de valeurs déterministes.
+
+Pour les assertions fluentes sur les outcomes et les erreurs, commencez par [Tester les outcomes et les erreurs](Testing.fr.md).
+
+## Setup commun aux exemples
+
+Chaque exemple ci-dessous raconte la même petite histoire — la recherche d’une commande absente — via une factory et deux stubs, afin que chaque extrait reste court :
+
+```csharp
+// L’erreur documentée que chaque exemple rapporte.
+private static DomainError MakeError() =>
+    DomainError
+        .Create(ErrorCode.Create("ORDER_NOT_FOUND"), "La commande 42 est introuvable.")
+        .WithPublicMessage("La commande n’existe pas.");
+
+private static readonly DateTimeOffset start = new(2026, 7, 8, 10, 30, 0, TimeSpan.Zero);
+
+// Un repository dont la recherche échoue pour missingOrderId, retournant un Outcome<Order> en échec.
+private readonly IOrderRepository orders = /* test double */;
+private readonly OrderId missingOrderId  = /* un id sans correspondance */;
+```
+
+`MakeError()` retourne le `DomainError` concret. Lorsqu’un exemple récupère plutôt l’erreur depuis un outcome en échec via `ShouldFail().Subject`, elle revient typée comme l’`Error` de base — c’est pourquoi certains extraits ci-dessous montrent `DomainError` et d’autres `Error`. C’est le même objet vu à deux niveaux de sa hiérarchie de types, pas deux types interchangeables.
+
+## Figer `OccurredAt`
+
+Tester avec l’horloge réelle impose généralement une fenêtre de temps imprécise :
+
+```csharp
+DateTimeOffset before = DateTimeOffset.UtcNow;
+DomainError error = MakeError();
+DateTimeOffset after = DateTimeOffset.UtcNow;
+
+Check.That(error.OccurredAt >= before && error.OccurredAt <= after).IsTrue();
+```
+
+`Clock.UseFixed(...)` rend l’instant attendu explicite :
+
+```csharp
+[Fact]
+public void Une_erreur_enregistre_l_instant_fixe() {
+    var instant = new DateTimeOffset(2026, 7, 8, 10, 30, 0, TimeSpan.Zero);
+
+    using (Clock.UseFixed(instant)) {
+        DomainError error = MakeError();
+
+        Check.That(error.OccurredAt).IsEqualTo(instant);
+    }
+}
+```
+
+L’override ne s’applique qu’à l’intérieur de la portée `using`. La fin de la portée restaure l’horloge précédente.
+
+## Utiliser une horloge personnalisée
+
+Lorsqu’un test nécessite plusieurs instants contrôlés, implémentez `IClock` et passez-la à `Clock.Use(...)` :
+
+```csharp
+sealed class StepClock : IClock {
+    private DateTimeOffset _now;
+
+    public StepClock(DateTimeOffset start) => _now = start;
+
+    public DateTimeOffset UtcNow {
+        get {
+            DateTimeOffset current = _now;
+            _now = _now.AddSeconds(1);
+            return current;
+        }
+    }
+}
+```
+
+```csharp
+using (Clock.Use(new StepClock(start))) {
+    DomainError first = MakeError();
+    DomainError second = MakeError();
+
+    Check.That(first.OccurredAt).IsEqualTo(start);
+    Check.That(second.OccurredAt).IsEqualTo(start.AddSeconds(1));
+}
+```
+
+N’utilisez une horloge personnalisée que lorsque la progression elle-même compte. Une horloge fixe est plus simple dans la plupart des tests.
+
+## Figer `InstanceId`
+
+Un `Guid` aléatoire est correct en production, mais instable dans un snapshot :
+
+```csharp
+[Fact]
+public void Une_erreur_de_commande_absente_a_un_identifiant_stable() {
+    var id = new Guid("11111111-1111-1111-1111-111111111111");
+
+    using (InstanceIds.UseFixed(id)) {
+        Error error = orders.Find(missingOrderId).ShouldFail().Subject;
+
+        Check.That(error.InstanceId).IsEqualTo(id);
+    }
+}
+```
+
+Comme pour l’horloge, l’override prend fin lorsque la portée est disposée.
+
+## Générer plusieurs identifiants stables
+
+Lorsqu’un test crée plusieurs erreurs, fournissez une source déterministe :
+
+```csharp
+static Func<Guid> SequentialIds() {
+    int value = 0;
+    return () => new Guid(++value, 0, 0, new byte[8]);
+}
+```
+
+```csharp
+using (InstanceIds.Use(SequentialIds())) {
+    DomainError first = MakeError();
+    DomainError second = MakeError();
+
+    Check.That(first.InstanceId.ToString()).IsEqualTo("00000001-0000-0000-0000-000000000000");
+    Check.That(second.InstanceId.ToString()).IsEqualTo("00000002-0000-0000-0000-000000000000");
+}
+```
+
+Préférez des identifiants visiblement synthétiques afin qu’ils ne puissent pas être confondus avec des valeurs de production.
+
+## Figer simultanément `OccurredAt` et `InstanceId`
+
+```csharp
+[Fact]
+public void Une_erreur_de_commande_absente_est_totalement_deterministe() {
+    var instant = new DateTimeOffset(2026, 7, 8, 10, 30, 0, TimeSpan.Zero);
+    var id = new Guid("11111111-1111-1111-1111-111111111111");
+
+    using (Clock.UseFixed(instant)) {
+        using (InstanceIds.UseFixed(id)) {
+            Error error = orders.Find(missingOrderId)
+                                .ShouldFail()
+                                .WithCode("ORDER_NOT_FOUND")
+                                .WithContextEntry("OrderId", missingOrderId)
+                                .Subject;
+
+            Check.That(error.OccurredAt).IsEqualTo(instant);
+            Check.That(error.InstanceId).IsEqualTo(id);
+        }
+    }
+}
+```
+
+## Portée et tests parallèles
+
+Un override prend effet à l’ouverture de son `using` et est défait à sa libération. En dehors de ce bloc, l’horloge et les identifiants retrouvent leur comportement réel.
+
+L’override n’est pas un état global partagé : il suit le flux d’exécution du test lui-même (en interne, il est stocké dans un `AsyncLocal`). Une valeur figée dans un test est donc invisible pour tout code s’exécutant en dehors de ce test — y compris les autres tests s’exécutant en même temps. Deux tests peuvent chacun figer l’horloge à un instant différent et s’exécuter en parallèle sans se gêner.
+
+Pour cette raison, gardez le `using` aussi serré que possible autour du code qui crée les erreurs : les valeurs figées couvrent alors exactement ce que le test vérifie, et rien d’autre.
+
+## Erreurs fréquentes
+
+### Oublier de disposer l’override
+
+Utilisez toujours `using`. Une gestion manuelle de la durée de vie rend les tests plus difficiles à comprendre.
+
+### Figer les valeurs dans tous les tests
+
+La majorité des tests doit vérifier la sémantique stable via `ShouldSucceed()` et `ShouldFail()`. Ne figez les données d’occurrence que lorsqu’elles font partie de l’assertion.
+
+### Traiter les overrides comme de la configuration de production
+
+Les overrides de `Clock` et `InstanceIds` sont des aides de test. La production doit conserver l’horloge UTC réelle et des identifiants uniques.
+
+### Réutiliser le même identifiant fixe lorsque l’identité compte
+
+Si le test vérifie plusieurs occurrences distinctes, utilisez une séquence déterministe plutôt qu’un identifiant répété.
+
+## Checklist de revue
+
+Avant d’approuver un test déterministe, vérifiez que :
+
+- l’horodatage ou l’identifiant est réellement pertinent ;
+- chaque override est entouré d’un `using` ;
+- la portée est étroite ;
+- une valeur fixe est utilisée lorsque la progression est inutile ;
+- une séquence déterministe est utilisée lorsque plusieurs erreurs distinctes sont créées ;
+- les valeurs synthétiques sont évidentes dans les snapshots ;
+- le test ne dépend pas accidentellement du temps réel ou d’identifiants aléatoires.
+
+---
+
+<div align="center">
+<a href="Testing.fr.md">← Tester les outcomes et les erreurs</a> · <a href="README.fr.md#-étapes-suivantes">↑ Table des matières</a> · <a href="OperationalIntegration.fr.md">Générer et publier le catalogue →</a>
+</div>
+
+---
\ No newline at end of file
diff --git a/doc/LoggingIntegration.en.md b/doc/LoggingIntegration.en.md
new file mode 100644
index 0000000..e84e757
--- /dev/null
+++ b/doc/LoggingIntegration.en.md
@@ -0,0 +1,256 @@
+# Logging and Operational Integration
+
+🌍 **Languages:**  
+🇬🇧 English (this file) | 🇫🇷 [Français](./LoggingIntegration.fr.md)
+
+FirstClassErrors does not replace structured logging. It adds stable semantic information to the technical and execution context already present in logs.
+
+This guide explains what to log, how to preserve inner errors, and how to connect an occurrence to the generated catalog.
+
+For catalog generation and publication, see [Generating and Publishing the Error Catalog](OperationalIntegration.en.md).
+
+## Three complementary layers
+
+| Layer | Answers |
+| --- | --- |
+| structured log properties | what happened technically? |
+| scopes (ambient logging scopes such as `ILogger.BeginScope`) and correlation identifiers | in which request, message, or workflow did it happen? |
+| FirstClassErrors | what does this recognized failure mean? |
+
+A useful production event combines all three rather than flattening everything into one message.
+
+## Minimum error properties to log
+
+For every `Error`, capture at least:
+
+| Property | Purpose |
+| --- | --- |
+| `Code` | stable grouping and alerting key |
+| `InstanceId` | identity of this specific occurrence |
+| `OccurredAt` | UTC creation time of the error |
+| runtime error type | domain, infrastructure, primary port, or secondary port |
+| `DiagnosticMessage` | internal explanation for developers and support |
+| `Context` | structured facts specific to the occurrence |
+| inner errors | causal or aggregated diagnostic depth |
+
+For `InfrastructureError`, also capture:
+
+- `Transience`;
+- `InteractionDirection`.
+
+Do not expose `DiagnosticMessage` or unrestricted context in public API responses merely because they are present in logs.
+
+## Example structured event
+
+A serialized event might look like this:
+
+```json
+{
+  "level": "Error",
+  "message": "Payment authorization failed",
+  "traceId": "91c1d1bda3be4d0c",
+  "service": "checkout-api",
+  "deploymentVersion": "2.4.0",
+  "error": {
+    "code": "PAYMENT_PROVIDER_UNAVAILABLE",
+    "instanceId": "be1226ef-8464-4f88-9dca-9ab1f74da824",
+    "occurredAt": "2026-07-14T13:40:52.184Z",
+    "type": "SecondaryPortError",
+    "direction": "Outgoing",
+    "transience": "Transient",
+    "diagnosticMessage": "The payment provider timed out after 5 seconds.",
+    "context": {
+      "PaymentId": "f646943f-eec1-46bb-8989-32a97cba60fa",
+      "Provider": "ExamplePay"
+    },
+    "innerErrors": []
+  }
+}
+```
+
+The exact JSON schema belongs to the application or logging adapter. The important point is to keep fields structured and queryable.
+
+## Log the `Error`, not only `Exception.Message`
+
+A `DiagnosableException` — the exception type that `error.ToException()` produces — exposes its semantic model through `.Error`:
+
+```csharp
+catch (DiagnosableException exception) {
+    Error error = exception.Error;
+
+    logger.LogError(
+        exception,
+        "Operation failed with {ErrorCode} ({ErrorInstanceId})",
+        error.Code,
+        error.InstanceId);
+}
+```
+
+Passing the exception preserves the stack trace. Logging named properties preserves the stable semantic keys.
+
+A formatter, enricher, filter, or middleware can then serialize the remaining `Error` properties consistently.
+
+## Preserve context as structured data
+
+Do not concatenate context into one diagnostic string:
+
+```text
+Payment f646... failed for provider ExamplePay
+```
+
+Prefer separate fields that can be filtered and aggregated:
+
+```json
+{
+  "PaymentId": "f646943f-eec1-46bb-8989-32a97cba60fa",
+  "Provider": "ExamplePay"
+}
+```
+
+Context keys are operational vocabulary. Keep their names stable and ensure the values are safe for the intended log destination.
+
+See [Error Context](ErrorContext.en.md) for key design and data-safety rules.
+
+## Traverse `InnerErrors`
+
+`DiagnosableException` does not use `Exception.InnerException` for the FirstClassErrors diagnostic tree. Causes and aggregated failures live in:
+
+```csharp
+exception.Error.InnerErrors
+```
+
+A logging adapter must traverse that collection explicitly:
+
+```csharp
+static object ToLogModel(Error error) {
+    return new {
+        Code = error.Code.ToString(),
+        error.InstanceId,
+        error.OccurredAt,
+        Type = error.GetType().Name,
+        error.DiagnosticMessage,
+        Context = error.Context,
+        InnerErrors = error.InnerErrors.Select(ToLogModel).ToArray()
+    };
+}
+```
+
+This example shows the recursive shape; adapt context serialization and infrastructure-specific fields to the application.
+
+If only the outer error is logged, the most useful cause may disappear from operational analysis.
+
+## Keep the outer and inner meanings
+
+Consider an incoming request rejected because a domain value cannot be created:
+
+```text
+PrimaryPortError: REQUEST_REJECTED
+└── DomainError: AMOUNT_NEGATIVE
+```
+
+The outer error explains what happened at the boundary. The inner error explains the violated domain rule. Logging both preserves the complete diagnostic story.
+
+Do not flatten the tree into one synthetic code or replace the outer error with the deepest cause.
+
+## Correlate the occurrence
+
+`InstanceId` identifies one error occurrence. It complements, but does not replace:
+
+- trace and span identifiers;
+- request or message identifiers;
+- business identifiers stored in `ErrorContext`;
+- deployment version.
+
+A useful investigation path is:
+
+```text
+alert → traceId → error InstanceId → business context → catalog entry
+```
+
+Include the deployment version so support can open the catalog that matches the running code rather than the latest documentation by accident.
+
+## Link logs to the catalog
+
+A log event may include a documentation URL derived from the code and deployed catalog location:
+
+```text
+https://docs.mycompany/errors/releases/2.4.0/payment-provider-unavailable
+```
+
+The URL may be emitted as a structured property such as `error.documentationUrl`.
+
+When an exception object is used by tooling that recognizes `Exception.HelpLink`, the application may also set it before logging or rethrowing:
+
+```csharp
+exception.HelpLink = documentationUrl;
+```
+
+The generated catalog remains the source of explanation; the log stores the navigational link, not a duplicated copy of the documentation.
+
+## Logging outcomes without throwing
+
+An `Outcome` failure may never become an exception. Log its `Error` directly when the application decides the failure belongs in operational logs:
+
+```csharp
+Outcome<Receipt> outcome = checkout.Pay(order);
+
+if (outcome.IsFailure) {
+    logger.LogWarning(
+        "Checkout failed with {ErrorCode} ({ErrorInstanceId})",
+        outcome.Error!.Code,
+        outcome.Error.InstanceId);
+}
+```
+
+Do not throw solely to make the logging framework see the error. A shared serializer can handle both `Error` and `DiagnosableException.Error`.
+
+## Choose the log level from operational impact
+
+The existence of an `Error` does not automatically imply an error-level log.
+
+Examples:
+
+| Situation | Possible treatment |
+| --- | --- |
+| user input rejected as expected | information or warning, depending on policy |
+| item rejected inside a normal batch | warning or metric, possibly sampled |
+| transient outgoing dependency failure | warning or error, depending on retries and final outcome |
+| exhausted retries causing request failure | error |
+| domain failure already returned to a caller and fully expected | potentially no log at this layer |
+
+Use `Transience`, `InteractionDirection`, application outcome, and repetition rate to inform the policy. Avoid duplicate logs at every layer of the call stack.
+
+## Protect sensitive data
+
+Before logging context or diagnostic messages, verify that they do not contain:
+
+- secrets, passwords, tokens, or credentials;
+- unrestricted personal data;
+- full request or response payloads;
+- payment data or other regulated values;
+- unbounded collections or files.
+
+The internal audience permits technical detail; it does not remove security, privacy, retention, or access-control obligations.
+
+## Review checklist
+
+Before approving a logging integration, verify that:
+
+- the exception stack trace and the structured `Error` are both preserved when an exception exists;
+- code, instance id, occurrence time, type, diagnostic message, and context are queryable fields;
+- infrastructure direction and transience are logged;
+- `InnerErrors` are traversed recursively;
+- outcome failures can be logged without manufacturing exceptions;
+- trace, business, occurrence, and deployment identifiers remain distinct;
+- the log level reflects operational impact rather than merely the presence of an error;
+- sensitive and unbounded data are excluded;
+- documentation links target the catalog version matching the deployment;
+- the same failure is not logged repeatedly by every layer.
+
+---
+
+<div align="center">
+<a href="OperationalIntegration.en.md">← Generating and Publishing the Catalog</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioning.en.md">Catalog Versioning →</a>
+</div>
+
+---
\ No newline at end of file
diff --git a/doc/LoggingIntegration.fr.md b/doc/LoggingIntegration.fr.md
new file mode 100644
index 0000000..02415ed
--- /dev/null
+++ b/doc/LoggingIntegration.fr.md
@@ -0,0 +1,254 @@
+# Logging et intégration opérationnelle
+
+🌍 **Langues :**  
+🇬🇧 [English](./LoggingIntegration.en.md) | 🇫🇷 Français (ce fichier)
+
+FirstClassErrors ne remplace pas le logging structuré. Il ajoute une information sémantique stable au contexte technique et d’exécution déjà présent dans les logs.
+
+Ce guide explique quoi logger, comment préserver les erreurs internes et comment relier une occurrence au catalogue généré.
+
+Pour la génération et la publication du catalogue, voir [Générer et publier le catalogue d’erreurs](OperationalIntegration.fr.md).
+
+## Trois couches complémentaires
+
+| Couche | Répond à |
+| --- | --- |
+| propriétés structurées du log | que s’est-il passé techniquement ? |
+| scopes (portées de logging ambiantes, comme `ILogger.BeginScope`) et identifiants de corrélation | dans quelle requête, quel message ou quel workflow ? |
+| FirstClassErrors | que signifie cette défaillance reconnue ? |
+
+Un événement de production utile combine les trois au lieu de tout aplatir dans un seul message.
+
+## Propriétés minimales à logger
+
+Pour chaque `Error`, capturez au moins :
+
+| Propriété | Rôle |
+| --- | --- |
+| `Code` | clé stable de regroupement et d’alerte |
+| `InstanceId` | identité de cette occurrence précise |
+| `OccurredAt` | instant UTC de création de l’erreur |
+| type runtime de l’erreur | domaine, infrastructure, port primaire ou port secondaire |
+| `DiagnosticMessage` | explication interne pour les développeurs et le support |
+| `Context` | faits structurés propres à l’occurrence |
+| erreurs internes | profondeur causale ou agrégée du diagnostic |
+
+Pour une `InfrastructureError`, capturez également :
+
+- `Transience` ;
+- `InteractionDirection`.
+
+N’exposez pas `DiagnosticMessage` ou un contexte non filtré dans une réponse API publique sous prétexte qu’ils sont présents dans les logs.
+
+## Exemple d’événement structuré
+
+Un événement sérialisé peut ressembler à ceci :
+
+```json
+{
+  "level": "Error",
+  "message": "Payment authorization failed",
+  "traceId": "91c1d1bda3be4d0c",
+  "service": "checkout-api",
+  "deploymentVersion": "2.4.0",
+  "error": {
+    "code": "PAYMENT_PROVIDER_UNAVAILABLE",
+    "instanceId": "be1226ef-8464-4f88-9dca-9ab1f74da824",
+    "occurredAt": "2026-07-14T13:40:52.184Z",
+    "type": "SecondaryPortError",
+    "direction": "Outgoing",
+    "transience": "Transient",
+    "diagnosticMessage": "The payment provider timed out after 5 seconds.",
+    "context": {
+      "PaymentId": "f646943f-eec1-46bb-8989-32a97cba60fa",
+      "Provider": "ExamplePay"
+    },
+    "innerErrors": []
+  }
+}
+```
+
+Le schéma JSON exact appartient à l’application ou à l’adapter de logging. L’important est de conserver des champs structurés et requêtables.
+
+## Logger l’`Error`, pas seulement `Exception.Message`
+
+Une `DiagnosableException` — le type d’exception produit par `error.ToException()` — expose son modèle sémantique via `.Error` :
+
+```csharp
+catch (DiagnosableException exception) {
+    Error error = exception.Error;
+
+    logger.LogError(
+        exception,
+        "Operation failed with {ErrorCode} ({ErrorInstanceId})",
+        error.Code,
+        error.InstanceId);
+}
+```
+
+Passer l’exception préserve la stack trace. Logger des propriétés nommées préserve les clés sémantiques stables.
+
+Un formatter, enricher, filtre ou middleware peut ensuite sérialiser les autres propriétés de l’`Error` de manière cohérente.
+
+## Préserver le contexte comme données structurées
+
+Ne concaténez pas le contexte dans une seule chaîne de diagnostic :
+
+```text
+Payment f646... failed for provider ExamplePay
+```
+
+Préférez des champs distincts, filtrables et agrégeables :
+
+```json
+{
+  "PaymentId": "f646943f-eec1-46bb-8989-32a97cba60fa",
+  "Provider": "ExamplePay"
+}
+```
+
+Les clés de contexte constituent un vocabulaire opérationnel. Gardez leurs noms stables et vérifiez que les valeurs sont sûres pour la destination de logs visée.
+
+Voir [Contexte d’erreur](ErrorContext.fr.md) pour la conception des clés et les règles de sécurité des données.
+
+## Parcourir `InnerErrors`
+
+`DiagnosableException` n’utilise pas `Exception.InnerException` pour l’arbre diagnostique FirstClassErrors. Les causes et erreurs agrégées vivent dans :
+
+```csharp
+exception.Error.InnerErrors
+```
+
+Un adapter de logging doit parcourir explicitement cette collection :
+
+```csharp
+static object ToLogModel(Error error) {
+    return new {
+        Code = error.Code.ToString(),
+        error.InstanceId,
+        error.OccurredAt,
+        Type = error.GetType().Name,
+        error.DiagnosticMessage,
+        Context = error.Context,
+        InnerErrors = error.InnerErrors.Select(ToLogModel).ToArray()
+    };
+}
+```
+
+Cet exemple montre la forme récursive ; adaptez la sérialisation du contexte et les champs propres aux erreurs d’infrastructure à l’application.
+
+Si seule l’erreur externe est loggée, la cause la plus utile peut disparaître de l’analyse opérationnelle.
+
+## Conserver le sens externe et interne
+
+Prenons une requête entrante rejetée parce qu’une valeur métier ne peut pas être construite :
+
+```text
+PrimaryPortError: REQUEST_REJECTED
+└── DomainError: AMOUNT_NEGATIVE
+```
+
+L’erreur externe explique ce qui s’est passé à la frontière. L’erreur interne explique la règle métier violée. Logger les deux conserve toute l’histoire diagnostique.
+
+N’aplatissez pas l’arbre en un code synthétique unique et ne remplacez pas l’erreur externe par la cause la plus profonde.
+
+## Corréler l’occurrence
+
+`InstanceId` identifie une occurrence d’erreur. Il complète, sans les remplacer :
+
+- les identifiants de trace et de span ;
+- les identifiants de requête ou de message ;
+- les identifiants métier placés dans `ErrorContext` ;
+- la version de déploiement.
+
+Un parcours d’investigation utile est :
+
+```text
+alerte → traceId → InstanceId de l’erreur → contexte métier → entrée du catalogue
+```
+
+Incluez la version de déploiement afin que le support ouvre le catalogue correspondant au code exécuté, et non la documentation la plus récente par erreur.
+
+## Relier les logs au catalogue
+
+Un événement peut inclure une URL de documentation dérivée du code et de l’emplacement du catalogue déployé :
+
+```text
+https://docs.mycompany/errors/releases/2.4.0/payment-provider-unavailable
+```
+
+L’URL peut être publiée comme propriété structurée telle que `error.documentationUrl`.
+
+Lorsque l’objet exception est utilisé par un outil qui comprend `Exception.HelpLink`, l’application peut aussi le renseigner avant le logging ou la relance :
+
+```csharp
+exception.HelpLink = documentationUrl;
+```
+
+Le catalogue généré reste la source d’explication ; le log conserve le lien de navigation, pas une copie dupliquée de la documentation.
+
+## Logger un outcome sans lever
+
+Un échec d’`Outcome` peut ne jamais devenir une exception. Loggez directement son `Error` lorsque l’application décide que l’échec doit apparaître dans les logs opérationnels :
+
+```csharp
+Outcome<Receipt> outcome = checkout.Pay(order);
+
+if (outcome.IsFailure) {
+    logger.LogWarning(
+        "Checkout failed with {ErrorCode} ({ErrorInstanceId})",
+        outcome.Error!.Code,
+        outcome.Error.InstanceId);
+}
+```
+
+Ne levez pas une exception uniquement pour que le framework de logging voie l’erreur. Un sérialiseur partagé peut gérer à la fois `Error` et `DiagnosableException.Error`.
+
+## Choisir le niveau selon l’impact opérationnel
+
+La présence d’une `Error` n’implique pas automatiquement un log de niveau erreur.
+
+| Situation | Traitement possible |
+| --- | --- |
+| saisie utilisateur rejetée comme prévu | information ou warning selon la politique |
+| élément rejeté dans un batch normal | warning ou métrique, éventuellement échantillonné |
+| dépendance sortante en échec transitoire | warning ou erreur selon les retries et le résultat final |
+| retries épuisés provoquant l’échec de la requête | erreur |
+| erreur métier déjà retournée à l’appelant et totalement attendue | éventuellement aucun log à cette couche |
+
+Utilisez `Transience`, `InteractionDirection`, le résultat applicatif et la fréquence pour guider la politique. Évitez les logs dupliqués à chaque couche de la stack.
+
+## Protéger les données sensibles
+
+Avant de logger le contexte ou les messages de diagnostic, vérifiez qu’ils ne contiennent pas :
+
+- secrets, mots de passe, tokens ou credentials ;
+- données personnelles non maîtrisées ;
+- corps complets de requête ou de réponse ;
+- données de paiement ou autres valeurs réglementées ;
+- collections ou fichiers non bornés.
+
+Le public interne autorise davantage de détail technique ; il ne supprime pas les obligations de sécurité, de confidentialité, de rétention ou de contrôle d’accès.
+
+## Checklist de revue
+
+Avant d’approuver une intégration de logging, vérifiez que :
+
+- la stack trace de l’exception et l’`Error` structurée sont toutes deux préservées lorsqu’une exception existe ;
+- code, instance id, instant, type, message de diagnostic et contexte sont requêtables ;
+- la direction et la transience sont loggées pour l’infrastructure ;
+- `InnerErrors` est parcouru récursivement ;
+- les échecs d’outcome peuvent être loggés sans fabriquer d’exception ;
+- les identifiants de trace, métier, occurrence et déploiement restent distincts ;
+- le niveau de log reflète l’impact opérationnel et non la simple présence d’une erreur ;
+- les données sensibles et non bornées sont exclues ;
+- les liens documentaires ciblent la version du catalogue correspondant au déploiement ;
+- la même erreur n’est pas loggée à répétition par chaque couche.
+
+---
+
+<div align="center">
+<a href="OperationalIntegration.fr.md">← Générer et publier le catalogue</a> · <a href="README.fr.md#-étapes-suivantes">↑ Table des matières</a> · <a href="CatalogVersioning.fr.md">Versionnage du catalogue →</a>
+</div>
+
+---
\ No newline at end of file
diff --git a/doc/OperationalIntegration.en.md b/doc/OperationalIntegration.en.md
index d76f122..b33108d 100644
--- a/doc/OperationalIntegration.en.md
+++ b/doc/OperationalIntegration.en.md
@@ -1,130 +1,219 @@
-# CI/CD and Operational Integration
+# Generating and Publishing the Error Catalog
 
 🌍 **Languages:**  
 🇬🇧 English (this file) | 🇫🇷 [Français](./OperationalIntegration.fr.md)
 
-FirstClassErrors reaches its full value when it is integrated into the delivery pipeline and operational tooling. The goal is not only to define error knowledge, but to make it automatically available to the people who need it: developers, support teams, and operators.
+FirstClassErrors becomes operationally useful when the catalog is generated from the exact code being built, and published where developers, support teams, and operators can reach it.
 
-## 📦 Documentation as a build artifact
+This guide covers the delivery workflow. For structured logging and production diagnostics, see [Logging and Operational Integration](LoggingIntegration.en.md).
 
-Error documentation should be generated automatically during CI.
+## The delivery flow
 
-The `fce` generator is distributed as a .NET tool
-([`FirstClassErrors.Cli`](https://www.nuget.org/packages/FirstClassErrors.Cli)), so a
-pipeline installs it and runs it as build steps:
+```mermaid
+flowchart LR
+    A[Build application] --> B[Extract error knowledge]
+    B --> C[Render catalog]
+    C --> D[Publish artifact or site]
+    B --> E[Compare contract baseline]
+```
+
+A reliable pipeline should:
+
+1. build the application;
+2. generate the catalog from the built code;
+3. publish the generated files;
+4. optionally compare the current contract with a committed baseline — the last accepted snapshot of your error codes and context keys (see [Catalog Versioning](CatalogVersioning.en.md)).
+
+## Opt projects into generation
+
+Solution-level generation is opt-in. Add the marker directly to every `.csproj` that defines documented application errors:
+
+```xml
+<PropertyGroup>
+  <GenerateErrorDocumentation>true</GenerateErrorDocumentation>
+</PropertyGroup>
+```
+
+The marker is read from the project file itself. A value inherited from `Directory.Build.props` is not detected.
+
+When no project opts in, the generator warns instead of silently presenting an empty catalog as a valid result.
 
-1. Install the generator: `dotnet tool install --global FirstClassErrors.Cli`
-2. Build the solution
-3. Run the generator (`fce generate`) to produce the error catalog (Markdown, HTML or JSON)
-4. Publish it as a pipeline artifact or deploy it to a documentation portal
+For ambiguous declarations, project discovery, and worker behavior, see [Architecture of the Documentation Pipeline](ArchitectureOfTheDocumentationPipeline.en.md).
 
-Concretely:
+## Generate the catalog locally
+
+Install the CLI, build, then generate from the existing binaries:
 
 ```bash
 dotnet tool install --global FirstClassErrors.Cli
 dotnet build MyApp.sln -c Release
-fce generate --solution MyApp.sln --no-build \
-             --output artifacts/errors.md --format markdown --service-name my-api
+fce generate \
+  --solution MyApp.sln \
+  --configuration Release \
+  --no-build \
+  --format markdown \
+  --output artifacts/errors.md \
+  --service-name my-api
 ```
 
-Generation is **opt-in per project**: only projects whose project file (`.csproj`) sets `<GenerateErrorDocumentation>true</GenerateErrorDocumentation>` are scanned; a project without it is silently skipped. The marker must sit in the `.csproj` itself — it is read straight from the project XML, so a value inherited from a shared `Directory.Build.props` is not picked up. When not a single project opts in, the generator logs a warning naming the property rather than producing an empty catalog silently. If a fresh pipeline produces an empty catalog, check the opt-in first. See [Opting a project in](ArchitectureOfTheDocumentationPipeline.en.md#opting-a-project-in).
+`--service-name` is required for Markdown and HTML because their RFC 9457 examples use problem types such as:
 
-This ensures that documentation always matches the version of the system that is deployed. No manual updates are required, and no drift can occur.
+```text
+urn:problem:my-api:payment-declined
+```
 
-You can emit the catalog per locale by adding `--language <…>` (e.g. a CI matrix over `en`, `fr`, `sv`); file names and anchors stay stable across languages. See [Internationalization](Internationalization.en.md).
+JSON output does not require a service name.
 
-The public RFC 9457 examples carry a problem `type` of the shape `urn:problem:{service}:{code}`. Provide the service segment with `--service-name <name>` (or `serviceName` in `fce.json`); it is required for the `markdown` and `html` formats — `fce generate` fails with a clear message when it is missing — while `json` (which carries no such example) does not need it.
+## Recommended GitHub Actions workflow
 
-## 🛡️ Guarding the error contract
+The workflow renders the catalog as HTML with `--layout split` (one page per error; see [The HTML Renderer](TheHtmlRenderer.en.md)):
 
-Error codes and context keys are a public contract: clients branch on them, dashboards alert on them, support procedures reference them. A CI step can guard that contract by comparing the current catalog against a committed baseline and failing the build when a code disappears by accident:
+```yaml
+name: error-documentation
 
-```bash
-fce catalog diff --solution MyApp.sln
-```
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  generate-error-catalog:
+    runs-on: ubuntu-latest
 
-See [Catalog Versioning](CatalogVersioning.en.md) for the baseline workflow, the change classification and the exit-code semantics.
+    steps:
+      - uses: actions/checkout@v4
 
-## 🌍 Publishing documentation
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
 
-The generated documentation can be:
+      - name: Install FirstClassErrors CLI
+        run: dotnet tool install --global FirstClassErrors.Cli
 
-* published to an internal documentation portal
-* exposed via a static site
-* attached to release artifacts
+      - name: Build
+        run: dotnet build MyApp.sln -c Release
 
-The important principle is:
+      - name: Generate catalog
+        run: |
+          fce generate \
+            --solution MyApp.sln \
+            --configuration Release \
+            --no-build \
+            --format html \
+            --layout split \
+            --output artifacts/error-catalog \
+            --service-name my-api
 
-> The documentation must be reachable by the people investigating production issues.
+      - name: Publish catalog artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: error-catalog
+          path: artifacts/error-catalog
+```
 
-## 📜 Logging integration
+The build and generation steps use the same configuration. `--no-build` prevents the generator from rebuilding a different set of binaries.
 
-FirstClassErrors are designed to integrate naturally with structured logging.
+## Generate several languages
 
-Logs can include:
+Run one generation per locale:
 
-* the error code
-* the unique instance ID
-* the occurrence timestamp
-* the error context
+```yaml
+strategy:
+  matrix:
+    language: [en, fr]
 
-This makes logs not only readable but also correlatable across systems.
+steps:
+  # checkout, setup, install, and build omitted
 
-## 🔍 Logging inner errors
+  - name: Generate ${{ matrix.language }} catalog
+    run: |
+      fce generate \
+        --solution MyApp.sln \
+        --configuration Release \
+        --no-build \
+        --format html \
+        --layout split \
+        --language "${{ matrix.language }}" \
+        --output "artifacts/error-catalog-${{ matrix.language }}" \
+        --service-name my-api
+```
 
-By default, most logging setups treat exceptions as flat messages or stack traces. They do not automatically traverse and structure the diagnostic information carried by a `DiagnosableException` in a meaningful way for analysis.
+File names and anchors remain stable across languages. See [Internationalization](Internationalization.en.md) for how content and renderer templates are localized.
 
-A `DiagnosableException` does not set `Exception.InnerException`; instead, the diagnostic chain lives on its `Error`. Through `exception.Error.InnerErrors` (a list of `Error`), a logging filter or middleware should explicitly traverse and log the chain. Without this step, part of the diagnostic information carried by the model may remain unused in logs.
+## Choose a publication target
 
-This filter can:
+The generated catalog may be:
 
-* detect `DiagnosableException`
-* read its `.Error`
-* traverse `Error.InnerErrors` and log the full chain in a structured form
+- retained as a pipeline artifact;
+- attached to a release;
+- deployed as a static site;
+- copied into an internal documentation portal;
+- published beside service operational documentation.
 
-This preserves diagnostic depth and ensures that the richness of the error model is actually visible in operational logs.
+The important requirement is not the platform. It is that the catalog for a deployed version is reachable by the people investigating that version.
 
-## 🔗 Linking logs to documentation
+## Keep versioned catalogs
 
-A powerful pattern is to enrich the thrown exception (via its `Error`) with a documentation URL.
+A single “latest” site is useful for daily work, but it does not explain an older production release after the contract has evolved.
 
-During the documentation generation step, each error can be associated with a page or anchor. A logging filter can then populate:
+For long-lived or support-critical systems, publish at least one immutable form per release:
 
+```text
+/errors/latest/
+/errors/releases/2.4.0/
+/errors/releases/2.3.1/
 ```
-exception.HelpLink = "https://docs.mycompany/errors/AMOUNT_CURRENCY_MISMATCH"
-```
 
-This makes production logs navigable: support can move directly from a log entry to the corresponding error documentation.
+Log events that record the deployed version alongside the error then let support start from a logged occurrence — its `InstanceId` plus that version — and open the matching catalog.
+
+## Guard the error contract
+
+Generation answers “what does this version document?” Catalog versioning answers “did this version break a previously accepted contract?”
+
+`fce catalog diff` compares the catalog extracted from the current build against a baseline file committed to the repository and reports contract changes:
+
+```bash
+fce catalog diff --solution MyApp.sln --configuration Release --no-build
+```
 
-## 🧩 Complementary to structured logging
+Keep the accepted baseline in source control and run the comparison in pull requests.
 
-FirstClassErrors do not replace structured logging, scopes, or correlation IDs.
+See:
 
-They complement them:
+- [Catalog Versioning](CatalogVersioning.en.md) for the mental model and daily workflow;
+- [Catalog Versioning CI/CD](CatalogVersioningCI.en.md) for complete GitHub Actions and GitLab examples.
 
-* structured logging → technical context
-* scopes → execution context
-* FirstClassErrors → semantic error meaning
+## Failure policy
 
-Together, they provide a complete picture of what happened.
+Treat these situations differently:
 
-## 🎯 The objective
+| Situation | Pipeline meaning |
+| --- | --- |
+| application build fails | the product cannot be produced |
+| extraction or rendering fails | the catalog cannot be trusted |
+| no project opted in | configuration is incomplete or the solution intentionally has no documented project |
+| catalog contract breaks | human review is required before acceptance |
+| publishing fails | the documentation is unavailable even if generation succeeded |
 
-Industrial integration turns errors into a shared operational language.
+Do not hide extraction or publication failures behind `continue-on-error` in a pipeline that promises operational documentation.
 
-Errors become:
+## Review checklist
 
-* documented
-* traceable
-* searchable
-* actionable
+Before approving a catalog-delivery pipeline, verify that:
 
-**automatically**, as part of the build and delivery process — without relying on manual documentation efforts.
+- opted-in projects declare the marker in their own `.csproj`;
+- generation uses the same binaries and configuration as the application build;
+- `--service-name` is supplied for Markdown or HTML;
+- generated files are published somewhere reachable;
+- locale-specific outputs do not overwrite one another;
+- released versions can retain immutable documentation;
+- contract comparison is separate from catalog rendering;
+- generation and publication failures are visible.
 
 ---
 
 <div align="center">
-<a href="Testing.en.md">← Testing Guide</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioning.en.md">Catalog Versioning →</a>
+<a href="DeterministicTesting.en.md">← Deterministic Error Tests</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="LoggingIntegration.en.md">Logging and Operational Integration →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/OperationalIntegration.fr.md b/doc/OperationalIntegration.fr.md
index bcbfe9c..d2f9fd7 100644
--- a/doc/OperationalIntegration.fr.md
+++ b/doc/OperationalIntegration.fr.md
@@ -1,130 +1,219 @@
-# CI/CD et intégration opérationnelle
+# Générer et publier le catalogue d’erreurs
 
-🌍 **Langues:**  
+🌍 **Langues :**  
 🇬🇧 [English](./OperationalIntegration.en.md) | 🇫🇷 Français (ce fichier)
 
-FirstClassErrors révèle toute sa valeur lorsqu’il est intégré dans la chaîne de livraison et les outils opérationnels. L’objectif n’est pas seulement de définir la connaissance liée aux erreurs, mais de la rendre automatiquement accessible aux personnes qui en ont besoin : développeurs, équipes de support et opérateurs.
+FirstClassErrors devient réellement utile pour l’exploitation lorsque le catalogue est généré depuis le code exact en cours de build, puis publié à un endroit accessible aux développeurs, au support et aux opérateurs.
 
-## 📦 La documentation comme artefact de build
+Ce guide couvre la chaîne de livraison. Pour le logging structuré et les diagnostics de production, voir [Logging et intégration opérationnelle](LoggingIntegration.fr.md).
 
-La documentation des erreurs doit être générée automatiquement pendant la CI.
+## Le flux de livraison
 
-Le générateur `fce` est distribué comme outil .NET
-([`FirstClassErrors.Cli`](https://www.nuget.org/packages/FirstClassErrors.Cli)) : un
-pipeline l’installe puis l’exécute comme étapes de build :
+```mermaid
+flowchart LR
+    A[Compiler l’application] --> B[Extraire la connaissance d’erreur]
+    B --> C[Rendre le catalogue]
+    C --> D[Publier l’artefact ou le site]
+    B --> E[Comparer la baseline de contrat]
+```
+
+Un pipeline fiable doit :
+
+1. compiler l’application ;
+2. générer le catalogue depuis le code compilé ;
+3. publier les fichiers générés ;
+4. éventuellement comparer le contrat courant à une baseline commitée — le dernier snapshot accepté de vos codes d’erreur et clés de contexte (voir [Versionnage du catalogue](CatalogVersioning.fr.md)).
+
+## Activer les projets
+
+La génération au niveau solution est opt-in. Ajoutez le marqueur directement dans chaque `.csproj` qui définit des erreurs applicatives documentées :
+
+```xml
+<PropertyGroup>
+  <GenerateErrorDocumentation>true</GenerateErrorDocumentation>
+</PropertyGroup>
+```
+
+Le marqueur est lu dans le fichier projet lui-même. Une valeur héritée de `Directory.Build.props` n’est pas détectée.
+
+Lorsqu’aucun projet n’a opté, le générateur émet un avertissement plutôt que de présenter silencieusement un catalogue vide comme un résultat valide.
 
-1. Installer le générateur : `dotnet tool install --global FirstClassErrors.Cli`  
-2. Compiler la solution  
-3. Exécuter le générateur (`fce generate`) pour produire le catalogue d’erreurs (Markdown, HTML ou JSON)  
-4. Le publier comme artefact du pipeline ou le déployer sur un portail documentaire  
+Pour les déclarations ambiguës, la découverte de projets et le fonctionnement des workers, voir [Architecture du pipeline de documentation](ArchitectureOfTheDocumentationPipeline.fr.md).
 
-Concrètement :
+## Générer le catalogue en local
+
+Installez le CLI, compilez, puis générez depuis les binaires existants :
 
 ```bash
 dotnet tool install --global FirstClassErrors.Cli
 dotnet build MyApp.sln -c Release
-fce generate --solution MyApp.sln --no-build \
-             --output artifacts/errors.md --format markdown --service-name my-api
+fce generate \
+  --solution MyApp.sln \
+  --configuration Release \
+  --no-build \
+  --format markdown \
+  --output artifacts/errors.md \
+  --service-name my-api
 ```
 
-La génération est **opt-in par projet** : seuls les projets dont le fichier projet (`.csproj`) définit `<GenerateErrorDocumentation>true</GenerateErrorDocumentation>` sont analysés ; un projet sans cette propriété est silencieusement ignoré. Le marqueur doit figurer dans le `.csproj` lui-même — il est lu directement dans le XML du projet, donc une valeur héritée d’un `Directory.Build.props` partagé n’est pas prise en compte. Quand aucun projet n’a opté, le générateur journalise un avertissement nommant la propriété plutôt que de produire un catalogue vide en silence. Si un pipeline neuf produit un catalogue vide, vérifiez d’abord l’opt-in. Voir [Activer un projet (opt-in)](ArchitectureOfTheDocumentationPipeline.fr.md#activer-un-projet-opt-in).
+`--service-name` est requis pour Markdown et HTML car leurs exemples RFC 9457 utilisent des types de problème comme :
 
-Cela garantit que la documentation correspond toujours à la version du système déployée. Aucune mise à jour manuelle n’est nécessaire et aucune dérive ne peut apparaître.
+```text
+urn:problem:my-api:payment-declined
+```
 
-Vous pouvez produire le catalogue par langue en ajoutant `--language <…>` (par ex. une matrice CI sur `en`, `fr`, `sv`) ; les noms de fichiers et les ancres restent stables d’une langue à l’autre. Voir [Internationalisation](Internationalisation.fr.md).
+La sortie JSON ne nécessite pas de nom de service.
 
-Les exemples publics RFC 9457 portent un `type` de problème de la forme `urn:problem:{service}:{code}`. Fournissez le segment de service avec `--service-name <nom>` (ou `serviceName` dans `fce.json`) ; il est requis pour les formats `markdown` et `html` — `fce generate` échoue avec un message clair lorsqu’il est absent — tandis que `json` (qui ne contient pas cet exemple) n’en a pas besoin.
+## Workflow GitHub Actions recommandé
 
-## 🛡️ Protéger le contrat d'erreurs
+Le workflow rend le catalogue en HTML avec `--layout split` (une page par erreur ; voir [Le renderer HTML](TheHtmlRenderer.fr.md)) :
 
-Les codes d'erreur et les clés de contexte sont un contrat public : des clients branchent leur logique dessus, des tableaux de bord alertent dessus, des procédures de support y font référence. Une étape de CI peut protéger ce contrat en comparant le catalogue courant à une baseline commitée et en faisant échouer le build quand un code disparaît par accident :
+```yaml
+name: error-documentation
 
-```bash
-fce catalog diff --solution MyApp.sln
-```
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  generate-error-catalog:
+    runs-on: ubuntu-latest
 
-Voir [Versionnage du catalogue](CatalogVersioning.fr.md) pour le workflow de baseline, la classification des changements et la sémantique des codes de sortie.
+    steps:
+      - uses: actions/checkout@v4
 
-## 🌍 Publication de la documentation
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
 
-La documentation générée peut être :
+      - name: Install FirstClassErrors CLI
+        run: dotnet tool install --global FirstClassErrors.Cli
 
-* publiée sur un portail documentaire interne  
-* exposée via un site statique  
-* attachée aux artefacts de release  
+      - name: Build
+        run: dotnet build MyApp.sln -c Release
 
-Le principe clé est :
+      - name: Generate catalog
+        run: |
+          fce generate \
+            --solution MyApp.sln \
+            --configuration Release \
+            --no-build \
+            --format html \
+            --layout split \
+            --output artifacts/error-catalog \
+            --service-name my-api
 
-> La documentation doit être accessible aux personnes qui investiguent les incidents en production.
+      - name: Publish catalog artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: error-catalog
+          path: artifacts/error-catalog
+```
 
-## 📜 Intégration avec les logs
+Le build et la génération utilisent la même configuration. `--no-build` évite que le générateur reconstruise un autre ensemble de binaires.
 
-FirstClassErrors est conçu pour s’intégrer naturellement avec le logging structuré.
+## Générer plusieurs langues
 
-Les logs peuvent inclure :
+Exécutez une génération par locale :
 
-* le code d'erreur
-* l'identifiant unique de l'erreur
-* l'horodatage de l'occurrence
-* le contexte d’erreur
+```yaml
+strategy:
+  matrix:
+    language: [en, fr]
 
-Cela rend les logs non seulement lisibles, mais aussi corrélables entre systèmes.
+steps:
+  # checkout, setup, installation et build omis
 
-## 🔍 Logging des inner errors
+  - name: Generate ${{ matrix.language }} catalog
+    run: |
+      fce generate \
+        --solution MyApp.sln \
+        --configuration Release \
+        --no-build \
+        --format html \
+        --layout split \
+        --language "${{ matrix.language }}" \
+        --output "artifacts/error-catalog-${{ matrix.language }}" \
+        --service-name my-api
+```
 
-Par défaut, la plupart des configurations de logging traitent les exceptions comme de simples messages ou des stack traces. Elles ne parcourent pas automatiquement l’information de diagnostic portée par une `DiagnosableException` de manière structurée et exploitable pour l’analyse.
+Les noms de fichiers et les ancres restent stables d’une langue à l’autre. Voir [Internationalisation](Internationalisation.fr.md) pour la localisation du contenu et des templates de renderer.
 
-Une `DiagnosableException` ne renseigne pas `Exception.InnerException` ; la chaîne de diagnostic vit plutôt sur son `Error`. Via `exception.Error.InnerErrors` (une liste d’`Error`), un filtre de logging ou un middleware devrait explicitement parcourir et logger cette chaîne. Sans cela, une partie de l’information de diagnostic portée par le modèle peut rester inutilisée dans les logs.
+## Choisir une cible de publication
 
-Ce filtre peut :
+Le catalogue généré peut être :
 
-* détecter les `DiagnosableException`  
-* lire son `.Error`  
-* parcourir `Error.InnerErrors` et logger toute la chaîne de manière structurée  
+- conservé comme artefact de pipeline ;
+- attaché à une release ;
+- déployé comme site statique ;
+- copié dans un portail documentaire interne ;
+- publié à côté de la documentation opérationnelle du service.
 
-Cela préserve la profondeur diagnostique et garantit que la richesse du modèle d’erreur est réellement visible dans les logs opérationnels.
+La plateforme importe moins que l’accessibilité : le catalogue correspondant à une version déployée doit être atteignable par les personnes qui investiguent cette version.
 
-## 🔗 Lier les logs à la documentation
+## Conserver des catalogues versionnés
 
-Un pattern puissant consiste à enrichir l’exception levée (via son `Error`) avec une URL vers la documentation.
+Un site « latest » est pratique au quotidien, mais n’explique plus correctement une ancienne release de production après l’évolution du contrat.
 
-Lors de la génération de la documentation, chaque erreur peut être associée à une page ou une ancre. Un filtre de logging peut alors renseigner :
+Pour les systèmes durables ou critiques pour le support, publiez au moins une forme immuable par release :
 
+```text
+/errors/latest/
+/errors/releases/2.4.0/
+/errors/releases/2.3.1/
 ```
-exception.HelpLink = "https://docs.mycompany/errors/AMOUNT_CURRENCY_MISMATCH"
-```
 
-Les logs de production deviennent ainsi navigables : le support peut passer directement d’une entrée de log à la documentation correspondante de l’erreur.
+Des événements de log qui enregistrent la version déployée à côté de l’erreur permettent alors au support de partir d’une occurrence loggée — son `InstanceId` plus cette version — et d’ouvrir le catalogue correspondant.
+
+## Protéger le contrat d’erreurs
+
+La génération répond à « que documente cette version ? ». Le versionnage répond à « cette version casse-t-elle un contrat déjà accepté ? ».
+
+`fce catalog diff` compare le catalogue extrait du build courant à un fichier de baseline commité dans le dépôt et signale les changements de contrat :
+
+```bash
+fce catalog diff --solution MyApp.sln --configuration Release --no-build
+```
 
-## 🧩 Complémentaire au logging structuré
+Conservez la baseline acceptée dans le dépôt et exécutez la comparaison dans les pull requests.
 
-FirstClassErrors ne remplace ni le logging structuré, ni les scopes, ni les correlation IDs.
+Voir :
 
-Il les complète :
+- [Versionnage du catalogue](CatalogVersioning.fr.md) pour le modèle mental et le workflow quotidien ;
+- [Intégration CI/CD du versionnage](CatalogVersioningCI.fr.md) pour les exemples complets GitHub Actions et GitLab.
 
-* logging structuré → contexte technique  
-* scopes → contexte d’exécution  
-* FirstClassErrors → signification sémantique de l’erreur  
+## Politique d’échec
 
-Ensemble, ils donnent une vision complète de ce qui s’est passé.
+Traitez séparément les situations suivantes :
 
-## 🎯 L’objectif
+| Situation | Signification dans le pipeline |
+| --- | --- |
+| le build applicatif échoue | le produit ne peut pas être construit |
+| l’extraction ou le rendu échoue | le catalogue n’est pas fiable |
+| aucun projet n’a opté | la configuration est incomplète ou la solution ne contient volontairement aucun projet documenté |
+| le contrat du catalogue casse | une revue humaine est nécessaire avant acceptation |
+| la publication échoue | la documentation reste indisponible malgré une génération réussie |
 
-L’intégration industrielle transforme les erreurs en langage opérationnel partagé.
+Ne masquez pas les erreurs d’extraction ou de publication avec `continue-on-error` dans un pipeline qui promet une documentation opérationnelle.
 
-Les erreurs deviennent :
+## Checklist de revue
 
-* documentées  
-* traçables  
-* recherchables  
-* exploitables  
+Avant d’approuver un pipeline de livraison du catalogue, vérifiez que :
 
-**automatiquement**, dans le cadre du processus de build et de livraison — sans dépendre d’efforts manuels de documentation.
+- les projets activés déclarent le marqueur dans leur propre `.csproj` ;
+- la génération utilise les mêmes binaires et la même configuration que le build applicatif ;
+- `--service-name` est fourni pour Markdown ou HTML ;
+- les fichiers générés sont publiés à un endroit accessible ;
+- les sorties par langue ne s’écrasent pas ;
+- les releases peuvent conserver une documentation immuable ;
+- la comparaison de contrat reste distincte du rendu du catalogue ;
+- les échecs de génération et de publication sont visibles.
 
 ---
 
 <div align="center">
-<a href="Testing.fr.md">← Guide des tests</a> · <a href="README.fr.md#-étapes-suivantes">↑ Table des matières</a> · <a href="CatalogVersioning.fr.md">Versionnage du catalogue →</a>
+<a href="DeterministicTesting.fr.md">← Tests d’erreur déterministes</a> · <a href="README.fr.md#-étapes-suivantes">↑ Table des matières</a> · <a href="LoggingIntegration.fr.md">Logging et intégration opérationnelle →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/Testing.en.md b/doc/Testing.en.md
index 3ce29ba..f6b4b18 100644
--- a/doc/Testing.en.md
+++ b/doc/Testing.en.md
@@ -1,128 +1,106 @@
-# Testing Guide
+# Testing Outcomes and Errors
 
 🌍 **Languages:**  
 🇬🇧 English (this file) | 🇫🇷 [Français](./Testing.fr.md)
 
-Errors and outcomes are values, so your tests should read like tests about
-values — not like plumbing. The companion package **`FirstClassErrors.Testing`**
-gives you three small things that make that easy:
+Errors and outcomes are values. Their tests should therefore describe success, failure, and error semantics directly—not the plumbing used to inspect them.
 
-* **Fluent assertions** on `Outcome`, `Outcome<T>` and `Error`.
-* **A freezable clock**, so `OccurredAt` is deterministic.
-* **Freezable instance ids**, so `InstanceId` is deterministic.
+The companion package **`FirstClassErrors.Testing`** provides framework-agnostic fluent assertions for `Outcome`, `Outcome<T>`, and `Error`.
 
-Two promises the package keeps:
-
-* **It imposes no test or assertion framework.** The assertions throw a plain
-  exception that xUnit, NUnit, MSTest — anything — reports as a failure.
-* **It adds nothing to your production dependencies.** Everything lives in a
-  separate test-only package, and the overrides only ever affect code running
-  inside their `using` scope.
+## Install the testing package
 
 ```xml
-<!-- in your test project -->
 <PackageReference Include="FirstClassErrors.Testing" Version="..." />
 ```
 
 ```csharp
 using FirstClassErrors;
 using FirstClassErrors.Testing;
+using NFluent;
 ```
 
-> The examples below use xUnit for the scaffolding (`[Fact]`, `Assert`), but the
-> FirstClassErrors assertions work the same in any framework.
+The examples use xUnit for test scaffolding and NFluent for plain-value assertions — the convention this repository's own test suite follows — but the FirstClassErrors assertions do not depend on xUnit, NUnit, MSTest, NFluent, or another assertion library.
 
----
+The package belongs only in test projects and adds nothing to production dependencies.
 
-## ✅ Asserting on outcomes
+## Assert a successful `Outcome<T>`
 
-This is the part you'll use every day. Testing code that returns an `Outcome`
-usually means unwrapping it by hand and reaching for the null-forgiving
-`!` operator:
+Without the testing package, a test usually checks the state and unwraps the result separately:
 
 ```csharp
-// 😐 Before
 Outcome<Receipt> outcome = checkout.Pay(order);
 
-Assert.True(outcome.IsFailure);
-Assert.Equal("PAYMENT_DECLINED", outcome.Error!.Code.ToString());
+Check.That(outcome.IsSuccess).IsTrue();
+Receipt receipt = outcome.GetResultOrThrow();
+Check.That(receipt.AmountCharged).IsEqualTo(order.Total);
 ```
 
-With the testing package, the intent comes first and the boilerplate disappears:
-
-```csharp
-// 🙂 After
-checkout.Pay(order)
-        .ShouldFail()
-        .WithCode("PAYMENT_DECLINED");
-```
-
-### Successes return their value
-
-`ShouldSucceed()` asserts the outcome succeeded and hands you the carried value,
-ready to assert on:
+`ShouldSucceed()` performs the state assertion and returns the carried value:
 
 ```csharp
 [Fact]
-public void Paying_a_valid_order_produces_a_receipt()
-{
-    Outcome<Receipt> outcome = checkout.Pay(order);
+public void Paying_a_valid_order_produces_a_receipt() {
+    Receipt receipt = checkout.Pay(order).ShouldSucceed();
 
-    Receipt receipt = outcome.ShouldSucceed();
-
-    Assert.Equal(order.Total, receipt.AmountCharged);
+    Check.That(receipt.AmountCharged).IsEqualTo(order.Total);
 }
 ```
 
-For the non-generic `Outcome`, `ShouldSucceed()` simply asserts success:
+For non-generic `Outcome`, it simply asserts success:
 
 ```csharp
 inventory.Reserve(sku).ShouldSucceed();
 ```
 
-### Failures return a fluent handle
+## Assert a failure
 
-`ShouldFail()` asserts the outcome failed and returns an `ErrorAssertion` you can
-chain expectations on. Each step checks one facet of the error:
+`ShouldFail()` asserts failure and returns an `ErrorAssertion`:
 
 ```csharp
 [Fact]
-public void Declining_a_payment_reports_a_diagnosable_error()
-{
-    Outcome<Receipt> outcome = checkout.Pay(declinedCard);
-
-    outcome.ShouldFail()
-           .WithCode("PAYMENT_DECLINED")
-           .WithShortMessage("Your payment was declined.")
-           .WithDiagnosticMessage("Issuer refused authorization (code 51).")
-           .WithContextEntry("CardNetwork", "VISA");
+public void Declining_a_payment_reports_a_diagnosable_error() {
+    checkout.Pay(declinedCard)
+            .ShouldFail()
+            .WithCode("PAYMENT_DECLINED")
+            .WithShortMessage("Your payment was declined.")
+            .WithDiagnosticMessage("Issuer refused authorization (code 51).")
+            .WithContextEntry("CardNetwork", "VISA");
 }
 ```
 
-Available checks on `ErrorAssertion`:
+This keeps the expected contract visible in one place: stable code, public message, internal diagnostic, and occurrence context.
+
+## Available error checks
 
 | Method | Asserts |
 | --- | --- |
-| `WithCode("...")` / `WithCode(errorCode)` | the error's `Code` |
-| `WithShortMessage("...")` | the public `ShortMessage` |
-| `WithDiagnosticMessage("...")` | the internal `DiagnosticMessage` |
-| `WithContextEntry("key")` | a context entry is present |
-| `WithContextEntry("key", value)` | a context entry is present **and** equals `value` |
+| `WithCode("...")` | the error code as text |
+| `WithCode(errorCode)` | the strongly typed `ErrorCode` |
+| `WithShortMessage("...")` | the public short message |
+| `WithDiagnosticMessage("...")` | the internal diagnostic message |
+| `WithContextEntry("key")` | that a context entry exists |
+| `WithContextEntry("key", value)` | that the entry exists and equals the expected value |
+
+Use only the assertions that express the behavior owned by the test. Avoid asserting every field mechanically when only the code and one context value matter.
 
-Need something the fluent surface doesn't cover? `Subject` gives you the raw
-`Error` back:
+## Access the underlying error
+
+`Subject` returns the asserted `Error` when the fluent surface does not cover a property:
 
 ```csharp
-Error error = outcome.ShouldFail().WithCode("ORDER_NOT_FOUND").Subject;
+Error error = outcome.ShouldFail()
+                     .WithCode("ORDER_NOT_FOUND")
+                     .Subject;
 
-Assert.Empty(error.InnerErrors);
+Check.That(error.InnerErrors).IsEmpty();
+Check.That(((InfrastructureError)error).Transience).IsEqualTo(Transience.NonTransient);
 ```
 
-### Failure messages read well
+Use `Subject` for targeted assertions, not to immediately rebuild all the manual plumbing that the fluent API removed.
+
+## Failure messages
 
-When an expectation is not met, the assertions throw `OutcomeAssertionException`
-with a message that tells you what actually happened — not the domain's own
-exception:
+When an expectation fails, the package throws `OutcomeAssertionException` with a message describing the mismatch:
 
 ```text
 Expected the outcome to succeed, but it failed with [PAYMENT_DECLINED]: Issuer refused authorization (code 51).
@@ -132,165 +110,63 @@ Expected the outcome to succeed, but it failed with [PAYMENT_DECLINED]: Issuer r
 Expected the error to have code "ORDER_NOT_FOUND", but it was "ORDER_LOCKED".
 ```
 
----
+`OutcomeAssertionException` is a test-framework failure, not the exception `error.ToException()` would produce. A failed test therefore reports what the test expected and what the outcome actually contained.
 
-## 🕒 Freezing the clock
+## What should a test assert?
 
-Every `Error` records the moment it occurred in `OccurredAt`. In a test, the real
-clock forces you into a time window:
+Prefer assertions on the stable behavior of the error:
 
-```csharp
-// 😐 Before
-DateTimeOffset before = DateTimeOffset.UtcNow;
-DomainError    error  = MakeError();
-DateTimeOffset after  = DateTimeOffset.UtcNow;
+- the error code;
+- the error category when relevant;
+- public wording only when it is part of the intended contract;
+- diagnostic wording when the exact diagnostic is deliberately specified;
+- context keys and values used by consumers or operations;
+- inner errors when composition is itself the behavior under test.
 
-Assert.True(error.OccurredAt >= before && error.OccurredAt <= after);
-```
+Avoid coupling every test to incidental prose or timestamps unless those values are the subject of the test.
 
-`Clock.UseFixed(...)` pins the time to an exact instant for the duration of a
-`using` scope, so you can assert equality:
+## Complete example
 
 ```csharp
-// 🙂 After
 [Fact]
-public void An_error_records_when_it_occurred()
-{
-    var instant = new DateTimeOffset(2026, 7, 8, 10, 30, 0, TimeSpan.Zero);
-
-    using (Clock.UseFixed(instant))
-    {
-        DomainError error = DomainError
-            .Create(ErrorCode.Create("ORDER_NOT_FOUND"), "Order 42 was not found.")
-            .WithPublicMessage("This order does not exist.");
-
-        Assert.Equal(instant, error.OccurredAt);
-    }
-}
-```
-
-Need a clock you control across several reads (for example a clock that
-advances)? Implement `IClock` and pass it to `Clock.Use(...)`:
+public void Looking_up_a_missing_order_returns_the_expected_error() {
+    Outcome<Order> outcome = orders.Find(missingOrderId);
 
-```csharp
-sealed class StepClock : IClock
-{
-    private DateTimeOffset _now;
-    public StepClock(DateTimeOffset start) => _now = start;
-
-    public DateTimeOffset UtcNow
-    {
-        get
-        {
-            DateTimeOffset current = _now;
-            _now = _now.AddSeconds(1); // each read advances by one second
-            return current;
-        }
-    }
-}
+    Error error = outcome.ShouldFail()
+                         .WithCode("ORDER_NOT_FOUND")
+                         .WithShortMessage("The order does not exist.")
+                         .WithContextEntry("OrderId", missingOrderId)
+                         .Subject;
 
-using (Clock.Use(new StepClock(start)))
-{
-    // errors created here get start, start + 1s, start + 2s, ...
+    Check.That(error).IsInstanceOf<DomainError>();
+    Check.That(error.InnerErrors).IsEmpty();
 }
 ```
 
-**How the scope behaves**
-
-* Outside a scope — i.e. in production — the clock is always the real system
-  clock. This type only affects code running inside a `using` block.
-* Disposing the scope restores the previous clock. Always use `using`.
-* The override flows with the current execution context, so it never leaks into
-  tests running in parallel.
+The test reads as a description of the failure contract rather than a sequence of nullable checks and casts.
 
----
+## Deterministic timestamps and instance ids
 
-## 🔢 Freezing instance ids
+Every error occurrence contains an `OccurredAt` timestamp and a unique `InstanceId`. When a test or snapshot (a test comparing a serialized object against an approved reference file) must assert those values, use the scoped overrides provided by the testing package.
 
-Each error occurrence gets a unique `InstanceId` (a random `Guid`). That is
-exactly what you want in production and exactly what breaks a snapshot or an
-equality assertion over a whole error. `InstanceIds` lets you pin it.
+See [Deterministic Error Tests](DeterministicTesting.en.md) for `Clock.UseFixed(...)`, `InstanceIds.UseFixed(...)`, custom sources, parallel-test behavior, and full-error snapshots.
 
-Pin a single id:
+## Review checklist
 
-```csharp
-[Fact]
-public void A_not_found_error_snapshots_cleanly()
-{
-    var id = new Guid("11111111-1111-1111-1111-111111111111");
+Before approving an error test, verify that:
 
-    using (InstanceIds.UseFixed(id))
-    {
-        DomainError error = orders.Find(missingId).ShouldFail().Subject as DomainError;
-
-        Assert.Equal(id, error!.InstanceId);
-    }
-}
-```
-
-Or provide your own source — a counter, for instance, when a test creates
-several errors and you want stable, distinct ids:
-
-```csharp
-static Func<Guid> Sequential()
-{
-    int n = 0;
-    return () => new Guid(++n, 0, 0, new byte[8]); // 00000001-..., 00000002-...
-}
-
-using (InstanceIds.Use(Sequential()))
-{
-    // first error  -> 00000001-0000-0000-0000-000000000000
-    // second error -> 00000002-0000-0000-0000-000000000000
-}
-```
-
-`InstanceIds` follows the same scope rules as `Clock`: disposable, context-local,
-and inert outside a `using` block.
-
----
-
-## 🧪 Putting it together
-
-Fixing the clock and the id turns a whole error into a completely deterministic
-value — ideal for a single, readable assertion or a snapshot:
-
-```csharp
-[Fact]
-public void Looking_up_a_missing_order_fails_deterministically()
-{
-    var instant = new DateTimeOffset(2026, 7, 8, 10, 30, 0, TimeSpan.Zero);
-    var id      = new Guid("11111111-1111-1111-1111-111111111111");
-
-    using (Clock.UseFixed(instant))
-    using (InstanceIds.UseFixed(id))
-    {
-        Outcome<Order> outcome = orders.Find(missingId);
-
-        ErrorAssertion failure = outcome.ShouldFail()
-                                        .WithCode("ORDER_NOT_FOUND")
-                                        .WithContextEntry("OrderId", missingId);
-
-        Assert.Equal(instant, failure.Subject.OccurredAt);
-        Assert.Equal(id,      failure.Subject.InstanceId);
-    }
-}
-```
-
----
-
-## 📎 Good to know
-
-* Everything is **scoped and disposable** — always reach for `using`.
-* Overrides are **context-local**: they apply to the current async flow only, so
-  parallel tests don't interfere with each other.
-* Nothing here changes production behavior, and the package pulls **no test or
-  assertion framework** into your project.
+- it asserts behavior rather than implementation plumbing;
+- success values are obtained through `ShouldSucceed()`;
+- failures are asserted through `ShouldFail()`;
+- the error code is checked when it identifies the scenario;
+- exact prose is asserted only when intentionally contractual;
+- `Subject` is used only for properties outside the fluent surface;
+- time and identifiers are frozen only when the test needs them.
 
 ---
 
 <div align="center">
-<a href="BestPractices.en.md">← Best Practices</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="OperationalIntegration.en.md">CI/CD and Operational Integration →</a>
+<a href="BestPractices.en.md">← Best Practices</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="DeterministicTesting.en.md">Deterministic Error Tests →</a>
 </div>
 
----
+---
\ No newline at end of file
diff --git a/doc/Testing.fr.md b/doc/Testing.fr.md
index 505b606..5e7a0f5 100644
--- a/doc/Testing.fr.md
+++ b/doc/Testing.fr.md
@@ -1,302 +1,172 @@
-# Guide des tests
+# Tester les outcomes et les erreurs
 
 🌍 **Langues :**  
 🇫🇷 Français (ce fichier) | 🇬🇧 [English](./Testing.en.md)
 
-Les erreurs et les outcomes sont des valeurs : vos tests devraient donc se lire
-comme des tests sur des valeurs — pas comme de la tuyauterie. Le package
-compagnon **`FirstClassErrors.Testing`** apporte trois petites choses qui rendent
-cela facile :
+Les erreurs et les outcomes sont des valeurs. Leurs tests doivent donc décrire directement le succès, l’échec et la sémantique de l’erreur — pas la tuyauterie nécessaire pour les inspecter.
 
-* des **assertions fluentes** sur `Outcome`, `Outcome<T>` et `Error` ;
-* une **horloge figeable**, pour que `OccurredAt` soit déterministe ;
-* des **identifiants d'instance figeables**, pour que `InstanceId` soit déterministe.
+Le package compagnon **`FirstClassErrors.Testing`** fournit des assertions fluentes indépendantes du framework sur `Outcome`, `Outcome<T>` et `Error`.
 
-Deux promesses tenues par le package :
-
-* **Il n'impose aucun framework de test ni d'assertion.** Les assertions lèvent
-  une simple exception que xUnit, NUnit, MSTest — n'importe lequel — rapporte
-  comme un échec.
-* **Il n'ajoute rien à vos dépendances de production.** Tout vit dans un package
-  séparé réservé aux tests, et les overrides n'affectent jamais que le code qui
-  s'exécute à l'intérieur de leur portée `using`.
+## Installer le package de test
 
 ```xml
-<!-- dans votre projet de test -->
 <PackageReference Include="FirstClassErrors.Testing" Version="..." />
 ```
 
 ```csharp
 using FirstClassErrors;
 using FirstClassErrors.Testing;
+using NFluent;
 ```
 
-> Les exemples ci-dessous utilisent xUnit pour l'échafaudage (`[Fact]`,
-> `Assert`), mais les assertions de FirstClassErrors fonctionnent de la même
-> manière dans n'importe quel framework.
+Les exemples utilisent xUnit pour la structure des tests et NFluent pour les assertions sur les valeurs simples — la convention suivie par la suite de tests de ce dépôt — mais les assertions FirstClassErrors ne dépendent ni de xUnit, ni de NUnit, ni de MSTest, ni de NFluent, ni d’une autre bibliothèque d’assertions.
 
----
+Le package doit rester réservé aux projets de test et n’ajoute aucune dépendance en production.
 
-## ✅ Asserter sur les outcomes
+## Asserter un `Outcome<T>` réussi
 
-C'est la partie que vous utiliserez tous les jours. Tester du code qui renvoie un
-`Outcome` revient d'ordinaire à le déballer à la main et à sortir l'opérateur
-`!` qui écrase le nullable :
+Sans le package de test, un test vérifie généralement l’état puis récupère séparément le résultat :
 
 ```csharp
-// 😐 Avant
 Outcome<Receipt> outcome = checkout.Pay(order);
 
-Assert.True(outcome.IsFailure);
-Assert.Equal("PAYMENT_DECLINED", outcome.Error!.Code.ToString());
+Check.That(outcome.IsSuccess).IsTrue();
+Receipt receipt = outcome.GetResultOrThrow();
+Check.That(receipt.AmountCharged).IsEqualTo(order.Total);
 ```
 
-Avec le package de test, l'intention passe en premier et le boilerplate disparaît :
-
-```csharp
-// 🙂 Après
-checkout.Pay(order)
-        .ShouldFail()
-        .WithCode("PAYMENT_DECLINED");
-```
-
-### Les succès renvoient leur valeur
-
-`ShouldSucceed()` vérifie que l'outcome a réussi et vous rend la valeur portée,
-prête à être asssertée :
+`ShouldSucceed()` effectue l’assertion d’état et retourne la valeur portée :
 
 ```csharp
 [Fact]
-public void Payer_une_commande_valide_produit_un_recu()
-{
-    Outcome<Receipt> outcome = checkout.Pay(order);
+public void Payer_une_commande_valide_produit_un_recu() {
+    Receipt receipt = checkout.Pay(order).ShouldSucceed();
 
-    Receipt receipt = outcome.ShouldSucceed();
-
-    Assert.Equal(order.Total, receipt.AmountCharged);
+    Check.That(receipt.AmountCharged).IsEqualTo(order.Total);
 }
 ```
 
-Pour l'`Outcome` non générique, `ShouldSucceed()` vérifie simplement le succès :
+Pour l’`Outcome` non générique, la méthode vérifie simplement le succès :
 
 ```csharp
 inventory.Reserve(sku).ShouldSucceed();
 ```
 
-### Les échecs renvoient un handle fluent
+## Asserter un échec
 
-`ShouldFail()` vérifie que l'outcome a échoué et renvoie une `ErrorAssertion` sur
-laquelle enchaîner des attentes. Chaque étape vérifie une facette de l'erreur :
+`ShouldFail()` vérifie l’échec et retourne une `ErrorAssertion` :
 
 ```csharp
 [Fact]
-public void Un_paiement_refuse_remonte_une_erreur_diagnosable()
-{
-    Outcome<Receipt> outcome = checkout.Pay(declinedCard);
-
-    outcome.ShouldFail()
-           .WithCode("PAYMENT_DECLINED")
-           .WithShortMessage("Votre paiement a été refusé.")
-           .WithDiagnosticMessage("L'émetteur a refusé l'autorisation (code 51).")
-           .WithContextEntry("CardNetwork", "VISA");
+public void Un_paiement_refuse_remonte_une_erreur_diagnosable() {
+    checkout.Pay(declinedCard)
+            .ShouldFail()
+            .WithCode("PAYMENT_DECLINED")
+            .WithShortMessage("Votre paiement a été refusé.")
+            .WithDiagnosticMessage("L’émetteur a refusé l’autorisation (code 51).")
+            .WithContextEntry("CardNetwork", "VISA");
 }
 ```
 
-Vérifications disponibles sur `ErrorAssertion` :
+Le contrat attendu reste visible au même endroit : code stable, message public, diagnostic interne et contexte de l’occurrence.
+
+## Vérifications disponibles
 
 | Méthode | Vérifie |
 | --- | --- |
-| `WithCode("...")` / `WithCode(errorCode)` | le `Code` de l'erreur |
-| `WithShortMessage("...")` | le `ShortMessage` public |
-| `WithDiagnosticMessage("...")` | le `DiagnosticMessage` interne |
-| `WithContextEntry("clé")` | la présence d'une entrée de contexte |
-| `WithContextEntry("clé", valeur)` | la présence d'une entrée **et** son égalité à `valeur` |
+| `WithCode("...")` | le code d’erreur sous forme de texte |
+| `WithCode(errorCode)` | l’`ErrorCode` typé |
+| `WithShortMessage("...")` | le message public court |
+| `WithDiagnosticMessage("...")` | le message de diagnostic interne |
+| `WithContextEntry("clé")` | la présence d’une entrée de contexte |
+| `WithContextEntry("clé", valeur)` | la présence de l’entrée et l’égalité à la valeur attendue |
+
+N’utilisez que les assertions qui expriment le comportement couvert par le test. Évitez de vérifier mécaniquement tous les champs lorsque seuls le code et une valeur de contexte importent.
 
-Besoin de quelque chose que la surface fluente ne couvre pas ? `Subject` vous
-rend l'`Error` brute :
+## Accéder à l’erreur sous-jacente
+
+`Subject` retourne l’`Error` assertée lorsque la surface fluente ne couvre pas une propriété :
 
 ```csharp
-Error error = outcome.ShouldFail().WithCode("ORDER_NOT_FOUND").Subject;
+Error error = outcome.ShouldFail()
+                     .WithCode("ORDER_NOT_FOUND")
+                     .Subject;
 
-Assert.Empty(error.InnerErrors);
+Check.That(error.InnerErrors).IsEmpty();
+Check.That(((InfrastructureError)error).Transience).IsEqualTo(Transience.NonTransient);
 ```
 
-### Les messages d'échec se lisent bien
+Utilisez `Subject` pour des assertions ciblées, pas pour reconstruire immédiatement toute la tuyauterie manuelle que l’API fluente vient de supprimer.
+
+## Messages d’échec
 
-Quand une attente n'est pas satisfaite, les assertions lèvent une
-`OutcomeAssertionException` dont le message dit ce qui s'est réellement passé —
-et non l'exception propre au domaine :
+Lorsqu’une attente échoue, le package lève `OutcomeAssertionException` avec un message décrivant l’écart :
 
 ```text
-Expected the outcome to succeed, but it failed with [PAYMENT_DECLINED]: L'émetteur a refusé l'autorisation (code 51).
+Expected the outcome to succeed, but it failed with [PAYMENT_DECLINED]: L’émetteur a refusé l’autorisation (code 51).
 ```
 
 ```text
 Expected the error to have code "ORDER_NOT_FOUND", but it was "ORDER_LOCKED".
 ```
 
----
+`OutcomeAssertionException` est un échec du framework de test, pas l’exception que produirait `error.ToException()`. Le test indique donc ce qu’il attendait et ce que l’outcome contenait réellement.
 
-## 🕒 Figer l'horloge
+## Que doit vérifier un test ?
 
-Chaque `Error` enregistre l'instant où elle est survenue dans `OccurredAt`. Dans
-un test, l'horloge réelle vous force à raisonner par fenêtre de temps :
+Privilégiez les assertions sur le comportement stable de l’erreur :
 
-```csharp
-// 😐 Avant
-DateTimeOffset before = DateTimeOffset.UtcNow;
-DomainError    error  = MakeError();
-DateTimeOffset after  = DateTimeOffset.UtcNow;
+- le code d’erreur ;
+- la catégorie d’erreur lorsqu’elle est pertinente ;
+- le texte public uniquement lorsqu’il fait partie du contrat voulu ;
+- le diagnostic lorsque sa formulation exacte est volontairement spécifiée ;
+- les clés et valeurs de contexte exploitées par des consommateurs ou par l’exploitation ;
+- les erreurs internes lorsque la composition est elle-même le comportement testé.
 
-Assert.True(error.OccurredAt >= before && error.OccurredAt <= after);
-```
+Évitez de coupler chaque test à du texte secondaire, à un horodatage ou à un identifiant lorsque ces valeurs ne sont pas le sujet du test.
 
-`Clock.UseFixed(...)` épingle le temps à un instant exact pendant la durée d'une
-portée `using`, ce qui permet d'asserter une égalité :
+## Exemple complet
 
 ```csharp
-// 🙂 Après
 [Fact]
-public void Une_erreur_enregistre_quand_elle_survient()
-{
-    var instant = new DateTimeOffset(2026, 7, 8, 10, 30, 0, TimeSpan.Zero);
-
-    using (Clock.UseFixed(instant))
-    {
-        DomainError error = DomainError
-            .Create(ErrorCode.Create("ORDER_NOT_FOUND"), "La commande 42 est introuvable.")
-            .WithPublicMessage("Cette commande n'existe pas.");
-
-        Assert.Equal(instant, error.OccurredAt);
-    }
-}
-```
-
-Besoin d'une horloge que vous contrôlez sur plusieurs lectures (par exemple une
-horloge qui avance) ? Implémentez `IClock` et passez-la à `Clock.Use(...)` :
+public void Chercher_une_commande_absente_retourne_l_erreur_attendue() {
+    Outcome<Order> outcome = orders.Find(missingOrderId);
 
-```csharp
-sealed class StepClock : IClock
-{
-    private DateTimeOffset _now;
-    public StepClock(DateTimeOffset start) => _now = start;
-
-    public DateTimeOffset UtcNow
-    {
-        get
-        {
-            DateTimeOffset current = _now;
-            _now = _now.AddSeconds(1); // chaque lecture avance d'une seconde
-            return current;
-        }
-    }
-}
+    Error error = outcome.ShouldFail()
+                         .WithCode("ORDER_NOT_FOUND")
+                         .WithShortMessage("La commande n’existe pas.")
+                         .WithContextEntry("OrderId", missingOrderId)
+                         .Subject;
 
-using (Clock.Use(new StepClock(start)))
-{
-    // les erreurs créées ici obtiennent start, start + 1s, start + 2s, ...
+    Check.That(error).IsInstanceOf<DomainError>();
+    Check.That(error.InnerErrors).IsEmpty();
 }
 ```
 
-**Comportement de la portée**
-
-* En dehors d'une portée — c'est-à-dire en production — l'horloge est toujours
-  l'horloge système réelle. Ce type n'affecte que le code exécuté dans un bloc
-  `using`.
-* Disposer la portée restaure l'horloge précédente. Utilisez toujours `using`.
-* L'override suit le contexte d'exécution courant : il ne fuit donc jamais dans
-  des tests exécutés en parallèle.
+Le test se lit comme une description du contrat d’échec plutôt que comme une suite de vérifications nullable et de casts.
 
----
+## Horodatages et identifiants déterministes
 
-## 🔢 Figer les identifiants d'instance
+Chaque occurrence d’erreur contient un horodatage `OccurredAt` et un `InstanceId` unique. Lorsqu’un test ou un snapshot (un test qui compare un objet sérialisé à un fichier de référence approuvé) doit vérifier ces valeurs, utilisez les overrides bornés fournis par le package de test.
 
-Chaque occurrence d'erreur reçoit un `InstanceId` unique (un `Guid` aléatoire).
-C'est exactement ce que l'on veut en production, et exactement ce qui casse un
-snapshot ou une assertion d'égalité sur une erreur entière. `InstanceIds`
-permet de l'épingler.
+Voir [Tests d’erreur déterministes](DeterministicTesting.fr.md) pour `Clock.UseFixed(...)`, `InstanceIds.UseFixed(...)`, les sources personnalisées, le comportement en tests parallèles et les snapshots d’erreurs complètes.
 
-Épingler un identifiant unique :
+## Checklist de revue
 
-```csharp
-[Fact]
-public void Une_erreur_not_found_se_snapshote_proprement()
-{
-    var id = new Guid("11111111-1111-1111-1111-111111111111");
+Avant d’approuver un test d’erreur, vérifiez que :
 
-    using (InstanceIds.UseFixed(id))
-    {
-        DomainError error = orders.Find(missingId).ShouldFail().Subject as DomainError;
-
-        Assert.Equal(id, error!.InstanceId);
-    }
-}
-```
-
-Ou fournissez votre propre source — un compteur, par exemple, quand un test crée
-plusieurs erreurs et que vous voulez des identifiants stables et distincts :
-
-```csharp
-static Func<Guid> Sequential()
-{
-    int n = 0;
-    return () => new Guid(++n, 0, 0, new byte[8]); // 00000001-..., 00000002-...
-}
-
-using (InstanceIds.Use(Sequential()))
-{
-    // première erreur  -> 00000001-0000-0000-0000-000000000000
-    // deuxième erreur  -> 00000002-0000-0000-0000-000000000000
-}
-```
-
-`InstanceIds` suit les mêmes règles de portée que `Clock` : jetable, local au
-contexte, et inerte en dehors d'un bloc `using`.
-
----
-
-## 🧪 Tout mettre ensemble
-
-Figer l'horloge et l'identifiant transforme une erreur entière en une valeur
-totalement déterministe — idéale pour une assertion unique et lisible, ou pour
-un snapshot :
-
-```csharp
-[Fact]
-public void Chercher_une_commande_absente_echoue_de_facon_deterministe()
-{
-    var instant = new DateTimeOffset(2026, 7, 8, 10, 30, 0, TimeSpan.Zero);
-    var id      = new Guid("11111111-1111-1111-1111-111111111111");
-
-    using (Clock.UseFixed(instant))
-    using (InstanceIds.UseFixed(id))
-    {
-        Outcome<Order> outcome = orders.Find(missingId);
-
-        ErrorAssertion failure = outcome.ShouldFail()
-                                        .WithCode("ORDER_NOT_FOUND")
-                                        .WithContextEntry("OrderId", missingId);
-
-        Assert.Equal(instant, failure.Subject.OccurredAt);
-        Assert.Equal(id,      failure.Subject.InstanceId);
-    }
-}
-```
-
----
-
-## 📎 Bon à savoir
-
-* Tout est **borné et jetable** — sortez toujours le `using`.
-* Les overrides sont **locaux au contexte** : ils ne s'appliquent qu'au flux
-  asynchrone courant, si bien que des tests parallèles ne se marchent pas dessus.
-* Rien ici ne change le comportement de production, et le package n'introduit
-  **aucun framework de test ni d'assertion** dans votre projet.
+- il teste un comportement et non la tuyauterie d’implémentation ;
+- les valeurs de succès sont obtenues via `ShouldSucceed()` ;
+- les échecs sont vérifiés via `ShouldFail()` ;
+- le code d’erreur est asserté lorsqu’il identifie le scénario ;
+- le texte exact n’est vérifié que lorsqu’il est volontairement contractuel ;
+- `Subject` est réservé aux propriétés hors de la surface fluente ;
+- le temps et les identifiants ne sont figés que lorsque le test en a besoin.
 
 ---
 
 <div align="center">
-<a href="BestPractices.fr.md">← Bonnes pratiques</a> · <a href="README.fr.md#-étapes-suivantes">↑ Table des matières</a> · <a href="OperationalIntegration.fr.md">Intégration CI/CD et exploitation →</a>
+<a href="BestPractices.fr.md">← Bonnes pratiques</a> · <a href="README.fr.md#-étapes-suivantes">↑ Table des matières</a> · <a href="DeterministicTesting.fr.md">Tests d’erreur déterministes →</a>
 </div>
 
----
+---
\ No newline at end of file