@breadstone/archipel-mcp 0.0.23 → 0.0.25

package/data/guides/caching.md

@@ -24,6 +24,39 @@ yarn add ioredis
 
 ---
 
+## Configuration
+
+### Core Variables
+
+```env
+CACHE_DEFAULT_TTL_MS=60000
+CACHE_MAX_ENTRIES=1000
+CACHE_STALE_WHILE_REVALIDATE=false
+```
+
+All core variables are optional. When omitted, each cache instance uses the values passed directly to its constructor options.
+
+### Redis Variables
+
+```env
+REDIS_URL=redis://localhost:6379
+REDIS_KEY_PREFIX=app:
+REDIS_TTL_SECONDS=300
+```
+
+`REDIS_URL` is required when using `RedisLayeredCache`. The other variables are optional.
+
+### Using Config Keys
+
+Import the typed config keys and pass them to your module registration:
+
+```typescript
+import { PLATFORM_CACHING_CONFIG_ENTRIES } from '@breadstone/archipel-platform-caching';
+import { REDIS_CONFIG_ENTRIES } from '@breadstone/archipel-platform-caching/redis';
+```
+
+---
+
 ## Concepts
 
 `platform-caching` provides a generic `ILayeredCache<TKey, TValue>` interface with two implementations:

package/data/guides/email-delivery.md

@@ -147,7 +147,33 @@ The `template` field is the template name (without extension). The `context` obj
 
 ---
 
