@breadstone/archipel-mcp 0.0.55 → 0.0.57

package/data/guides/ai-image-generation.md

@@ -1,15 +1,15 @@
 ---
 title: AI Image Generation
-description: Generate and edit images through the provider-neutral Archipel media facade.
+description: Generate and edit images through the provider-neutral Archipel image generator.
 order: 16
 ---
 
 # AI Image Generation
 
-Image generation is one operation of `IntelligenceMediaGenerator`. The same
-facade owns speech, transcription, and video so applications have one media
-boundary and one set of model, timeout, cancellation, error, and file
-contracts.
+`IntelligenceImageGenerator` owns image generation and editing. Speech,
+transcription, and video use their own capability-specific generators while
+sharing Archipel's provider resolution, timeout, cancellation, error, and file
+infrastructure.
 
 Applications install only Archipel:
 
@@ -24,28 +24,25 @@ not import `ai`, `@ai-sdk/*`, or provider clients.
 
 ```typescript
 import { Module } from '@nestjs/common';
-import {
-  IntelligenceCapabilityNames,
-  IntelligenceModule,
-  IntelligenceProviderNames,
-} from '@breadstone/archipel-platform-intelligence';
-import { OpenAIIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/openai';
+import { IntelligenceCapabilityNames, IntelligenceModule, IntelligenceProviderNames } from '@breadstone/archipel-platform-intelligence';
+import { OPENAI_CONFIG_ENTRIES, OpenAIIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/provider/openai';
 
 @Module({
-  imports: [
-    IntelligenceModule.register({
-      providerAdapters: [new OpenAIIntelligenceProviderAdapter()],
-      defaultModels: {
-        [IntelligenceCapabilityNames.Image]: {
-          provider: IntelligenceProviderNames.OpenAI,
-          model: 'gpt-image-1.5',
-        },
-      },
-      requestTimeouts: {
-        [IntelligenceCapabilityNames.Image]: 120_000,
-      },
-    }),
-  ],
+    imports: [
+        IntelligenceModule.register({
+            configEntries: OPENAI_CONFIG_ENTRIES,
+            providerAdapters: [OpenAIIntelligenceProviderAdapter],
+            defaultModels: {
+                [IntelligenceCapabilityNames.Image]: {
+                    provider: IntelligenceProviderNames.OpenAI,
+                    model: 'gpt-image-1.5',
+                },
+            },
+            requestTimeouts: {
+                [IntelligenceCapabilityNames.Image]: 120_000,
+            },
+        }),
+    ],
 })
 export class ApplicationModule {}
 ```
@@ -54,35 +51,39 @@ export class ApplicationModule {}
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { IntelligenceMediaGenerator } from '@breadstone/archipel-platform-intelligence';
+import { IntelligenceImageGenerator } from '@breadstone/archipel-platform-intelligence';
 
 @Injectable()
 export class ProductPosterService {
-  public constructor(private readonly _media: IntelligenceMediaGenerator) {}
-
-  public generate() {
-    return this._media.generateImage({
-      prompt: 'A clean editorial product photograph without text or logos.',
-      count: 3,
-      size: '1536x1024',
-      maxRetries: 2,
-    });
-  }
-
-  public edit(referenceImage: Uint8Array, mask: Uint8Array) {
-    return this._media.generateImage({
-      prompt: {
-        images: [referenceImage],
-        mask,
-        text: 'Replace the background with a neutral studio wall.',
-      },
-    });
-  }
+    public constructor(private readonly _images: IntelligenceImageGenerator) {}
+
+    public generate() {
+        return this._images.generate({
+            prompt: 'A clean editorial product photograph without text or logos.',
+            count: 3,
+            size: '1536x1024',
+            maxRetries: 2,
+        });
+    }
+
+    public edit(referenceImage: Uint8Array, mask: Uint8Array) {
+        return this._images.generate({
+            prompt: {
+                images: [referenceImage],
+                mask,
+                text: 'Replace the background with a neutral studio wall.',
+            },
+        });
+    }
 }
 ```
 
 The result contains normalized generated files, provider, model, warnings, and
-usage. Generated bytes are not persisted by Archipel.
+usage. The usage contract distinguishes text input, image input, and generated
+image output tokens when the provider reports enough detail. For a text-only
+prompt, an otherwise undifferentiated input total is safely classified as text;
+for an edit request, missing modality details remain `null` rather than being
+invented. Generated bytes are not persisted by Archipel.
 
 ## Safety Boundary
 
@@ -90,6 +91,10 @@ Before calling the facade, the application must complete authentication,
 authorization, tenant ownership, AI enablement, entitlement, quota, and rate
 limit checks. It owns usage charging and persistence after success.
 
+The application must price usage by the resolved provider and model. Archipel
+does not convert token counters into money or product credits, and a missing
+counter must not be treated as zero-cost usage.
+
 Provider failures become `IntelligenceProviderError`. Invalid provider,
 capability, model, or timeout configuration fails before a remote generation
 call. The 120-second default is a total-operation bound and can be overridden

package/data/guides/ai-realtime-voice.md

@@ -10,8 +10,7 @@ order: 17
 audio/text sessions. Provider credentials and upstream sockets remain in the
 backend.
 
-Realtime is separate from
-`IntelligenceMediaGenerator.streamTranscription()`:
+Realtime is separate from `IntelligenceTranscriptionGenerator.stream()`:
 
 - streaming transcription accepts raw audio and emits transcript updates;
 - realtime is a bidirectional conversational session with input/output audio,
@@ -22,32 +21,33 @@ Realtime is separate from
 ```typescript
 import { Module } from '@nestjs/common';
 import { IntelligenceModule } from '@breadstone/archipel-platform-intelligence';
