@x12i/ai-gateway 7.9.1

package/README.md

@@ -0,0 +1,4259 @@
+# @x12i/ai-gateway
+
+Unified gateway for LLM provider routing and management with production-ready features: context propagation, usage tier tracking, activity tracking, and comprehensive metadata. Built on top of `@x12i/ai-providers-router` with integrations for `@x12i/x-models`, `@x12i/activix` **v5.x** (xronox-activitix; this repo pins `^5.0.1` — see `package.json`), and `logs-gateway`.
+
+## Features
+
+- **🔀 Provider Routing**: Dynamic provider registration and automatic routing with fallback support
+- **📊 Context Propagation**: `aiRequestId` and identity propagation for distributed tracing (see [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md))
+- **⚡ Usage Tier Tracking**: RPM/TPM limit enforcement via `@x12i/x-models`
+- **📈 Activity Tracking**: Comprehensive activity logging via `@x12i/activix` v5 (xronox-activitix), fixed Mongo collections `ai-activities` / `bad-requests`, validated `structure` + `runContext` for Activix 5
+- **📝 Structured Logging**: Production-ready logging via `logs-gateway` with comprehensive diagnostic tracing for instruction resolution and propagation debugging
+- **📋 Rich Metadata**: Detailed execution metadata (latency, tokens, model, cost, `aiRequestId`, `identity`)
+- **🏥 Health Checks**: Monitor provider health and availability
+- **🔄 Request/Response Interceptors**: Modify requests and responses
+- **🔍 Auto-Discovery**: Automatically discover and register installed provider packages
+- **🎯 Object Type Output Support**: Parse responses into typed inference outputs (classification, extraction, Q&A, etc.) via `@x12i/outputs-library`
+- **✅ Enhanced Schema Validation**: Strict/non-strict validation modes, automatic schema resolution from instruction metadata, and graceful outputs library fallback (v1.7.0+)
+- **✅ Graceful Outputs Library Error Handling**: Automatic fallback parsing, clear error detection, and parsing method metadata (v1.7.1+)
+- **✅ Guaranteed Consistent Structure**: Always returns consistent structure at all levels (content, parsedContent, parsedOutput) - JSON is always JSON, text is always text, structures are forced when needed (v1.7.4+)
+- **📋 Automatic Output Schema Guidance**: Automatically extends instructions with JSON schema expectations when outputType/schema is available (v2.1.1+)
+- **🔍 Output Structure Audit**: Automatically audits response structure against schema - identifies missing/extra fields, always available when schema exists (v2.1.1+)
+- **🔄 Automatic Retry**: Intelligent retry logic for network errors, server errors (5xx), and throttling (429) with exponential backoff
+- **📚 Content Resolver (nx-content)**: Resolve instruction keys, prompt keys, and instructions blocks from local folder or git repo via **nx-content**. See [Content Resolver — Upstream Guide](./CONTENT_RESOLVER_UPSTREAM_GUIDE.md).
+- **📋 Instruction Metadata API**: Fetch structured metadata (outputType, schema, validation rules) for metadata-driven inference systems (v1.6.9+)
+- **🔧 Response Transformation Hooks**: Transform responses at different stages (preParse, postParse, preValidate, postValidate) for output mapping and data normalization (v1.6.9+)
+- **🔧 Custom/Dynamic Instructions Mode**: Use instructions that already contain full JSON schema - no schema formatting added, instructions used exactly as provided (v3.0.4+)
+- **🤖 Response Repair Fallback**: In `mode=prod`, performs a minimal in-gateway repair attempt for malformed JSON/Markdown responses (logs a warning when used). In `mode=debug`, parsing failures hard-fail for maximum visibility.
+- **📊 Response Fix Metadata**: Track when and how responses were fixed, including fix strategy, confidence, and warnings (v3.0.4+)
+- **🔍 Instruction Optimizer**: Use AI to analyze and fix poorly-written instructions - meta-feature that improves instruction quality (v3.0.4+)
+- **🧪 Instruction Testing**: Test instructions by running them and analyzing if responses match expected format (v3.0.4+)
+- **📝 Multiple Output Modes**: Support for JSON output, structured text output, and two-step conversion (v3.0.5+)
+- **📋 Dual Instruction Formats**: Support for JSON schema instructions and structured text format specifications (v3.0.5+)
+- **📚 Standard Object Types**: Reference standard object types by name (e.g., `'sentiment-analysis'`) instead of defining schemas manually - includes examples, validation, and structured text instructions (v3.0.6+)
+- **🔍 Auto-Extraction of Output Formats**: Automatically extract output format specifications from instruction templates when using structured-text mode - no need to manually specify `flexMdFormat` or `primaryObjectType` (v3.3.3+)
+- **✅ Output Format Validation**: Validates output format specifications using flex-md SDK before sending to LLM, with configurable minimum compliance level (L0-L3)
+- **📋 Contract Output Parsing**: Parse AI responses against expected schemas and store results in activity records for compliance monitoring (v6.3.1+)
+
+## Installation
+
+```bash
+npm install @x12i/ai-gateway
+```
+
+**📚 Documentation**: After installation, documentation is available in:
+- `node_modules/@x12i/ai-gateway/CONTENT_RESOLVER_UPSTREAM_GUIDE.md` - **Content resolver (nx-content)**: config, keys, local/git, upstream checklist
+- `node_modules/@x12i/ai-gateway/docs/IDENTITY_OBJECT_CONTRACT.md` - **Identity contract** for Activix (`sessionId` + `instance`)
+- `node_modules/@x12i/ai-gateway/docs/LOGGER_INITIALIZATION.md` - **Required reading**: How to properly initialize logger
+- `node_modules/@x12i/ai-gateway/TROUBLESHOOTING.md` - Troubleshooting guide
+- `node_modules/@x12i/ai-gateway/TROUBLESHOOTING_TOOLBOX.md` - Diagnostic tools
+- `node_modules/@x12i/ai-gateway/INTEGRATION_GUIDANCE.md` - Integration guidance
+
+**🔧 Troubleshooting Helpers**: Import diagnostic functions directly:
+```typescript
+import { validateAIRequest, diagnoseRequest, formatDiagnostic } from '@x12i/ai-gateway';
+```
+
+**🔍 Debugging**: Enable detailed request logging and comprehensive diagnostic tracing:
+
+```bash
+export AI_GATEWAY_DEBUG=true           # Basic request logging
+export AI_GATEWAY_DEBUG_REQUEST=true   # Detailed request structure
+export FLEX_MD_MIN_COMPLIANCE_LEVEL=L0 # Output format validation level (L0/L1/L2/L3, default: L0)
+```
+
+This logs the exact request structure received by `invoke()`, including property descriptors, which is critical for debugging validation errors like "objectTypes is required".
+
+### 🔍 Advanced Diagnostic Logging
+
+The gateway includes comprehensive diagnostic logging for instruction resolution and propagation debugging. When debug logging is enabled, the following diagnostic events are logged:
+
+**Phase 2 Instruction Resolution:**
+- `instructions.phase2.validation_inputs` - Logs comparison inputs for key echo validation
+- `instructions.phase2.resolution_result` - Logs resolution status, source, and attempts
+
+**Instruction Propagation Chain:**
+- `instructions.propagation.autoExtract.entry` - Instruction hash at auto-extraction
+- `instructions.propagation.constructMessages.entry` - Instruction hash at message construction
+- `instructions.propagation.providerInvoke.entry` - System prompt hash at LLM invocation
+
+**Resolution Detection:**
+- `instructions.constructMessages.entry` - Detects if constructMessages receives resolved instructions
+
+**Gate Checks:**
+- `gate.activityStart.precheck` - Validates instructions before activity tracking
+- `gate.llmInvoke.precheck` - Validates instructions before LLM calls
+
+**Error Handling:**
+- `badRequest.written` - Confirms bad request path execution
+
+**Benefits:**
+- **Trace ID**: Each request gets a stable trace ID for correlation across all logs
+- **Hash Chain**: Track instruction content changes through the entire pipeline
+- **Fail-Safe Gating**: Verify that invalid instructions are properly rejected
+- **Resolution Audit**: Detect double-resolution or propagation failures
+
+All diagnostic logs include `traceId`, `jobId`, and `agentId` for correlation. Content is safely redacted (first 80 chars only) with hashes for comparison.
+
+## Quick Start
+
+### Basic Usage with Enhanced Gateway
+
+```typescript
+import { AIGateway } from '@x12i/ai-gateway';
+import { OpenAIProvider } from '@x12i/ai-provider-openai';
+import { GrokProvider } from '@x12i/ai-provider-grok';
+
+// Create enhanced gateway
+const gateway = new AIGateway({
+  defaultProvider: 'openai',
+  fallbackChain: ['grok'],
+  usageTier: 'tier-3',  // RPM/TPM limits
+  enableActivityTracking: true,
+  enableUsageTracking: true,
+  enableLogging: true
+});
+
+// Register providers
+gateway.register(new OpenAIProvider({ 
+  apiKey: process.env.OPENAI_API_KEY 
+}));
+gateway.register(new GrokProvider({
+  apiKey: process.env.GROK_API_KEY
+}));
+
+// Invoke with context
+const response = await gateway.invoke({
+  messages: [{ role: 'user', content: 'Hello!' }],
+  jobId: 'job-123',  // Context propagation
+  agentId: 'agent-456',
+  taskId: 'task-789'
+});
+
+// Response includes comprehensive metadata
+console.log(response.metadata);
+// {
+//   jobId: 'job-123',
+//   latencyMs: 1250,
+//   tokens: { prompt: 100, completion: 50, total: 150 },
+//   model: 'gpt-4o',
+//   provider: 'openai',
+//   cost: 0.002
+// }
+```
+
+### Using Base Router (Direct Access)
+
+```typescript
+import { LLMProviderRouter } from '@x12i/ai-gateway';
+
+// Use base router if you don't need enhanced features
+const router = new LLMProviderRouter({
+  defaultProvider: 'openai',
+  fallbackChain: ['grok']
+});
+
+router.register(new OpenAIProvider({ 
+  apiKey: process.env.OPENAI_API_KEY 
+}));
+
+const response = await router.invoke({
+  messages: [{ role: 'user', content: 'Hello!' }]
+});
+```
+
+### Provider registration and OpenRouter (no manual register required)
+
+If you only use the gateway (e.g. via `@woroces/ai-tasks`) and do not call `gateway.register()` or configure the router yourself:
+
+- **OpenRouter:** Set `OPEN_ROUTER_KEY` or `OPENROUTER_API_KEY` in the environment and do not set `USE_OPENROUTER=false`. The gateway enables OpenRouter mode so the router can route without any registered provider (requires router support). Load `.env` before any code that creates the gateway; if the gateway is created by another package (e.g. ai-skills) before env is loaded, pass the key explicitly: `openrouter: { apiKey: process.env.OPEN_ROUTER_KEY ?? process.env.OPENROUTER_API_KEY }` in the gateway config.
+- **Direct providers:** Set the relevant API key (e.g. `OPENAI_API_KEY`, `GROK_API_KEY`). The gateway **lazy-auto-registers** these on first `invoke()`/`invokeChat()`, so you do not need to call `autoRegisterProviders` or `register()`.
+
+If you see **"No provider specified and no providers registered"** or **"Provider not registered: openrouter"**, set `OPEN_ROUTER_KEY` (or another provider’s API key), ensure `.env` is loaded before the process that creates the gateway, or pass `openrouter: { apiKey }` in the gateway config. See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md#issue-no-provider-specified-and-no-providers-registered) for details.
+
+## Setup Guide
+
+This guide shows where and how to configure each functionality of the AI Gateway.
+
+### Configuration Overview
+
+The AI Gateway can be configured in multiple ways:
+1. **Gateway Constructor** - Main configuration when creating the gateway
+2. **JSON Default Files** - Default configurations loaded from `src/defaults/` (model-config.json, instructions-blocks.json)
+3. **Environment Variables** - Via `nx-config2` (for logging and other settings)
+   - `FLEX_MD_MIN_COMPLIANCE_LEVEL` - Minimum flex-md compliance level for output format validation (default: `L0`). Valid values: `L0`, `L1`, `L2`, `L3`. See [Output Format Validation](#output-format-validation) section for details. When set to `L0` (default), no format validation is required. When set to `L1` or higher, format specifications are required in instructions and validation errors will reject requests.
+4. **Request-Level** - Override gateway defaults per request
+
+### 1. Logging Configuration (logs-gateway)
+
+**Logger Initialization: Two Options**
+
+The gateway supports two ways to initialize the logger:
+
+1. **Option 1 (Recommended)**: Provide your project's logger instance - ensures consistent logging
+2. **Option 2 (Fallback)**: Let the gateway create a default logger - works out of the box
+
+**📚 See [Logger Initialization Guide](./docs/LOGGER_INITIALIZATION.md) for complete instructions.**
+
+**Where to configure:**
+- Gateway constructor: `enableLogging`, `packageName`, `logger` (**logger is REQUIRED**)
+- Environment variables: **`{PREFIX}_LOGS_LEVEL`** (canonical per-package level; see below), legacy `{PREFIX}_LOG_LEVEL`, plus `{PREFIX}_LOG_FORMAT`, etc. Cross-cutting sink/format options are configured by the host app; see [logs-gateway](https://www.npmjs.com/package/logs-gateway) README and [`docs/package-usage.md`](https://github.com/nx-intelligence/logs-gateway/blob/main/docs/package-usage.md).
+
+**How to configure:**
+
+```typescript
+import { AIGateway } from '@x12i/ai-gateway';
+import { createLogger } from 'logs-gateway';
+
+// Create logger once at application startup
+const logger = createLogger(
+  { packageName: 'MY_APP', envPrefix: 'MY_APP' },
+  {
+    logLevel: 'info',           // verbose|debug|info|warn|error
+    logFormat: 'json',          // text|json|yaml
+    logToFile: true,
+    logFilePath: '/var/log/app.log',
+    enableUnifiedLogger: true,
+    unifiedLogger: {
+      transports: { papertrail: true },
+      service: 'my-app',
+      env: 'production'
+    }
+  }
+);
+
+// Pass the SAME logger instance to gateway (REQUIRED)
+const gateway = new AIGateway({
+  enableLogging: true,
+  logger: logger,  // REQUIRED: Use your project's logger instance
+  packageName: 'MY_APP'
+});
+```
+
+**Why Use the Same Logger?**
+- Consistent log format across your application
+- Unified logging destination
+- Proper context and metadata
+- Single point of control for log levels
+
+**Per-package log level (logs-gateway ≥ 3.5.x):**
+
+- **Canonical:** `{PREFIX}_LOGS_LEVEL` — use the same `envPrefix` you pass to `createLogger` / your `packageName` (e.g. `MY_APP` → `MY_APP_LOGS_LEVEL`).
+- **Legacy:** `{PREFIX}_LOG_LEVEL` is used only if `{PREFIX}_LOGS_LEVEL` is **not** set.
+- **Default** when both are unset: **`warn`** (not `info`, not silent).
+- **Silence** this package’s diagnostics: `off`, `none`, or `silent` (case-insensitive).
+- **Values:** `off` \| `none` \| `silent` \| `error` \| `warn` \| `info` \| `debug` \| `verbose`.
+
+If the gateway builds the default logger and you omit `packageName`, the prefix is **`AI_GATEWAY`** → e.g. **`AI_GATEWAY_LOGS_LEVEL`**.
+
+**Environment Variables (examples):**
+```bash
+MY_APP_LOGS_LEVEL=info             # raise verbosity (or use debug / verbose)
+MY_APP_LOGS_LEVEL=off              # silence this package’s logs
+# MY_APP_LOG_LEVEL=info            # legacy; ignored if MY_APP_LOGS_LEVEL is set
+
+MY_APP_LOG_FORMAT=json             # text|json|yaml
+MY_APP_LOG_TO_FILE=true
+MY_APP_LOG_FILE=/var/log/app.log
+MY_APP_LOG_TO_UNIFIED=true
+DEBUG=my-app                       # elevates verbose/debug when package is not fully silent
+```
+
+**🔍 Diagnostic Logging:** When debug level is enabled, the gateway provides comprehensive diagnostic logs for instruction resolution and propagation. See the debugging section above for details on the diagnostic events logged.
+
+**What Happens If Logger is Not Provided:**
+If `logger` is not provided, the gateway will automatically create a default logger. However, for best results (consistent format, unified destination), it's recommended to provide your project's logger instance.
+
+### 2. Activity Tracking Configuration (xronox-activitix via @x12i/activix v5)
+
+**Activix version:** This gateway targets **`@x12i/activix` v5.x** (built on `@xronoces/xronox-store`). The dependency range is declared in `package.json` (currently `^5.0.1`).
+
+**Where to configure:**
+- Gateway constructor: `enableActivityTracking`, `activityTracker`
+- **Environment variables** (auto-configured when no custom tracker provided):
+  - `MONGO_URI` (required) - MongoDB connection string
+  - `MONGO_LOGS_DB` or `MONGO_DB` (required) - Database name
+
+**✅ Centralized configuration**
+
+The gateway resolves activity tracking from environment variables via `src/config/activity-tracking-config.ts`. **Main and bad-request collection names are fixed at the package level** (not overridden by env): **`ai-activities`** for normal runs and **`bad-requests`** for failed/invalid requests. **`skill-executions`** is used for skill-related flows when applicable.
+
+**Environment variable priority (connection only):**
+- **Database**: `MONGO_LOGS_DB` → `MONGO_DB` (no default, must be provided)
+- **URI**: `MONGO_URI` (required)
+
+**⚠️ CRITICAL: correlation and identity**
+
+- **`aiRequestId`** (required on each gateway request): Primary correlation id for this LLM call; the gateway does **not** invent a `jobId` for you.
+- **Run context** (Activix BSON field `runContext`): `sessionId` plus nested `instance: { instanceId, type }`, plus gateway correlation fields; see [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md) (request still uses `identity`; persisted row uses `runContext`).
+- **`jobTypeId`**, **`taskId`**, **`taskTypeId`**: Optional aggregation / grouping fields (unchanged semantics).
+- **Each activity**: Gets its own **unique database record** with unique `_id` (MongoDB ObjectId).
+- **Two-phase tracking**: `startActivity()` creates a new record; `logSuccess()` / `logFailure()` update the same record by that record’s id.
+
+**Runtime objects observability (debug only):**
+
+`@x12i/ai-gateway` exports `runtimeObjects` for runtime diagnostics. This package is a leaf runtime package, so `runtimeObjects?.packagesRuntimeObjects` is always `[]`.
+
+Runtime objects are available only in debug mode:
+
+```env
+mode=debug
+```
+
+`debug` is the default when `mode` is omitted. In production, use:
+
+```env
+mode=prod
+```
+
+When `mode=prod`, `runtimeObjects` is `undefined`.
+
+```typescript
+import { runtimeObjects } from '@x12i/ai-gateway';
+
+const activities = await runtimeObjects?.activixClient?.getJobActivities({ jobId });
+const logs = await runtimeObjects?.logxerClient?.getJobLogs({ jobId });
+```
+
+The gateway only exposes official queryable clients. It exposes `activixClient` only when the effective Activix client already implements `getJobActivities()`, and `logxerClient` only when the effective Logxer client already implements `getJobLogs()`. The gateway does not query Mongo, Logxer storage, or private package internals to emulate missing query APIs.
+
+See [Runtime Objects Observability Methodology](./docs/RUNTIME_OBJECTS_OBSERVABILITY.md) for the reusable package-level contract.
+
+**Recommended (auto-configured from environment variables):**
+
+```typescript
+import { AIGateway } from '@x12i/ai-gateway';
+import { OpenAIProvider } from '@x12i/ai-provider-openai';
+
+// Set environment variables:
+// MONGO_URI=mongodb://localhost:27017
+// MONGO_LOGS_DB=logs-db
+
+const gateway = new AIGateway({
+  enableActivityTracking: true,  // default: true
+  // Activix is auto-configured; writes use collections ai-activities / bad-requests / skill-executions
+});
+
+gateway.register(new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY
+}));
+```
+
+**Advanced (custom Activix v5 instance):**
+
+If you pass your own `Activix`, configure **the same collection names** the gateway expects so routing matches persistence:
+
+```typescript
+import { AIGateway } from '@x12i/ai-gateway';
+import { Activix } from '@x12i/activix';
+
+const statusValues = {
+  started: 'started',
+  inProgress: 'in_progress',
+  completed: 'success',
+  failed: 'failed',
+  timeout: 'timeout'
+};
+
+const activityTracker = new Activix({
+  collections: [
+    { name: 'ai-activities', statusValues },
+    { name: 'skill-executions', statusValues },
+    { name: 'bad-requests', statusValues }
+  ]
+});
+
+const gateway = new AIGateway({
+  enableActivityTracking: true,          // default: true
+  activityTracker,                       // plug in custom tracker
+});
+```
+
+**What gets tracked (persisted when DB is configured):**
+- **Identity**: `sessionId`, `instance`, **`aiRequestId`** (correlation), optional deprecated `jobId` for compatibility, plus `jobTypeId`, `agentId`, `taskId`, `taskTypeId` as provided
+- **Timing**: `startTime`, `endTime`, `duration`, `status` (`started|success|failed`)
+- **Request data**: Stored in `request` object (instructions, prompt, input, messages, workingMemory)
+- **Config data**: Stored in `config` object (model, provider, temperature, maxTokens)
+- **Response data**: Stored in `response` object (content, metadata)
+- **Cost**: Calculated and stored per activity
+
+**Best Practices for Type IDs:**
+- **`jobTypeId`**: Use MD5 hash of your job type string (e.g., `MD5('data-processing-job')`) for consistent job-level aggregation
+- **`taskTypeId`**: Use MD5 hash of your task/instruction text (e.g., `MD5('What is the capital of France?')`) for consistent task-level aggregation
+- If `taskTypeId` is not provided, it's auto-generated from the pre-parsed instructions MD5 hash
+- Same type = same hash = easy aggregation and tracking across multiple jobs/tasks
+
+**Key design points:**
+- ✅ Each activity = separate database record with unique `_id`
+- ✅ **`aiRequestId`** = per-request correlation (required); optional `jobId` only if you supply it for grouping
+- ✅ Request data sent once in `startActivity()` (creates new record)
+- ✅ Response data sent once in `logSuccess()` (updates same record by `_id`)
+
+**Default:** Activity tracking is enabled by default; without DB config it will log but not persist.
+
+**✅ Activix v5 integration**
+
+1. **Configuration** (`activity-tracking-config.ts`):
+   - Mongo connection from env; **collection names** `ai-activities` and `bad-requests` are fixed for consistency across deployments.
+
+2. **Lifecycle** (`@x12i/activix` v5):
+   - ✅ `startRecord` / `completeRecord` / `failRecord` (two-phase lifecycle)
+   - ✅ Status transitions: `started` → `success` or `failed` (per your `statusValues` mapping)
+   - ✅ Persistence via xronox-store queue semantics (see Activix package docs)
+
+3. **Testing** (ai-gateway):
+   - Standalone test available (`npm run test:activities:standalone`) that bypasses config parsing issues
+   - Tests activity lifecycle end-to-end: creation → completion → database persistence
+   - See `.tests/TESTING_GUIDE.md` for complete testing documentation
+
+**See**: `.reports/new/ACTIVITY_LIFECYCLE_IMPROVEMENTS_VERIFICATION_REPORT.md` for complete verification details.
+
+#### Skill Execution Tracking
+
+When executing skills (instruction keys starting with `skills/`), the gateway automatically tracks skill executions separately from gateway invocations. Skill executions are stored in the `skill-executions` collection and support parent-child relationships.
+
+**Required Fields:**
+- `instructions`: Skill instruction key (e.g., `skills/professional-answer`)
+- `inferenceType`: Recommended - type of inference (e.g., `question-answer`, `classification`)
+
+**Optional Fields:**
+- `masterSkillActivityId`: Parent skill activity ID (when a skill calls another skill)
+- `skillId`: Skill identifier (auto-detected from instruction key, can be overridden)
+- `masterSkillId`: Parent skill identifier (when a skill calls another skill)
+
+**Example: Basic Skill Execution**
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'my-agent',
+  instructions: 'skills/professional-answer',
+  inferenceType: 'question-answer', // Recommended
+  skillId: 'skills/professional-answer', // Optional, auto-detected from instructions
+  input: { question: 'What is...' },
+  primaryObjectType: 'professional-answer'
+});
+
+// Get the activity ID for linking child skills
+const activityId = response.metadata?.activityId;
+```
+
+**Example: Nested Skill Execution (Skill Calling Another Skill)**
+
+```typescript
+// Parent skill execution
+const parentResponse = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'my-agent',
+  instructions: 'skills/parent-skill',
+  inferenceType: 'analysis',
+  skillId: 'skills/parent-skill'
+});
+
+// When parent skill calls child skill, pass parent's activityId and skillId
+const childResponse = await gateway.invoke({
+  jobId: 'job-123', // ✅ Same jobId (links activities)
+  agentId: 'my-agent',
+  instructions: 'skills/child-skill',
+  inferenceType: 'question-answer',
+  skillId: 'skills/child-skill',
+  masterSkillActivityId: parentResponse.metadata?.activityId, // ✅ Parent's activity ID
+  masterSkillId: 'skills/parent-skill' // ✅ Parent's skill ID
+});
+```
+
+**Automatic Tracking:**
+
+The gateway automatically:
+- Detects skill executions from instruction keys starting with `skills/`
+- Connects to instruction metadata (key, version) from content resolution
+- Routes to `skill-executions` collection (ActivityManager + Activix handle routing)
+- Returns `activityId` in response metadata for linking child skills
+- Supports parent-child skill relationships via `masterSkillActivityId` and `masterSkillId`
+
+**For detailed integration guides, see:**
+- [Skill Execution Client Integration Guide](./docs/SKILL_EXECUTION_CLIENT_INTEGRATION.md)
+- [AI Gateway Integration Guide: Skill Requests](./docs/AI_GATEWAY_INTEGRATION_SKILL_REQUESTS.md)
+- [Extending AI Activities with Skill Fields](./docs/EXTENDING_AI_ACTIVITIES_WITH_SKILL_FIELDS.md)
+
+### 3. Usage Tracking Configuration (x-models)
+
+**Where to configure:**
+- Gateway constructor: `enableUsageTracking`, `usageTier`
+- JSON defaults: `src/defaults/model-config.json` (not used for usage tracking)
+
+**How to configure:**
+
+```typescript
+const gateway = new AIGateway({
+  enableUsageTracking: true,  // Default: true
+  usageTier: 'tier-3'         // RPM/TPM limits: 'tier-1' | 'tier-2' | 'tier-3'
+});
+```
+
+**Note:** If `@x12i/x-models` is not available or has export issues, usage tracking will gracefully degrade with warnings logged.
+
+**Default:** Usage tracking is enabled by default with `usageTier: 'tier-3'`
+
+### 4. Default Model and Engine Configuration
+
+**Where to configure:**
+1. **JSON Defaults** (lowest priority): `src/defaults/model-config.json`
+2. **Gateway Constructor** (medium priority): `defaultModel`, `defaultEngine`
+3. **Request Config** (highest priority): `request.config.model`, `request.config.provider`
+
+**How to configure:**
+
+**Step 1: Create/Edit JSON defaults** (`src/defaults/model-config.json`):
+```json
+{
+  "defaultModel": "gpt-4o",
+  "defaultEngine": "openai",
+  "temperature": 0.7,
+  "maxTokens": 2000,
+  "topP": 1.0,
+  "frequencyPenalty": 0.0,
+  "presencePenalty": 0.0
+}
+```
+
+**Step 2: Gateway constructor:**
+```typescript
+const gateway = new AIGateway({
+  defaultModel: 'gpt-5-nano',      // Overrides JSON default
+  defaultEngine: 'openai',            // Overrides JSON default
+  temperature: 0.9,                  // Overrides JSON default
+  maxTokens: 4000                    // Overrides JSON default
+});
+```
+
+**Step 3: Request-level override:**
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'You are helpful',
+  input: 'Hello',
+  config: {
+    model: 'gpt-4o',        // Overrides gateway default
+    provider: 'openai',     // Overrides gateway default
+    temperature: 0.5        // Overrides gateway default
+  }
+});
+```
+
+**Priority Order:**
+1. Request config (highest)
+2. Gateway constructor config
+3. JSON defaults (lowest)
+
+### 5. InstructionsBlocks Configuration
+
+**Where to configure:**
+1. **JSON Defaults** (lowest priority): `src/defaults/instructions-blocks.json`
+2. **Content resolver (nx-content)** (medium priority): blocks under e.g. `blocks/{blockName}/{agentId}` (see [Content Resolver — Upstream Guide](./CONTENT_RESOLVER_UPSTREAM_GUIDE.md))
+3. **Gateway Constructor** (highest priority): `instructionsBlocks` object
+
+**How to configure:**
+
+**Step 1: Create/Edit JSON defaults** (`src/defaults/instructions-blocks.json`):
+```json
+{
+  "input-prefix": "Please process the following input:",
+  "default-prompt": "You are a helpful assistant."
+}
+```
+
+**Step 2: Gateway constructor:**
+```typescript
+const gateway = new AIGateway({
+  instructionsBlocks: {
+    'input-prefix': 'Custom prefix from config:',  // Overrides JSON default
+    'custom-block': 'Custom block content'
+  }
+});
+```
+
+**Step 3: Content Registry** (if available):
+- Store blocks at paths supported by nx-content (e.g. `blocks/{blockName}/{agentId}` or with taskTypeId). When content resolver is configured (via `contentRegistryConfig` or env vars), instructions blocks are resolved from local or git.
+
+**Priority Order** (highest to lowest):
+1. Gateway constructor `instructionsBlocks` (highest priority)
+2. Content registry with `taskTypeId` (if taskTypeId provided)
+3. Content registry without `taskTypeId`
+4. JSON defaults (lowest priority)
+
+**See**: [Content Resolver — Upstream Guide](./CONTENT_RESOLVER_UPSTREAM_GUIDE.md) for configuration, env vars, key vs text rule, and checklist.
+
+### 6. Instruction Resolution (Content Resolver / nx-content)
+
+**How it works:** The gateway uses **nx-content** to resolve content. Instruction type is determined by whitespace:
+
+- **No spaces** → **Key** (resolved from local folder or git)
+- **Has spaces** → **Literal text** (used as-is)
+
+There is **no** option to override this; the spaces rule is the only decision point.
+
+**Configuration:** Pass `contentRegistryConfig` (or legacy `contentRegistry`) when creating the gateway:
+
+```typescript
+// Local content only
+const gateway = new AIGateway({
+  contentRegistryConfig: {
+    localPath: '.metadata'   // or absolute path
+  }
+});
+
+// Local + Git (mode: 'dev' = local wins, 'prod' = git wins)
+const gateway = new AIGateway({
+  contentRegistryConfig: {
+    localPath: '.metadata',
+    mode: 'dev',
+    github: {
+      repo: process.env.GITHUB_REPO_URL,
+      token: process.env.GITHUB_TOKEN,
+      branch: 'main'
+    }
+  }
+});
+```
+
+**Environment variables** (used when no explicit config): `CONTENT_REGISTRY_LOCAL_ROOT`, `CONTENT_REGISTRY_MODE`, `GITHUB_REPO_URL`, `GITHUB_TOKEN`, `CONTENT_REGISTRY_GIT_BRANCH`.
+
+**Behavior:**
+- Keys (no spaces) → resolved from nx-content (local or git); **never** sent as message content
+- Literal text (has spaces) → used as-is
+- Unresolvable key → error; no LLM call
+
+**File layout:** e.g. `skills/<name>.instructions.md`, `skills/<name>.prompt.md` under the content root. See [Content Resolver — Upstream Guide](./CONTENT_RESOLVER_UPSTREAM_GUIDE.md) for full layout, checklist, and diagnostics.
+
+### 7. Template Parsing Configuration (workingMemory)
+
+**Where to configure:**
+- Request-level: `workingMemory` object
+
+**How to configure:**
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  // Instructions can be a key (resolved from content resolver) or text (parsed as template)
+  instructions: 'professional-answer.instructions',  // Key with suffix
+  // OR: instructions: 'You are a {{role}} assistant.',  // Text with template variables
+  context: 'User is working on {{project}} project.',
+  // Prompts can be a key (resolved from content resolver) or text (parsed as template)
+  prompt: 'professional-answer.prompt',  // Key with suffix
+  // OR: prompt: 'Analyze this {{type}}: {{input}}',  // Text with template variables
+  input: 'This is a review',
+  workingMemory: {
+    role: 'helpful',
+    project: 'AI Gateway',
+    type: 'product review',
+    input: 'This is a review'
+  }
+});
+```
+
+**What gets parsed:**
+- `instructions` - Resolved from content resolver (nx-content) if it's a key (no spaces), or parsed as template if text
+- `context` - Parsed as template with `workingMemory`
+- `prompt` - Resolved from content resolver if it's a key (no spaces), or parsed as template if text
+- All parsed using `@x12i/rendrix` (v4+) with `workingMemory`, `shortTermMemory`, `experienceMemory`, `knowledgeMemory`
+
+**Rendrix (@x12i/rendrix) v4 template protocol**
+
+- Simple placeholders `{{name}}` or `{{a.b.c}}` are **required** (MUST): if resolution is **`undefined`** after the usual memory merge, rendering throws **`TemplateResolutionError`** from the parser. The gateway **rethrows** that error (it is not converted into a silent fallback).
+- Values that **do not** throw include **`null`**, empty string **`""`**, **`0`**, and **`false`**.
+- **Optional** placeholders: `{{path |}}` (empty if missing) or `{{path | fallback text}}` (literal fallback when missing).
+- Helpers, blocks, `{{file:...}}`, `{{json ...}}`, etc. follow the parser’s own rules; the MUST/optional rules above apply to plain path mustaches.
+- For full parser API details, see **`@x12i/rendrix`** README / `CHANGELOG.md`.
+
+**Gateway template options (passthrough)**
+
+- **`GatewayConfig.templateRendering`** — default `TemplateRenderOptions` for every `invoke()` render path (merged after packaged **`src/defaults/template-rendering.json`**, which ships with **`subPathSearch.enabled: false`**). Your gateway config overrides that JSON.
+- **`templateRenderOptions` on the request** (`ChatRequest` / `AIRequest`) — merged on top of the gateway default for that call only (per-field override; `subPathSearch` fields merge with request winning).
+- Supported fields match the parser: **`templateId`**, **`subPathSearch`** (`enabled`, `roots`), **`silentMissingMustTokens`** (legacy Handlebars-style silence for missing MUST paths).
+- **Sub-path root priority:** `subPathSearch.roots` is an **ordered** list. The parser tries roots in **array order**; **the first root that resolves the leaf path wins** (see ISSUE-005). There is no separate “priority” field—the order of `roots` *is* the priority. Omit `roots` when `enabled` is true to use **`@x12i/rendrix`** packaged defaults.
+
+```typescript
+// Example: prefer execution.*, then input.*, then inputs.* when a full path misses
+new AIGateway({
+  templateRendering: {
+    subPathSearch: {
+      enabled: true,
+      roots: ['execution', 'input', 'inputs']
+    }
+  }
+});
+```
+- **Memory overlay priority** for value resolution (highest first): **`templateTokens`** (merged into short-term before render) → **`shortTermMemory`** → **`workingMemory`** → **`experienceMemory`** → **`knowledgeMemory`**.
+- Root **`config.defaults.json`** may include a **`templateRendering`** block for apps that merge this file into `GatewayConfig`. Packaged **`template-rendering.json`** includes a sample **`roots`** order (used when you turn **`enabled`** on; while **`enabled`** is **`false`**, roots are ignored by the parser).
+
+**Template-Based Prompts:**
+- Prompts work exactly like instructions - both can be resolved using explicit keys. See [Content Resolver — Upstream Guide](./CONTENT_RESOLVER_UPSTREAM_GUIDE.md).
+- Both instructions and prompts receive the same memory context for template rendering
+- Use explicit keys with suffixes: `professional-answer.instructions` and `professional-answer.prompt`
+- See [Prompt Template Usage Guide](./docs/PROMPT_TEMPLATE_USAGE.md) for details
+
+**Note:** Requires `@x12i/rendrix` **^4.x** (already a dependency).
+
+
+### 9. Provider Registration
+
+**Where to configure:**
+- **Automatic (Recommended)**: Environment variables - providers auto-register on gateway creation
+- **Manual**: Runtime: `gateway.register(provider)`
+
+**Automatic Registration (v4.0.7+):**
+
+Providers are automatically registered based on environment variables when the gateway is created:
+
+```typescript
+// Set environment variables in .env:
+// OPENAI_API_KEY=sk-...
+// GROK_API_KEY=xai-...
+// ANTHROPIC_API_KEY=sk-ant-... (optional)
+// GOOGLE_API_KEY=... (optional)
+
+const gateway = new AIGateway({
+  defaultProvider: 'openai',
+  fallbackChain: ['grok']
+});
+
+// Providers are automatically registered! No manual registration needed.
+// The gateway will log which providers were auto-registered.
+```
+
+**📋 Configuration Reference:**
+
+See `.env.example` in the project root for a comprehensive guide to all environment variables, including:
+- Provider API keys (required/optional)
+- MongoDB/activity tracking configuration
+- Content registry setup (S3, GitHub, Redis)
+- Internal system actions configuration
+- Logging and debugging options
+
+Copy `.env.example` to `.env` and fill in your values.
+
+**Supported Providers (Auto-Registration):**
+
+- **OpenAI**: `OPENAI_API_KEY` → Auto-registers `openai` provider
+- **Grok**: `GROK_API_KEY` → Auto-registers `grok` provider
+- **Anthropic**: `ANTHROPIC_API_KEY` → Auto-registers `anthropic` provider (if package installed)
+- **Google**: `GOOGLE_API_KEY` → Auto-registers `google` provider (if package installed)
+- **Cohere**: `COHERE_API_KEY` → Auto-registers `cohere` provider (if package installed)
+- **Mistral**: `MISTRAL_API_KEY` → Auto-registers `mistral` provider (if package installed)
+
+**Manual Registration (Optional):**
+
+You can still manually register providers if needed:
+
+```typescript
+import { OpenAIProvider } from '@x12i/ai-provider-openai';
+import { GrokProvider } from '@x12i/ai-provider-grok';
+
+const gateway = new AIGateway({
+  defaultProvider: 'openai',
+  fallbackChain: ['grok']
+});
+
+// Manual registration (optional - auto-registration handles this if env vars are set)
+gateway.register(new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY
+}));
+
+gateway.register(new GrokProvider({
+  apiKey: process.env.GROK_API_KEY
+}));
+```
+
+**Note:** Auto-registration only registers providers that:
+1. Have their API key set in environment variables
+2. Have their provider package installed (e.g., `@x12i/ai-provider-openai`)
+
+If a provider package is not installed, auto-registration will skip it gracefully (with a debug log for optional providers, warning for required ones).
+
+### 9. Complete Configuration Example
+
+```typescript
+import { AIGateway } from '@x12i/ai-gateway';
+import { createLogger } from 'logs-gateway';
+import { Activix } from '@x12i/activix';
+import { OpenAIProvider } from '@x12i/ai-provider-openai';
+
+// 1. Configure activity tracker (and reuse its logger)
+// Single source of truth: set up the logger once, pass it to the tracker,
+// then reuse the same logger for the gateway.
+const logger = createLogger(
+  { packageName: 'MY_APP', envPrefix: 'MY_APP' },
+  {
+    logLevel: 'info',
+    logFormat: 'json',
+    enableUnifiedLogger: true
+  }
+);
+
+const statusValues = {
+  started: 'started',
+  inProgress: 'in_progress',
+  completed: 'success',
+  failed: 'failed',
+  timeout: 'timeout'
+};
+
+const activityTracker = new Activix({
+  collections: [
+    { name: 'ai-activities', statusValues },
+    { name: 'skill-executions', statusValues },
+    { name: 'bad-requests', statusValues }
+  ]
+});
+
+// 2. Create gateway with all configurations
+const gateway = new AIGateway({
+  // Provider routing
+  defaultProvider: 'openai',
+  defaultModel: 'gpt-4o',
+  defaultEngine: 'openai',
+  fallbackChain: ['grok'],
+  
+  // Usage tracking
+  enableUsageTracking: true,
+  usageTier: 'tier-3',
+  
+  // Activity tracking
+  enableActivityTracking: true,
+  activityTracker: activityTracker,
+  
+  // Logging
+  enableLogging: true,
+  packageName: 'MY_APP',
+  logger: logger,
+  
+  // Content resolver (local and/or git)
+  contentRegistryConfig: {
+    localPath: '.metadata',
+    // optional: mode: 'prod', github: { repo: process.env.GITHUB_REPO_URL, token: process.env.GITHUB_TOKEN }
+  },
+  
+  // InstructionsBlocks
+  instructionsBlocks: {
+    'input-prefix': 'Custom prefix:'
+  },
+  
+  // LLM defaults
+  temperature: 0.7,
+  maxTokens: 2000
+});
+
+// 4. Register providers
+gateway.register(new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY
+}));
+```
+
+### Configuration Priority Summary
+
+For each configuration option, priority is (highest to lowest):
+1. **Request-level config** (in `invoke()` call)
+2. **Gateway constructor config**
+3. **Content resolver (nx-content)** (for instructionsBlocks only)
+4. **JSON defaults** (from `src/defaults/`)
+
+## Enhanced Gateway Features
+
+### 1. Context Propagation (Job ID)
+
+The gateway automatically propagates `jobId` through the entire request lifecycle for distributed tracing.
+
+```typescript
+const response = await gateway.invoke({
+  // Minimum required fields
+  jobId: 'job-123',           // required
+  agentId: 'agent-456',       // required
+  instructions: 'You are a helpful assistant.', // required
+
+  // Provide either messages OR prompt/input
+  messages: [{ role: 'user', content: 'What is AI?' }],
+  // OR:
+  // prompt: 'professional-answer.prompt',  // Key resolved from content resolver (nx-content)
+  // input: 'What is AI?',
+  // Optional extra context inserted between instructions and user prompt/input
+  // context: 'Only answer with a single sentence.',
+
+  // Optional
+  taskId: 'task-789',
+  taskTypeId: 'question-answering',  // Or auto-generated from instructions MD5 hash
+  graphId: 'graph-123',              // Optional: Graph execution context
+  nodeId: 'node-456',                // Optional: Node execution context
+  config: { model: 'gpt-5-nono' }
+});
+
+// jobId is automatically:
+// - Attached to request metadata
+// - Included in response metadata
+// - Logged in all log entries
+// - Tracked in activity logs
+```
+
+**Request requirements:** 
+- **Required fields**: `jobId`, `agentId`, and `instructions` are mandatory
+- **Content field (choose one)**:
+  - `messages` array (for tool calling or custom message sequences)
+  - OR `prompt` + `input` (prompt template resolved from content resolver or parsed with template variables)
+  - OR `input` alone (uses default prefix from instructionsBlocks)
+- **Optional fields**: `context` (inserted as system message between instructions and user content), `workingMemory` (for template variables), `graphId`/`nodeId`/`coreSkillId` (for graph execution context - see [Graph Execution Support](./docs/GRAPH_EXECUTION_SUPPORT.md))
+- **Model requirement**: `config.model` must be supplied per request (no default model)
+
+**Important Notes:**
+- `instructions` is **always required**, even when using `messages` array
+- When `messages` is provided, the gateway constructs system messages from `instructions` (and `context` if provided), then appends your `messages` array
+- `context` is inserted as a separate system message between instructions and the user prompt/input
+- **Template-Based Instructions and Prompts**: Both `instructions` and `prompt` can be resolved from the content resolver (nx-content) using keys (e.g., `professional-answer.instructions` and `professional-answer.prompt`). Both receive the same memory context for template rendering. See [Content Resolver — Upstream Guide](./CONTENT_RESOLVER_UPSTREAM_GUIDE.md) and [Prompt Template Usage Guide](./docs/PROMPT_TEMPLATE_USAGE.md).
+- All template fields (`instructions`, `context`, `prompt`) support template variables via `workingMemory`
+
+**Benefits:**
+- Full request traceability across distributed systems
+- Correlate logs, activities, and metrics by jobId
+- Debug complex multi-step AI workflows
+
+### 2. Usage Tier Tracking (RPM/TPM Limits)
+
+The gateway integrates with `@x12i/x-models` to enforce usage tier limits and prevent rate limit errors.
+
+```typescript
+import { AIGateway, getTierInfo } from '@x12i/ai-gateway';
+
+// Initialize with usage tier
+const gateway = new AIGateway({
+  usageTier: 'tier-3',  // 5,000 RPM, 2M TPM
+  enableUsageTracking: true
+});
+
+// Get tier information
+const tierInfo = getTierInfo('tier-3');
+console.log(`RPM Limit: ${tierInfo?.rpm}, TPM Limit: ${tierInfo?.tpm}`);
+
+// Gateway automatically:
+// - Records every request to x-models
+// - Calculates RPM/TPM consumption
+// - Logs consumption percentages
+// - Prevents exceeding tier limits
+```
+
+**Available Tiers:**
+- `tier-1`: 500 RPM, 500K TPM
+- `tier-2`: 5,000 RPM, 1M TPM
+- `tier-3`: 5,000 RPM, 2M TPM (default)
+- `tier-4`: 10,000 RPM, 4M TPM
+- `tier-5`: 15,000 RPM, 40M TPM
+
+### 3. Activity Tracking (xronox-activitix via @x12i/activix v5)
+
+The gateway uses **`@x12i/activix` v5** (xronox-activitix) for full lifecycle logging. Recommended: enable MongoDB persistence so tracking is automatic. Default collections: **`ai-activities`**, **`bad-requests`**, **`skill-executions`** (see section 2).
+
+#### ⚠️ CRITICAL: correlation, identity, and unique record ids
+
+**IMPORTANT DESIGN CONCEPTS:**
+
+1. **Per-request correlation**
+   - **`aiRequestId`** (required): One id per gateway invocation; used as the primary leaf correlation field (stored on the activity row and inside Activix `runContext`; the gateway does not generate a `jobId` for you).
+   - **`jobTypeId`**, **`taskId`**, **`taskTypeId`**: Optional aggregation fields (same ideas as before).
+   - **Activity**: Each individual LLM request is a separate **activity** with its own unique record.
+
+2. **Mongo `_id` is the unique row key**
+   - Optional **`jobId`** (if you pass it) is only grouping metadata — multiple activities may share it.
+   - Activix updates rows by the **record id** from the start phase, not by `jobId`.
+
+3. **Two-phase tracking (Activix v5)**
+   - **Phase 1 (start)**: Creates a NEW database record with unique `_id`
+     - Sends request-side data: `request`, `config`, `runContext`, `structure`, `startTime`, `status: 'started'` (plus other gateway metadata)
+     - Returns metadata containing the unique record id for completion
+   - **Phase 2 (complete / fail)**: Updates the SAME record by that id
+     - Sends response/error data: `response`, `endTime`, `duration`, `cost`, `status`
+     - Does not re-send full request payload
+
+4. **Data structure (v2.6.0+):**
+   - Request fields (`messages`, `instructions`, `prompt`, `input`, `context`, `workingMemory`) → **ONLY in `request` object**
+   - Config fields (`model`, `provider`, `temperature`, `maxTokens`) → **ONLY in `config` object**
+   - Response fields (`content`, `metadata`) → **ONLY in `response` object**
+   - **NO duplication**: Fields are NOT at root level, only in their structured objects
+
+**Example: same logical job, three LLM calls**
+
+Each call must have a **distinct `aiRequestId`**. Optionally pass the same `jobId` (or only `jobTypeId`) if you want to group rows in Mongo.
+
+```typescript
+import * as crypto from 'crypto';
+
+function md5(text: string): string {
+  return crypto.createHash('md5').update(text).digest('hex');
+}
+
+const jobTypeId = md5('data-processing-job');
+
+await gateway.invoke({
+  aiRequestId: 'req-001',
+  jobId: 'job-123',       // optional grouping
+  jobTypeId,
+  agentId: 'agent-1',
+  sessionId: 'sess-1',
+  instance: { instanceId: 'inst-1', type: 'gateway' },
+  // ...
+});
+
+await gateway.invoke({
+  aiRequestId: 'req-002',
+  jobId: 'job-123',
+  jobTypeId,
+  agentId: 'agent-1',
+  sessionId: 'sess-1',
+  instance: { instanceId: 'inst-1', type: 'gateway' },
+  // ...
+});
+
+// Query in Mongo (main collection name is ai-activities):
+// db.getCollection('ai-activities').find({ 'runContext.aiRequestId': 'req-001' })
+// db.getCollection('ai-activities').find({ 'runContext.jobId': 'job-123' })  // if you set jobId
+```
+
+#### Configuration
+
+```typescript
+import { Activix } from '@x12i/activix';
+
+const statusValues = {
+  started: 'started',
+  inProgress: 'in_progress',
+  completed: 'success',
+  failed: 'failed',
+  timeout: 'timeout'
+};
+
+const activityTracker = new Activix({
+  collections: [
+    { name: 'ai-activities', statusValues },
+    { name: 'skill-executions', statusValues },
+    { name: 'bad-requests', statusValues }
+  ]
+});
+
+const gateway = new AIGateway({
+  enableActivityTracking: true,
+  activityTracker
+});
+
+// Auto-persisted by the tracker:
+// - Each activity creates a new record with unique _id
+// - Start/end/duration, status (started|success|failed)
+// - Provider, model, cost
+// - Request/response metadata, errors
+// - Correlation via runContext (and mirrored top-level fields); optional jobId for grouping
+```
+
+#### Database Record Structure
+
+```typescript
+{
+  // Unique identifier (MongoDB auto-generated)
+  _id: ObjectId('693970636e8d0f171e4aa528'),  // ← UNIQUE per activity
+  
+  // Activix v5: canonical correlation BSON object `runContext` (gateway builds it from `request.identity`)
+  runContext: {
+    sessionId: 'sess-1',
+    instance: { instanceId: 'gw-1', type: 'gateway' },
+    aiRequestId: 'req-abc',
+    jobId: 'job-123',
+    jobTypeId: 'xyz789...',
+    agentId: 'agent-456',
+    taskId: 'task-789',
+    taskTypeId: 'abc123...',
+    graphId: 'graph-456',
+    nodeId: 'node-789',
+    masterSkillId: '...',
+    masterSkillActivityId: '...'
+  },
+  // Mirrored / denormalized top-level fields may also appear from the gateway payload (query either as needed)
+  aiRequestId: 'req-abc',
+  sessionId: 'sess-1',
+  instance: { instanceId: 'gw-1', type: 'gateway' },
+  jobId: 'job-123',
+  jobTypeId: 'xyz789...',
+  agentId: 'agent-456',
+  taskId: 'task-789',
+  taskTypeId: 'abc123...',
+  graphId: 'graph-456',
+  nodeId: 'node-789',
+
+  // Required activity I/O envelope (`structure` required since Activix v4; unchanged in v5 — see @x12i/activix docs)
+  structure: {
+    outer: { input: { ... }, output: { ... } | null, metadata: { ... } },
+    // inner?: { input, output, metadata }
+  },
+  
+  // Timing
+  startTime: 1765372020804,
+  endTime: 1765372021535,   // Added by logSuccess
+  duration: 731,            // Added by logSuccess
+  status: 'success',        // Updated by logSuccess (was 'started')
+  
+  // Request data (from startActivity - ONLY in request object)
+  request: {
+    raw: { 
+      instructions,  // Original instructions (before template parsing)
+      context,      // Original context (before template parsing)
+      prompt        // Original prompt (before template parsing)
+    },
+    parsed: { 
+      instructions,  // Parsed instructions (after template parsing with workingMemory)
+      context,       // Parsed context (after template parsing with workingMemory)
+      prompt         // Parsed prompt (after template parsing with workingMemory, includes input if provided)
+    },
+    input: "...",     // Original input text
+    messages: [...],  // Final constructed messages array
+    workingMemory: {...}  // Working memory used for template parsing
+  },
+  
+  // Config data (from startActivity - ONLY in config object)
+  config: {
+    model: 'gpt-5-',
+    provider: 'openai',
+    temperature: 0.7,
+    maxTokens: 1000,
+    rawConfig: {...}
+  },
+  
+  // Response data (from logSuccess - ONLY in response object)
+  response: {
+    content: "...",
+    metadata: {...}
+  },
+  
+  // Cost (from logSuccess)
+  cost: 0.002,
+  
+  // Metadata
+  createdAt: Date,
+  updatedAt: Date
+}
+```
+
+**Key points:**
+- ✅ Each activity = separate record with unique `_id`
+- ✅ **`aiRequestId`** = per-request correlation (required on invoke)
+- ✅ Optional `jobId` = grouping metadata only
+- ✅ Request data sent once at activity start; response data on completion
+- ✅ Updates use Activix record id / `_id`, not `jobId`
+
+#### Retry Tracking (@x12i/activix v5)
+
+The gateway automatically retries network errors, server errors (5xx), and throttling (429) with exponential backoff. Retry attempts are tracked and stored in activity records.
+
+**Retry Metadata Structure:**
+
+```typescript
+// Success case - retry metadata in response.metadata.retries
+{
+  response: {
+    metadata: {
+      retries: {
+        count: 2,  // Number of retry attempts
+        attempts: [
+          {
+            attempt: 1,                    // 1-based attempt number
+            timestamp: 1234567890,          // When retry occurred
+            error: "fetch failed",          // Error message
+            errorType: "network",           // Error classification
+            delayMs: 1000                   // Delay before retry
+          },
+          {
+            attempt: 2,
+            timestamp: 1234568890,
+            error: "fetch failed",
+            errorType: "network",
+            delayMs: 2000
+          }
+        ]
+      }
+    }
+  }
+}
+
+// Failure case - retry count in error message
+{
+  status: "failed",
+  error: "Grok API network error: fetch failed [Retries: 3]"
+}
+```
+
+**Error Types:**
+- `network`: Network errors (fetch failed, DNS, connectivity)
+- `http-429`: Throttling/rate limiting
+- `http-5xx`: Server errors (500, 502, 503, etc.)
+- `timeout`: Timeout errors
+
+**Querying Activities with Retries:**
+
+```typescript
+// Query activities that had retries
+const activitiesWithRetries = await db.activities.find({
+  'response.metadata.retries.count': { $gt: 0 }
+});
+
+// Query activities with network errors that were retried
+const networkRetries = await db.activities.find({
+  'response.metadata.retries.attempts.errorType': 'network'
+});
+
+// Query activities that failed after retries
+const failedAfterRetries = await db.activities.find({
+  status: 'failed',
+  error: /\[Retries: \d+\]/
+});
+```
+
+**Requirements:**
+ - `@x12i/activix` required for retry tracking metadata persistence
+- Backward compatible: Works with older versions (retry metadata just won't be stored)
+
+### 4. Response Structure (v2.1.0+)
+
+The gateway returns a comprehensive response structure that captures the full lifecycle: raw provider response, gateway normalization, inference parsing, and calculated metrics.
+
+#### Complete Response Structure
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'You are a helpful assistant.',
+  input: 'What is AI?',
+  config: { model: 'gpt-5-nano' }
+});
+
+// Response structure:
+{
+  // ============================================
+  // Raw Provider Response (from router)
+  // ============================================
+  content: string,              // Normalized string (always present)
+  rawText?: string,             // Original raw text from provider (before parsing)
+  
+  // Raw content from provider (if preserved)
+  // Note: response.content is normalized, rawContent would be in routerResponse
+  
+  // ============================================
+  // Gateway Normalization & Parsing
+  // ============================================
+  parsedContent?: TContent,     // Parsed JSON object/array (if content was JSON)
+  
+  metadata: {
+    // Content type classification
+    contentType?: 'string' | 'object' | 'array' | 'null',
+    
+    // ============================================
+    // Gateway Calculated Metrics
+    // ============================================
+    jobId?: string,             // Job ID for correlation
+    latencyMs: number,          // Execution time in milliseconds
+    tokens: {
+      prompt: number,           // Input tokens
+      completion: number,       // Output tokens
+      total: number,            // Total tokens
+      // Cache token support (if available)
+      cacheInputTokens?: number,
+      cacheOutputTokens?: number,
+      cacheTotalTokens?: number
+    },
+    model?: string,             // Model ID used (e.g., 'gpt-4o', 'claude-sonnet-4')
+    provider?: string,          // Provider used (e.g., 'openai', 'anthropic')
+    cost?: number,              // Cost in USD (if available)
+    
+    // ============================================
+    // Inference Output Parsing (if inferenceType provided)
+    // ============================================
+    parsedOutput?: unknown,     // Typed inference output (classification, Q&A, etc.)
+    inferenceType?: string,     // Inference type used (e.g., 'classification')
+    outputValidationErrors?: string[], // Schema validation errors (if validation enabled)
+    
+    // ============================================
+    // Provider Metadata (from router)
+    // ============================================
+    // Additional metadata from provider response
+    // (merged from routerResponse.metadata)
+  },
+  
+  // ============================================
+  // Usage Information (from router)
+  // ============================================
+  usage?: {
+    cost?: number,              // Cost from provider
+    // Additional usage fields from provider
+  }
+}
+```
+
+#### Response Structure Breakdown
+
+**1. Raw Provider Response:**
+- `content` - Normalized string (always present, never "[object Object]")
+- `rawText` - Original raw text from provider (preserved if available)
+- `usage` - Usage information from provider (cost, tokens if available)
+- Provider metadata merged into `response.metadata`
+
+**2. Gateway Normalization & Parsing:**
+- `parsedContent` - Parsed JSON object/array (if content was JSON)
+- `metadata.contentType` - Type classification: `'string' | 'object' | 'array' | 'null'`
+
+**3. Inference Output Parsing** (if `inferenceType` provided in request):
+- `metadata.parsedOutput` - Typed inference output (classification, question-answer, extraction, etc.)
+- `metadata.inferenceType` - Inference type used
+- `metadata.outputValidationErrors` - Schema validation errors (if validation enabled)
+
+**4. Gateway Calculated Metrics:**
+- `metadata.jobId` - Job ID for correlation
+- `metadata.latencyMs` - Request duration in milliseconds
+- `metadata.tokens` - Token breakdown (prompt, completion, total, cache tokens)
+- `metadata.cost` - Cost in USD
+- `metadata.model` - Model ID used
+- `metadata.provider` - Provider used
+
+#### Example: Full Response
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'Classify sentiment',
+  input: 'I love this product!',
+  inferenceType: 'classification',
+  parseOptions: { classes: ['positive', 'negative', 'neutral'] },
+  config: { model: 'gpt-5-nano' }
+});
+
+// Complete response structure:
+{
+  // Normalized content (always string)
+  content: '{"label":"positive","confidence":0.95}',
+  
+  // Raw text from provider
+  rawText: '{"label":"positive","confidence":0.95}',
+  
+  // Parsed JSON (if content was JSON)
+  parsedContent: { label: 'positive', confidence: 0.95 },
+  
+  metadata: {
+    // Content classification
+    contentType: 'object',
+    
+    // Gateway metrics
+    jobId: 'job-123',
+    latencyMs: 1250,
+    tokens: {
+      prompt: 100,
+      completion: 50,
+      total: 150
+    },
+    model: 'gpt-5-mini',
+    provider: 'openai',
+    cost: 0.002,
+    
+    // Inference output (parsed)
+    parsedOutput: {
+      label: 'positive',
+      confidence: 0.95
+    },
+    inferenceType: 'classification',
+    outputValidationErrors: undefined // No validation errors
+  }
+}
+```
+
+**Note:** The response structure captures the full lifecycle from raw provider response through gateway normalization to final parsed inference output, providing complete observability and traceability.
+
+### 5. Structured Logging
+
+The gateway uses `logs-gateway` for production-ready structured logging with correlation support.
+
+```typescript
+const gateway = new AIGateway({
+  enableLogging: true,
+  packageName: 'MY_APP',
+  logger: createLogger(
+    { packageName: 'MY_APP', envPrefix: 'MY_APP' },
+    {
+      logLevel: 'info',
+      logFormat: 'json',
+      enableUnifiedLogger: true
+    }
+  )
+});
+
+// All operations are automatically logged:
+// - Request initiation with jobId
+// - Provider/model selection
+// - Usage consumption
+// - Success/failure with full context
+```
+
+### 6. Object Type Output Support (@x12i/outputs-library)
+
+The gateway integrates with `@x12i/outputs-library` to parse LLM responses into typed inference outputs (classification, question-answer, extraction, etc.).
+
+#### Overview
+
+When you specify an `inferenceType` in your request, the gateway automatically:
+1. Parses the response into a typed output object
+2. Validates against JSON Schema (optional)
+3. Provides type-safe access to structured data
+
+#### Installation
+
+```bash
+npm install @x12i/outputs-library
+```
+
+**Note**: `@x12i/outputs-library` is automatically installed as a dependency.
+
+**Dependency Resolution**: The gateway includes npm overrides to resolve version conflicts between the outputs library and content-registry. The integration uses dynamic imports for graceful degradation - if the outputs library is not available, the gateway will continue to work (parsing will be skipped with a warning).
+
+**Installation**: The package.json includes overrides to handle version conflicts automatically. If you still encounter issues:
+
+```bash
+npm install --legacy-peer-deps
+```
+
+**Note for Package Maintainers**: The `@x12i/outputs-library` package should update its peer dependency from `@xronoces/content-registry@^1.0.0` to `@xronoces/content-registry@>=1.0.0` or `^1.0.0 || >=2.7.0` to support both versions. See `DEPENDENCY_RESOLUTION.md` for details.
+
+#### Supported Inference Types
+
+- `classification` - Classify content into predefined categories
+- `question-answer` - Answer questions based on context
+- `extraction` - Extract structured data from unstructured text
+- `summarization` - Generate summaries of content
+- `risk-assessment` - Assess risks with scores and factors
+- `recommendation` - Generate recommendations with priorities
+- `transformation` - Transform data between formats
+
+#### Basic Usage
+
+```typescript
+import { AIGateway } from '@x12i/ai-gateway';
+import type { ClassificationOutput } from '@x12i/ai-gateway';
+
+const gateway = new AIGateway({
+  defaultProvider: 'openai'
+});
+
+// Request with inference type
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'Classify the sentiment of the text.',
+  input: 'This product is amazing!',
+  inferenceType: 'classification',
+  parseOptions: {
+    classes: ['positive', 'negative', 'neutral']
+  }
+});
+
+// Access parsed output
+const classification = response.metadata.parsedOutput as ClassificationOutput;
+console.log(classification.classes); // ['positive', 'negative', 'neutral']
+console.log(classification.confidence); // { positive: 0.85, negative: 0.1, neutral: 0.05 }
+```
+
+#### With Schema Validation
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'Extract user information.',
+  input: 'Name: John Doe, Email: john@example.com',
+  inferenceType: 'extraction',
+  validateOutputSchema: true  // Enable validation
+});
+
+// Check validation errors (if any)
+if (response.metadata.outputValidationErrors) {
+  console.warn('Validation errors:', response.metadata.outputValidationErrors);
+}
+
+// Access parsed output
+const extraction = response.metadata.parsedOutput as ExtractionOutput;
+console.log(extraction.extracted); // { name: 'John Doe', email: 'john@example.com' }
+```
+
+#### Question-Answer Example
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'Answer the question based on the context.',
+  input: 'What is the capital of France?',
+  inferenceType: 'question-answer',
+  parseOptions: {
+    question: 'What is the capital of France?'
+  }
+});
+
+const qa = response.metadata.parsedOutput as QuestionAnswerOutput;
+console.log(qa.answer); // 'The capital of France is Paris.'
+console.log(qa.confidence); // 0.95
+```
+
+#### Extraction Example
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'Extract structured data from the text.',
+  input: 'User: John Doe, Age: 30, Location: New York',
+  inferenceType: 'extraction'
+});
+
+const extraction = response.metadata.parsedOutput as ExtractionOutput;
+console.log(extraction.extracted); // { user: 'John Doe', age: 30, location: 'New York' }
+```
+
+#### Response Structure
+
+When `inferenceType` is provided, the response includes:
+
+```typescript
+{
+  content: string;              // Normalized content (ALWAYS a string - JSON objects are stringified)
+  rawText?: string;             // Original raw text (always a string when present)
+  parsedContent?: object | array; // Parsed JSON content (ALWAYS object/array when JSON, forced structure)
+  metadata: {
+    // ... standard metadata ...
+    parsedOutput?: unknown;      // Typed inference output (ALWAYS present with consistent structure when inferenceType provided)
+    inferenceType?: string;       // The inference type used
+    outputValidationErrors?: string[];  // Validation errors (if enabled)
+    outputValidationPassed?: boolean;    // Whether validation passed (v1.7.0+)
+    outputSchema?: Record<string, unknown>;  // Schema used for validation (v1.7.0+)
+    outputsLibraryAvailable?: boolean;      // Whether outputs library was used (v1.7.0+)
+    parsingMethod?: 'outputs-library' | 'json-parse' | 'raw';  // Parsing method used (v1.7.0+)
+    isFallback?: boolean;                    // Whether fallback structure was used (v1.7.4+)
+    outputAudit?: {                          // Structure audit results (v2.1.1+)
+      hasAllRequiredFields: boolean;
+      missingRequiredFields?: string[];
+      extraFields?: string[];
+      matchingFields?: string[];
+      responseFieldCount: number;
+      schemaFieldCount: number;
+      structureMatches: boolean;
+    };
+  }
+}
+```
+
+**Guaranteed Structure Consistency (v1.7.4+):**
+
+The gateway ensures structures are always consistent:
+
+- **`content`**: Always a string (objects/arrays are JSON.stringified)
+- **`parsedContent`**: Always an object or array when content is JSON (forced structure)
+- **`parsedOutput`**: Always has type-specific structure when `inferenceType` is provided (never undefined)
+
+**Forced Structure Examples:**
+
+```typescript
+// Invalid JSON string → Wrapped in object
+// Input: "not valid json"
+// parsedContent: { text: "not valid json", _wrapped: true }
+
+// Plain text → Wrapped in object if expecting JSON
+// Input: "Hello world"
+// parsedContent: { text: "Hello world", _wrapped: true }
+
+// Object → Always preserved as object
+// Input: { key: "value" }
+// parsedContent: { key: "value" }
+
+// Array → Always preserved as array
+// Input: [1, 2, 3]
+// parsedContent: [1, 2, 3]
+```
+
+#### Using Outputs Library Directly
+
+You can also use the outputs library utilities directly:
+
+```typescript
+import { 
+  ResponseParser, 
+  SchemaValidator, 
+  SchemaRegistry,
+  type ClassificationOutput 
+} from '@x12i/ai-gateway';
+
+// Parse manually
+const output = ResponseParser.parse<ClassificationOutput>(
+  rawText,
+  parsedContent,
+  contentType,
+  'classification',
+  { classes: ['positive', 'negative'] }
+);
+
+// Validate against schema
+const schema = SchemaRegistry.getSchema('classification');
+const validator = new SchemaValidator();
+if (!validator.validate(output, schema)) {
+  console.error('Validation errors:', validator.getErrors());
+}
+```
+
+#### Automatic Output Schema Guidance (v2.1.1+)
+
+When you want to get a JSON response that conforms to a specific schema, you must provide the output object schema. The gateway automatically extends instructions with clear expectations about the JSON structure.
+
+**How It Works:**
+
+1. **Provide `inferenceType`** in your request, OR
+2. **Use an instruction key** that has `outputSchema` in its metadata
+
+The gateway will:
+- Automatically fetch the schema from instruction metadata (if using content-registry)
+- Resolve `outputObjectPrefix` from `instructions-blocks.json`
+- Append detailed schema guidance to instructions, including:
+  - Field descriptions and types
+  - Required vs optional fields
+  - Full JSON schema in a code block
+
+**Example:**
+
+```typescript
+// Instruction metadata has:
+// {
+//   instructionKey: 'extraction/user-data',
+//   outputSchema: {
+//     type: 'object',
+//     properties: {
+//       name: { type: 'string', description: 'User full name' },
+//       email: { type: 'string', description: 'User email address' },
+//       age: { type: 'number', description: 'User age' }
+//     },
+//     required: ['name', 'email']
+//   }
+// }
+
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'extraction/user-data',  // Instruction key with outputSchema
+  input: 'John Doe, john@example.com, 30 years old',
+  inferenceType: 'extraction'
+});
+
+// Instructions automatically extended with:
+// "You must respond with a single valid JSON object that strictly conforms to the schema provided below:
+//
+// Expected fields:
+// - name (string) [REQUIRED]: User full name
+// - email (string) [REQUIRED]: User email address
+// - age (number) [optional]: User age
+//
+// Full JSON Schema:
+// ```json
+// { ... schema ... }
+// ```"
+```
+
+**Configuration:**
+
+Add `outputObjectPrefix` to `instructions-blocks.json`:
+
+```json
+{
+  "outputObjectPrefix": "You must respond with a single valid JSON object that strictly conforms to the schema provided below:"
+}
+```
+
+This prefix is automatically appended to instructions when `outputType` or `outputSchema` is available.
+
+#### Schema Validation (v1.7.0+)
+
+The gateway supports enhanced schema validation with strict/non-strict modes and automatic schema resolution from instruction metadata.
+
+**Validation Options:**
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'classification/vulnerability-severity',
+  input: 'CVE-2024-1234: Critical RCE',
+  inferenceType: 'classification',
+  validateOutputSchema: true,      // Enable validation
+  strictValidation: false          // Non-strict: log warnings, don't throw (default)
+});
+```
+
+**Strict Validation Mode:**
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'classification/vulnerability-severity',
+  input: 'CVE-2024-1234: Critical RCE',
+  inferenceType: 'classification',
+  validateOutputSchema: true,
+  strictValidation: true            // Strict: throw error if validation fails
+});
+
+// If validation fails, throws error:
+// Error: Schema validation failed for inference type 'classification': ...
+```
+
+**Automatic Schema Resolution:**
+
+When `inferenceType` is provided and instruction metadata is available, the gateway automatically:
+1. Checks instruction metadata for `outputSchema`
+2. Uses it for validation (overrides default schema from outputs-library)
+3. Falls back to outputs-library schema registry if not found
+
+```typescript
+// Instruction metadata has:
+// {
+//   instructionKey: 'classification/vulnerability-severity',
+//   outputSchema: { /* custom schema */ }
+// }
+
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'classification/vulnerability-severity',  // Instruction key
+  input: 'CVE-2024-1234: Critical RCE',
+  inferenceType: 'classification',
+  validateOutputSchema: true
+  // Gateway automatically uses outputSchema from metadata
+});
+```
+
+**Validation Error Handling:**
+
+- **Non-strict mode (default)**: Validation failures log warnings but continue
+- **Strict mode**: Validation failures throw errors and stop execution
+- **Validation results** are always available in `response.metadata.outputValidationErrors` and `response.metadata.outputValidationPassed`
+
+#### Output Structure Audit (v2.1.1+)
+
+The gateway automatically audits the structure of parsed output against the expected schema when a schema is available. This provides detailed analysis of what fields are present, missing, or extra - without affecting the response itself.
+
+**Automatic Audit:**
+
+When `outputSchema` is available (from instruction metadata or provided directly), the gateway automatically:
+- Compares the response structure against the schema
+- Identifies missing required fields
+- Identifies extra fields (in response but not in schema)
+- Reports matching fields
+- Provides structure match status
+
+**Audit Results:**
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'extraction/user-data',
+  input: 'John Doe, john@example.com',
+  inferenceType: 'extraction',
+  validateOutputSchema: true
+});
+
+// Audit results in metadata (always available when schema exists)
+console.log(response.metadata.outputAudit);
+// {
+//   hasAllRequiredFields: true,
+//   missingRequiredFields: undefined,
+//   extraFields: ['timestamp'],  // Extra field not in schema
+//   matchingFields: ['name', 'email'],
+//   responseFieldCount: 3,
+//   schemaFieldCount: 2,
+//   structureMatches: false  // false because of extra field
+// }
+```
+
+**Audit Metadata:**
+
+- `outputAudit.hasAllRequiredFields` - Whether all required fields are present
+- `outputAudit.missingRequiredFields` - Array of missing required field names
+- `outputAudit.extraFields` - Array of fields in response but not in schema
+- `outputAudit.matchingFields` - Array of fields present in both response and schema
+- `outputAudit.responseFieldCount` - Total fields in response
+- `outputAudit.schemaFieldCount` - Total fields expected in schema
+- `outputAudit.structureMatches` - Whether structure matches exactly (all required present, no extra fields)
+
+**Note:** Audit is always performed when a schema is available - it's informational only and doesn't affect the response. Clients can use it for monitoring, logging, or quality checks.
+
+**Graceful Outputs Library Handling:**
+
+When outputs library is not available:
+- Gateway automatically falls back to JSON parsing
+- Response metadata indicates parsing method used (`outputsLibraryAvailable`, `parsingMethod`)
+- Clear warnings are logged (not generic errors)
+- Request continues with fallback parsing
+
+```typescript
+// Check parsing method in response
+if (response.metadata.parsingMethod === 'json-parse') {
+  console.log('Outputs library unavailable, used JSON parsing fallback');
+}
+if (!response.metadata.outputsLibraryAvailable) {
+  console.log('Outputs library was not available for this request');
+}
+
+// Check if fallback structure was used
+if (response.metadata.isFallback) {
+  console.log('Parsing failed, using fallback structure');
+  // parsedOutput will have _fallback: true and _raw fields
+  const fallbackOutput = response.metadata.parsedOutput as any;
+  if (fallbackOutput._fallback) {
+    console.log('Raw response:', fallbackOutput._raw);
+  }
+}
+```
+
+**Guaranteed Consistent Structure (v1.7.4+):**
+
+The gateway ensures **consistent structure at all levels**:
+
+1. **Content Level**: `content` is always a string (JSON objects are stringified)
+2. **Parsed Content Level**: `parsedContent` is always an object/array when content is JSON (forced structure)
+3. **Parsed Output Level**: `parsedOutput` always has type-specific structure when `inferenceType` is provided
+
+**Forced Structure Conversion:**
+- **JSON → Object/Array**: Always parsed into object/array structure (even if invalid JSON, wrapped)
+- **Text → String**: Always kept as string in `content` field
+- **Object → JSON String**: Always stringified in `content` field
+- **Array → JSON String**: Always stringified in `content` field
+
+When `inferenceType` is provided, the gateway **always** returns a consistent structure in `parsedOutput`, even when parsing fails:
+
+```typescript
+// Success case
+{
+  metadata: {
+    parsedOutput: {
+      extracted: { ... }  // ✅ Structured output
+    },
+    isFallback: false
+  }
+}
+
+// Failure case - guaranteed structure
+{
+  metadata: {
+    parsedOutput: {
+      extracted: parsedContent || {},  // ✅ Always present
+      _fallback: true,                 // ✅ Indicates parsing failed
+      _raw: rawText                    // ✅ Original response preserved
+    },
+    isFallback: true,
+    parsingMethod: 'json-parse'
+  }
+}
+```
+
+**Type-Specific Fallback Structures:**
+
+Each inference type has a standard fallback structure:
+
+- **Extraction**: `{ extracted: {}, _fallback: true, _raw: string }`
+- **Classification**: `{ classes: [], confidence: {}, _fallback: true, _raw: string }`
+- **Question-Answer**: `{ answer: string, confidence?: number, _fallback: true, _raw: string }`
+- **Summarization**: `{ summary: string, keyPoints: [], _fallback: true, _raw: string }`
+- **Sentiment**: `{ sentiment: string, score: number, _fallback: true, _raw: string }`
+
+This ensures consumers can always safely access expected fields without null checks:
+
+```typescript
+// ✅ Safe - structure is guaranteed
+const output = response.metadata.parsedOutput as ExtractionOutput;
+const extracted = output.extracted;  // Always present, never undefined
+
+// Check if it's a fallback
+if (output._fallback) {
+  console.warn('Parsing failed, using fallback structure');
+  console.log('Raw response:', output._raw);
+}
+```
+
+**Fallback Parsing Priority:**
+
+When outputs library is not available, the gateway automatically falls back in this order:
+
+1. **Outputs Library** (preferred) - Full parsing with type inference
+2. **JSON Parse** - If `parsedContent` is available as object/array
+3. **Raw Content** - Last resort, returns raw text/object
+
+**Error Detection:**
+
+The gateway automatically detects and handles outputs library errors:
+- **Module Not Found**: Clear warning logged, fallback parsing used
+- **Export Missing**: Clear warning logged, fallback parsing used
+- **Version Mismatch**: Clear warning logged, fallback parsing used
+
+All errors are logged with clear messages indicating the issue and the fallback method used.
+
+#### Benefits
+
+- **Type Safety**: Full TypeScript support with typed outputs
+- **Consistency**: Standardized object structures across all SDKs
+- **Validation**: Built-in schema validation with strict/non-strict modes (v1.7.0+)
+- **Metadata-Driven**: Automatic schema resolution from instruction metadata (v1.7.0+)
+- **Consistent Structure**: Guaranteed consistent `parsedOutput` structure even when parsing fails (v1.7.4+)
+- **Flexibility**: Works with any inference type
+- **Integration**: Seamlessly integrated into gateway responses
+- **Graceful Degradation**: Automatic fallback when outputs library unavailable (v1.7.0+)
+
+### 7. Response Transformation Hooks (v1.6.9+)
+
+The gateway supports transformation hooks that allow you to modify responses at different stages of processing: before parsing, after parsing, before validation, and after validation. This enables output mapping, data normalization, computed fields, and custom transformations.
+
+#### Overview
+
+Transformation hooks are provided via the `transformations` field in `ChatRequest` or `AIRequest`. Each hook receives the data at a specific stage and returns the transformed data.
+
+**Available Hooks:**
+
+1. **`preParse`**: Transform raw text before parsing (applied to `rawText`)
+2. **`postParse`**: Transform parsed content after parsing (applied to `parsedOutput` or `parsedContent`)
+3. **`preValidate`**: Transform parsed content before schema validation
+4. **`postValidate`**: Transform validated content after validation
+
+#### Interface
+
+```typescript
+interface ResponseTransformationConfig {
+  preParse?: (rawText: string, metadata: any) => string;
+  postParse?: (parsed: any, metadata: any) => any;
+  preValidate?: (parsed: any, schema: any) => any;
+  postValidate?: (validated: any, metadata: any) => any;
+}
+```
+
+**Metadata Object:**
+
+The `metadata` parameter passed to hooks contains:
+
+```typescript
+{
+  jobId: string;
+  agentId: string;
+  taskId?: string;
+  taskTypeId?: string;
+  instructionKey: string;  // The instruction key or text
+  inferenceType?: string;
+}
+```
+
+#### Basic Usage
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-1',
+  agentId: 'agent-1',
+  instructions: 'classification/basic',
+  input: 'This is great!',
+  config: { model: 'gpt-4o' },
+  inferenceType: 'classification',
+  transformations: {
+    // Clean raw text before parsing
+    preParse: (rawText, metadata) => {
+      return rawText.trim().replace(/\s+/g, ' ');
+    },
+    
+    // Transform parsed output
+    postParse: (parsed, metadata) => {
+      return {
+        ...parsed,
+        transformed: true,
+        timestamp: Date.now()
+      };
+    },
+    
+    // Apply output mapping before validation
+    preValidate: (parsed, schema) => {
+      // Map fields to standardized names
+      return {
+        label: parsed.class,
+        score: parsed.confidence,
+        ...parsed
+      };
+    },
+    
+    // Add computed fields after validation
+    postValidate: (validated, metadata) => {
+      return {
+        ...validated,
+        computed: {
+          isHighConfidence: validated.confidence > 0.8,
+          category: validated.class === 'positive' ? 'positive' : 'negative'
+        }
+      };
+    }
+  }
+});
+```
+
+#### Use Cases
+
+**1. Output Field Mapping**
+
+Map output fields to standardized names:
+
+```typescript
+transformations: {
+  postParse: (parsed, metadata) => {
+    // Map from LLM output to standardized format
+    const mapping = {
+      'class': 'label',
+      'confidence': 'score',
+      'reason': 'explanation'
+    };
+    
+    const mapped: Record<string, any> = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      const mappedKey = mapping[key] || key;
+      mapped[mappedKey] = value;
+    }
+    
+    return { ...parsed, ...mapped };
+  }
+}
+```
+
+**2. Data Normalization**
+
+Normalize data formats across different providers:
+
+```typescript
+transformations: {
+  postParse: (parsed, metadata) => {
+    // Normalize confidence scores to 0-1 range
+    if (parsed.confidence && parsed.confidence > 1) {
+      parsed.confidence = parsed.confidence / 100;
+    }
+    
+    // Normalize class names to lowercase
+    if (parsed.class) {
+      parsed.class = parsed.class.toLowerCase();
+    }
+    
+    return parsed;
+  }
+}
+```
+
+**3. Add Computed Fields**
+
+Add derived/computed fields:
+
+```typescript
+transformations: {
+  postValidate: (validated, metadata) => {
+    return {
+      ...validated,
+      metadata: {
+        ...validated.metadata,
+        computed: {
+          isPositive: validated.class === 'positive',
+          confidenceLevel: validated.confidence > 0.8 ? 'high' : 'low',
+          processedAt: new Date().toISOString()
+        }
+      }
+    };
+  }
+}
+```
+
+**4. Response Structure Transformation**
+
+Restructure response data:
+
+```typescript
+transformations: {
+  postParse: (parsed, metadata) => {
+    // Transform flat structure to nested
+    return {
+      result: {
+        classification: {
+          label: parsed.class,
+          confidence: parsed.confidence
+        },
+        metadata: {
+          jobId: metadata.jobId,
+          agentId: metadata.agentId
+        }
+      }
+    };
+  }
+}
+```
+
+**5. Clean Raw Text**
+
+Clean and normalize raw text before parsing:
+
+```typescript
+transformations: {
+  preParse: (rawText, metadata) => {
+    // Remove markdown code blocks if present
+    let cleaned = rawText.replace(/```json\n?/g, '').replace(/```\n?/g, '');
+    
+    // Remove leading/trailing whitespace
+    cleaned = cleaned.trim();
+    
+    // Fix common JSON issues
+    cleaned = cleaned.replace(/,(\s*[}\]])/g, '$1'); // Remove trailing commas
+    
+    return cleaned;
+  }
+}
+```
+
+#### Error Handling
+
+Transformation hooks have built-in error handling - if a transformation fails, the gateway logs a warning and continues with the original (untransformed) data. This ensures that transformation errors don't break the request.
+
+```typescript
+// If transformation throws an error, gateway logs:
+// "postParse transformation failed, using original parsed output"
+// and continues with the original data
+```
+
+#### Integration with Instruction Metadata
+
+Combine transformation hooks with instruction metadata for fully metadata-driven systems:
+
+```typescript
+// Fetch metadata
+const metadata = await gateway.getInstructionMetadata('classification/basic');
+
+if (metadata?.defaultOutputMapping) {
+  // Use metadata to configure transformation
+  const response = await gateway.invoke({
+    jobId: 'job-1',
+    agentId: 'agent-1',
+    instructions: 'classification/basic',
+    input: 'This is great!',
+    config: { model: 'gpt-4o' },
+    inferenceType: metadata.outputType,
+    transformations: {
+      postParse: (parsed, reqMetadata) => {
+        // Apply output mapping from metadata
+        const mapped: Record<string, any> = {};
+        for (const [key, mappedKey] of Object.entries(metadata.defaultOutputMapping!)) {
+          if (key in parsed) {
+            mapped[mappedKey] = (parsed as any)[key];
+          }
+        }
+        return { ...parsed, ...mapped };
+      }
+    }
+  });
+}
+```
+
+#### Processing Order
+
+Transformations are applied in this order:
+
+1. **preParse**: Raw text → Transformed raw text
+2. **Parsing**: Transformed raw text → Parsed output (if `inferenceType` provided)
+3. **postParse**: Parsed output → Transformed parsed output
+4. **preValidate**: Transformed parsed output → Pre-validated output (if validation enabled)
+5. **Validation**: Pre-validated output → Validated output (if validation enabled)
+6. **postValidate**: Validated output → Final transformed output
+
+If no `inferenceType` is provided, `postParse` is applied to `parsedContent` instead.
+
+### 8. Content Registry Integration (Instruction Keys)
+
+The gateway integrates with `@xronoces/content-registry` to fetch instructions by key instead of hardcoding them. This enables centralized content management, versioning, and zero-deploy updates.
+
+#### Overview: Two Modes for Instructions
+
+The gateway supports **two modes** for providing instructions to LLMs:
+
+1. **Text Mode (Default)**: Instructions are actual text strings embedded in code
+2. **Key Mode (New)**: Instructions are keys that reference content stored in `@xronoces/content-registry`
+
+Both modes work seamlessly - the gateway automatically detects which mode you're using based on the instruction format.
+
+#### Installation
+
+```bash
+npm install @xronoces/content-registry
+```
+
+**Note**: `@xronoces/content-registry` (v2.14.0+) is automatically installed as a dependency. This version includes simplified APIs for easier integration. 
+
+**Configuration**: Content registry is used when `contentRegistryConfig` is provided in the gateway configuration.
+
+**For Internal Use**: Content-registry auto-initializes from environment variables if available, enabling instructionsBlocks resolution without requiring explicit configuration.
+
+**See**: [Content Resolver — Upstream Guide](./CONTENT_RESOLVER_UPSTREAM_GUIDE.md) for configuration, environment variables, content layout, and upstream checklist.
+
+#### Configuration
+
+```typescript
+import { AIGateway } from '@x12i/ai-gateway';
+
+const gateway = new AIGateway({
+  defaultProvider: 'openai',
+  // Enable content-registry mode
+  enableContentRegistry: true,
+  // Configure content registry
+  contentRegistryConfig: {
+    s3Bucket: 'my-content-registry-bucket',
+    cacheTTL: 3600,  // Cache content for 1 hour
+    redis: {
+      host: 'localhost',
+      port: 6379,
+      password: process.env.REDIS_PASSWORD
+    },
+    // ... other content-registry config options
+  }
+});
+```
+
+#### Mode 1: Text Mode (Automatic - Has Spaces)
+
+**How it works**: Automatically detected when instructions contain whitespace. Used as literal text without any resolution.
+
+**When used automatically**:
+- Instructions contain spaces, tabs, or newlines
+- No content registry lookup performed
+- Fast processing with no external dependencies
+
+**Example**:
+```typescript
+// Text mode - instructions as plain text
+const response = await gateway.invoke({
+  messages: [
+    {
+      role: 'system',
+      content: 'You are a helpful assistant that classifies text into categories: positive, negative, or neutral.'
+    },
+    {
+      role: 'user',
+      content: 'Classify: "This product is amazing!"'
+    }
+  ],
+  jobId: 'job-123'
+});
+```
+
+**Behavior**:
+- Gateway uses the text as-is
+- No content-registry lookup
+- Fast (no network calls)
+
+#### Mode 2: Key Mode (Automatic - No Spaces)
+
+**How it works**: Automatically detected when instructions contain no whitespace. Keys are resolved from content registry.
+
+**When used automatically**:
+- Instructions contain no spaces, tabs, or newlines
+- Content is fetched from configured content registry
+- Supports template variables and dynamic content
+- Fail-closed: unresolvable keys become bad requests
+
+**Example**:
+```typescript
+// Key mode - instructions as keys to content-registry
+const response = await gateway.invoke({
+  messages: [
+    {
+      role: 'system',
+      content: 'classification/basic'  // ✅ Key - will be resolved from content-registry
+    },
+    {
+      role: 'user',
+      content: 'Classify: "This product is amazing!"'
+    }
+  ],
+  jobId: 'job-123',
+  // Optional: variables for template rendering
+  contentVariables: {
+    task: 'classification',
+    context: 'product reviews'
+  }
+});
+```
+
+**What happens behind the scenes**:
+1. Gateway detects `'classification/basic'` is a key (not plain text)
+2. Creates ContentResolver with hierarchical patterns for instruction resolution
+3. ContentResolver resolves content using configurable fallback chains:
+   - `content/instructions/{contentId}` (primary pattern)
+   - Handles consolidated vs individual file resolution
+4. Content-registry returns raw template content with full metadata envelope
+5. Instructions parser renders template with `contentVariables` using Rendrix
+6. Gateway returns rendered instruction text with metadata
+7. Sends the resolved instruction to the LLM
+
+**Template-Based Prompts (Same as Instructions)**:
+Prompts work exactly like instructions - both can be resolved from content-registry using explicit keys with suffixes:
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'professional-answer.instructions',  // Key with suffix
+  prompt: 'professional-answer.prompt',              // Key with suffix
+  input: 'What is the capital of France?',
+  workingMemory: {
+    taskDescription: 'Answer questions professionally'
+  }
+});
+```
+
+**File Structure in Content-Registry**:
+```
+.metadata/
+  content/
+    instructions/
+      professional-answer.instructions.md
+      professional-answer.prompt.md
+```
+
+**Key Features**:
+- Both instructions and prompts use the same memory context (`workingMemory`, `shortTermMemory`, `experienceMemory`, `knowledgeMemory`)
+- Both use the same template rendering system (Rendrix)
+- Both support the same key detection logic (no spaces = key, has spaces = text)
+- Postfix handling (`.instructions` and `.prompt`) is done upstream by AI skills
+
+See [Prompt Template Usage Guide](./docs/PROMPT_TEMPLATE_USAGE.md) for complete documentation.
+
+**Behavior**:
+- Gateway resolves keys automatically using ContentResolver
+- Requires `contentRegistryConfig` to be set
+- Uses hierarchical content resolution with configurable patterns
+- Template rendering handled by dedicated instructions parser
+- Supports complex variable substitution (workingMemory, shortTermMemory, etc.)
+- Keys don't include file extensions (e.g., `classification/basic` not `classification/basic.md`)
+- Access to YAML front matter and version metadata
+- Enhanced error handling with detailed resolution information
+
+#### Content Resolution Patterns
+
+Instruction keys are resolved using configurable hierarchical patterns through the ContentResolver. The resolver tries multiple path patterns in priority order.
+
+**Resolution Pattern Examples**:
+```typescript
+// For instruction key 'classification/basic':
+// Pattern 1: content/instructions/classification/basic
+// Tries: classification/basic.md, classification/basic.txt, etc.
+
+// For instructionsBlocks 'input' with agentId 'agent-1':
+// Pattern 1: content/instructions/agent-1/input
+// Pattern 2: content/instructions/shared/input
+```
+
+**How Resolution Works**:
+1. Key is provided: `"classification/basic"` (no file extension)
+2. ContentResolver applies hierarchical patterns with `{contentType}`, `{contentId}`, etc.
+3. Tries patterns in priority order until content is found
+4. Returns raw template content with metadata
+5. Instructions parser renders templates with Rendrix
+6. Final rendered content sent to LLM
+
+**Key Detection Rules**:
+The gateway automatically detects if a string is a key or plain text:
+
+```typescript
+// ✅ Detected as KEYS (will be resolved from content-registry):
+'classification/basic'           // Path-like structure
+'extraction/entities'             // Contains slashes
+'instructions/path/to/content'    // Already normalized format
+'short-key'                       // Short, no spaces
+
+// ❌ Treated as TEXT (used as-is):
+'You are a helpful assistant...'   // Contains newlines
+'This is a very long instruction that exceeds 200 characters and contains multiple sentences with spaces and newlines...'  // Too long
+'Instruction with spaces'         // Contains spaces (unless very short)
+```
+
+**Detection Logic**:
+- ✅ **Key if**: Contains `/` (path-like) OR (short length < 100 chars AND no spaces)
+- ❌ **Text if**: Contains newlines OR length > 200 chars OR has spaces (for longer strings)
+
+#### Template Variables (Content Registry)
+
+When using instruction keys, you can pass variables for template rendering. Template rendering is handled by Rendrix after fetching content from content-registry.
+
+**How it works**:
+1. Content stored in registry uses template syntax: `{{variableName}}`
+2. Gateway fetches content from content-registry using `fetchContent()`
+3. Gateway uses Rendrix to render the template with your variables
+4. Resolved instruction is used in the LLM request
+
+**Example**:
+
+**Content stored in registry** (`instructions/classification/basic`):
+```
+You are a {{task}} expert. 
+Classify text into the following categories: {{classes}}.
+Provide confidence scores and reasoning.
+```
+
+**Code**:
+```typescript
+const response = await gateway.invoke({
+  messages: [
+    {
+      role: 'system',
+      content: 'classification/basic'  // Key - will be resolved
+    },
+    {
+      role: 'user',
+      content: 'Classify: "This product is amazing!"'
+    }
+  ],
+  contentVariables: {
+    task: 'classification',
+    classes: 'positive, negative, neutral'
+  }
+});
+```
+
+**Resolved instruction** (what the LLM actually receives):
+```
+You are a classification expert. 
+Classify text into the following categories: positive, negative, neutral.
+Provide confidence scores and reasoning.
+```
+
+**Benefits**:
+- Same instruction template, different variables
+- Dynamic instruction generation
+- A/B testing with different variable values
+- Centralized template management
+
+#### Mixed Mode (Text + Keys)
+
+You can mix text and keys in the same request. The gateway automatically handles both:
+
+```typescript
+const response = await gateway.invoke({
+  messages: [
+    {
+      role: 'system',
+      content: 'classification/basic'  // ✅ Key - resolved from content-registry
+    },
+    {
+      role: 'user',
+      content: 'You are analyzing product reviews.'  // ✅ Text - used as-is
+    },
+    {
+      role: 'assistant',
+      content: 'I understand.'
+    },
+    {
+      role: 'user',
+      content: 'Classify: "This product is amazing!"'
+    }
+  ],
+  jobId: 'job-123',
+  contentVariables: {
+    task: 'classification'
+  }
+});
+```
+
+**What happens**:
+- `'classification/basic'` → Detected as key → Resolved from content-registry
+- `'You are analyzing product reviews.'` → Detected as text → Used as-is
+- Other messages → Used as-is
+
+**Use cases**:
+- Mix static instructions (text) with dynamic instructions (keys)
+- Gradually migrate from text mode to key mode
+- Use keys for complex instructions, text for simple ones
+
+#### Content Registry Accessor Methods
+
+The gateway exposes content-registry methods for pre-validation, batch operations, and debugging without making LLM calls:
+
+```typescript
+const gateway = new AIGateway({
+  enableContentRegistry: true,
+  contentRegistryConfig: { github: { ... } }
+});
+
+// Get the underlying content-registry instance
+const registry = gateway.getContentRegistry();
+if (registry) {
+  // Use registry methods directly
+  const content = await registry.getByPath({ 
+    pathKey: 'classification/basic', 
+    category: 'instruction' 
+  });
+}
+
+// Resolve an instruction key with variables (without making LLM call)
+const resolved = await gateway.resolveInstructionKey('classification/basic', {
+  task: 'classification',
+  classes: 'positive, negative, neutral'
+});
+console.log(resolved); // "You are a classification expert. Classify text into: positive, negative, neutral."
+
+// Check if an instruction key exists
+const exists = await gateway.hasInstructionKey('classification/basic');
+if (exists) {
+  // Key exists, safe to use
+}
+
+// Get instruction metadata (structured metadata for metadata-driven systems)
+const metadata = await gateway.getInstructionMetadata('classification/basic');
+if (metadata) {
+  console.log('Output type:', metadata.outputType);           // 'classification'
+  console.log('Required variables:', metadata.requiredVariables); // ['task', 'classes']
+  console.log('Schema:', metadata.outputSchema);              // JSONSchema7
+  console.log('Validation rules:', metadata.validationRules);
+  console.log('Output mapping:', metadata.defaultOutputMapping);
+  console.log('Parse options:', metadata.parseOptions);
+  console.log('Version:', metadata.version);
+}
+```
+
+**Benefits:**
+- **Pre-validation**: Check if keys exist before making requests
+- **Batch operations**: Resolve multiple keys in parallel
+- **Debugging**: Inspect resolved instructions without LLM calls
+- **Consistency**: Use same content-registry instance as gateway
+
+**Note**: All methods return `undefined` or throw errors if `contentRegistryConfig` is not set.
+
+#### Instruction Metadata API (v1.6.9+)
+
+The `getInstructionMetadata()` method returns structured metadata from content-registry, enabling fully metadata-driven inference systems. This is the primary API for accessing instruction configuration without making LLM calls.
+
+**Interface:**
+
+```typescript
+interface InstructionMetadata {
+  instructionKey: string;              // The instruction key (e.g., 'classification/basic')
+  outputType?: string;                // Inference type for parsing (e.g., 'classification')
+  outputSchema?: Record<string, unknown>;  // JSONSchema7 for validation
+  requiredVariables?: string[];        // Required template variables
+  optionalVariables?: string[];        // Optional template variables
+  validationRules?: ValidationRule[];   // Validation rules
+  defaultOutputMapping?: Record<string, string>;  // Output field mapping
+  parseOptions?: {                     // Default parse options
+    question?: string;
+    classes?: string[];
+    [key: string]: unknown;
+  };
+  version?: string;                    // Instruction version
+  [key: string]: unknown;              // Additional metadata preserved
+}
+```
+
+**Use Cases:**
+
+1. **Metadata-Driven Inference**: Fetch metadata to configure inference without hardcoding
+2. **Variable Validation**: Check required/optional variables before making requests
+3. **Schema Validation**: Get output schema for validation
+4. **Output Mapping**: Apply default field mappings from metadata
+5. **Parse Configuration**: Get default parse options for outputs library
+
+**Example: Metadata-Driven System**
+
+```typescript
+const gateway = new AIGateway({
+  enableContentRegistry: true,
+  contentRegistryConfig: { github: { ... } }
+});
+
+// Fetch instruction metadata
+const metadata = await gateway.getInstructionMetadata('classification/basic');
+
+if (metadata) {
+  // Validate required variables
+  const requiredVars = metadata.requiredVariables || [];
+  const providedVars = Object.keys(variables);
+  const missingVars = requiredVars.filter(v => !providedVars.includes(v));
+  
+  if (missingVars.length > 0) {
+    throw new Error(`Missing required variables: ${missingVars.join(', ')}`);
+  }
+  
+  // Use metadata to configure inference
+  const response = await gateway.invoke({
+    jobId: 'job-1',
+    agentId: 'agent-1',
+    instructions: 'classification/basic',
+    input: 'This is great!',
+    config: { model: 'gpt-4o' },
+    // Use metadata to configure parsing
+    inferenceType: metadata.outputType,
+    parseOptions: {
+      ...metadata.parseOptions,
+      classes: variables.classes || metadata.parseOptions?.classes
+    },
+    validateOutputSchema: !!metadata.outputSchema
+  });
+  
+  // Apply output mapping if provided
+  let output = response.metadata.parsedOutput;
+  if (metadata.defaultOutputMapping && output) {
+    const mapped: Record<string, any> = {};
+    for (const [key, mappedKey] of Object.entries(metadata.defaultOutputMapping)) {
+      if (key in output) {
+        mapped[mappedKey] = (output as any)[key];
+      }
+    }
+    output = { ...output, ...mapped };
+  }
+}
+```
+
+**Metadata Storage in Content-Registry:**
+
+Store metadata in your content-registry files:
+
+```json
+{
+  "messages": [
+    {
+      "role": "system",
+      "content": "You are a {{task}} expert. Classify text into: {{classes}}."
+    }
+  ],
+  "metadata": {
+    "outputType": "classification",
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "class": { "type": "string" },
+        "confidence": { "type": "number" }
+      }
+    },
+    "requiredVariables": ["task", "classes"],
+    "optionalVariables": ["context"],
+    "validationRules": [
+      {
+        "name": "confidence-threshold",
+        "type": "range",
+        "config": { "min": 0, "max": 1 }
+      }
+    ],
+    "defaultOutputMapping": {
+      "class": "label",
+      "confidence": "score"
+    },
+    "parseOptions": {
+      "classes": ["positive", "negative", "neutral"]
+    },
+    "version": "v1.0.0"
+  }
+}
+```
+
+**Return Value:**
+
+- Returns `InstructionMetadata | null` (not `undefined`)
+- Returns `null` if content-registry is not enabled
+- Returns `null` if instruction key not found
+- Preserves all additional metadata fields from content-registry
+
+#### Complete Example: Using Content Registry
+
+**Step 1: Store content in content-registry**
+
+```typescript
+import { ContentRegistry } from '@xronoces/content-registry';
+
+const registry = new ContentRegistry({
+  s3Bucket: 'my-content-bucket',
+  // ... config
+});
+
+// Store instruction content
+await registry.createPrompt({
+  id: 'instructions/classification/basic',
+  name: 'Basic Classification',
+  version: 'v1.0.0',
+  messages: [
+    {
+      role: 'system',
+      content: 'You are a {{task}} expert. Classify text into: {{classes}}.'
+    }
+  ]
+});
+```
+
+**Step 2: Use key mode in gateway**
+
+```typescript
+const gateway = new AIGateway({
+  enableContentRegistry: true,
+  contentRegistryConfig: {
+    s3Bucket: 'my-content-bucket',
+    // ... same config as registry
+  }
+});
+
+// Use key instead of text
+const response = await gateway.invoke({
+  messages: [
+    {
+      role: 'system',
+      content: 'classification/basic'  // ✅ Key - automatically resolved
+    },
+    {
+      role: 'user',
+      content: 'Classify: "This is great!"'
+    }
+  ],
+  contentVariables: {
+    task: 'classification',
+    classes: 'positive, negative, neutral'
+  }
+});
+```
+
+**Step 3: Update content without code changes**
+
+```typescript
+// Update instruction in content-registry (no code deployment needed!)
+await registry.createPrompt({
+  id: 'instructions/classification/basic',
+  version: 'v1.1.0',  // New version
+  messages: [
+    {
+      role: 'system',
+      content: 'You are an advanced {{task}} expert. Classify text with high accuracy into: {{classes}}.'
+    }
+  ]
+});
+
+// Gateway automatically uses latest version
+// No code changes needed!
+```
+
+#### Benefits
+
+- **Centralized Management**: All instructions stored in one place (S3 + MongoDB via content-registry)
+- **Versioning**: Track changes and rollback if needed (content-registry supports versioning)
+- **Zero-Deploy Updates**: Update instructions without code changes
+- **A/B Testing**: Test different instruction versions
+- **Template Support**: Use Handlebars templates with variables
+- **Caching**: Instructions are cached for performance (Redis via content-registry)
+- **Backward Compatible**: Text mode still works (default) - no breaking changes
+- **Automatic Detection**: Gateway automatically detects keys vs text - no manual mode switching
+
+#### Error Handling
+
+If a key cannot be resolved, the gateway falls back to using the key as text and logs a warning:
+
+```typescript
+// If key 'invalid/key' doesn't exist in registry:
+const response = await gateway.invoke({
+  messages: [
+    {
+      role: 'system',
+      content: 'invalid/key'  // Will fallback to using 'invalid/key' as text
+    }
+  ]
+});
+
+// Gateway logs:
+// WARN: Failed to resolve instruction key: invalid/key
+// The key will be used as-is (text mode)
+```
+
+#### Advanced: Custom Instruction Resolver
+
+You can also use the `InstructionResolver` directly:
+
+```typescript
+import { InstructionResolver } from '@x12i/ai-gateway';
+
+const resolver = new InstructionResolver({
+  enableContentRegistry: true,
+  contentRegistryConfig: {
+    s3Bucket: 'my-bucket',
+    // ... config
+  }
+});
+
+// Resolve a key
+const instructions = await resolver.resolveInstructions(
+  'classification/basic',
+  { task: 'classification' }
+);
+
+console.log(instructions);  // Resolved instruction text
+```
+
+### 9. Contract Output Parsing (v6.3.1+)
+
+The gateway supports contract output parsing and validation, where AI responses are parsed against expected schemas and the results are stored in activity records for compliance monitoring and debugging.
+
+#### How It Works
+
+1. **Schema Input**: Provide an optional `expectedSchema` parameter in your gateway calls
+2. **Response Parsing**: AI responses are automatically parsed using flex-md against the expected schema
+3. **Activity Storage**: Parsed results are stored in activity records under `content.contractOutput`
+4. **Status Tracking**: Compliance status is tracked in `content.outputStatus`
+
+#### Basic Usage
+
+```typescript
+import { AIGateway } from '@x12i/ai-gateway';
+
+const gateway = new AIGateway({ /* config */ });
+
+// Call with expected schema for contract validation
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-456',
+  instructions: 'Analyze the following text and provide structured output.',
+
+  // Provide expected schema for contract output parsing
+  expectedSchema: {
+    description: "Analysis results with key insights and recommendations",
+    formatHint: "### Key Insights\n[insights]\n\n### Recommendations\n[recommendations]"
+  },
+
+  messages: [{ role: 'user', content: 'Analyze this product review...' }]
+});
+
+// Activity record will contain:
+// content.contractOutput: { keyInsights: "...", recommendations: "..." }
+// content.outputStatus: "different" (parsed successfully)
+```
+
+#### Schema Format
+
+The `expectedSchema` parameter accepts a `StructuredTextSpec`:
+
+```typescript
+interface StructuredTextSpec {
+  description: string;        // Human-readable description of expected output
+  formatHint?: string;        // Optional flex-md format specification
+}
+```
+
+#### Activity Record Structure
+
+When contract output parsing is enabled, activity records include additional fields:
+
+```json
+{
+  "content": {
+    "contractOutput": {
+      // Parsed structured data from AI response
+      // Empty object {} if parsing fails
+    },
+    "outputStatus": "ok" | "different" | undefined
+  }
+}
+```
+
+#### Status Values
+
+- `"ok"`: Contract output matches expected schema structure perfectly
+- `"different"`: Contract output parsed successfully but differs from expected schema
+- `undefined`: No schema validation performed (when `expectedSchema` not provided)
+
+#### Use Cases
+
+**Contract Compliance Monitoring:**
+```typescript
+// Ensure AI responses follow expected structure
+const result = await gateway.call({
+  messages: [...],
+  expectedSchema: {
+    description: "Professional answer with short summary and detailed analysis",
+    formatHint: "### Short Answer\n[summary]\n\n### Full Answer\n[analysis]"
+  }
+});
+```
+
+**Debugging Response Parsing:**
+```typescript
+// When AI doesn't follow expected format, contractOutput will be {}
+// Check activity records to debug parsing issues
+const result = await gateway.call({
+  messages: [...],
+  expectedSchema: { /* schema */ }
+});
+// If parsing fails: content.contractOutput = {}
+// If parsing succeeds: content.contractOutput = { parsed: "data" }
+```
+
+#### Integration with Activity Tracking
+
+Contract output parsing integrates seamlessly with `@x12i/activix` v5 (xronox-activitix):
+
+- **Automatic Processing**: Parsing happens automatically when `expectedSchema` is provided
+- **Error Resilience**: Parsing failures don't break activity recording
+- **Performance**: Minimal overhead when schema is provided
+- **Backward Compatibility**: Existing calls work unchanged
+
+#### Advanced Configuration
+
+```typescript
+// Detailed schema specification
+const schema = {
+  description: "Structured analysis with multiple sections",
+  formatHint: `### Executive Summary
+[summary]
+
+### Detailed Analysis
+[analysis]
+
+### Recommendations
+[recommendations]
+
+### Confidence Level
+[level]`
+};
+
+const response = await gateway.invoke({
+  aiRequestId: 'analysis-req-001',
+  jobId: 'analysis-123',
+  agentId: 'analyzer-bot',
+  sessionId: 'sess-analyzer',
+  instance: { instanceId: 'analyzer-1', type: 'gateway' },
+  instructions: 'Analyze the provided data...',
+  expectedSchema: schema,
+  messages: [{ role: 'user', content: data }]
+});
+```
+
+## API Reference
+
+### AIGateway
+
+Enhanced gateway class with production-ready features.
+
+#### Constructor
+
+```typescript
+const gateway = new AIGateway(config?: GatewayConfig);
+```
+
+**GatewayConfig Options:**
+
+```typescript
+interface GatewayConfig extends RouterConfig {
+  usageTier?: UsageTier;              // Default: 'tier-3'
+  enableActivityTracking?: boolean;   // Default: true
+  enableUsageTracking?: boolean;      // Default: true
+  enableLogging?: boolean;            // Default: true
+  contentRegistryConfig?: any;         // Content registry config for instruction key resolution
+  logger?: LogsGateway;               // Custom logger
+  activityTracker?: Activix;           // Custom Activix v5 instance (match collection names: ai-activities, bad-requests, skill-executions)
+  packageName?: string;               // Default: 'AI_GATEWAY'
+  // ... all RouterConfig options
+}
+```
+
+#### Methods
+
+- `register(provider: LLMProviderInterface): void` - Register a provider
+- `unregister(providerName: LLMProvider): void` - Unregister a provider
+- `getProvider(providerName: LLMProvider)` - Get a provider instance
+- `listProviders(): LLMProvider[]` - List all registered providers
+- `invoke(request: AIRequest): Promise<EnhancedLLMResponse>` - Invoke with structured output (requires `objectTypes`)
+- `invokeChat(request: ChatRequest): Promise<EnhancedLLMResponse>` - Invoke for chat/conversational requests (optional `objectTypes`)
+- `setDefaultProvider(provider: LLMProvider): void` - Set the default provider
+- `setFallbackChain(chain: LLMProvider[]): void` - Configure fallback chain
+- `addRequestInterceptor(interceptor: RequestInterceptor): void` - Add request interceptor
+- `addResponseInterceptor(interceptor: ResponseInterceptor): void` - Add response interceptor
+- `checkHealth(provider: LLMProvider): Promise<HealthCheckResult>` - Check provider health
+- `checkAllHealth(): Promise<Map<LLMProvider, HealthCheckResult>>` - Check all providers' health
+- `getRouter(): LLMProviderRouter` - Get underlying router instance
+- `getLogger(): LogsGateway` - Get logger instance
+- `setActivityManager(activityManager)` - Advanced/test hook to replace the internal activity manager; typical apps inject **`Activix` via `activityTracker`** in the constructor instead
+- `getContentRegistry(): ContentRegistry | undefined` - Get underlying content-registry instance (returns undefined if not enabled)
+- `resolveInstructionKey(key: string, variables?: Record<string, unknown>): Promise<string>` - Resolve instruction key with variables (without making LLM call)
+- `hasInstructionKey(key: string): Promise<boolean>` - Check if instruction key exists in content-registry
+- `getInstructionMetadata(key: string): Promise<InstructionMetadata | null>` - Get structured instruction metadata from content-registry (v1.6.9+)
+- `generateTaskTypeId(instructions: string): Promise<string>` - Generate taskTypeId from instructions (instance method)
+- `static generateTaskTypeId(instructions: string, options?: { contentRegistryConfig?, agentId? }): Promise<string>` - Generate taskTypeId from instructions (static method)
+- `optimizeInstructions(originalInstructions: string, options?: OptimizeInstructionsOptions): Promise<InstructionOptimizationResult>` - Optimize AI instructions using AI (v3.0.4+)
+- `testInstructions(instructions: string, testInput: string, expectedSchema?: Record<string, unknown>, options?: TestInstructionsOptions): Promise<TestInstructionsResult>` - Test instructions by running them and analyzing responses (v3.0.4+)
+- `generateRequestReport(request: AIRequest): Promise<RequestReport>` - Generate comprehensive request report with validation, examples, and structured text information (v3.0.6+)
+
+### ChatRequest and AIRequest
+
+**⚠️ BREAKING CHANGE**: The old `EnhancedLLMRequest` type has been removed. Use `ChatRequest` or `AIRequest` instead.
+
+**Two Request Types:**
+
+1. **`ChatRequest`** - For chat/conversational requests where `objectTypes` is optional
+2. **`AIRequest`** - For structured output requests where `objectTypes` is required
+
+#### StructuredTextSpec (v6.3.1+)
+
+Interface for defining expected output schemas used in contract output parsing:
+
+```typescript
+interface StructuredTextSpec {
+  description: string;        // Human-readable description of expected output structure
+  formatHint?: string;        // Optional flex-md format specification for parsing guidance
+}
+```
+
+#### ChatRequest
+
+Base request interface for chat/conversational requests. Use with `invokeChat()` method.
+
+```typescript
+interface ChatRequest extends Omit<LLMRequest, 'messages'> {
+  jobId: string;                     // Required for context propagation and activity tracking
+  agentId: string;                   // Required agent identifier
+  instructions: string;              // Required instructions (key or text)
+  taskId?: string;                   // Optional task identifier
+  taskTypeId?: string;               // Optional task type ID (auto-generated from instructions MD5 if not provided)
+  graphId?: string;                  // Optional graph identifier for graph execution context
+  nodeId?: string;                   // Optional node identifier for graph execution context
+  coreSkillId?: string;              // Optional alternative node identifier for graph execution context
+  prompt?: string;                   // Optional prompt key or text (resolved from content-registry if key, parsed as template if text)
+  input?: string;                    // Optional input text
+  context?: string;                   // Optional context text (template with workingMemory)
+  workingMemory?: unknown;            // Optional template variables for Rendrix
+  expectedSchema?: StructuredTextSpec; // Optional schema for contract output parsing (v6.3.1+)
+  inferenceType?: string;             // Optional inference type for outputs library parsing
+  parseOptions?: Record<string, unknown>;  // Optional parse options for outputs library
+  validateOutputSchema?: boolean;     // Optional schema validation flag
+  transformations?: ResponseTransformationConfig;  // Optional response transformation hooks (v1.6.9+)
+  config?: any;                      // LLM config (model, temperature, etc.)
+  modelConfig?: ModelConfig;          // Model configuration (modelConfig > config > gateway defaults)
+  objectTypes?: Array<{              // Optional object types for structured output
+    type: string;
+    schema?: Record<string, unknown>;
+    whenToUse: string;
+    description?: string;
+  }>;
+}
+```
+
+#### AIRequest
+
+Request interface for structured output requests. **Extends `BaseLLMRequest`** with required `objectTypes`. Use with `invoke()` method.
+
+```typescript
+interface AIRequest extends BaseLLMRequest {
+  // REQUIRED - main expected output structure
+  // Can be string (standard type name) or object (custom type with schema)
+  primaryObjectType: string | {
+    type: string;                    // Required: object type identifier
+    schema?: Record<string, unknown>; // Optional: JSON schema (required for custom types)
+    whenToUse: string;               // Required: guidance on when to use this type
+    description?: string;            // Optional: description
+  };
+
+  expectedSchema?: StructuredTextSpec; // Optional schema for contract output parsing (v6.3.1+)
+  
+  // Optional - alternative output structures
+  // Each item can be string (standard type name) or object (custom type with schema)
+  secondaryObjectTypes?: Array<string | {
+    type: string;
+    schema?: Record<string, unknown>;
+    whenToUse: string;
+    description?: string;
+  }>;
+  
+  // Output mode configuration (v3.0.5+)
+  outputMode?: 'json' | 'structured-text' | 'two-step';  // Default: 'json'
+  instructionFormat?: 'json-schema' | 'structured-text-spec';  // Default: 'json-schema'
+  structuredTextSpec?: {             // Required when instructionFormat is 'structured-text-spec'
+    description: string;              // Free-form description of output structure
+    formatHint?: string;              // Optional format hint (markdown, yaml, etc.)
+  };
+  conversionInstructions?: string;   // Optional custom conversion instructions for two-step mode
+  
+  // Optional graph execution fields (also available via BaseLLMRequest)
+  masterSkillId?: string;            // Optional graph identifier (maps to runContext.graphId when persisted)
+  skillId?: string;                  // Optional node identifier (maps to runContext.nodeId when persisted)
+  masterSkillActivityId?: string;    // Optional parent skill activity ID (preserved in identity)
+}
+```
+
+**Note:** `AIRequest` extends `BaseLLMRequest`, which includes optional graph execution fields (`graphId`, `nodeId`, `coreSkillId`). For graph execution context, you can use either `masterSkillId`/`skillId` (AIRequest only) or `graphId`/`nodeId` (available on all request types). See [Graph Execution Support](./docs/GRAPH_EXECUTION_SUPPORT.md) for details.
+
+**Key Differences:**
+- `ChatRequest`: `objectTypes` is **NOT supported** - use with `invokeChat()` for conversational requests
+- `AIRequest`: `objectTypes` is **REQUIRED** - use with `invoke()` for structured output
+
+**⚠️ BREAKING CHANGE**: `invoke()` now requires `objectTypes`. For requests without structured output, use `invokeChat()` instead.
+
+**Output Modes (v3.0.5+):**
+
+The gateway supports three output modes, each with two instruction formats:
+
+1. **JSON Output Mode** (`outputMode: 'json'` - default):
+   - Expects JSON response from LLM
+   - Parses response as JSON object
+   - Works with both instruction formats
+
+2. **Structured Text Output Mode** (`outputMode: 'structured-text'`):
+   - Expects structured text (not JSON) - can be stories, narratives, free-form text
+   - Does NOT parse as JSON
+   - Content remains as string
+   - Works with both instruction formats
+   - **Auto-Extraction**: When `outputMode: 'structured-text'` is set and no explicit format (`flexMdFormat` or `primaryObjectType`) is provided, the gateway automatically extracts and validates the output format specification from the instruction template's "OUTPUT FORMAT" section (v3.3.3+)
+
+3. **Two-Step Conversion Mode** (`outputMode: 'two-step'`):
+   - Step 1: Get structured text response
+   - Step 2: Automatically convert structured text to JSON using internal conversion instructions
+   - Returns JSON response (from step 2)
+
+**Instruction Formats:**
+
+1. **JSON Schema Format** (`instructionFormat: 'json-schema'` - default):
+   - Instructions include JSON schema embedded
+   - Current behavior - schema is injected into instructions
+
+2. **Structured Text Spec Format** (`instructionFormat: 'structured-text-spec'`):
+   - Instructions include free-form description of desired output structure
+   - Example: "a story with character, setting, and conflict"
+   - Requires `structuredTextSpec` field
+
+**Minimal AIRequest Example (Custom Type):**
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-1',
+  instructions: 'professional-answer/general', // Content registry key
+  input: 'What is the capital of France?',
+  primaryObjectType: {
+    type: 'professional-answer',
+    whenToUse: 'For professional Q&A responses'
+    // schema is optional
+  },
+  modelConfig: {
+    model: 'gpt-4o',
+    provider: 'openai'
+  }
+});
+```
+
+**Using modelConfig for Model Selection:**
+```typescript
+// modelConfig provides structured model configuration
+// Priority: modelConfig > config > gateway defaults
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-1',
+  instructions: 'Analyze the data',
+  primaryObjectType: 'sentiment-analysis',
+  modelConfig: {
+    model: 'gpt-4-turbo',
+    provider: 'openai',
+    temperature: 0.7,
+    maxTokens: 2000,
+    topP: 0.9
+  }
+});
+```
+
+**modelConfig Overrides config:**
+```typescript
+// modelConfig takes precedence over config
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-1',
+  instructions: 'Process request',
+  primaryObjectType: 'classification',
+  config: {
+    model: 'gpt-3.5-turbo',  // This will be overridden
+    temperature: 0.5  // This will be overridden
+  },
+  modelConfig: {
+    model: 'gpt-4-turbo',  // This takes precedence
+    temperature: 0.9  // This takes precedence
+  }
+});
+// Result: Uses gpt-4-turbo with temperature 0.9
+```
+
+**Standard Object Type Example (v3.0.6+):**
+```typescript
+// Use standard type from @x12i/outputs-library by name
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-1',
+  instructions: 'Analyze the sentiment of this text',
+  input: 'I love this product!',
+  primaryObjectType: 'sentiment-analysis', // Standard type name - no schema needed!
+  config: {
+    model: 'gpt-5-nano',
+    provider: 'openai'
+  }
+});
+
+// Standard types include:
+// - Pre-defined schemas
+// - Few-shot examples (automatically used for better results)
+// - Validation instructions
+// - Structured text formatting guidelines
+```
+
+**Available Standard Types:**
+- `sentiment-analysis` - Sentiment analysis with confidence and reasoning
+- `classification` - General text classification
+- `extraction` - Structured data extraction
+- `question-answer` - Question answering
+- `email-extraction` - Email address extraction
+- `person-extraction` - Person information extraction
+- `location-extraction` - Location name extraction
+- `weather-report` - Weather information structure
+- And 10+ more types (see `@x12i/outputs-library` documentation)
+
+**Note**: Standard types require content-registry to be configured (`contentRegistryConfig`). Custom types work without content-registry.
+
+### Output Format Validation
+
+**Output Format Validation:**
+
+The gateway validates output format specifications from instruction templates before sending to LLM. Instructions should include an "OUTPUT FORMAT" section that describes the expected output structure.
+
+**Important: Communication Flow with LLM**
+
+The gateway uses **flex-md (Markdown-based format)** for all LLM communication, while returning proper JavaScript objects to your code:
+
+1. **To LLM**: Instructions should include output format specifications - the gateway validates these but does not inject them
+2. **From LLM**: LLM responds with flex-md (Markdown) containing structured data in fenced blocks
+3. **Gateway Processing**: Gateway automatically extracts structured data from flex-md (Markdown) fenced blocks using flex-md SDK
+4. **To Your Code**: Gateway returns parsed JavaScript objects in `response.parsedContent` - you always get clean objects, never raw Markdown
+
+**Why flex-md (Markdown) Instead of Direct JSON?**
+
+- **flex-md is Markdown-based**: We use flex-md format, which is built on Markdown, for all LLM communication
+- **Better LLM Compliance**: LLMs are more reliable at following Markdown format instructions than raw JSON
+- **Flexibility**: Allows LLMs to structure responses in Markdown while embedding structured data
+- **Robust Extraction**: Multiple fallback methods ensure structured data is extracted from Markdown even if format varies slightly
+- **Consistent API**: Your code always receives clean JavaScript objects, regardless of how the LLM formatted its Markdown response
+
+**Output Format Validation Process:**
+
+1. Gateway extracts output format from instruction templates (if present)
+2. Validates format specification using flex-md SDK
+3. Checks compliance level against minimum required level (from `FLEX_MD_MIN_COMPLIANCE_LEVEL` environment variable)
+4. If validation fails and minimum level > L0, request is rejected with error
+5. If validation fails and minimum level is L0, request continues with warning
+6. Output format information is included in response metadata and activity tracking
+
+**Example:**
+
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-1',
+  instructions: 'Classify the sentiment of this text',
+  input: 'This product is amazing!',
+  primaryObjectType: {
+    type: 'classification',
+    schema: {
+      type: 'object',
+      properties: {
+        sentiment: {
+          type: 'string',
+          enum: ['positive', 'negative', 'neutral'],
+          description: 'The sentiment classification'
+        },
+        confidence: {
+          type: 'number',
+          minimum: 0,
+          maximum: 1,
+          description: 'Confidence score'
+        }
+      },
+      required: ['sentiment', 'confidence']
+    },
+    whenToUse: 'For sentiment classification',
+    description: 'Simple sentiment classification'
+  },
+  config: { model: 'gpt-5-nano', provider: 'openai' }
+});
+
+// What the LLM receives (system message - using flex-md/Markdown format):
+// OUTPUT FORMAT:
+// Output Format: classification
+// Simple sentiment classification
+//
+// Return structured data with the following structure:
+// [Schema with properties and descriptions]
+// IMPORTANT: Return your answer as structured data inside the markdown fenced block.
+//
+// What the LLM might return (flex-md/Markdown):
+// ```markdown
+// {"sentiment": "positive", "confidence": 0.95}
+// ```
+//
+// What you receive (response.parsedContent):
+// { sentiment: "positive", confidence: 0.95 }  // Clean JavaScript object (not Markdown)
+```
+
+**Structured Data Extraction Process:**
+
+The gateway uses flex-md (Markdown-based) for communication and extracts structured data from Markdown responses using multiple methods (in order of preference):
+
+1. **flex-md SDK**: Uses `extractFencedBlocks()` and `detectJsonAll()` to extract structured data from flex-md (Markdown) fenced blocks
+2. **Manual Regex Fallback**: Extracts structured data from Markdown fenced blocks if flex-md SDK methods fail
+3. **Response Repair (prod only)**: Uses a minimal in-gateway fallback repair (warn-logged) to recover JSON from malformed Markdown/prose. In `mode=debug`, failures throw immediately.
+
+**Result**: You always receive clean JavaScript objects in `response.parsedContent`, never raw Markdown text.
+
+**Output Format Validation Configuration:**
+
+Set the minimum compliance level using the `FLEX_MD_MIN_COMPLIANCE_LEVEL` environment variable:
+
+```bash
+export FLEX_MD_MIN_COMPLIANCE_LEVEL=L0  # Default: allows anything
+export FLEX_MD_MIN_COMPLIANCE_LEVEL=L1  # Requires section headings
+export FLEX_MD_MIN_COMPLIANCE_LEVEL=L2  # Requires fenced block + sections
+export FLEX_MD_MIN_COMPLIANCE_LEVEL=L3  # Maximum strictness
+```
+
+- **L0 (default)**: No format validation required - allows any output format
+- **L1+**: Format specification required in instructions - validation errors will reject requests if format is missing or invalid
+
+**Transforming Objects to Instruction Blocks:**
+
+The gateway automatically transforms instruction blocks (from `instructions-blocks.json` or content-registry) into system message instructions. This allows you to configure instruction behavior declaratively without hardcoding.
+
+**Supported Features:**
+
+1. **Nested Instruction Blocks**: Access nested properties using dot notation
+   - `input.inputPrefix` - Prefix added before user input
+   - `reinforcement.inputAlreadyProvided` - Reinforcement rules
+
+2. **Template Resolution**: Instruction blocks can contain template variables that get resolved with request context
+   - `{{taskDescription}}` - Replaced with task description
+   - `{{input}}` - Replaced with actual input value
+
+3. **Compliance Level Enforcement**: Use `flexMdComplianceLevel` (L0-L3) to automatically apply appropriate markdown enforcement rules
+   - L0: Plain Markdown (minimum structure)
+   - L1: Sectioned Markdown (headings required)
+   - L2: Single-container Markdown (fenced block required) - **Default**
+   - L3: Fully-typed Markdown (strict formatting rules)
+
+4. **Automatic Block Selection**: The gateway automatically selects the right instruction blocks based on:
+   - Request type (AIRequest vs ChatRequest)
+   - Presence of `primaryObjectType` or `flexMdFormat`
+   - Compliance level specified
+   - Agent ID and Task Type ID (for content-registry resolution)
+
+**Example: Output Format in Instructions**
+
+Instructions should include output format specifications:
+
+```markdown
+## Task
+Classify the sentiment of the input text.
+
+## OUTPUT FORMAT
+Return your answer in the following structure:
+
+Sentiment:
+- One of: positive, negative, neutral
+
+Confidence:
+- A number between 0 and 1
+
+Reasoning:
+- Brief explanation of your classification
+```
+
+The gateway will:
+1. Extract and validate the output format from instructions
+2. Check compliance level against `FLEX_MD_MIN_COMPLIANCE_LEVEL`
+3. Include format information in response metadata (`response.metadata.outputFormat`)
+4. Track format information in activity records
+// 2. Retrieves output.complianceLevels.L2 rules
+// 3. Applies markdownEnforcement, structuralRule, and immediateComplianceRule
+// 4. Adds these to the system message
+```
+
+**Example: Custom Instruction Blocks Structure**
+
+The `instructions-blocks.json` file supports nested objects that get automatically resolved:
+
+```json
+{
+  "input": {
+    "inputPrefix": "INPUT DATA (process this now):",
+    "inputRecognitionRule": "The user message below is the complete input to process."
+  },
+  "output": {
+    "complianceLevels": {
+      "L2": {
+        "markdownEnforcement": "Return your entire answer inside a single ```markdown fenced block.",
+        "structuralRule": "No conversational text before or after the fenced block.",
+        "immediateComplianceRule": "Immediately return your answer inside a single ```markdown fenced block."
+      }
+    }
+  },
+  "reinforcement": {
+    "inputAlreadyProvided": "The input has been provided in the user message. Process it immediately.",
+    "noConversation": "You are not having a conversation."
+  }
+}
+```
+
+**Resolution Priority:**
+
+1. **Content Registry** (highest): `instructions/{agentId}/{taskTypeId}/{blockPath}`
+2. **Content Registry (agent-level)**: `instructions/{agentId}/{blockPath}`
+3. **Default JSON File**: `src/defaults/instructions-blocks.json`
+4. **Hardcoded Fallbacks**: Built-in defaults if file loading fails
+
+**How Blocks Are Transformed:**
+
+- **System Message**: Instruction blocks are combined with user instructions, OUTPUT FORMAT, and compliance rules
+- **User Message**: Input blocks (like `inputPrefix`) are prepended to user input
+- **Template Variables**: All `{{variable}}` placeholders are resolved using request context
+- **Nested Access**: Dot notation (e.g., `output.complianceLevels.L2`) automatically traverses nested objects
+
+**AIRequest with Schema:**
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-1',
+  instructions: 'professional-answer/general',
+  input: 'User question here',
+  inferenceType: 'professional-answer',
+  objectTypes: [
+    {
+      type: 'professional-answer',
+      whenToUse: 'For professional Q&A responses',
+      description: 'Professional answer JSON structure',
+      schema: {
+        type: 'object',
+        properties: {
+          answer: { type: 'string' },
+          reasoning: { type: 'string' },
+          citations: { type: 'array', items: { type: 'string' } }
+        },
+        required: ['answer']
+      }
+    }
+  ],
+  validateOutputSchema: true,
+  config: {
+    model: 'gpt-4o',
+    provider: 'openai'
+  }
+});
+```
+
+**Content Registry + AIRequest Pattern (Recommended):**
+
+When using content-registry with AIRequest, the gateway automatically:
+1. Resolves instruction keys from content-registry
+2. Fetches instruction metadata (outputType, outputSchema)
+3. Enforces JSON response format (`response_format: { type: 'json_object' }`)
+4. Validates responses against schema if `validateOutputSchema: true`
+
+```typescript
+// Instruction stored in content-registry at: content/instructions/professional-answer/general.md
+// Metadata can include: outputType, outputSchema, validationRules
+
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-1',
+  instructions: 'professional-answer/general', // Content registry key
+  input: 'User question',
+  inferenceType: 'professional-answer',
+  objectTypes: [
+    {
+      type: 'professional-answer',
+      whenToUse: 'For professional Q&A responses',
+      // Schema can come from instruction metadata or be provided here
+      schema: instructionMetadata?.outputSchema || {
+        type: 'object',
+        properties: { answer: { type: 'string' } }
+      }
+    }
+  ],
+  validateOutputSchema: true,
+  config: {
+    model: 'gpt-4o',
+    provider: 'openai'
+  }
+});
+```
+
+**Output Modes Examples (v3.0.5+):**
+
+**1. JSON Output Mode (Default):**
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'agent-1',
+  instructions: 'Answer the question',
+  prompt: 'What is the capital of France?',
+  primaryObjectType: {
+    type: 'question-answer',
+    schema: {
+      answer: { type: 'string' },
+      confidence: { type: 'number' }
+    },
+    whenToUse: 'For Q&A responses'
+  },
+  outputMode: 'json',  // Default - expects JSON response
+  instructionFormat: 'json-schema',  // Default - includes JSON schema in instructions
+  config: { model: 'gpt-5-nano', provider: 'openai' }
+});
+// Response.parsedContent will be a JSON object
+```
+
+**2. Structured Text Output Mode:**
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'story-teller',
+  instructions: 'Write a short story',
+  prompt: 'Create a story about a brave knight',
+  primaryObjectType: {
+    type: 'story',
+    whenToUse: 'For narrative content'
+  },
+  outputMode: 'structured-text',  // Expects structured text, not JSON
+  instructionFormat: 'structured-text-spec',
+  structuredTextSpec: {
+    description: 'A story with a character, setting, conflict, and resolution',
+    formatHint: 'markdown'  // Optional
+  },
+  config: { model: 'gpt-5-nano', provider: 'openai' }
+});
+// Response.content will be structured text (string)
+// Response.parsedContent will be undefined
+```
+
+**3. Two-Step Conversion Mode:**
+```typescript
+const response = await gateway.invoke({
+  jobId: 'job-123',
+  agentId: 'story-converter',
+  instructions: 'Write a detailed story',
+  prompt: 'Create a story about space exploration',
+  primaryObjectType: {
+    type: 'story',
+    schema: {
+      character: { type: 'string' },
+      setting: { type: 'string' },
+      conflict: { type: 'string' },
+      resolution: { type: 'string' }
+    },
+    whenToUse: 'For structured stories'
+  },
+  outputMode: 'two-step',  // Step 1: Get structured text, Step 2: Convert to JSON
+  instructionFormat: 'structured-text-spec',
+  structuredTextSpec: {
+    description: 'A story with character, setting, conflict, and resolution'
+  },
+  // Optional: Custom conversion instructions
+  // conversionInstructions: 'Your custom conversion instructions here',
+  config: { model: 'gpt-5-nano', provider: 'openai' }
+});
+// Step 1: LLM generates structured text
+// Step 2: Gateway automatically converts structured text to JSON
+// Response.parsedContent will be a JSON object with the story structure
+```
+
+**Instruction Format Combinations:**
+
+- **JSON Schema + JSON Mode** (default): Instructions include JSON schema, expects JSON response
+- **JSON Schema + Structured Text Mode**: Instructions include JSON schema, but expects structured text (schema used as reference)
+- **Structured Text Spec + JSON Mode**: Instructions describe structure in free-form, expects JSON response
+- **Structured Text Spec + Structured Text Mode**: Instructions describe structure in free-form, expects structured text
+- **Structured Text Spec + Two-Step Mode**: Instructions describe structure in free-form, gets structured text first, then converts to JSON
+
+**Troubleshooting**: If you see `"objectTypes is required for invoke()"`:
+1. Verify you're calling `invoke()`, not `invokeChat()`
+2. Ensure `primaryObjectType` is provided
+3. Use `validateAIRequest()` from troubleshooting helper before sending
+4. Enable `AI_GATEWAY_DEBUG_REQUEST=true` to see request at entry point
+5. See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md#airequest-validation-issues) for detailed solutions
+
+#### Task Type ID (taskTypeId)
+
+The `taskTypeId` field is used to identify recurring tasks that you perform repeatedly with the same instructions but different context, prompts, or inputs. This is especially useful when processing large batches of data (e.g., 15k records) with the same question/instruction pattern.
+
+**Auto-Generation Behavior:**
+
+If `taskTypeId` is not provided in the request, the gateway automatically generates it as an MD5 hash of the **pre-parsed instructions** (after resolving from content-registry if it's a key, but before template parsing with workingMemory). This ensures:
+
+- **Consistency**: All requests with the same base instruction text get the same `taskTypeId`
+- **Automatic**: No need to manually calculate or provide hashes
+- **Stable**: The hash is based on the instruction text itself, not variable content
+
+**Manual Generation (Helper Method):**
+
+For maximum control and consistency, you can use the gateway's helper method to compute `taskTypeId`:
+
+```typescript
+// Static method (requires content-registry config if instructions is a key)
+const taskTypeId = await AIGateway.generateTaskTypeId('classification/basic', {
+  contentRegistryConfig: { github: { ... } },
+  agentId: 'agent-1'
+});
+
+// Instance method (uses gateway's configured content-registry)
+const gateway = new AIGateway({ enableContentRegistry: true, ... });
+const taskTypeId = await gateway.generateTaskTypeId('classification/basic');
+
+// Example: Processing 15k records with the same question
+const question = "What is the sentiment of this text?";
+const taskTypeId = await gateway.generateTaskTypeId(question);
+
+// All 15k requests will have the same taskTypeId
+for (const record of records) {
+  await gateway.invoke({
+    jobId: `job-${record.id}`,
+    agentId: 'sentiment-analyzer',
+    instructions: question,
+    input: record.text,
+    taskTypeId,  // Same for all records
+    objectTypes: [ /* REQUIRED for invoke() */ ],
+    config: { model: 'gpt-5-nano' }
+  });
+}
+```
+
+**What Exactly is Hashed:**
+
+The hash is computed from the **pre-parsed instructions**:
+1. If `instructions` is a key (e.g., `'classification/basic'`), it's resolved from content-registry first
+2. The resolved instruction text (or original text if not a key) is then hashed
+3. Template parsing with `workingMemory` happens **after** hash generation, so variable values don't affect the hash
+
+This ensures that:
+- Instruction keys resolve to the same hash across services
+- Template variables don't affect taskTypeId consistency
+- The same instruction text always produces the same taskTypeId
+
+**How It Works:**
+
+1. If `taskTypeId` is provided → Uses the provided value
+2. If `taskTypeId` is not provided → Gateway automatically:
+   - Resolves instructions from content-registry if it's a key (without workingMemory)
+   - Computes MD5 hash of the resolved instruction text
+   - Uses the hash as `taskTypeId`
+   - Logs the auto-generated value for debugging
+
+**Use Cases:**
+
+- **Batch Processing**: Process thousands of records with the same instruction/question
+- **Task Grouping**: Group related activities in activity tracking
+- **Content Registry**: Use `taskTypeId` in content-registry paths: `instructions/{agentId}/{taskTypeId}/{blockName}`
+- **Analytics**: Track performance and costs by task type
+
+### EnhancedLLMResponse
+
+Extended response interface with comprehensive metadata.
+
+```typescript
+interface EnhancedLLMResponse extends LLMResponse {
+  content: string;                    // Normalized content (always string)
+  rawText?: string;                   // Original raw text before fixing (v3.0.4+)
+  parsedContent?: TContent;            // Parsed JSON content
+  metadata: {
+    jobId?: string;
+    latencyMs: number;
+    tokens: {
+      prompt: number;
+      completion: number;
+      total: number;
+    };
+    // Output mode metadata (v3.0.5+)
+    outputMode?: 'json' | 'structured-text' | 'two-step';
+    instructionFormat?: 'json-schema' | 'structured-text-spec';
+    isTwoStepConversion?: boolean;
+    structuredTextStep?: 'first' | 'second';
+    model?: string;
+    provider?: string;
+    cost?: number;
+    // Response fixer metadata (v3.0.4+)
+    responseWasFixed?: boolean;        // Whether a response repair fallback was applied
+    responseFixApplied?: string;       // Which fix strategy was used
+    responseFixConfidence?: number;    // Confidence level (0-1)
+    responseFixWarnings?: string[];    // Warnings about the fix
+    [key: string]: any;
+  };
+}
+```
+
+## Advanced Usage
+
+### Custom Activix instance
+
+Use the same **`collections`** names the gateway writes to (`ai-activities`, `skill-executions`, `bad-requests`) and the same **`statusValues`** mapping as in section 2.
+
+```typescript
+import { Activix } from '@x12i/activix';
+
+const statusValues = {
+  started: 'started',
+  inProgress: 'in_progress',
+  completed: 'success',
+  failed: 'failed',
+  timeout: 'timeout'
+};
+
+const customTracker = new Activix({
+  collections: [
+    { name: 'ai-activities', statusValues },
+    { name: 'skill-executions', statusValues },
+    { name: 'bad-requests', statusValues }
+  ]
+});
+
+const gateway = new AIGateway({
+  activityTracker: customTracker,
+  enableActivityTracking: true
+});
+```
+
+### Custom Logger
+
+```typescript
+import { createLogger } from 'logs-gateway';
+
+const customLogger = createLogger(
+  { packageName: 'MY_APP', envPrefix: 'MY_APP' },
+  {
+    logLevel: 'debug',
+    logFormat: 'json',
+    enableUnifiedLogger: true,
+    unifiedLogger: {
+      transports: { papertrail: true },
+      service: 'ai-gateway',
+      env: 'production'
+    }
+  }
+);
+
+const gateway = new AIGateway({
+  logger: customLogger,
+  enableLogging: true
+});
+```
+
+### Usage Consumption Monitoring
+
+```typescript
+import { calculateAggregateConsumption } from '@x12i/ai-gateway';
+
+// After making requests, check aggregate consumption
+const aggregate = calculateAggregateConsumption('openai');
+
+if (aggregate) {
+  console.log(`Total requests: ${aggregate.totalRequests}`);
+  console.log(`RPM consumption: ${aggregate.rpmConsumption.toFixed(2)}%`);
+  console.log(`TPM consumption: ${aggregate.tpmConsumption.toFixed(2)}%`);
+  
+  // Alert if approaching limits
+  if (aggregate.rpmConsumption > 80) {
+    console.warn('⚠️ Approaching RPM limit!');
+  }
+}
+```
+
+### Health Checks
+
+```typescript
+// Check single provider
+const health = await gateway.checkHealth('openai');
+console.log(health.healthy, health.latencyMs);
+
+// Check all providers
+const allHealth = await gateway.checkAllHealth();
+for (const [provider, result] of allHealth) {
+  console.log(`${provider}: ${result.healthy ? 'healthy' : 'unhealthy'}`);
+  if (!result.healthy) {
+    console.error(`Error: ${result.error}`);
+  }
+}
+```
+
+### Interceptors
+
+```typescript
+// Add request interceptor
+gateway.addRequestInterceptor(async (request, provider) => {
+  console.log(`Request to ${provider}:`, request);
+  // Modify request if needed
+  return request;
+});
+
+// Add response interceptor
+gateway.addResponseInterceptor(async (response, provider) => {
+  console.log(`Response from ${provider}:`, response);
+  // Modify response if needed
+  return response;
+});
+```
+
+## Integration Examples
+
+### With Agent Framework
+
+```typescript
+import { AIGateway } from '@x12i/ai-gateway';
+
+const gateway = new AIGateway({
+  defaultProvider: 'openai',
+  usageTier: 'tier-3',
+  enableActivityTracking: true
+});
+
+// In your agent execution
+async function executeAgentTask(task: Task, jobId: string) {
+  // Use invokeChat() for chat requests without structured output
+  const response = await gateway.invokeChat({
+    jobId,  // Propagate jobId
+    agentId: task.agentId,
+    instructions: task.instructions,
+    input: task.input,
+    taskId: task.id,
+    taskTypeId: task.typeId  // Or use MD5 hash of question/instruction for consistent identification
+  });
+  
+  return {
+    content: response.content,
+    metadata: response.metadata  // Includes jobId, latency, tokens, etc.
+  };
+}
+```
+
+### With x-models for Smart Selection
+
+```typescript
+import { AIGateway } from '@x12i/ai-gateway';
+import { registry } from '@x12i/x-models';
+
+// Select optimal model
+const model = registry.selectModel({
+  strategy: 'cheapest',
+  capabilities: { toolCalling: true },
+  minContext: 16000
+});
+
+if (model) {
+  const gateway = new AIGateway({
+    defaultProvider: model.provider
+  });
+  
+  const response = await gateway.invokeChat({
+    jobId: 'job-123',
+    agentId: 'agent-1',
+    instructions: 'You are a helpful assistant',
+    input: 'Hello!',
+    config: {
+      model: model.id
+    }
+  });
+}
+```
+
+### Unified Reasoning API (OpenRouter Reasoning)
+
+The gateway supports unified reasoning/thoughts configuration through the OpenRouter Reasoning API. This provides normalized reasoning capabilities across all providers.
+
+#### Request Configuration
+
+```typescript
+const response = await gateway.invokeChat({
+  jobId: 'reasoning-example',
+  agentId: 'agent-1',
+  instructions: 'Solve this step-by-step',
+  input: 'What is 15 * 23?',
+  config: {
+    provider: 'openai',
+    model: 'gpt-5-nano',
+    // Unified reasoning configuration
+    reasoning: {
+      effort: 'high',           // 'none' | 'low' | 'medium' | 'high' | 'xhigh'
+      visibility: 'trace',      // 'none' | 'summary' | 'trace'
+      onUnsupported: 'downgrade' // 'error' | 'downgrade' | 'ignore'
+    }
+  }
+});
+```
+
+**Reasoning Configuration Options:**
+
+- **`effort`**: Controls reasoning depth
+  - `'none'`: No reasoning (default)
+  - `'low'`: Basic reasoning
+  - `'medium'`: Moderate reasoning
+  - `'high'`: Deep reasoning
+  - `'xhigh'`: Maximum reasoning depth
+
+- **`visibility`**: Controls what reasoning data is returned
+  - `'none'`: No reasoning in response (default)
+  - `'summary'`: Human-readable reasoning summary
+  - `'trace'`: Detailed reasoning trace
+
+- **`onUnsupported`**: Behavior when provider doesn't support requested reasoning
+  - `'error'`: Throw error (default)
+  - `'downgrade'`: Automatically downgrade to supported level
+  - `'ignore'`: Proceed without reasoning
+
+#### Response Structure
+
+```typescript
+interface EnhancedLLMResponse {
+  content: string;
+  // Unified reasoning response object (not array)
+  reasoning?: {
+    requested: {
+      effort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh';
+      visibility?: 'none' | 'summary' | 'trace';
+    };
+    applied: {
+      effort?: 'none' | 'low' | 'medium' | 'high';
+      visibility?: 'none' | 'summary' | 'trace';
+    };
+    artifacts?: {
+      summary?: { text: string; format: string };
+      trace?: { chunks: any[] };
+      encrypted?: Array<{
+        id: string;
+        format: string;
+        type?: string;
+        [key: string]: any;
+      }>;
+    };
+    availability?: {
+      supportsEffort?: boolean;
+      supportsSummary?: boolean;
+      supportsTrace?: boolean;
+      supportsEncrypted?: boolean;
+    };
+    warnings?: Array<{
+      code: 'EFFORT_NORMALIZED' | 'VISIBILITY_DOWNGRADED' | 'EFFORT_IGNORED' | 'REASONING_UNSUPPORTED';
+      message: string;
+    }>;
+  };
+  // ... other response fields
+}
+```
+
+#### Usage Examples
+
+**Basic Reasoning Request:**
+```typescript
+const response = await gateway.invokeChat({
+  jobId: 'basic-reasoning',
+  agentId: 'agent-1',
+  instructions: 'Explain your reasoning step by step',
+  input: 'Why is the sky blue?',
+  config: {
+    provider: 'openai',
+    model: 'gpt-5-nano',
+    reasoning: {
+      effort: 'medium',
+      visibility: 'summary'
+    }
+  }
+});
+
+// Access reasoning data
+console.log('Response:', response.content);
+console.log('Reasoning effort applied:', response.reasoning?.applied.effort);
+console.log('Reasoning summary:', response.reasoning?.artifacts?.summary?.text);
+```
+
+**Encrypted Reasoning Continuity:**
+```typescript
+// First request with encrypted trace
+const response1 = await gateway.invokeChat({
+  jobId: 'continuity-1',
+  agentId: 'agent-1',
+  instructions: 'Solve this complex problem',
+  input: 'Calculate the trajectory of a satellite',
+  config: {
+    provider: 'openai',
+    model: 'o1-preview', // OpenAI o-series models support encrypted traces
+    reasoning: {
+      effort: 'xhigh',
+      visibility: 'trace'
+    }
+  }
+});
+
+// Check for encrypted artifacts
+const encryptedArtifacts = response1.reasoning?.artifacts?.encrypted;
+if (encryptedArtifacts && encryptedArtifacts.length > 0) {
+  console.log(`Found ${encryptedArtifacts.length} encrypted reasoning artifacts`);
+
+  // Second request with continuity (encrypted artifacts would be passed back)
+  // Note: Continuity input format depends on provider-specific implementation
+  const response2 = await gateway.invokeChat({
+    jobId: 'continuity-2',
+    agentId: 'agent-1',
+    instructions: 'Continue from previous reasoning',
+    input: 'Now apply this to Mars orbit',
+    config: {
+      provider: 'openai',
+      model: 'o1-preview',
+      reasoning: {
+        effort: 'xhigh',
+        visibility: 'trace'
+      }
+      // reasoningContinuity: encryptedArtifacts // Format depends on provider
+    }
+  });
+}
+```
+
+**Provider Support Notes:**
+
+- **Encrypted reasoning traces**: Currently supported for `openai/o*` models via OpenRouter
+- **Reasoning effort levels**: Varies by provider and model capabilities
+- **Automatic fallback**: When `onUnsupported: 'downgrade'` is set, the gateway automatically adjusts to supported reasoning levels
+
+**Model Recommendations for Reasoning:**
+
+- **High reasoning**: `openai/o1-preview`, `openai/o1-mini`, `openai/gpt-4o` with reasoning config
+- **Standard models**: `openai/gpt-5-nano`, `anthropic/claude-3.5-sonnet` (reasoning support varies)
+
+## Troubleshooting
+
+### Quick Reference
+
+**📚 Documentation** (included in npm package - accessible after `npm install @x12i/ai-gateway`):
+- **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)** - Comprehensive troubleshooting guide with test cases for all common issues
+- **[TROUBLESHOOTING_TOOLBOX.md](./TROUBLESHOOTING_TOOLBOX.md)** - Diagnostic utilities API and usage examples  
+- **[INTEGRATION_GUIDANCE.md](./INTEGRATION_GUIDANCE.md)** - Official patterns, integration examples, and debugging steps
+
+**Location after install**: `node_modules/@x12i/ai-gateway/TROUBLESHOOTING.md` (and other .md files)
+
+**🔧 Troubleshooting Helper Functions** (exported from SDK - use immediately, no file reading needed):
+```typescript
+import {
+  validateAIRequest,      // Validate request before sending
+  diagnoseRequest,        // Get comprehensive diagnostics
+  formatDiagnostic,       // Format diagnostics as text
+  assertValidAIRequest,   // Throw if invalid (for testing)
+  extractJSON,            // Extract JSON from text/markdown
+  supportsJSONMode        // Check provider JSON mode support
+} from '@x12i/ai-gateway';
+```
+
+**See**: [TROUBLESHOOTING_TOOLBOX.md](./TROUBLESHOOTING_TOOLBOX.md) for complete API documentation.
+
+### Common Issue: "objectTypes is required for invoke()"
+
+**Error**: `Request validation failed: objectTypes is required for invoke()`
+
+**Quick Fix Checklist**:
+
+1. ✅ **Verify you're calling `invoke()`, not `invokeChat()`**
+   ```typescript
+   // ✅ Correct for structured output
+   await gateway.invoke({
+     jobId: 'job-123',
+     agentId: 'agent-1',
+     instructions: 'professional-answer/general',
+     input: 'User question',
+     objectTypes: [
+       {
+         type: 'professional-answer',
+         whenToUse: 'For professional Q&A responses'
+       }
+     ],
+     config: { model: 'gpt-4o', provider: 'openai' }
+   });
+   ```
+
+2. ✅ **Use troubleshooting helper to validate before sending**
+   ```typescript
+   import { validateAIRequest, assertValidAIRequest } from '@x12i/ai-gateway';
+   
+   // Validate before sending
+   assertValidAIRequest(request);
+   await gateway.invoke(request);
+   ```
+
+3. ✅ **Enable debug logging to see request at entry point**
+   ```bash
+   export AI_GATEWAY_DEBUG_REQUEST=true
+   npm run your-test
+   ```
+
+**See**: [TROUBLESHOOTING.md](./TROUBLESHOOTING.md#airequest-validation-issues) for detailed solutions and test cases.
+
+### Using Troubleshooting Tools
+
+```typescript
+import {
+  validateAIRequest,
+  diagnoseRequest,
+  formatDiagnostic,
+  supportsJSONMode
+} from '@x12i/ai-gateway';
+
+// Validate request
+const validation = validateAIRequest(request);
+if (!validation.valid) {
+  console.error('Errors:', validation.errors);
+}
+
+// Get diagnostics
+const diagnostic = diagnoseRequest(request);
+console.log(formatDiagnostic(diagnostic));
+```
+
+**See**: [TROUBLESHOOTING_TOOLBOX.md](./TROUBLESHOOTING_TOOLBOX.md) for complete API.
+
+## Error Handling
+
+The gateway throws specific error types:
+
+- `ProviderNotFoundError`: When a requested provider is not registered
+- `FallbackExhaustedError`: When all providers in the fallback chain have failed
+
+```typescript
+import { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-gateway';
+
+try {
+  const response = await gateway.invokeChat({
+    aiRequestId: 'chat-req-001',
+    sessionId: 'sess-1',
+    instance: { instanceId: 'gw-1', type: 'gateway' },
+    jobId: 'job-123',
+    agentId: 'agent-1',
+    instructions: 'You are a helpful assistant',
+    input: 'Hello!'
+  });
+} catch (error) {
+  if (error instanceof FallbackExhaustedError) {
+    console.error('All providers failed:', error.attempts);
+    // With enableActivityTracking, success/failure is recorded automatically inside the gateway
+  } else if (error instanceof ProviderNotFoundError) {
+    console.error('Provider not found:', error.message);
+  }
+}
+```
+
+## Package Integrations
+
+This package integrates with:
+
+- **@x12i/ai-providers-router**: Core routing functionality
+- **@xronoces/content-registry**: Instruction key resolution and content management (optional)
+- **@x12i/x-models**: Usage tier tracking and model metadata
+- **@x12i/activix** v5 (xronox-activitix): Activity logging and tracking (`^5.0.1` in this package)
+- **logs-gateway**: Structured logging with correlation
+- **nx-config2**: Configuration management (via dependencies)
+
+## Related Packages Status
+
+### @x12i/ai-gateway
+
+**Fixes:**
+- ✅ "[object Object]" bug when router returns objects
+- ✅ Enhanced `extractRawText()` with multiple safety layers
+
+**Features:**
+- ✅ Automatic recovery if "[object Object]" is detected
+- ✅ Original object preserved in `parsedContent`
+- ✅ Normalized content as JSON string (backward compatible)
+- ✅ `metadata.contentType` for type indication
+- ✅ Content-registry integration for instruction keys
+- ✅ Centralized activity tracking configuration (v2.0.5+)
+- ✅ Activity lifecycle verification and enhanced logging (v2.0.5+)
+
+### @x12i/ai-providers-router
+
+**Fixes:**
+- ✅ Dynamic import registration issue
+
+**Features:**
+- ✅ Batch API support
+- ✅ Enhanced provider management
+
+### Integration
+
+The gateway fix handles cases where the router returns structured data (objects/arrays) instead of plain strings, ensuring:
+
+- **Backward compatibility** — `content` is always a string
+- **Data preservation** — original object in `parsedContent`
+- **Type safety** — `metadata.contentType` indicates the type
+
+### Installation
+
+```bash
+npm install @x12i/ai-gateway
+npm install @x12i/ai-providers-router
+```
+
+**Package compatibility:**
+- Router handles dynamic imports and batch operations
+- Gateway handles object responses from the router
+- Gateway provides content normalization and type safety
+
+## Testing
+
+### Activity Tracking Tests
+
+**Standalone Test** (Recommended):
+```bash
+npm run test:activities:standalone
+```
+
+This test bypasses config parsing issues and tests activity lifecycle end-to-end:
+- ✅ Gateway initialization with activity tracking enabled
+- ✅ Activity creation with `jobId`, `agentId`, `taskId`
+- ✅ LLM invocation through gateway
+- ✅ Activity status update from "started" to "success"
+- ✅ Database persistence of activity records
+
+**Standard Test Suite**:
+```bash
+npm test
+```
+
+**Note**: Some tests may be blocked by `nx-config2` Postgres parsing issue. See `.reports/new/nx-config2-skip-config-sections-feature-request.md` for details.
+
+**See**: `.tests/TESTING_GUIDE.md` for complete testing documentation.
+
+## Known Issues
+
+### nx-config2 Postgres Parsing Issue
+
+**Status**: 🟡 **FEATURE REQUEST OPEN** - Not a bug in ai-gateway
+
+**Issue**: `nx-config2` attempts to parse Postgres configuration even when Postgres is not used, causing test failures.
+
+**Workaround**: Use standalone test (`npm run test:activities:standalone`) which bypasses `nx-config2`.
+
+**Feature Request**: See `.reports/new/nx-config2-skip-config-sections-feature-request.md` for complete details. Requesting:
+1. Fix/remove broken Postgres port parsing
+2. Add selective config loading by sections (from `.env`) and groups (from config map)
+3. Ensure ai-gateway and activix configs are covered in DEFAULT_CONFIG_MAP
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0.0 (if using TypeScript)
+
+## License
+
+ISC
+
+## Repository
+
+[GitHub](https://github.com/x12i/ai-gateway)