-## Email Verification
+## SMTP Connection Verification
+
+`SmtpConnectionVerifier` verifies SMTP server connectivity and optionally sends a test email. It replaces the deprecated `MailVerificationService`.
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { SmtpConnectionVerifier } from '@breadstone/archipel-platform-mailing';
+
+@Injectable()
+export class HealthService {
+  constructor(private readonly _smtpVerifier: SmtpConnectionVerifier) {}
+
+  public async checkSmtpConnectivity(): Promise<boolean> {
+    return this._smtpVerifier.verifyConnection();
+  }
+
+  public async sendTestEmail(to: string): Promise<boolean> {
+    return this._smtpVerifier.sendTestEmail(to);
+  }
+}
+```
+
+## Email Verification (Deprecated)
+
+::: warning Deprecated
+`MailVerificationService` is deprecated. Use `SmtpConnectionVerifier` for SMTP connectivity checks.
+:::
 
 `MailVerificationService` provides a complete email verification flow:
 

package/data/guides/esigning-integration.md

@@ -56,11 +56,17 @@ export class AppModule {}
 
 ## Configuration
 
-```env
-ESIGNING_API_BASE_URL=https://demo.docusign.net/restapi
-ESIGNING_API_KEY=your-api-key
-ESIGNING_WEBHOOK_SECRET=your-webhook-secret
-```
+Each provider requires its own set of environment variables. See the [platform-esigning package docs](../packages/platform-esigning/) for the full table per provider.
+
+### Provider Environment Variables (Summary)
+
+| Provider       | Key Variables                                                                                      |
+| -------------- | -------------------------------------------------------------------------------------------------- |
+| **DocuSign**   | `DOCUSIGN_INTEGRATION_KEY`, `DOCUSIGN_SECRET_KEY`, `DOCUSIGN_ACCOUNT_ID`, `DOCUSIGN_BASE_URL`     |
+| **Adobe Sign** | `ADOBE_SIGN_INTEGRATION_KEY`, `ADOBE_SIGN_CLIENT_SECRET`, `ADOBE_SIGN_BASE_URL`, `ADOBE_SIGN_WEBHOOK_CLIENT_ID` (required) |
+| **Dropbox Sign** | `DROPBOX_SIGN_API_KEY`, `DROPBOX_SIGN_CLIENT_ID`                                               |
+
+> **Breaking change:** `ADOBE_SIGN_WEBHOOK_CLIENT_ID` is now **required** for Adobe Sign webhook verification.
 
 ---
 

package/data/guides/health-indicators.md

@@ -0,0 +1,220 @@
+---
+title: Health Indicators
+description: Integrate health checks from all Archipel platform libraries using the unified health indicator architecture.
+order: 10
+---
+
+# Health Indicators
+
+Every Archipel platform library ships an optional **health indicator** as a separate `/health` subpath export. Health indicators implement the `IHealthIndicator` interface from `platform-health` and can be registered with the `HealthModule` to build a unified `/health` endpoint for your application.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  subgraph App
+    HealthController --> HealthOrchestrator
+  end
+
+  subgraph platform-health
+    HealthOrchestrator
+  end
+
+  subgraph Indicators
+    DatabaseHealthIndicator
+    BlobHealthIndicator
+    MailHealthIndicator
+    CachingHealthIndicator
+    QueueHealthIndicator
+    PaymentHealthIndicator
+    EsigningHealthIndicator
+    IntelligenceHealthIndicator
+    AnalyticsHealthIndicator
+    TelemetryHealthIndicator
+    AuthenticationHealthIndicator
+    McpHealthIndicator
+  end
+
+  HealthOrchestrator --> Indicators
+```
+
+The `HealthOrchestrator` aggregates all registered `IHealthIndicator` instances and returns a combined result. Each indicator reports its own key and status independently.
+
+## Prerequisites
+
+- `@breadstone/archipel-platform-health` installed
+- `@nestjs/terminus` installed (peer dependency)
+
+## IHealthIndicator Interface
+
+Every health indicator implements this contract:
+
+```typescript
+interface IHealthIndicator {
+  /** Unique key identifying this indicator in the health response. */
+  readonly key: string;
+
+  /** Run the health check and return a Terminus HealthIndicatorResult. */
+  check(): HealthIndicatorResult | Promise<HealthIndicatorResult>;
+}
+```
+
+## Available Indicators
+
+All 12 platform libraries provide a health indicator via their `/health` subpath:
+
+| Library | Subpath Import | Class | Key | Check Behavior |
+| ------- | -------------- | ----- | --- | -------------- |
+| `platform-database` | `@breadstone/archipel-platform-database/health` | `DatabaseHealthIndicator` | `database` | Prisma `SELECT 1` ping |
+| `platform-blob-storage` | `@breadstone/archipel-platform-blob-storage/health` | `BlobHealthIndicator` | `blob` | HTTP ping to blob URL (or `disabled` if unconfigured) |
+| `platform-mailing` | `@breadstone/archipel-platform-mailing/health` | `MailHealthIndicator` | `mail` | Validates mail host, user, and port config |
+| `platform-caching` | `@breadstone/archipel-platform-caching/health` | `CachingHealthIndicator` | `caching` | Always `up` |
+| `platform-queue` | `@breadstone/archipel-platform-queue/health` | `QueueHealthIndicator` | `queue` | Always `up` |
+| `platform-payments` | `@breadstone/archipel-platform-payments/health` | `PaymentHealthIndicator` | `payment` | Calls `PaymentClientPort.ping()` to verify provider connectivity |
+| `platform-esigning` | `@breadstone/archipel-platform-esigning/health` | `EsigningHealthIndicator` | `esigning` | Calls `EsigningClientPort.ping()` to verify provider connectivity, reports `providerId` |
+| `platform-intelligence` | `@breadstone/archipel-platform-intelligence/health` | `IntelligenceHealthIndicator` | `intelligence` | Checks `list().length > 0` on the capability registry, reports count |
+| `platform-analytics` | `@breadstone/archipel-platform-analytics/health` | `AnalyticsHealthIndicator` | `analytics` | Calls `AnalyticsClientPort.ping()` to verify provider readiness |
+| `platform-telemetry` | `@breadstone/archipel-platform-telemetry/health` | `TelemetryHealthIndicator` | `telemetry` | Checks `OtelSdkHolder.isInitialized` for SDK presence |
+| `platform-authentication` | `@breadstone/archipel-platform-authentication/health` | `AuthenticationHealthIndicator` | `authentication` | Always `up` |
+| `platform-mcp` | `@breadstone/archipel-platform-mcp/health` | `McpHealthIndicator` | `mcp` | Checks tool/resource/prompt registry counts, reports breakdown |
+
+### Indicator Categories
+
+**Active checks** — perform a real probe:
+- `DatabaseHealthIndicator` — executes a SQL ping
+- `BlobHealthIndicator` — sends an HTTP request to the blob URL
+- `MailHealthIndicator` — validates configuration values
+- `PaymentHealthIndicator` — calls `PaymentClientPort.ping()` (adapters can override for real API calls)
+- `EsigningHealthIndicator` — calls `EsigningClientPort.ping()` (adapters can override for real API calls)
+- `AnalyticsHealthIndicator` — calls `AnalyticsClientPort.ping()` (adapters can override for SDK readiness checks)
+
+**State checks** — inspect in-memory state (zero-cost, no I/O):
+- `IntelligenceHealthIndicator` — verifies at least one capability is registered
+- `TelemetryHealthIndicator` — checks whether the OpenTelemetry SDK has been initialized
+- `McpHealthIndicator` — verifies at least one tool/resource/prompt handler is registered
+
+**Stub checks** — always report `up`:
+- `CachingHealthIndicator`, `QueueHealthIndicator`, `AuthenticationHealthIndicator`
+
+## Quick Start
+
+### 1. Register Indicators
+
+Use `HealthModule.withIndicators()` to register the indicators you need:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { HealthModule } from '@breadstone/archipel-platform-health';
+import { DatabaseHealthIndicator } from '@breadstone/archipel-platform-database/health';
+import { MailHealthIndicator } from '@breadstone/archipel-platform-mailing/health';
+import { PaymentHealthIndicator } from '@breadstone/archipel-platform-payments/health';
+import { CachingHealthIndicator } from '@breadstone/archipel-platform-caching/health';
+
+@Module({
+  imports: [
+    // ... your feature modules
+    HealthModule.withIndicators([
+      DatabaseHealthIndicator,
+      MailHealthIndicator,
+      PaymentHealthIndicator,
+      CachingHealthIndicator,
+    ]),
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Expose a Health Endpoint
+
+The `HealthOrchestrator` runs all registered indicators and returns an aggregated result:
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { HealthOrchestrator } from '@breadstone/archipel-platform-health';
+
+@Controller('health')
+export class HealthController {
+  constructor(private readonly _health: HealthOrchestrator) {}
+
+  @Get()
+  public async check() {
+    return this._health.check();
+  }
+}
+```
+
+### 3. Example Response
+
+```json
+{
+  "status": "ok",
+  "details": {
+    "database": { "status": "up" },
+    "mail": { "status": "up" },
+    "payment": { "status": "up" },
+    "caching": { "status": "up" },
+    "intelligence": { "status": "up", "registeredCapabilities": 3 },
+    "mcp": { "status": "up", "tools": 5, "resources": 2, "prompts": 1 },
+    "telemetry": { "status": "up", "sdkInitialized": true }
+  }
+}
+```
+
+When a provider is not registered (e.g., no `PaymentClientPort` injected), the indicator reports:
+
+```json
+{
+  "payment": { "status": "up", "disabled": true }
+}
+```
+
+When a ping fails, the indicator reports `down` with error details:
+
+```json
+{
+  "payment": { "status": "down", "error": "ECONNREFUSED" }
+}
+```
+
+## Writing a Custom Indicator
+
+Implement `IHealthIndicator` to create a health check for your own services:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { IHealthIndicator } from '@breadstone/archipel-platform-health';
+import type { HealthIndicatorResult } from '@nestjs/terminus';
+
+@Injectable()
+export class SearchHealthIndicator implements IHealthIndicator {
+  public readonly key = 'search';
+
+  public check(): HealthIndicatorResult<'search'> {
+    return { search: { status: 'up' } };
+  }
+}
+```
+
+Register it alongside built-in indicators:
+
+```typescript
+HealthModule.withIndicators([
+  DatabaseHealthIndicator,
+  SearchHealthIndicator,
+]);
+```
+
+## Tree-Shaking
+
+Health indicators are **not** included in the main library entry point. They are exported from a separate `/health` subpath, so they are fully tree-shakeable. If you don't import the health subpath, the indicator code and its `@nestjs/terminus` peer dependency are never bundled.
+
+## Peer Dependencies
+
+Each health indicator requires these optional peer dependencies:
+
+| Package | Notes |
+| ------- | ----- |
+| `@breadstone/archipel-platform-health` | `IHealthIndicator` interface and `HealthModule` |
+| `@nestjs/terminus` | `HealthIndicatorResult` type |
+
+Both are listed as optional peer dependencies in each library's `package.json`.

package/data/guides/index.md

@@ -52,6 +52,8 @@ Practical guides for working with Archipel packages in your NestJS application.
 | [Telemetry & Observability](./telemetry-and-observability)   | OpenTelemetry metrics, distributed tracing, and structured logging.                   |
 | [Analytics & Error Tracking](./analytics-and-error-tracking) | Capture errors and user context with Sentry, AppInsights, or Datadog.                 |
 | [Caching](./caching)                                         | In-memory LRU and Redis layered caches with TTL, stale-while-revalidate, and metrics. |
+| [Queue Infrastructure](./queue-infrastructure)               | In-memory FIFO, BullMQ (Redis), and Azure Service Bus job queues.                     |
+| [Health Indicators](./health-indicators)                     | Integrate health checks from all platform libraries using the unified health architecture. |
 
 ## AI & Extensibility
 

package/data/guides/queue-infrastructure.md

@@ -0,0 +1,329 @@
+---
+title: Queue Infrastructure
+description: Add job queue infrastructure to your NestJS application with in-memory FIFO, BullMQ (Redis), and Azure Service Bus providers.
+order: 25
+---
+
+# Queue Infrastructure
+
+This guide covers job queue infrastructure with `platform-queue`: choosing between in-memory, Redis-backed, and Azure Service Bus backends, managing job lifecycles, handling errors, and switching providers without code changes.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-queue
+```
+
+For BullMQ (Redis), also install the SDK:
+
+```bash
+yarn add bullmq
+```
+
+For Azure Service Bus:
+
+```bash
+yarn add @azure/service-bus
+```
+
+---
+
+## Configuration
+
+### Core Variables
+
+```env
+QUEUE_MAX_JOBS=10000
+```
+
+`QUEUE_MAX_JOBS` is optional and only applies to `MemoryQueue`. When omitted, the default of `10_000` is used.
+
+### BullMQ Variables
+
+```env
+BULLMQ_REDIS_URL=redis://localhost:6379
+BULLMQ_PREFIX=myapp:
+```
+
+`BULLMQ_REDIS_URL` is required when using `BullMqQueue`. `BULLMQ_PREFIX` is optional (defaults to empty string).
+
+### Azure Service Bus Variables
+
+```env
+AZURE_CONNECTION_STRING=Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=...;SharedAccessKey=...
+AZURE_RECEIVE_WAIT_MS=5000
+```
+
+`AZURE_CONNECTION_STRING` is required when using `AzureQueue`. `AZURE_RECEIVE_WAIT_MS` is optional (defaults to `5000`).
+
+### Using Config Keys
+
+Import the typed config keys and pass them to your module registration:
+
+```typescript
+import { PLATFORM_QUEUE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue';
+import { BULLMQ_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/bullmq';
+import { AZURE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/azure';
+```
+
+---
+
+## Concepts
+
+`platform-queue` provides a generic `IQueue<TPayload>` interface with three implementations:
+
+| Implementation | Backend            | Persistence | Best for                                    |
+| -------------- | ------------------ | ----------- | ------------------------------------------- |
+| `MemoryQueue`  | In-memory          | No          | Development, testing, single-instance apps  |
+| `BullMqQueue`  | Redis via BullMQ   | Yes         | Multi-instance deployments, distributed jobs|
+| `AzureQueue`   | Azure Service Bus  | Yes         | Enterprise cloud messaging, peek-lock       |
+
+All implementations share the same `IQueue` contract, so switching providers requires only changing the import and constructor options — no business logic changes.
+
+### Job Lifecycle
+
+Every job follows a four-state lifecycle:
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending : enqueue()
+    pending --> processing : dequeue()
+    processing --> completed : markCompleted()
+    processing --> failed : markFailed()
+```
+
+Each `IQueueJob` carries full metadata: `id`, `queueName`, `payload`, `status`, `attempts`, `createdAt`, `processedAt`, `completedAt`, `failedAt`, and an optional `errorMessage`.
+
+---
+
+## In-Memory Queue
+
+### Basic Setup
+
+`MemoryQueue` ships with the core entry point and requires no extra dependencies:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { MemoryQueue } from '@breadstone/archipel-platform-queue';
+
+@Module({
+    providers: [
+        {
+            provide: 'IQueue',
+            useFactory: () => new MemoryQueue({ maxJobs: 5_000 }),
+        },
+    ],
+    exports: ['IQueue'],
+})
+export class QueueModule {}
+```
+
+### Capacity Eviction
+
+When the total number of jobs across all named queues exceeds `maxJobs`, the oldest completed or failed jobs are evicted automatically. Pending and processing jobs are never evicted.
+
+> **When to use:** Development, automated tests, or single-instance services where persistence is not required.
+
+---
+
+## BullMQ (Redis)
+
+### Basic Setup
+
+`BullMqQueue` creates Redis-backed queues that survive process restarts and can be shared across multiple instances:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { BullMqQueue } from '@breadstone/archipel-platform-queue/bullmq';
+
+@Module({
+    providers: [
+        {
+            provide: 'IQueue',
+            useFactory: () =>
+                new BullMqQueue({
+                    redisUrl: 'redis://localhost:6379',
+                    prefix: 'myapp:',
+                }),
+        },
+    ],
+    exports: ['IQueue'],
+})
+export class QueueModule {}
+```
+
+### How It Works
+
+Each named queue lazily creates its own BullMQ `Queue` and `Worker` instance. When `dequeue()` is called, the worker picks the next available job using a one-time token. Job tokens are tracked internally so that `markCompleted()` and `markFailed()` can transition jobs to their terminal state.
+
+### Graceful Shutdown
+
+`BullMqQueue` implements `OnModuleDestroy` and automatically closes all queues and workers when the NestJS module is destroyed. No manual cleanup is needed.
+
+---
+
+## Azure Service Bus
+
+### Basic Setup
+
+`AzureQueue` integrates with Azure Service Bus using peek-lock message handling:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { AzureQueue } from '@breadstone/archipel-platform-queue/azure';
+
+@Module({
+    providers: [
+        {
+            provide: 'IQueue',
+            useFactory: () =>
+                new AzureQueue({
+                    connectionString: 'Endpoint=sb://...',
+                    receiveWaitMs: 5_000,
+                }),
+        },
+    ],
+    exports: ['IQueue'],
+})
+export class QueueModule {}
+```
+
+### How It Works
+
+Senders and receivers are lazily created per queue name and cached for the lifetime of the instance. `enqueue()` sends a message to the queue, `dequeue()` receives the next message with peek-lock, `markCompleted()` completes the message, and `markFailed()` dead-letters it.
+
+### Graceful Shutdown
+
+`AzureQueue` implements `OnModuleDestroy` and automatically closes all senders, receivers, and the underlying `ServiceBusClient` when the module is destroyed.
+
+---
+
+## Usage in Services
+
+Inject the `IQueue` token and use the same API regardless of the underlying provider:
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common';
+import { IQueue, QUEUE_JOB_STATUS } from '@breadstone/archipel-platform-queue';
+
+@Injectable()
+export class InvoiceService {
+    // #region Fields
+
+    private readonly _queue: IQueue;
+
+    // #endregion
+
+    // #region Ctor
+
+    constructor(@Inject('IQueue') queue: IQueue) {
+        this._queue = queue;
+    }
+
+    // #endregion
+
+    // #region Methods
+
+    public async scheduleInvoice(invoiceId: number): Promise<void> {
+        await this._queue.enqueue('invoices', { invoiceId });
+    }
+
+    public async processNext(): Promise<void> {
+        const job = await this._queue.dequeue<{ invoiceId: number }>('invoices');
+
+        if (!job) {
+            return;
+        }
+
+        try {
+            // ... process the invoice
+            await this._queue.markCompleted(job.id);
+        } catch (error) {
+            await this._queue.markFailed(job.id, (error as Error).message);
+        }
+    }
+
+    // #endregion
+}
+```
+
+---
+
+## Error Handling
+
+All queue implementations throw domain-specific errors that extend `QueueError`:
+
+| Error Class             | When Thrown                                             |
+| ----------------------- | ------------------------------------------------------- |
+| `QueueValidationError`  | Empty or whitespace-only queue name or error message    |
+| `QueueJobNotFoundError` | Job ID does not exist in the underlying store           |
+| `QueueJobStateError`    | Job is in the wrong state for the requested transition  |
+
+Handle these in your service layer or map them centrally via an exception filter:
+
+```typescript
+import { QueueJobNotFoundError, QueueJobStateError } from '@breadstone/archipel-platform-queue';
+
+try {
+    await this._queue.markCompleted(jobId);
+} catch (error) {
+    if (error instanceof QueueJobNotFoundError) {
+        this._logger.warn(`Job ${jobId} not found — may have been evicted.`);
+    } else if (error instanceof QueueJobStateError) {
+        this._logger.warn(`Job ${jobId} is not in processing state.`);
+    } else {
+        throw error;
+    }
+}
+```
+
+---
+
+## Listing Jobs
+
+Use `getJobs()` to retrieve all jobs for a named queue. This is useful for admin dashboards or monitoring:
+
+```typescript
+const jobs = await this._queue.getJobs('invoices');
+
+const pending = jobs.filter((j) => j.status === QUEUE_JOB_STATUS.pending);
+const failed = jobs.filter((j) => j.status === QUEUE_JOB_STATUS.failed);
+
+this._logger.log(`Queue 'invoices': ${pending.length} pending, ${failed.length} failed`);
+```
+
+---
+
+## Switching Providers
+
+Swap the provider by changing the import — no business logic changes needed:
+
+```typescript
+// Before: in-memory
+import { MemoryQueue } from '@breadstone/archipel-platform-queue';
+useFactory: () => new MemoryQueue({ maxJobs: 10_000 }),
+
+// After: Redis
+import { BullMqQueue } from '@breadstone/archipel-platform-queue/bullmq';
+useFactory: () => new BullMqQueue({ redisUrl: 'redis://localhost:6379' }),
+
+// After: Azure Service Bus
+import { AzureQueue } from '@breadstone/archipel-platform-queue/azure';
+useFactory: () => new AzureQueue({ connectionString: 'Endpoint=sb://...' }),
+```
+
+---
+
+## Best Practices
+
+| Practice                                    | Why                                                                   |
+| ------------------------------------------- | --------------------------------------------------------------------- |
+| Use `MemoryQueue` only for dev and tests    | Data is lost on restart; not suitable for production workloads         |
+| Set `maxJobs` for `MemoryQueue`             | Prevents unbounded memory growth in long-running processes            |
+| Always handle `markFailed`                  | Ensures failed jobs are properly tracked and not stuck in processing  |
+| Use typed payloads with generics            | `enqueue<T>()` and `dequeue<T>()` keep your job data type-safe       |
+| Rely on `OnModuleDestroy` for cleanup       | Both `BullMqQueue` and `AzureQueue` close connections automatically   |
+| Keep queue names short and descriptive      | e.g. `invoices`, `emails`, `reports` — avoid deeply nested names      |
+| Wrap queue calls in services                | Never call `IQueue` directly from controllers                         |

package/data/guides/telemetry-and-observability.md

@@ -135,6 +135,26 @@ export class PaymentService {
 
 All log entries automatically include `requestId` for request-level correlation.
 
+### ContextLogger (from platform-logging)
+
+For services that need automatic request context enrichment without manual `requestId` plumbing, use `ContextLogger` from `platform-logging`:
+
+```typescript
+import { ContextLogger } from '@breadstone/archipel-platform-logging';
+
+@Injectable()
+export class OrderService {
+  private readonly _logger = new ContextLogger(OrderService.name);
+
+  public async processOrder(orderId: string): Promise<void> {
+    this._logger.log('Processing order', { orderId });
+    // Automatically includes requestId + userId from RequestContextStore
+  }
+}
+```
+
+Pair with `RequestIdMiddleware` to propagate the `x-request-id` header across the request lifecycle. See the [platform-logging docs](../packages/platform-logging/) for setup details.
+
 ---
 
 ## Automatic Operation Instrumentation