-import { GatewayIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/gateway';
-import { GoogleIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/google';
-import { GrokIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/grok';
-import { OpenAIIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/openai';
+import { AI_GATEWAY_CONFIG_ENTRIES, GatewayIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/provider/gateway';
+import { GOOGLE_CONFIG_ENTRIES, GoogleIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/provider/google';
+import { GROK_CONFIG_ENTRIES, GrokIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/provider/grok';
+import { OPENAI_CONFIG_ENTRIES, OpenAIIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/provider/openai';
 
 @Module({
-  imports: [
-    IntelligenceModule.register({
-      providerAdapters: [
-        new OpenAIIntelligenceProviderAdapter(),
-        new GoogleIntelligenceProviderAdapter(),
-        new GrokIntelligenceProviderAdapter(),
-        new GatewayIntelligenceProviderAdapter(),
-      ],
-      realtime: {
-        connectionTimeoutMs: 5_000,
-        idleTimeoutMs: 120_000,
-        absoluteSessionTimeoutMs: 1_800_000,
-        maxActiveSessions: 100,
-        maxBufferedAmountBytes: 1_048_576,
-        maxMessageBytes: 1_048_576,
-        meteringIntervalMs: 30_000,
-        meteringAdapter: ApplicationRealtimeMeteringAdapter,
-      },
-    }),
-  ],
+    imports: [
+        IntelligenceModule.register({
+            configEntries: [...OPENAI_CONFIG_ENTRIES, ...GOOGLE_CONFIG_ENTRIES, ...GROK_CONFIG_ENTRIES, ...AI_GATEWAY_CONFIG_ENTRIES],
+            providerAdapters: [
+                OpenAIIntelligenceProviderAdapter,
+                GoogleIntelligenceProviderAdapter,
+                GrokIntelligenceProviderAdapter,
+                GatewayIntelligenceProviderAdapter,
+            ],
+            realtime: {
+                connectionTimeoutMs: 5_000,
+                idleTimeoutMs: 120_000,
+                absoluteSessionTimeoutMs: 1_800_000,
+                maxActiveSessions: 100,
+                maxBufferedAmountBytes: 1_048_576,
+                maxMessageBytes: 1_048_576,
+                meteringIntervalMs: 30_000,
+                meteringAdapter: ApplicationRealtimeMeteringAdapter,
+            },
+        }),
+    ],
 })
 export class ApplicationModule {}
 ```
@@ -59,25 +59,25 @@ or import provider SDKs.
 
 ```typescript
 const session = await sessions.createSession({
-  sessionId: applicationSessionId,
-  provider: 'openai',
-  model: 'gpt-realtime',
-  metadata: {
-    tenantId,
-    userId,
-  },
-  activeToolNames: ['customer_search'],
-  sessionConfiguration: {
-    instructions: 'Help with the authenticated tenant context only.',
-    modalities: ['text', 'audio'],
-  },
-  onEvent: (event) => forwardToApplicationSocket(event),
+    sessionId: applicationSessionId,
+    provider: 'openai',
+    model: 'gpt-realtime',
+    metadata: {
+        tenantId,
+        userId,
+    },
+    activeToolNames: ['customer_search'],
+    sessionConfiguration: {
+        instructions: 'Help with the authenticated tenant context only.',
+        modalities: ['text', 'audio'],
+    },
+    onEvent: (event) => forwardToApplicationSocket(event),
 });
 
 await session.connect();
 await session.send({
-  type: 'input_audio_buffer.append',
-  audio: base64AudioChunk,
+    type: 'input_audio_buffer.append',
+    audio: base64AudioChunk,
 });
 ```
 
@@ -96,6 +96,13 @@ idempotently. Session-start, interval, provider-usage, and session-end events
 carry stable event IDs for deduplication. Business-critical charging should be
 transactional with the application usage ledger.
 
+Provider-usage events expose the common `IIntelligenceUsage` dimensions for
+text, image, audio, cache reads/writes, reasoning, input, and output. Missing
+provider dimensions remain `null`; raw provider usage is retained only as
+diagnostic event data. The application owns provider/model pricing and billing
+units so lifecycle intervals and token-based provider cost cannot accidentally
+charge the same product entitlement twice.
+
 ## Runtime Guarantees
 
 The factory enforces:

package/data/guides/ai-text-generation.md

@@ -20,29 +20,23 @@ yarn add @breadstone/archipel-platform-intelligence
 
 ```typescript
 import { Module } from '@nestjs/common';
-import {
-  IntelligenceCapabilityNames,
-  IntelligenceModule,
-  IntelligenceProviderNames,
-} from '@breadstone/archipel-platform-intelligence';
-import { AnthropicIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/anthropic';
-import { OpenAIIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/openai';
+import { IntelligenceCapabilityNames, IntelligenceModule, IntelligenceProviderNames } from '@breadstone/archipel-platform-intelligence';
+import { ANTHROPIC_CONFIG_ENTRIES, AnthropicIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/provider/anthropic';
+import { OPENAI_CONFIG_ENTRIES, OpenAIIntelligenceProviderAdapter } from '@breadstone/archipel-platform-intelligence/provider/openai';
 
 @Module({
-  imports: [
-    IntelligenceModule.register({
-      providerAdapters: [
-        new OpenAIIntelligenceProviderAdapter(),
-        new AnthropicIntelligenceProviderAdapter(),
-      ],
-      defaultModels: {
-        [IntelligenceCapabilityNames.Language]: {
-          provider: IntelligenceProviderNames.OpenAI,
-          model: 'gpt-5.4-mini',
-        },
-      },
-    }),
-  ],
+    imports: [
+        IntelligenceModule.register({
+            configEntries: [...OPENAI_CONFIG_ENTRIES, ...ANTHROPIC_CONFIG_ENTRIES],
+            providerAdapters: [OpenAIIntelligenceProviderAdapter, AnthropicIntelligenceProviderAdapter],
+            defaultModels: {
+                [IntelligenceCapabilityNames.Language]: {
+                    provider: IntelligenceProviderNames.OpenAI,
+                    model: 'gpt-5.4-mini',
+                },
+            },
+        }),
+    ],
 })
 export class ApplicationModule {}
 ```
@@ -51,22 +45,22 @@ export class ApplicationModule {}
 
 ```typescript
 const completion = await language.generateText(
-  {
-    system: 'Answer using the supplied application context only.',
-    prompt: 'Summarize the open tasks.',
-  },
-  {
-    maxOutputTokens: 800,
-    maxRetries: 2,
-  },
+    {
+        system: 'Answer using the supplied application context only.',
+        prompt: 'Summarize the open tasks.',
+    },
+    {
+        maxOutputTokens: 800,
+        maxRetries: 2,
+    },
 );
 
 const structured = await language.generateObject(
-  { prompt: 'Classify the customer request.' },
-  z.object({
-    category: z.enum(['billing', 'technical', 'other']),
-    urgency: z.enum(['low', 'normal', 'high']),
-  }),
+    { prompt: 'Classify the customer request.' },
+    z.object({
+        category: z.enum(['billing', 'technical', 'other']),
+        urgency: z.enum(['low', 'normal', 'high']),
+    }),
 );
 ```
 
@@ -80,7 +74,7 @@ model.
 const stream = await language.streamText({ prompt: 'Explain the result.' });
 
 for await (const delta of stream.textStream) {
-  sendToAuthenticatedClient(delta);
+    sendToAuthenticatedClient(delta);
 }
 
 const finalText = await stream.text;
@@ -94,26 +88,23 @@ All stream iterables and result promises normalize provider failures as
 ## Application Tools
 
 ```typescript
-export class CustomerSearchTool extends IntelligenceToolBase<
-  ICustomerSearchInput,
-  ReadonlyArray<ICustomerSummary>
-> {
-  public override get name(): string {
-    return 'customer_search';
-  }
-
-  public override get tool() {
-    return defineIntelligenceTool({
-      description: 'Searches customers visible to the authenticated tenant.',
-      inputSchema: createIntelligenceJsonSchema<ICustomerSearchInput>({
-        type: 'object',
-        properties: { query: { type: 'string' } },
-        required: ['query'],
-        additionalProperties: false,
-      }),
-      execute: async ({ query }) => this._customers.search(query),
-    });
-  }
+export class CustomerSearchTool extends IntelligenceToolBase<ICustomerSearchInput, ReadonlyArray<ICustomerSummary>> {
+    public override get name(): string {
+        return 'customer_search';
+    }
+
+    public override get tool() {
+        return defineIntelligenceTool({
+            description: 'Searches customers visible to the authenticated tenant.',
+            inputSchema: createIntelligenceJsonSchema<ICustomerSearchInput>({
+                type: 'object',
+                properties: { query: { type: 'string' } },
+                required: ['query'],
+                additionalProperties: false,
+            }),
+            execute: async ({ query }) => this._customers.search(query),
+        });
+    }
 }
 ```
 
@@ -133,10 +124,10 @@ language facade:
 
 ```typescript
 const agent = agents.create({
-  name: 'researcher',
-  instructions: 'Use approved sources and report uncertainty.',
-  activeToolNames: ['web_search', 'document_search'],
-  maxSteps: 6,
+    name: 'researcher',
+    instructions: 'Use approved sources and report uncertainty.',
+    activeToolNames: ['web_search', 'document_search'],
+    maxSteps: 6,
 });
 
 const answer = await agent.generate({ prompt: question });
@@ -149,7 +140,10 @@ tools, model policy, and step limits already owned by Archipel.
 
 Language completions expose provider, model, text, typed output, finish reason,
 reasoning text, normalized sources and files, tool calls/results, warnings, and
-usage. The default total-operation timeout is 30 seconds.
+usage. Usage contains provider-neutral input, output, total, cache-read,
+cache-write, reasoning, and available modality counters. A `null` counter means
+the provider did not report it and must not be interpreted as measured zero.
+The default total-operation timeout is 30 seconds.
 
 Provider failures use `IntelligenceProviderError`; invalid prompts and options
 use `IntelligenceValidationError`; missing adapters or capability defaults use

package/data/guides/health-indicators.md

@@ -51,11 +51,11 @@ Every health indicator implements this contract:
 
 ```typescript
 interface IHealthIndicator {
-  /** Unique key identifying this indicator in the health response. */
-  readonly key: string;
+    /** 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>;
+    /** Run the health check and return a Terminus HealthIndicatorResult. */
+    check(): HealthIndicatorResult | Promise<HealthIndicatorResult>;
 }
 ```
 
@@ -63,37 +63,40 @@ interface IHealthIndicator {
 
 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` | Resolves text configuration and reports registered realtime providers plus active session 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 |
+| 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`   | Runs a bounded provider probe and reports capability plus realtime state                |
+| `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)
+- `IntelligenceHealthIndicator` — probes the default language provider with an independent three-second timeout
 - `AnalyticsHealthIndicator` — calls `AnalyticsClientPort.ping()` (adapters can override for SDK readiness checks)
 
 **State checks** — inspect in-memory state (zero-cost, no I/O):
-- `IntelligenceHealthIndicator` — resolves configured provider/model data and reports process-local realtime provider and session state
+
 - `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
@@ -111,15 +114,10 @@ import { PaymentHealthIndicator } from '@breadstone/archipel-platform-payments/h
 import { CachingHealthIndicator } from '@breadstone/archipel-platform-caching/health';
 
 @Module({
-  imports: [
-    // ... your feature modules
-    HealthModule.withIndicators([
-      DatabaseHealthIndicator,
-      MailHealthIndicator,
-      PaymentHealthIndicator,
-      CachingHealthIndicator,
-    ]),
-  ],
+    imports: [
+        // ... your feature modules
+        HealthModule.withIndicators([DatabaseHealthIndicator, MailHealthIndicator, PaymentHealthIndicator, CachingHealthIndicator]),
+    ],
 })
 export class AppModule {}
 ```
@@ -134,12 +132,12 @@ import { HealthOrchestrator } from '@breadstone/archipel-platform-health';
 
 @Controller('health')
 export class HealthController {
-  constructor(private readonly _health: HealthOrchestrator) {}
+    constructor(private readonly _health: HealthOrchestrator) {}
 
-  @Get()
-  public async check() {
-    return this._health.check();
-  }
+    @Get()
+    public async check() {
+        return this._health.check();
+    }
 }
 ```
 
@@ -147,25 +145,27 @@ export class HealthController {
 
 ```json
 {
-  "status": "ok",
-  "details": {
-    "database": { "status": "up" },
-    "mail": { "status": "up" },
-    "payment": { "status": "up" },
-    "caching": { "status": "up" },
-    "intelligence": {
-      "status": "up",
-      "provider": "openai",
-      "model": "gpt-4o-mini",
-      "realtime": {
-        "enabled": true,
-        "providers": ["openai", "google"],
-        "activeSessions": 2
-      }
-    },
-    "mcp": { "status": "up", "tools": 5, "resources": 2, "prompts": 1 },
-    "telemetry": { "status": "up", "sdkInitialized": true }
-  }
+    "status": "ok",
+    "details": {
+        "database": { "status": "up" },
+        "mail": { "status": "up" },
+        "payment": { "status": "up" },
+        "caching": { "status": "up" },
+        "intelligence": {
+            "status": "up",
+            "providerStatus": "operational",
+            "provider": "openai",
+            "model": "gpt-5.4-mini",
+            "failureCode": null,
+            "realtime": {
+                "enabled": true,
+                "providers": ["openai", "google"],
+                "activeSessions": 2
+            }
+        },
+        "mcp": { "status": "up", "tools": 5, "resources": 2, "prompts": 1 },
+        "telemetry": { "status": "up", "sdkInitialized": true }
+    }
 }
 ```
 
@@ -173,15 +173,19 @@ When a provider is not registered (e.g., no `PaymentClientPort` injected), the i
 
 ```json
 {
-  "payment": { "status": "up", "disabled": true }
+    "payment": { "status": "up", "disabled": true }
 }
 ```
 
-When a ping fails, the indicator reports `down` with error details:
+When an intelligence probe fails unexpectedly, the indicator reports a stable
+failure code without leaking provider transport details:
 
 ```json
 {
-  "payment": { "status": "down", "error": "ECONNREFUSED" }
+    "intelligence": {
+        "status": "down",
+        "failureCode": "INTELLIGENCE_HEALTH_CHECK_FAILED"
+    }
 }
 ```
 
@@ -196,21 +200,18 @@ import type { HealthIndicatorResult } from '@nestjs/terminus';
 
 @Injectable()
 export class SearchHealthIndicator implements IHealthIndicator {
-  public readonly key = 'search';
+    public readonly key = 'search';
 
-  public check(): HealthIndicatorResult<'search'> {
-    return { search: { status: 'up' } };
-  }
+    public check(): HealthIndicatorResult<'search'> {
+        return { search: { status: 'up' } };
+    }
 }
 ```
 
 Register it alongside built-in indicators:
 
 ```typescript
-HealthModule.withIndicators([
-  DatabaseHealthIndicator,
-  SearchHealthIndicator,
-]);
+HealthModule.withIndicators([DatabaseHealthIndicator, SearchHealthIndicator]);
 ```
 
 ## Tree-Shaking
@@ -221,9 +222,9 @@ Health indicators are **not** included in the main library entry point. They are
 
 Each health indicator requires these optional peer dependencies:
 
-| Package | Notes |
-| ------- | ----- |
+| Package                                | Notes                                           |
+| -------------------------------------- | ----------------------------------------------- |
 | `@breadstone/archipel-platform-health` | `IHealthIndicator` interface and `HealthModule` |
-| `@nestjs/terminus` | `HealthIndicatorResult` type |
+| `@nestjs/terminus`                     | `HealthIndicatorResult` type                    |
 
 Both are listed as optional peer dependencies in each library's `package.json`.