@x12i/ai-gateway 9.3.4 → 9.4.0

package/README.md

@@ -1,58 +1,21 @@
 # @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` (see `package.json` for pinned versions), and **`@x12i/logxer`** for structured logging.
+Unified gateway for LLM provider routing, structured logging, optional Activix activity persistence, and cost/model resolution via **@x12i/ai-tools** v2. Built on **@x12i/ai-providers-router**, **@x12i/logxer**, **@x12i/rendrix** (templates), and **@x12i/flex-md** (output-format hints and max-token lookup).
 
-## Mandatory runtime identity (v9+)
-
-Every **`invoke`** / **`invokeChat`** request **must** include **`identity`**: the full runtime envelope from the **upstream client** (not invented inside the gateway).
-
-- **`identity.jobId`** and **`identity.taskId`** are **only** taken from that upstream object. The gateway **never** generates, rewrites, or back-fills them from deprecated top-level `jobId` / `taskId` fields.
-- If `identity` is missing or `jobId` / `taskId` are empty, the gateway logs **`warn`** via Logxer (`missingRuntimeIdentityObject` / `missingUpstreamIdentityFields`) when a logger is configured, and still attaches the merged envelope so the rest of the pipeline can proceed.
-- The same merged object is **`request.identity`**, forwarded to the router, returned as **`response.metadata.identity`**, and persisted on Activix as **`runContext`** (same reference as `request.identity`).
-
-See [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md) and [Logger initialization](./docs/LOGGER_INITIALIZATION.md).
+## What this package does
 
-### AI invoke payload (`gateway.invoke`)
+| Area | Behavior |
+|------|----------|
+| **Routing** | Registers providers (or lazy-registers from env), invokes the router with merged model config, retries, and optional fallback chain. |
+| **`invoke()`** | Builds messages from instructions + prompt templates + `workingMemory`; requires runtime **identity** and **actionType** / **actionRef**. |
+| **`invokeChat()`** | Raw chat-style requests; no instruction builder or action classification. |
+| **Cost** | Forwards router `costStatus` when present; otherwise prices via **@x12i/ai-tools** open-assets catalogs (`calculateFromRecord`). |
+| **Activix** | Optional Mongo-backed activity rows (`ai-actions`, `bad-requests`, `skill-executions`) with root billing fields and `outer` I/O. |
+| **Trace mode** | `diagnostics.mode === 'trace'` adds `metadata.attempts[]`, `metadata.usage`, and per-attempt billing when priced. |
 
-Use a single object typed as **`AIInvokeRequest`** (exported alias: **`AIRequest`**). Besides **`identity`** / **`aiRequestId`** / **`agentId`** / **`instructions`**, every **`invoke()`** call **must** include:
+Pinned dependency versions are in `package.json` (currently **Activix ^7.2**, **ai-tools ^2**).
 
-- **`actionType`**: **`'skill'`** | **`'preSkill'`** | **`'postSkill'`** — whether this call is the main skill or a pre/post hook.
-- **`actionRef`**: non-empty string — stable reference for the action (for example the skill id).
-
-The gateway copies these onto **`request.identity`** for **`runContext`** (Activix) and onto activity documents when tracking is enabled. **`invokeChat()`** does **not** use these fields.
-
-## 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` v7 (xronox-activitix), fixed Mongo collections `ai-actions` / `bad-requests`, validated root-level **`outer` / `inner`** I/O plus **`runContext`** for Activix 7
-- **📝 Structured Logging**: Production-ready logging via **`@x12i/logxer`** (LogMeta `jobId` / `sessionId` / `correlationId`, optional `debugKind`, default `runtimeIdentity` from env) with 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+)
-- **Post-processing & interceptors**: Request-level `transformations` hooks were **removed**; transform outputs in your app or use router interceptors (see [Response transformation hooks](#7-response-transformation-hooks-removed-from-request))
-- **🔧 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 hints (`StructuredTextSpec`)**: Optional field on **`ChatRequest`** for typing / forward compatibility; dedicated activity **`contractOutput`** persistence is **not** implemented in the gateway runtime — validate **`parsedContent`** / **`content`** in your app or use interceptors (see **section 9** under Setup Guide)
+---
 
 ## Installation
 
@@ -60,89 +23,46 @@ The gateway copies these onto **`request.identity`** for **`runContext`** (Activ
 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/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md` - **Invoke metadata**, cost/billing (G8), output contract (G6), Activix completion fields
-- `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 (for example missing **`actionType`**, **`actionRef`**, or **`identity.jobId`** / **`identity.taskId`**).
+Peer/provider packages (for example `@x12i/ai-provider-openai`) are installed by your application when you register those providers.
 
-### 🔍 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
+## Mandatory runtime identity (v9+)
 
-**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
+Every **`invoke()`** / **`invokeChat()`** request **must** include **`identity`** from the upstream client (the gateway does not invent `jobId` / `taskId`).
 
-**Resolution Detection:**
-- `instructions.constructMessages.entry` - Detects if constructMessages receives resolved instructions
+- Missing or empty `identity.jobId` / `identity.taskId` → **warn** logs when a logger is configured; the call may still proceed with the merged envelope.
+- The same object is **`request.identity`**, **`response.metadata.identity`**, router context, and Activix **`runContext`**.
 
-**Gate Checks:**
-- `gate.activityStart.precheck` - Validates instructions before activity tracking
-- `gate.llmInvoke.precheck` - Validates instructions before LLM calls
+See [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md).
 
-**Error Handling:**
-- `badRequest.written` - Confirms bad request path execution
+### Action classification (`invoke()` only)
 
-**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
+| Field | Required | Values / notes |
+|-------|----------|----------------|
+| **`actionType`** | Yes | `'skill'` \| `'preSkill'` \| `'postSkill'` |
+| **`actionRef`** | Yes | Non-empty stable id (e.g. skill path) |
 
-All diagnostic logs include `traceId`, `jobId`, and `agentId` for correlation. Content is safely redacted (first 80 chars only) with hashes for comparison.
+Copied onto **`identity`** for Activix and activity metadata. Not used by **`invokeChat()`**.
 
-## Quick Start
+---
 
-### Basic Usage with Enhanced Gateway
+## Quick start
 
 ```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
+  defaultProvider: 'openrouter',
+  enableLogging: true,
   enableActivityTracking: true,
-  enableUsageTracking: true,
-  enableLogging: true
+  aiTools: {
+    enabled: true,
+    resolveModels: true,
+    calculateCost: 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 mandatory runtime identity + action classification (Activix / tracing)
 const response = await gateway.invoke({
   aiRequestId: 'call-001',
   agentId: 'agent-456',
@@ -159,4107 +79,191 @@ const response = await gateway.invoke({
     agentId: 'agent-456'
   },
   workingMemory: { input: 'Hello!' },
-  config: { model: 'gpt-4o-mini', provider: 'openai' }
-  // … primaryObjectType / objectTypes as needed for your flow (`invoke()` does not use client `messages`; use `invokeChat()` for raw transcripts)
-});
-
-// Response includes comprehensive metadata (including `identity`)
-console.log(response.metadata);
-```
-
-### 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 (@x12i/logxer)
-
-**Logger initialization:** The gateway uses **`@x12i/logxer`**. Pass a **`Logxer`** from **`createLogxer`**, or omit `logger` and let the gateway build a default (still Logxer-based). See **[Logger Initialization Guide](./docs/LOGGER_INITIALIZATION.md)** for mandatory **`identity`** on requests and **`LogMeta`** / **`debugKind`** usage.
-
-**Where to configure:**
-- Gateway constructor: `enableLogging`, `packageName`, `logger`
-- Environment variables: **`{PREFIX}_LOGS_LEVEL`** (canonical per-package level), legacy **`{PREFIX}_LOG_LEVEL`**, plus **`{PREFIX}_LOG_FORMAT`**, file sinks, unified logger, etc., as documented for **`@x12i/logxer`**.
-
-**How to configure:**
-
-```typescript
-import { AIGateway } from '@x12i/ai-gateway';
-import { createLogxer } from '@x12i/logxer';
-
-// Create logger once at application startup
-const logger = createLogxer(
-  { packageName: 'MY_APP', envPrefix: 'MY_APP', debugNamespace: 'my-app' },
-  {
-    logLevel: 'info',           // verbose|debug|info|warn|error
-    logFormat: 'json',          // text|json|yaml|table
-    logToFile: true,
-    logFilePath: '/var/log/app.log',
-    enableUnifiedLogger: true,
-    unifiedLogger: {
-      transports: { papertrail: true },
-      service: 'my-app',
-      env: 'production'
-    },
-    runtimeIdentity: {
-      service: 'my-app',
-      env: process.env.NODE_ENV,
-      version: process.env.npm_package_version
-    }
-  }
-);
-
-const gateway = new AIGateway({
-  enableLogging: true,
-  logger,
-  packageName: 'MY_APP'
-});
-```
-
-**Why use the same Logxer?**
-- Consistent log format across your application
-- Unified logging destination
-- **`LogMeta`** correlation (`jobId`, `sessionId`, `correlationId`, `debugKind`, `runtimeIdentity`) matches gateway and Activix fields
-- Single point of control for log levels
-
-**Per-package log level (`@x12i/logxer`):**
-
-- **Canonical:** `{PREFIX}_LOGS_LEVEL` — same `envPrefix` as **`createLogxer`** / 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|table
-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 emits diagnostic logs for instruction resolution and propagation through the same Logxer pipeline.
-
-**What happens if `logger` is not provided:** The gateway creates a default **`Logxer`** via **`createLogxer`**. For production, prefer passing your app’s logger so levels, transports, and **`runtimeIdentity`** stay aligned with the rest of your stack.
-
-### 2. Activity Tracking Configuration (xronox-activitix via @x12i/activix v7)
-
-**Activix version:** This gateway targets **`@x12i/activix` v7.x** (built on `@x12i/xronox-store`). The dependency range is declared in `package.json` (currently `^7.1.0`). Activity I/O is stored at the **document root** as **`outer`** (and optional **`inner`**); the deprecated nested **`structure`** wrapper is not used.
-
-**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 reads **Mongo connection** settings from the environment, but **collection names are package constants**: they are defined only in `src/config/activity-tracking-config.ts` and **cannot** be overridden by env vars. If you pass your own **`Activix`** instance, register collections whose **`name`** values match these strings exactly or persistence and dashboards will disagree.
-
-| Mongo collection | Typical `activityType` | What gets stored |
-|------------------|------------------------|------------------|
-| **`ai-actions`** | `gateway-invocation` | Normal LLM runs after validation: full request/config snapshots, lifecycle, **`runContext`**, and Activix **`outer`** I/O for each gateway invocation. |
-| **`skill-executions`** | `skill-execution` | Skill-specific lifecycle rows when skill execution tracking is used (separate from the main gateway row). |
-| **`bad-requests`** | `bad-request` | Failures **before** `startActivity` (validation, configuration, format extraction, etc.). |
-
-**What the gateway sends into Activix (lifecycle)**
-
-`ActivityManager` drives **`@x12i/activix` v7** with a **two-phase** API:
-
-1. **`startRecord`** — Inserts a new document with **`status: 'started'`**, **`startTime`**, **`runContext`** (same object as **`request.identity`**), root **`request`** / **`config`** snapshots, gateway metadata (e.g. **`activityType`**, **`aiRequestId`**), and the initial **`outer`** fragment (see below). Activix returns **`activityId`** (prefix **`act-`**, configured as the collection **`primaryKey`**); that id is used for all later updates — **not** `jobId`.
-2. **`completeRecord`** or **`failRecord`** — Patches the **same** document by **`activityId`**. On success, adds **`response`**, **`endTime`**, **`duration`**, root **`cost`** / **`costUsd`** / **`costStatus`**, sets **`outer.output`** to the completion payload, merges billing into **`outer.metadata`**, and when priced or unpriced with usage, sets Activix **`outer.cost`** (`usd`, `tokens`, `provider`, `model`, optional `details`). Failure adds error details (and may attach **`outer.output`** for certain failure modes such as response parsing).
-
-**How a document is shaped (reading `ai-actions` in Mongo)**
-
-- **`runContext`**: Canonical correlation BSON object — the merged gateway **`identity`** (`jobId`, `taskId`, `sessionId`, `instance`, `aiRequestId`, optional graph/skill linkage, `actionType` / `actionRef` on **`invoke()`**, plus any extra keys your upstream put on **`identity`**).
-- **Root-level copies** of common identity fields may appear beside **`runContext`** for convenient indexing; treat **`runContext`** as the full envelope when in doubt.
-- **`request`**: Structured snapshot only — **`raw`** / **`parsed`** instructions, context, prompt; **`messages`**; **`workingMemory`** (template/user payload). There is **no** separate legacy **`input`** field on this object; use **`workingMemory`**.
-- **`config`**: `model`, `provider`, `temperature`, `maxTokens`, **`rawConfig`** (exact router config).
-- **`outer`**: Activix v7 **validated I/O** at the document root. At **start**, **`outer.input`** contains **`activityType`** and the same **`request`** snapshot as root **`request`** when a body exists (`{ activityType, request }`). At **success**, **`outer.output`** matches the **`response`** object written on completion; **`outer.metadata`** mirrors routing and billing from **`response.metadata`** (`modelUsed`, `provider`, `cost`, `costUsd`, `costStatus`, optional `costBreakdown`); **`outer.cost`** holds the canonical Activix cost object when usage or price is known (see [Cost reporting](#cost-reporting-invoke-response--activix-run-analysis-g8) below). Root **`request`** / **`response`** support querying and older tooling; **`outer`** satisfies Activix’s envelope — so the same logical request snapshot can appear both at **`request`** and under **`outer.input.request`** by design. Large provider blobs (**`response.content.fullResponse`**) and size limits are described in [Activities outer duplication & payload controls](./docs/ACTIVITIES_OUTER_DUPLICATION.md).
-
-**Environment variable priority (Activix / Mongo — implemented in `@x12i/activix`, not in `activity-tracking-config.ts`):**
-- **Mongo URI**: `MONGO_LOGS_URI` if set, otherwise **`MONGO_URI`**. If neither is set, Activix cannot use the database.
-- **Mongo database name** (where collections such as **`ai-actions`** live): `ACTIVIX_DB_NAME` → `MONGO_AI_LOGS_DB` → **`MONGO_LOGS_DB`** → **`MONGO_DB`** → default **`activitix`** if none are set.
-
-**Why you might not see `ai-actions` in Mongo**
-
-1. **`storageMode: 'automatic'` (gateway default)** — On startup Activix **pings** Mongo with the URI above. If the URI is missing or the ping fails, it **silently falls back** to filesystem storage under **`./playground/`** (see `playground/collections/ai-actions/`). No Mongo collection is created in that mode. Check logs for **`Activity tracking persistence backend ready`**: `storageBackend` must be **`database`** for Mongo.
-2. **Lazy collections** — MongoDB normally creates a collection on the **first insert**. Until at least one activity **`startRecord`** succeeds against Mongo, **`ai-actions`** may not exist.
-3. **Wrong database in Compass / shell** — If you did not set `MONGO_LOGS_DB` / `MONGO_DB`, Activix uses the default database **`activitix`**, not your application’s primary DB.
-4. **`.env` load order** — Environment variables must be available **before** `new AIGateway(...)`. If another package constructs the gateway before `dotenv.config()`, Activix may never see `MONGO_URI`.
-
-**⚠️ 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`): Same object as **`request.identity`** (including required upstream **`jobId`** and **`taskId`**), plus `sessionId` and nested `instance: { instanceId, type }` when present; see [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md).
-- **`jobTypeId`**, **`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.
-- **Payload shape**: Root **`request`** and **`outer.input.request`** both snapshot the same gateway request (Activix `outer` envelope). Large provider blobs on completion live under **`content.fullResponse`** unless you opt out — see [Activities outer duplication & payload controls](./docs/ACTIVITIES_OUTER_DUPLICATION.md).
-
-**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.
-
-### Model catalog resolution and defaults (`@x12i/ai-tools`)
-
-Before each invoke, the gateway can normalize caller `config.model` / `modelConfig` via the **ai-models** Catalox catalog (`@x12i/ai-tools`). After invoke, when the router leaves cost **unpriced**, the gateway may compute USD from the same catalog.
-
-**Environment variables:**
-
-| Variable | Purpose |
-|----------|---------|
-| `AI_GATEWAY_DEFAULT_MODEL` | Default model when none is provided, or when resolution fails in **`mode=prod`**. Supports `provider/model` (e.g. `openrouter/openai/gpt-5-nano`) or a bare model id. |
-| `mode` / `MODE` | `prod` — unresolved models fall back to the default chain (with **Logxer `warn`**). `dev` / `debug` / omitted — unresolved models throw **`ModelResolutionError`**. |
-
-**Default model priority** (prod fallback only): `AI_GATEWAY_DEFAULT_MODEL` → `src/defaults/model-config.json` `defaultModel` → code constant `gpt-5-nano`.
-
-**Logxer warnings** on default substitution include structured fields: `reason` (`no_model_provided`, `model_resolution_failed`, `ai_tools_unavailable`), `defaultSource` (`env`, `model-config.json`, `code`), `originalModel`, `defaultModel`, and `mode`.
-
-Catalox/Firebase credentials are required for catalog bootstrap (same as `@x12i/ai-tools` — see that package’s README). Disable with `aiTools: { enabled: false }` on `GatewayConfig`, or inject `aiTools.catalox` for tests.
-
-**GatewayConfig (optional overrides):**
-
-```typescript
-const gateway = new AIGateway({
-  mode: 'prod', // or 'dev' | 'debug' — overrides process.env.mode
-  aiTools: {
-    enabled: true,
-    resolveModels: true,
-    calculateCost: true,
-    costIncludeBreakdown: false,
-    cacheTtlMs: 60_000,
-    // catalox: injectedCataloxInstance,
-  },
+  config: { model: 'openai/gpt-4o-mini', provider: 'openrouter' }
 });
-```
-
-#### Cost reporting (invoke response + Activix, Run Analysis G8)
-
-Billing is resolved once per successful **`invoke()`** / **`invokeChat()`** via **`resolveCostCompletionWithAiTools`** (see [`docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md`](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md)):
-
-| Layer | Fields |
-|--------|--------|
-| **Router** (`@x12i/ai-providers-router`) | Preferred source: **`metadata.costStatus`** (`priced` \| `unpriced`), **`metadata.costUsd`** / **`metadata.cost`** when priced |
-| **Gateway response** | Same slice on **`response.metadata`**: **`costStatus`**, **`costUsd`**, **`cost`**, optional **`costBreakdown`** (when **`aiTools.calculateCost`** and catalog pricing apply and the router left cost unpriced) |
-| **Activix activity (on `logSuccess`)** | Root **`cost`**, **`costUsd`**, **`costStatus`**; **`outer.metadata`** mirror; **`outer.cost`** (`usd`, `tokens` with `input`/`output`/`total`, `provider`, `model`, `details.costStatus`, optional `details.costBreakdown`) |
-
-**`costStatus` semantics:**
 
-- **`priced`** — **`costUsd`** / **`cost`** is a finite USD amount for this call (from the router or from **`@x12i/ai-tools`** catalog **`CostCalculator`** when the router did not price).
-- **`unpriced`** — Token usage was recorded but no authoritative USD price was available (explicit router **`unpriced`** is never overridden by catalog).
-- Omitted — No non-zero token usage (no billing signal).
-
-Requires **`enableActivityTracking: true`** (default when Mongo/env is configured) for Activix persistence; invoke metadata is always set on the gateway response regardless.
-
-**Tests before release:**
-
-```bash
-npm run build
-npm test                    # integration (tsx)
-npm run test:ai-tools       # unit: mode, defaults, cost helper
-npm run test:live           # LIVE: catalog + invoke (needs .env + Firebase + LLM key)
-npm run test:real:comprehensive  # optional: compiled real router matrix + npm test
+console.log(response.content, response.metadata?.costUsd, response.metadata?.tokens);
 ```
 
-See [`.env.example`](./.env.example) for `AI_GATEWAY_DEFAULT_MODEL`, `mode`, provider keys, and Firebase/Catalox variables.
-
-**Recommended (auto-configured from environment variables):**
-
-```typescript
-import { AIGateway } from '@x12i/ai-gateway';
-import { OpenAIProvider } from '@x12i/ai-provider-openai';
-
-// Set environment variables (before creating the gateway):
-// MONGO_URI=mongodb://localhost:27017
-// MONGO_LOGS_DB=my-logs-db   # optional; default DB name for Activix is "activitix"
-
-const gateway = new AIGateway({
-  enableActivityTracking: true,  // default: true
-  // Activix is auto-configured; writes use collections ai-actions / bad-requests / skill-executions
-});
+### Providers without manual `register()`
 
-gateway.register(new OpenAIProvider({
-  apiKey: process.env.OPENAI_API_KEY
-}));
-```
+- **OpenRouter:** Set `OPEN_ROUTER_KEY` or `OPENROUTER_API_KEY` (unless `USE_OPENROUTER=false`). The gateway can lazy-register on first invoke.
+- **Direct providers:** Set `OPENAI_API_KEY`, `GROK_API_KEY`, etc. Same lazy registration.
 
-**Advanced (custom Activix v7 instance):**
+Load `.env` before constructing the gateway if another package creates it first.
 
-If you pass your own `Activix`, configure **the same collection names** the gateway expects so routing matches persistence:
+### Base router only
 
 ```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-actions', statusValues },
-    { name: 'skill-executions', statusValues },
-    { name: 'bad-requests', statusValues }
-  ]
-});
+import { LLMProviderRouter } from '@x12i/ai-gateway';
 
-const gateway = new AIGateway({
-  enableActivityTracking: true,          // default: true
-  activityTracker,                       // plug in custom tracker
-});
+const router = new LLMProviderRouter({ defaultProvider: 'openai' });
+// register providers, then router.invoke({ messages: [...] })
 ```
 
-When the gateway constructs Activix internally, each collection uses **`primaryKey: 'activityId'`** and **`primaryKeyPrefix: 'act-'`**. If you supply a custom **`Activix`**, align with that (or your **`activityId`** values will not match operational tooling).
-
-**What gets tracked (persisted when DB is configured):**
-- **Identity**: Fields aligned with **`request.identity`** / Activix **`runContext`**: **`aiRequestId`**, upstream **`jobId`** and **`taskId`**, `sessionId`, `instance`, plus optional `jobTypeId`, `agentId`, `taskTypeId`, etc., as provided
-- **Timing**: `startTime`, `endTime`, `duration`, `status` (`started|success|failed`)
-- **Request data**: Stored in **`request`** (raw/parsed prompts, **`messages`**, **`workingMemory`**) and mirrored under **`outer.input.request`** when Activix **`outer`** is populated — see table above
-- **Config data**: Stored in **`config`** (model, provider, temperature, maxTokens, **`rawConfig`**)
-- **Response data**: Stored in **`response`** on completion (content, metadata, optional **`fullResponse`** per diagnostics)
-- **Activix I/O**: Root **`outer`** — **`outer.input`** at start, **`outer.output`** on success (and some failure paths)
-- **Cost / billing**: On success, root **`cost`**, **`costUsd`**, **`costStatus`**, plus **`outer.metadata`** and **`outer.cost`** (same values as **`response.metadata`** from the invoke path — router passthrough or catalog pricing via **`@x12i/ai-tools`**)
-
-**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); **`jobId`** / **`taskId`** come from upstream **`identity`** (required on each request; see v9+ contract above)
-- ✅ 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 v7 integration**
+## Configuration
 
-1. **Configuration** (`activity-tracking-config.ts`):
-   - Mongo connection from env; **collection names** `ai-actions`, `bad-requests`, and `skill-executions` are **fixed literals** (not env-driven) for consistency across deployments.
-
-2. **Lifecycle** (`@x12i/activix` v7):
-   - ✅ `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 aiRequestId = 'skill-pa-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'my-agent',
-  actionType: 'skill',
-  actionRef: 'skills/professional-answer',
-  instructions: 'skills/professional-answer',
-  prompt: '{{question}}',
-  workingMemory: { question: 'What is...' },
-  inferenceType: 'question-answer', // Recommended
-  skillId: 'skills/professional-answer', // Optional, auto-detected from instructions
-  primaryObjectType: 'professional-answer',
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'my-agent', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'my-agent'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
+### Gateway constructor (common flags)
 
-// Get the activity ID for linking child skills
-const activityId = response.metadata?.activityId;
-```
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `enableLogging` | `true` | Logxer pipeline |
+| `logger` | built-in | Pass your app `createLogxer()` instance |
+| `enableActivityTracking` | `true` | Activix persistence (needs Mongo env when no `activityTracker`) |
+| `activityTracker` | — | Custom `Activix` instance (collection names must still match package constants) |
+| `enableUsageTracking` | `true` | In-process usage tier helper |
+| `aiTools` | see below | Model resolution + catalog pricing |
+| `mode` | `'debug'` | `'dev'` \| `'debug'` \| `'prod'` — affects strict model resolution |
+| `diagnostics` | — | `{ mode: 'trace' }` for rich `metadata.attempts` / `metadata.usage` |
+| `retry` / `rateLimit` | from `defaults/model-config.json` | Router retry and between-call spacing |
 
-**Example: Nested Skill Execution (Skill Calling Another Skill)**
+Defaults load from `defaults/model-config.json`, `instructions-blocks.json`, and `template-rendering.json` (copied into `dist/` on build).
 
-```typescript
-const parentAiRequestId = 'skill-parent-1';
-// Parent skill execution
-const parentResponse = await gateway.invoke({
-  aiRequestId: parentAiRequestId,
-  agentId: 'my-agent',
-  actionType: 'skill',
-  actionRef: 'skills/parent-skill',
-  instructions: 'skills/parent-skill',
-  prompt: '{{input}}',
-  workingMemory: { input: '…' },
-  inferenceType: 'analysis',
-  skillId: 'skills/parent-skill',
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'my-agent', type: 'test' },
-    aiRequestId: parentAiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-parent',
-    agentId: 'my-agent'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
+### Environment (selected)
 
-const childAiRequestId = 'skill-child-1';
-// When parent skill calls child skill, pass parent's activityId and skillId
-const childResponse = await gateway.invoke({
-  aiRequestId: childAiRequestId,
-  agentId: 'my-agent',
-  actionType: 'skill',
-  actionRef: 'skills/child-skill',
-  instructions: 'skills/child-skill',
-  prompt: '{{input}}',
-  workingMemory: { input: '…' },
-  inferenceType: 'question-answer',
-  skillId: 'skills/child-skill',
-  masterSkillActivityId: parentResponse.metadata?.activityId, // ✅ Parent's activity ID
-  masterSkillId: 'skills/parent-skill', // ✅ Parent's skill ID
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'my-agent', type: 'test' },
-    aiRequestId: childAiRequestId,
-    jobId: 'job-123', // ✅ Same jobId (links activities)
-    taskId: 'task-child',
-    agentId: 'my-agent'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
-```
+| Variable | Role |
+|----------|------|
+| `MONGO_URI`, `MONGO_LOGS_DB` / `MONGO_DB` | Activix when no custom tracker |
+| `AI_GATEWAY_DEFAULT_MODEL` | Default model slug (`provider/model` or OpenRouter id) |
+| `mode` / `MODE` | Operational mode (`dev`, `debug`, `prod`) |
+| `AI_GATEWAY_LOGS_LEVEL` | Log level when using default logger (`AI_GATEWAY` prefix) |
+| `FLEX_MD_MIN_COMPLIANCE_LEVEL` | `L0`–`L3` output-format validation (default `L0`) |
+| Provider API keys | OpenRouter, OpenAI, etc. |
 
-**Automatic Tracking:**
+Logging details: [Logger initialization](./docs/LOGGER_INITIALIZATION.md).
 
-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)
+## @x12i/ai-tools v2 (models + cost)
 
-### 3. Usage Tracking Configuration (x-models)
+- **No Catalox / Firestore** — catalogs come from ai-tools open-assets JSON (optional `bundledOnly`).
+- **`aiTools.enabled`** — bootstrap catalog client + calculator.
+- **`aiTools.resolveModels`** — `mergeConfig()` resolves model ids (strict in **`mode: 'dev'`**).
+- **`aiTools.calculateCost`** — prices usage before Activix `completeRecord` when the router did not mark the call priced.
 
-**Where to configure:**
-- Gateway constructor: `enableUsageTracking`, `usageTier`
-- JSON defaults: `src/defaults/model-config.json` (not used for usage tracking)
+Gateway helpers (also exported): `resolveCostCompletionWithAiTools`, `buildTraceUsageSummary`, `enrichTraceAttemptsWithBilling`.
 
-**How to configure:**
+---
 
-```typescript
-const gateway = new AIGateway({
-  enableUsageTracking: true,  // Default: true
-  usageTier: 'tier-3'         // RPM/TPM limits: 'tier-1' | 'tier-2' | 'tier-3'
-});
-```
+## Activity tracking (@x12i/activix 7.2)
 
-**Note:** If `@x12i/x-models` is not available or has export issues, usage tracking will gracefully degrade with warnings logged.
+When tracking is enabled and no custom tracker is supplied, the gateway constructs Activix with fixed collection names (see `src/config/activity-tracking-config.ts`):
 
-**Default:** Usage tracking is enabled by default with `usageTier: 'tier-3'`
+| Collection | Typical use |
+|------------|-------------|
+| `ai-actions` | Normal gateway invocations |
+| `bad-requests` | Validation / pre-start failures |
+| `skill-executions` | Skill-specific rows |
 
-### 4. Default Model and Engine Configuration
+**Lifecycle:** `startRecord` → `completeRecord` / `failRecord` keyed by **`activityId`** (not `jobId`).
 
-**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`
+**Successful completion** (no duplicate billing on `outer.metadata`):
 
-**How to configure:**
+- Root: `cost`, `costUsd`, `costStatus`, **`metadata`** (routing + billing mirror for Activix 7.x)
+- `outer.metadata`: routing only (`modelUsed`, `provider`, …)
+- `outer.cost`: Activix cost shape (`usd`, `tokens`, `provider`, `model`, `details`)
+- `response.metadata`: same billing slice as returned to callers
 
-**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
-}
-```
+When **`aiTools.calculateCost`** is on and you do not pass `activityTracker`, Activix **`autoCost`** is enabled with **`overwriteOuterCost: false`** so gateway-computed cost wins.
 
-**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
-});
-```
+Mongo env: `MONGO_URI` + `MONGO_LOGS_DB` or `MONGO_DB`.
 
-**Step 3: Request-level override:**
-```typescript
-const aiRequestId = 'cfg-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-456',
-  actionType: 'skill',
-  actionRef: 'skills/helpful',
-  instructions: 'You are helpful',
-  prompt: '{{input}}',
-  workingMemory: { input: 'Hello' },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-456', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-456'
-  },
-  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)
+## Response metadata and cost
 
-### 5. InstructionsBlocks Configuration
+On every successful **`invoke()`**:
 
-**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
+- **`metadata.provider`**, **`modelUsed`**, **`maxTokensRequested`**, **`effectiveModelConfig`**
+- **`metadata.tokens`**, **`costStatus`**, **`costUsd`** when usage exists and pricing applies
 
-**How to configure:**
+Full contract: [AI Gateway invoke execution metadata](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md).
 
-**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."
-}
-```
+### Trace diagnostics
 
-**Step 2: Gateway constructor:**
 ```typescript
-const gateway = new AIGateway({
-  instructionsBlocks: {
-    'input-prefix': 'Custom prefix from config:',  // Overrides JSON default
-    'custom-block': 'Custom block content'
-  }
+await gateway.invoke({
+  ...request,
+  diagnostics: { mode: 'trace' }
 });
 ```
 
-**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
-  }
-});
+Adds **`metadata.attempts`**, **`metadata.usage`**, **`metadata.requestIds`**, and per-attempt **`costUsd`** / **`costStatus`** after catalog enrichment.
 
-// 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`.
+## Operational modes
 
-**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
+| Mode | Model resolution | Notes |
+|------|------------------|-------|
+| `dev` | Strict — unknown models fail at `mergeConfig` | Best for CI / local |
+| `debug` | Lenient defaults | Default when env unset |
+| `prod` | Falls back to configured default model when resolution fails | See `src/gateway-mode.ts` |
 
-**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.
+Set via constructor `mode` or env `mode` / `MODE`.
 
-### 7. Template Parsing Configuration (workingMemory)
+---
 
-**Where to configure:**
-- Request-level: `workingMemory` object
+## Testing
 
-**How to configure:**
+| Script | What it runs |
+|--------|----------------|
+| `npm test` | All unit/integration tests in `.tests/run-all.js` (tsx, no network) |
+| `npm run test:ai-tools` | ai-tools + cost + trace helper unit tests |
+| `npm run test:ai-tools:live` | Real invoke + dev strict model check (needs API key) |
+| `npm run test:flex-md-parsing` | flex-md parsing scenarios |
+| `npm run test:flex-md-esm-regression` | ESM build regression for flex-md |
+| `npm run test:prepublish` | `build` + `npm test` |
 
-```typescript
-const aiRequestId = 'tpl-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-456',
-  actionType: 'skill',
-  actionRef: 'skills/professional-answer',
-  // 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
-  workingMemory: {
-    role: 'helpful',
-    project: 'AI Gateway',
-    type: 'product review',
-    input: 'This is a review'
-  },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-456', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-456'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
-```
+Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` + `openai/gpt-4o-mini`). Set `LIVE_SKIP_INVOKE=1` to skip the LLM call.
 
-**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**
+## Documentation index
 
-- 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`.
+| Document | Topic |
+|----------|--------|
+| [IDENTITY_OBJECT_CONTRACT.md](./docs/IDENTITY_OBJECT_CONTRACT.md) | Identity / `runContext` |
+| [AI_GATEWAY_INVOKE_EXECUTION_METADATA.md](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md) | Metadata, cost, trace, Activix completion |
+| [LOGGER_INITIALIZATION.md](./docs/LOGGER_INITIALIZATION.md) | Logxer setup |
+| [flex-md-compliance.md](./docs/flex-md-compliance.md) | Output format levels |
+| [PROMPT_TEMPLATE_USAGE.md](./docs/PROMPT_TEMPLATE_USAGE.md) | Rendrix templates |
+| [UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md](./docs/UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md) | Parser v4 |
+| [RUNTIME_OBJECTS_OBSERVABILITY.md](./docs/RUNTIME_OBJECTS_OBSERVABILITY.md) | Runtime object keys |
+| [GRAPH_EXECUTION_SUPPORT.md](./docs/GRAPH_EXECUTION_SUPPORT.md) | Graph / node identity |
+| [DUAL_PACKAGE_SETUP_GUIDE.md](./docs/DUAL_PACKAGE_SETUP_GUIDE.md) | ESM + CJS publish layout |
 
-**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` / `AIInvokeRequest`) — merged on top of the gateway default for that call only (per-field override; `subPathSearch` fields merge with request winning).
-- **Smart Input (optional shorthand on the request)** — top-level **`smartInput`** (`SmartInputConfig`) and **`smartInputRenderOptions`** (`SmartInputRenderOptions`) are merged into the same Rendrix options object **after** `GatewayConfig.templateRendering` and **before** `templateRenderOptions`. If you set the same field both as a shorthand and inside **`templateRenderOptions`**, the nested **`templateRenderOptions`** value wins. Templates use the **`{{smartInput}}`** insertion macro (see **`@x12i/rendrix`**). Types **`SmartInputConfig`** and **`SmartInputRenderOptions`** are re-exported from this package.
-- For programmatic merges (tests or wrappers), use **`mergeGatewayAndRequestTemplateRenderOptions`** (same rules as `buildMessages`).
-- Supported fields match the parser: **`templateId`**, **`subPathSearch`** (`enabled`, `roots`), **`silentMissingMustTokens`** (legacy Handlebars-style silence for missing MUST paths), **`smartInput`**, **`smartInputRenderOptions`**.
-- **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.
+## Troubleshooting helpers
 
 ```typescript
-// Example: prefer execution.*, then input.*, then inputs.* when a full path misses
-new AIGateway({
-  templateRendering: {
-    subPathSearch: {
-      enabled: true,
-      roots: ['execution', 'input', 'inputs']
-    }
-  }
-});
+import { validateAIRequest, diagnoseRequest, formatDiagnostic } from '@x12i/ai-gateway';
 ```
-- **Memory overlay priority** for Rendrix resolution (when memories are supplied): **`shortTermMemory`** → **`workingMemory`** → **`experienceMemory`** → **`knowledgeMemory`**. (Request-level **`templateTokens`** was removed; put overrides in **`workingMemory`** or resolver-backed memories.)
-- 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).
 
+Enable request logging:
 
-### 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.
+```bash
+export AI_GATEWAY_DEBUG=true
+export AI_GATEWAY_DEBUG_REQUEST=true
+export FLEX_MD_MIN_COMPLIANCE_LEVEL=L0
 ```
 
-**📋 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']
-});
+## Build and publish
 
-// 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
-}));
+```bash
+npm run build    # ESM + CJS + defaults copy + CJS verify
+npm run test:prepublish
 ```
 
-**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`)
+Published files: `dist/`, `dist-cjs/`, `config.defaults.json`, `README.md`.
 
-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 { createLogxer } from '@x12i/logxer';
-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 = createLogxer(
-  { packageName: 'MY_APP', envPrefix: 'MY_APP', debugNamespace: '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-actions', 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
-
-Throughout this section, **`gateway.invoke()`** examples must include **`aiRequestId`**, **`identity`** (with **`jobId`** / **`taskId`**), **`actionType`**, **`actionRef`**, and usually **`prompt`** + **`workingMemory`** unless noted. Older snippets that show only **`jobId`** / **`input`** / **`parseOptions`** / **`validateOutputSchema`** / **`transformations`** are outdated relative to the current [`AIInvokeRequest`](#chatrequest-and-airequest--aiinvokerequest) type.
-
-### 1. Context Propagation (identity / job / task)
-
-Correlation flows through **`request.identity`**: **`identity.jobId`** and **`identity.taskId`** are supplied by the upstream client, forwarded to the router, echoed in **`response.metadata.identity`**, and persisted as Activix **`runContext`**. For **`invoke()`**, also set **`actionType`** and **`actionRef`** (see [AI invoke payload](#ai-invoke-payload-gatewayinvoke)).
-
-```typescript
-const aiRequestId = 'call-001';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-456',
-  actionType: 'skill',
-  actionRef: 'skills/example',
-  instructions: 'You are a helpful assistant.',
-  prompt: '{{input}}',
-  workingMemory: { input: 'What is AI?' },
-  identity: {
-    sessionId: 'run-1',
-    instance: { instanceId: 'agent-456', type: 'ai-reasoner' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-789',
-    agentId: 'agent-456'
-  },
-  config: { model: 'gpt-5-nano', provider: 'openai' }
-});
-```
-
-**Note:** On **`invoke()`**, provider **`messages`** are produced by the internal message builder from **`instructions`** / **`prompt`** / **`context`** (not from a client **`messages`** array). Use **`invokeChat()`** if you need to pass a raw **`messages`** array.
-
-**Request requirements (`invoke`):**
-- **Required**: `aiRequestId`, `agentId`, `instructions`, `identity` (with upstream `jobId` / `taskId`), `actionType`, `actionRef`; structured flows typically need `prompt` + `workingMemory` for templates (see message builder).
-- **Optional**: `context`, `messages`, graph/skill linkage fields, `config` / `modelConfig`.
-- Do **not** use top-level **`input`** — use **`workingMemory.input`** (and **`{{input}}`** in templates).
-
-**Benefits:**
-- Stable tracing across logs and Activix
-- Clear separation between chat (`invokeChat`) and structured invoke (`invoke`)
-
-### 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 v7)
-
-The gateway uses **`@x12i/activix` v7** (xronox-activitix) for full lifecycle logging. Recommended: enable MongoDB persistence so tracking is automatic. Writes use the **fixed** Mongo collection names **`ai-actions`**, **`bad-requests`**, and **`skill-executions`** (literal strings from `activity-tracking-config.ts`; see **section 2** for what lands in each collection and how documents are shaped).
-
-#### ⚠️ 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`).
-   - **`identity.jobId`** and **`identity.taskId`** (required): Taken only from the upstream **`identity`** object; the gateway does not invent them.
-   - **`jobTypeId`**, **`taskTypeId`**: Optional aggregation fields (same ideas as before).
-   - **Activity**: Each individual LLM request is a separate **activity** with its own unique record.
-
-2. **`activityId` + Mongo `_id` (not `jobId`)**
-   - Each row gets Mongo **`_id`** and an Activix **`activityId`** (e.g. **`act-…`**, the collection **`primaryKey`**). **`completeRecord` / `failRecord`** address the row by **`activityId`** returned from **`startRecord`**.
-   - **`jobId`** / **`taskId`** mirror upstream **`identity`** for correlation only; many rows may share a **`jobId`**.
-
-3. **Two-phase tracking (Activix v7)**
-   - **Phase 1 (start)**: Creates a NEW database document
-     - Sends **`runContext`**, **`request`**, **`config`**, **`startTime`**, **`status: 'started'`**, plus Activix **`outer.input`** (wraps **`activityType`** and the same **`request`** snapshot when present — see section 2).
-     - Returns **`activityId`** (and record payload) for phase 2.
-   - **Phase 2 (complete / fail)**: Updates the SAME document by **`activityId`**
-     - Success: **`response`**, root **`cost`** / **`costUsd`** / **`costStatus`**, **`endTime`**, **`duration`**, **`status`**, **`outer.output`** (completion payload), **`outer.metadata`** (routing + billing mirror), and **`outer.cost`** when usage or price is known (see [Cost reporting](#cost-reporting-invoke-response--activix-run-analysis-g8)).
-     - Failure: error payload and timing; optional **`response`** / **`outer.output`** only for specific failure kinds.
-
-4. **Structured fields vs Activix `outer` (v2.6.0+):**
-   - LLM request fields live under root **`request`** (not as loose keys on the document root). Config under **`config`**; completion payload under **`response`**.
-   - **`outer`** duplicates the logical **request** snapshot under **`outer.input.request`** when applicable — required for Activix v7 validation — so root **`request`** and **`outer.input.request`** align by design ([details](./docs/ACTIVITIES_OUTER_DUPLICATION.md)).
-
-**Example: same logical job, three LLM calls**
-
-Each call must have a **distinct `aiRequestId`** and a full **`identity`** (including **`jobId`** and **`taskId`** from upstream). Use the same **`identity.jobId`** (and distinct **`taskId`** per call, or your own convention) 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',
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/example',
-  instructions: '…',
-  prompt: '{{input}}',
-  workingMemory: { input: '…' },
-  jobTypeId,
-  identity: {
-    sessionId: 'sess-1',
-    instance: { instanceId: 'inst-1', type: 'gateway' },
-    aiRequestId: 'req-001',
-    jobId: 'job-123',
-    taskId: 'task-001',
-    agentId: 'agent-1'
-  },
-  config: { model: 'gpt-5-nano', provider: 'openai' }
-});
-
-await gateway.invoke({
-  aiRequestId: 'req-002',
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/example',
-  instructions: '…',
-  prompt: '{{input}}',
-  workingMemory: { input: '…' },
-  jobTypeId,
-  identity: {
-    sessionId: 'sess-1',
-    instance: { instanceId: 'inst-1', type: 'gateway' },
-    aiRequestId: 'req-002',
-    jobId: 'job-123',
-    taskId: 'task-002',
-    agentId: 'agent-1'
-  },
-  config: { model: 'gpt-5-nano', provider: 'openai' }
-});
-
-// Query in Mongo (main collection name is ai-actions):
-// db.getCollection('ai-actions').find({ 'runContext.aiRequestId': 'req-001' })
-// db.getCollection('ai-actions').find({ 'runContext.jobId': 'job-123' })
-```
-
-#### 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-actions', 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
-
-Example shape for a completed row in **`ai-actions`** (`activityType: 'gateway-invocation'`). **`skill-executions`** / **`bad-requests`** share the same Activix lifecycle pattern but different **`activityType`** and fields.
-
-```typescript
-{
-  // Mongo primary key
-  _id: ObjectId('693970636e8d0f171e4aa528'),
-
-  // Activix logical row key (returned from startRecord; used by completeRecord / failRecord)
-  activityId: 'act-63f0357e-b2fc-4038-8f94-a9c7fa8fb892',
-
-  activityType: 'gateway-invocation',
-
-  // Activix v7: canonical correlation BSON object `runContext` (same reference as `request.identity`, merged with gateway fields)
-  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',
-
-  // Activix v7 root-level I/O tier — see section 2 for semantics
-  // startRecord: outer.input ≈ { activityType, request } (request matches root `request` when present)
-  // completeRecord: outer.output ← same object as root `response` on success
-  outer: {
-    input: { activityType: 'gateway-invocation', request: { /* same snapshot as root request */ } },
-    output: { /* success: gateway activity response (content, parsed, metadata, usage) */ },
-    metadata: {
-      modelUsed: 'openai/gpt-5-nano-2025-08-07',
-      provider: 'openrouter',
-      cost: 0.0000348,
-      costUsd: 0.0000348,
-      costStatus: 'priced'
-    },
-    cost: {
-      usd: 0.0000348,
-      unit: 'USD',
-      tokens: { input: 16, output: 85, total: 101 },
-      provider: 'openrouter',
-      model: 'openai/gpt-5-nano-2025-08-07',
-      details: { costStatus: 'priced' /* optional costBreakdown when aiTools.costIncludeBreakdown */ }
-    }
-  },
-  // inner: optional step array for multi-step flows (see @x12i/activix docs)
-  
-  // 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)
-    },
-    messages: [...],  // Final constructed messages array
-    workingMemory: {...}  // Template/user payload (e.g. { input: '…' } for '{{input}}'); not a separate root `input` field
-  },
-  
-  // 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: {...}
-  },
-  
-  // Billing (from logSuccess — mirrors response.metadata from invoke)
-  cost: 0.0000348,
-  costUsd: 0.0000348,
-  costStatus: 'priced',
-  
-  // Metadata
-  createdAt: Date,
-  updatedAt: Date
-}
-```
-
-**Key points:**
-- ✅ Each activity = separate Mongo document (**`_id`**) with stable **`activityId`** (`act-…`) for Activix APIs
-- ✅ **`aiRequestId`** = per-request correlation (required on invoke)
-- ✅ **`runContext.jobId`** / **`runContext.taskId`** = upstream identity (required on invoke since v9+)
-- ✅ Request/config sent at **start**; response/timing/billing (`cost`, `costUsd`, `costStatus`, `outer.cost`) at **complete**
-- ✅ Updates target **`activityId`** from **`startRecord`**, not **`jobId`**
-
-#### Retry Tracking (@x12i/activix v7)
-
-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 aiRequestId = 'resp-shape-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-456',
-  actionType: 'skill',
-  actionRef: 'skills/qa',
-  instructions: 'You are a helpful assistant.',
-  prompt: '{{input}}',
-  workingMemory: { input: 'What is AI?' },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-456', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-456'
-  },
-  config: { model: 'gpt-5-nano', provider: 'openai' }
-});
-
-// 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')
-    modelUsed?: string,         // Resolved/served model id (when distinct from request model)
-    provider?: string,          // Provider used (e.g., 'openai', 'anthropic')
-    costStatus?: 'priced' | 'unpriced',  // Billing state (Run Analysis G8)
-    costUsd?: number,           // USD when costStatus === 'priced' (preferred field)
-    cost?: number,              // USD mirror of costUsd when priced
-    costBreakdown?: {           // Optional when aiTools catalog pricing runs (calculateCost + breakdown)
-      promptCostUsd?: number;
-      completionCostUsd?: number;
-      // ...other breakdown keys from @x12i/ai-tools
-    },
-    
-    // ============================================
-    // 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.costStatus` - `priced` | `unpriced` (see [Cost reporting](#cost-reporting-invoke-response--activix-run-analysis-g8))
-- `metadata.costUsd` / `metadata.cost` - USD when priced
-- `metadata.costBreakdown` - Optional catalog breakdown when `aiTools.calculateCost` applies
-- `metadata.model` / `metadata.modelUsed` - Model id used
-- `metadata.provider` - Provider used
-
-#### Example: Full Response
-
-```typescript
-const aiRequestId = 'cls-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-456',
-  actionType: 'skill',
-  actionRef: 'skills/sentiment',
-  instructions: 'Classify sentiment',
-  prompt: '{{input}}',
-  workingMemory: { input: 'I love this product!' },
-  inferenceType: 'classification',
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-456', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-456'
-  },
-  config: { model: 'gpt-5-nano', provider: 'openai' }
-});
-
-// 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
-    },
-    modelUsed: 'gpt-5-mini',
-    provider: 'openai',
-    costStatus: 'priced',
-    costUsd: 0.002,
-    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 **`@x12i/logxer`** for structured logging with **`LogMeta`** correlation. See [Logger initialization](./docs/LOGGER_INITIALIZATION.md).
-
-```typescript
-import { createLogxer } from '@x12i/logxer';
-
-const gateway = new AIGateway({
-  enableLogging: true,
-  packageName: 'MY_APP',
-  logger: createLogxer(
-    { packageName: 'MY_APP', envPrefix: 'MY_APP', debugNamespace: '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.).
-
-> **Current request model:** **`parseOptions`**, **`validateOutputSchema`**, and **`strictValidation`** are **not** fields on **`ChatRequest`** / **`AIInvokeRequest`** anymore (removed). **`inferenceType`** may still be recorded for **Activix** / activity metadata. The primary **`invoke()`** response path uses **flex-md extraction** into **`parsedContent`**; for **`@x12i/outputs-library`** workflows, parse **`response.content`** / **`parsedContent`** in your app or follow instruction metadata (**`InstructionMetadata.parseOptions`** applies to catalog entries, not the invoke payload).  
-> The **code samples** in subsections below still show legacy request shapes for illustration — adjust them to include **`aiRequestId`**, **`identity`**, **`actionType`**, **`actionRef`**, **`prompt`**, **`workingMemory`**, and omit removed fields.
-
-#### Overview
-
-When **`@x12i/outputs-library`** is used (directly or via future gateway wiring), specifying an **`inferenceType`** can classify parsing intent. Response typing and validation should align with your integration layer and **`EnhancedLLMResponse.metadata`** (e.g. **`parsedContent`**, **`parsingMethod`**).
-
-#### 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 (`invoke` + `inferenceType`)
-
-`parseOptions` / `validateOutputSchema` / `strictValidation` are **not** request fields. Supply **`aiRequestId`**, **`identity`**, **`actionType`**, **`actionRef`**, **`prompt`**, **`workingMemory`**, and optionally **`inferenceType`** for activity metadata.
-
-```typescript
-const aiRequestId = 'cls-1';
-const identity = {
-  sessionId: 's1',
-  instance: { instanceId: 'agent-456', type: 'test' },
-  aiRequestId,
-  jobId: 'job-123',
-  taskId: 'task-1',
-  agentId: 'agent-456'
-};
-
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-456',
-  actionType: 'skill',
-  actionRef: 'skills/classification',
-  instructions: 'Classify the sentiment of the text.',
-  prompt: '{{input}}',
-  workingMemory: { input: 'This product is amazing!' },
-  inferenceType: 'classification',
-  identity,
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
-```
-
-Use the same shape for **`question-answer`**, **`extraction`**, etc., changing **`inferenceType`**, **`instructions`**, and **`workingMemory`**. Parse or validate structured output with **`@x12i/outputs-library`** in your process if needed.
-
-
-#### 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 aiRequestId = 'schema-guide-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-456',
-  actionType: 'skill',
-  actionRef: 'skills/extraction-user-data',
-  instructions: 'extraction/user-data', // Instruction key with outputSchema
-  prompt: '{{input}}',
-  workingMemory: { input: 'John Doe, john@example.com, 30 years old' },
-  inferenceType: 'extraction',
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-456', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-456'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
-
-// 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 (request flags removed)
-
-**`validateOutputSchema`** and **`strictValidation`** are **not** on **`AIInvokeRequest`** / **`ChatRequest`** anymore. Validate **`response.parsedContent`** or **`response.content`** in your application (for example **`SchemaValidator`** from **`@x12i/outputs-library`**).
-
-Instruction metadata can still carry **`outputSchema`** for documentation and instruction rendering via the content registry; that does **not** restore the old request-level validation switches.
-
-
-#### 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 aiRequestId = 'audit-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-456',
-  actionType: 'skill',
-  actionRef: 'skills/extraction-user-data',
-  instructions: 'extraction/user-data',
-  prompt: '{{input}}',
-  workingMemory: { input: 'John Doe, john@example.com' },
-  inferenceType: 'extraction',
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-456', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-456'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
-
-// When present, `outputAudit` is informational (see types / runtime behavior)
-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 (removed from request)
-
-**Current behavior:** Request-level `transformations` and the `ResponseTransformationConfig` type are **no longer** part of the gateway request model. They were removed in favor of a smaller public surface.
-
-**What to use instead:**
-
-- Post-process `EnhancedLLMResponse` in your application (e.g. map `parsedContent` / `content`).
-- Use router **request/response interceptors** from `@x12i/ai-providers-router` where appropriate.
-- For instruction-catalog defaults, `InstructionMetadata` may still carry its own `parseOptions`; that is metadata about an instruction definition, **not** a field on `ChatRequest` / `AIInvokeRequest`.
-
-Historical examples in older docs or forks that show `transformations` on `invoke()` payloads should be ignored or migrated.
-
-### 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 (structured invoke path resolves templates from workingMemory)
-const aiRequestId = 'text-mode-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/classification',
-  instructions:
-    'You are a helpful assistant that classifies text into categories: positive, negative, or neutral.',
-  prompt: '{{userLine}}',
-  workingMemory: { userLine: 'Classify: "This product is amazing!"' },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-1', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-1'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
-```
-
-**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 — pass the instruction key on `instructions`; user text via `prompt` + `workingMemory`
-const aiRequestId = 'key-mode-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-456',
-  actionType: 'skill',
-  actionRef: 'skills/classification',
-  instructions: 'classification/basic', // ✅ Key - resolved from content-registry
-  prompt: '{{userLine}}',
-  workingMemory: {
-    userLine: 'Classify: "This product is amazing!"',
-    task: 'classification',
-    context: 'product reviews'
-  },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-456', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-456'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
-```
-
-**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 **`workingMemory`** (and tier memories) using Rendrix
-6. Gateway returns rendered instruction text with metadata
-7. Sends the resolved instruction to the LLM
-
-**Note:** **`gateway.invoke()`** builds provider **`messages`** from **`instructions`** / **`prompt`** / **`context`** via the message builder; it does **not** append a raw **`messages`** array from the request. For a pre-built transcript, use **`gateway.invokeChat()`** (see below).
-
-**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 aiRequestId = 'tpl-key-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-456',
-  actionType: 'skill',
-  actionRef: 'skills/professional-answer',
-  instructions: 'professional-answer.instructions', // Key with suffix
-  prompt: 'professional-answer.prompt', // Key with suffix
-  workingMemory: {
-    input: 'What is the capital of France?',
-    taskDescription: 'Answer questions professionally'
-  },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-456', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-456'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
-```
-
-**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 aiRequestId = 'tpl-vars-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-456',
-  actionType: 'skill',
-  actionRef: 'skills/classification',
-  instructions: 'classification/basic',
-  prompt: '{{userLine}}',
-  workingMemory: {
-    userLine: 'Classify: "This product is amazing!"',
-    task: 'classification',
-    classes: 'positive, negative, neutral'
-  },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-456', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-456'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
-```
-
-**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 (multi-turn chat vs registry keys)
-
-**Registry keys** are resolved on **`gateway.invoke()`** when you pass the key on **`instructions`** / **`prompt`** (see key-mode example above). **`gateway.invoke()`** does **not** consume a client-supplied **`messages`** array for the provider call.
-
-For **multi-turn** transcripts (system/user/assistant/user, arbitrary order), use **`gateway.invokeChat()`**. Pass **`instructions: ''`** when your **`messages`** array already includes the system prompt, so the gateway does not prepend a second system message. Message bodies are sent **literally**—if you need a registry key as the system prompt, resolve it first (e.g. **`InstructionResolver`** / **`getInstructionMetadata`**) and put the rendered text in **`messages`**.
-
-```typescript
-const aiRequestId = 'mix-chat-1';
-const response = await gateway.invokeChat({
-  aiRequestId,
-  agentId: 'agent-1',
-  instructions: '',
-  messages: [
-    {
-      role: 'system',
-      content:
-        '…system prompt text (resolve content-registry keys beforehand if needed)…'
-    },
-    { role: 'user', content: 'You are analyzing product reviews.' },
-    { role: 'assistant', content: 'I understand.' },
-    { role: 'user', content: 'Classify: "This product is amazing!"' }
-  ],
-  workingMemory: { task: 'classification' },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-1', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-1'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
-```
-
-**Use cases**:
-- Multi-turn chat while keeping **`workingMemory`** / **`templateRenderOptions`** available on the chat path
-- Single-shot registry-backed flows → prefer **`invoke()`** with **`instructions`** as the key
-
-#### 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 (parsing options live on metadata for your app, not on the request)
-  const aiRequestId = `md-${Date.now()}`;
-  const response = await gateway.invoke({
-    aiRequestId,
-    agentId: 'agent-1',
-    actionType: 'skill',
-    actionRef: metadata.instructionKey || 'skills/classification',
-    instructions: 'classification/basic',
-    prompt: '{{input}}',
-    workingMemory: { input: 'This is great!', ...variables },
-    inferenceType: metadata.outputType,
-    identity: {
-      sessionId: 's1',
-      instance: { instanceId: 'agent-1', type: 'test' },
-      aiRequestId,
-      jobId: 'job-1',
-      taskId: 'task-1',
-      agentId: 'agent-1'
-    },
-    config: { model: 'gpt-4o', provider: 'openai' }
-  });
-  
-  // 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 instruction key on invoke() (resolved via content-registry)
-const aiRequestId = 'registry-step2-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/classification',
-  instructions: 'classification/basic',
-  prompt: '{{userLine}}',
-  workingMemory: {
-    userLine: 'Classify: "This is great!"',
-    task: 'classification',
-    classes: 'positive, negative, neutral'
-  },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-1', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-1'
-  },
-  config: { model: 'gpt-4o', provider: 'openai' }
-});
-```
-
-**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)
-- **Migration**: Prefer **`invoke()`** + **`instructions`** keys for registry-backed single-shot flows; multi-turn **`messages`** arrays belong on **`invokeChat()`** (see Mixed Mode). Request payloads require **`identity`**, **`aiRequestId`**, and (for **`invoke()`**) **`actionType`** / **`actionRef`** — top-level **`input`** is rejected.
-- **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, invoke() fails closed during message build
-// (bad-request logging when activity tracking is enabled)—there is no silent fallback to raw text.
-const aiRequestId = 'registry-err-1';
-try {
-  await gateway.invoke({
-    aiRequestId,
-    agentId: 'agent-1',
-    actionType: 'skill',
-    actionRef: 'skills/invalid',
-    instructions: 'invalid/key',
-    prompt: '{{input}}',
-    workingMemory: { input: 'hello' },
-    identity: {
-      sessionId: 's1',
-      instance: { instanceId: 'agent-1', type: 'test' },
-      aiRequestId,
-      jobId: 'job-123',
-      taskId: 'task-1',
-      agentId: 'agent-1'
-    },
-    config: { model: 'gpt-4o', provider: 'openai' }
-  });
-} catch (e) {
-  // Expect resolution / instruction errors; see TROUBLESHOOTING.md
-}
-```
-
-#### 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 hints (`StructuredTextSpec`) vs gateway parsing
-
-**`ChatRequest`** still includes an optional **`expectedSchema?: StructuredTextSpec`** field for typing and forward compatibility:
-
-```typescript
-interface StructuredTextSpec {
-  description: string;
-  formatHint?: string;
-}
-```
-
-**Current gateway behavior:** dedicated **contract-output** processing (persisting **`content.contractOutput`** / **`content.outputStatus`** on activities from **`expectedSchema`**) is **not** implemented on **`invoke()`** / **`invokeChat()`** — see comment in `gateway.ts` (“Contract output processing removed”). Passing **`expectedSchema`** does not, by itself, trigger extra persistence or validation inside this package.
-
-**Recommended patterns:**
-
-- Rely on **flex-md extraction** into **`response.parsedContent`** / **`response.content`** and validate in your app (e.g. **`@x12i/outputs-library`**, JSON Schema, or custom checks).
-- Use **response interceptors** if you need centralized post-processing or compliance logging.
-- Encode output shape in **instructions** / instruction metadata (**`outputSchema`**) so the model sees the contract; enforce it application-side.
-
-## 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?: import('@x12i/logxer').Logxer;  // Custom Logxer (from createLogxer)
-  activityTracker?: Activix;           // Custom Activix v7 instance (match collection names: ai-actions, 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: AIInvokeRequest): Promise<EnhancedLLMResponse>` - Structured / skill path; requires **`actionType`**, **`actionRef`**, **`identity`**, **`aiRequestId`**, **`instructions`**, etc. (`AIRequest` is a type alias)
-- `invokeChat(request: ChatRequest): Promise<EnhancedLLMResponse>` - Chat / conversational path (no **`actionType`** / **`actionRef`**)
-- `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(): Logxer` - Get logger instance (`@x12i/logxer`)
-- `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 / AIInvokeRequest
-
-**Naming**
-
-- **`ChatRequest`** — pass to **`gateway.invokeChat()`**. Conversational path; optional **`expectedSchema`** (`StructuredTextSpec`) for contract-style validation when enabled.
-- **`AIInvokeRequest`** — pass to **`gateway.invoke()`**. Canonical structured/skill path.
-- **`AIRequest`** — **type alias** for **`AIInvokeRequest`** (keeps existing imports working).
-
-**Mandatory on `invoke()` (`AIInvokeRequest`)**
-
-| Field | Meaning |
-|-------|--------|
-| **`actionType`** | **`'skill'`** \| **`'preSkill'`** \| **`'postSkill'`** — classifies the invocation for tracing and Activix. |
-| **`actionRef`** | Non-empty string reference for the action (e.g. **`skills/my-skill`**). Recorded with the activity. |
-
-These are validated by **`validateAIRequest`**, merged into **`request.identity`** ( **`runContext`** for Activix ), and duplicated on activity root fields **`actionType`** / **`actionRef`** when activity tracking runs.
-
-**Mandatory on both paths**
-
-- **`aiRequestId`**, **`agentId`**, **`instructions`**, **`identity`** (upstream **`identity.jobId`** and **`identity.taskId`** — see [Mandatory runtime identity](#mandatory-runtime-identity-v9)).
-- Top-level **`input`** is **not** supported; use **`workingMemory`** (e.g. **`workingMemory.input`**) for template data.
-
-**Removed from the shared request model (`BaseLLMRequest`)**
-
-Not accepted on gateway requests anymore:
-
-- **`taskConfig`**, **`templateTokens`**, **`validateOutputSchema`**, **`strictValidation`**, **`transformations`**, **`parseOptions`** (request-level).
-
-Use **`InstructionMetadata.parseOptions`** only as **instruction-catalog metadata**, not as invoke payload fields.
-
-**Exports**
-
-```typescript
-import type {
-  ChatRequest,
-  AIInvokeRequest,
-  AIRequest,           // alias of AIInvokeRequest
-  GatewayActionType,    // 'skill' | 'preSkill' | 'postSkill'
-  ActivityIdentity,
-  EnhancedLLMResponse
-} from '@x12i/ai-gateway';
-```
-
-**Structured output helpers**
-
-Structured flows often use **`primaryObjectType`** / **`objectTypes`** from the router **`LLMRequest`** intersection (type guards in message building). They are **not** duplicated here verbatim — see **`src/types.ts`** and **`LLMRequest`** from **`@x12i/ai-providers-router`**.
-
-**Key differences**
-
-- **`invokeChat(request)`** — `ChatRequest`; does **not** require **`actionType`** / **`actionRef`**.
-- **`invoke(request)`** — `AIInvokeRequest`; **requires** **`actionType`** and **`actionRef`**.
-
-#### StructuredTextSpec (chat / contract hints)
-
-Used by **`ChatRequest.expectedSchema`** when you attach optional contract structured-text hints:
-
-```typescript
-interface StructuredTextSpec {
-  description: string;
-  formatHint?: string;
-}
-```
-
-**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 AIInvokeRequest example (custom `primaryObjectType`):**
-```typescript
-const aiRequestId = 'req-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/professional-answer',
-  instructions: 'professional-answer/general', // Content registry key
-  prompt: '{{input}}',
-  workingMemory: { input: 'What is the capital of France?' },
-  identity: {
-    sessionId: 'run-1',
-    instance: { instanceId: 'agent-1', type: 'ai-reasoner' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-1'
-  },
-  primaryObjectType: {
-    type: 'professional-answer',
-    whenToUse: 'For professional Q&A responses'
-  },
-  modelConfig: {
-    model: 'gpt-4o',
-    provider: 'openai'
-  }
-});
-```
-
-**Using modelConfig for model selection:**
-```typescript
-const aiRequestId = 'req-2';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/sentiment',
-  instructions: 'Analyze the data',
-  prompt: '{{input}}',
-  workingMemory: { input: 'sample' },
-  identity: {
-    sessionId: 'run-1',
-    instance: { instanceId: 'agent-1', type: 'ai-reasoner' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-1'
-  },
-  primaryObjectType: 'sentiment-analysis',
-  modelConfig: {
-    model: 'gpt-4-turbo',
-    provider: 'openai',
-    temperature: 0.7,
-    maxTokens: 2000,
-    topP: 0.9
-  }
-});
-```
-
-**modelConfig overrides `config`:**
-```typescript
-const aiRequestId = 'req-3';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/classification',
-  instructions: 'Process request',
-  prompt: '{{input}}',
-  workingMemory: { input: 'sample' },
-  identity: {
-    sessionId: 'run-1',
-    instance: { instanceId: 'agent-1', type: 'ai-reasoner' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-1'
-  },
-  primaryObjectType: 'classification',
-  config: {
-    model: 'gpt-3.5-turbo',
-    temperature: 0.5
-  },
-  modelConfig: {
-    model: 'gpt-4-turbo',
-    temperature: 0.9
-  }
-});
-```
-
-**Standard object type example (v3.0.6+):**
-```typescript
-const aiRequestId = 'req-4';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/sentiment-analysis',
-  instructions: 'Analyze the sentiment of this text',
-  prompt: '{{input}}',
-  workingMemory: { input: 'I love this product!' },
-  identity: {
-    sessionId: 'run-1',
-    instance: { instanceId: 'agent-1', type: 'ai-reasoner' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-1'
-  },
-  primaryObjectType: 'sentiment-analysis',
-  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 aiRequestId = 'flex-md-ex-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/sentiment',
-  instructions: 'Classify the sentiment of this text',
-  prompt: '{{input}}',
-  workingMemory: { input: 'This product is amazing!' },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-1', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-1'
-  },
-  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
-
-**AIInvokeRequest with object types / schema (invoke):**
-```typescript
-const aiRequestId = 'pa-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/professional-answer',
-  instructions: 'professional-answer/general',
-  prompt: '{{input}}',
-  workingMemory: { input: 'User question here' },
-  inferenceType: 'professional-answer',
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-1', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-1'
-  },
-  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']
-      }
-    }
-  ],
-  config: {
-    model: 'gpt-4o',
-    provider: 'openai'
-  }
-});
-// Validate against schema in your app if needed — `validateOutputSchema` is not a request field.
-```
-
-**Content registry + AIInvokeRequest (recommended):**
-
-When using content-registry with **`invoke()`**, the gateway typically:
-1. Resolves instruction keys from content-registry
-2. Fetches instruction metadata (**`outputType`**, **`outputSchema`**, **`parseOptions`** on **metadata**, not on the request body)
-3. May configure provider JSON modes via merged **`config`** (provider-specific)
-
-```typescript
-const aiRequestId = 'pa-2';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/professional-answer',
-  instructions: 'professional-answer/general',
-  prompt: '{{input}}',
-  workingMemory: { input: 'User question' },
-  inferenceType: 'professional-answer',
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-1', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-1'
-  },
-  objectTypes: [
-    {
-      type: 'professional-answer',
-      whenToUse: 'For professional Q&A responses',
-      schema: instructionMetadata?.outputSchema || {
-        type: 'object',
-        properties: { answer: { type: 'string' } }
-      }
-    }
-  ],
-  config: {
-    model: 'gpt-4o',
-    provider: 'openai'
-  }
-});
-```
-
-**Output Modes Examples (v3.0.5+):**
-
-**1. JSON Output Mode (Default):**
-```typescript
-const aiRequestId = 'out-json-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'agent-1',
-  actionType: 'skill',
-  actionRef: 'skills/qa',
-  instructions: 'Answer the question',
-  prompt: '{{input}}',
-  workingMemory: { input: 'What is the capital of France?' },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-1', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'agent-1'
-  },
-  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 aiRequestId = 'out-st-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'story-teller',
-  actionType: 'skill',
-  actionRef: 'skills/story',
-  instructions: 'Write a short story',
-  prompt: '{{input}}',
-  workingMemory: { input: 'Create a story about a brave knight' },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'story-teller', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'story-teller'
-  },
-  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 aiRequestId = 'out-2step-1';
-const response = await gateway.invoke({
-  aiRequestId,
-  agentId: 'story-converter',
-  actionType: 'skill',
-  actionRef: 'skills/story-convert',
-  instructions: 'Write a detailed story',
-  prompt: '{{input}}',
-  workingMemory: { input: 'Create a story about space exploration' },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'story-converter', type: 'test' },
-    aiRequestId,
-    jobId: 'job-123',
-    taskId: 'task-1',
-    agentId: 'story-converter'
-  },
-  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 **`invoke()`** fails validation:
-1. Confirm **`actionType`**, **`actionRef`**, **`aiRequestId`**, and full **`identity`** (**`jobId`** / **`taskId`**) are set
-2. Remove top-level **`input`** — use **`prompt`** + **`workingMemory.input`**
-3. Use **`validateAIRequest()`** / **`assertValidAIRequest()`** before sending
-4. Enable **`AI_GATEWAY_DEBUG_REQUEST=true`** to inspect the request at the 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) {
-  const aiRequestId = `sentiment-${record.id}`;
-  await gateway.invoke({
-    aiRequestId,
-    agentId: 'sentiment-analyzer',
-    actionType: 'skill',
-    actionRef: 'skills/sentiment-batch',
-    instructions: question,
-    prompt: '{{input}}',
-    workingMemory: { input: record.text },
-    taskTypeId, // Same for all records
-    identity: {
-      sessionId: 'batch-1',
-      instance: { instanceId: 'sentiment-analyzer', type: 'batch' },
-      aiRequestId,
-      jobId: `job-${record.id}`,
-      taskId: `task-${record.id}`,
-      agentId: 'sentiment-analyzer'
-    },
-    primaryObjectType: 'sentiment-analysis',
-    config: { model: 'gpt-5-nano', provider: 'openai' }
-  });
-}
-```
-
-**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-actions`, `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-actions', statusValues },
-    { name: 'skill-executions', statusValues },
-    { name: 'bad-requests', statusValues }
-  ]
-});
-
-const gateway = new AIGateway({
-  activityTracker: customTracker,
-  enableActivityTracking: true
-});
-```
-
-### Custom Logger
-
-```typescript
-import { createLogxer } from '@x12i/logxer';
-
-const customLogger = createLogxer(
-  { packageName: 'MY_APP', envPrefix: 'MY_APP', debugNamespace: '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) {
-  const aiRequestId = `agent-${task.id}-${Date.now()}`;
-  // Use invokeChat() for chat requests without structured output
-  const response = await gateway.invokeChat({
-    aiRequestId,
-    agentId: task.agentId,
-    instructions: task.instructions,
-    prompt: '{{input}}',
-    workingMemory: { input: task.input },
-    taskTypeId: task.typeId, // Or use MD5 hash of question/instruction for consistent identification
-    identity: {
-      sessionId: jobId,
-      instance: { instanceId: task.agentId, type: 'agent' },
-      aiRequestId,
-      jobId,
-      taskId: task.id,
-      agentId: task.agentId
-    }
-  });
-  
-  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 aiRequestId = 'xmodels-1';
-  const response = await gateway.invokeChat({
-    aiRequestId,
-    agentId: 'agent-1',
-    instructions: 'You are a helpful assistant',
-    prompt: '{{input}}',
-    workingMemory: { input: 'Hello!' },
-    identity: {
-      sessionId: 's1',
-      instance: { instanceId: 'agent-1', type: 'test' },
-      aiRequestId,
-      jobId: 'job-123',
-      taskId: 'task-1',
-      agentId: 'agent-1'
-    },
-    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 aiRequestId = 'reasoning-example';
-const response = await gateway.invokeChat({
-  aiRequestId,
-  agentId: 'agent-1',
-  instructions: 'Solve this step-by-step',
-  prompt: '{{input}}',
-  workingMemory: { input: 'What is 15 * 23?' },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-1', type: 'test' },
-    aiRequestId,
-    jobId: 'job-reason',
-    taskId: 'task-reason',
-    agentId: 'agent-1'
-  },
-  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 aiRequestId = 'basic-reasoning';
-const response = await gateway.invokeChat({
-  aiRequestId,
-  agentId: 'agent-1',
-  instructions: 'Explain your reasoning step by step',
-  prompt: '{{input}}',
-  workingMemory: { input: 'Why is the sky blue?' },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-1', type: 'test' },
-    aiRequestId,
-    jobId: 'job-reason',
-    taskId: 'task-basic',
-    agentId: 'agent-1'
-  },
-  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 aiRequestId1 = 'continuity-1';
-const response1 = await gateway.invokeChat({
-  aiRequestId: aiRequestId1,
-  agentId: 'agent-1',
-  instructions: 'Solve this complex problem',
-  prompt: '{{input}}',
-  workingMemory: { input: 'Calculate the trajectory of a satellite' },
-  identity: {
-    sessionId: 's1',
-    instance: { instanceId: 'agent-1', type: 'test' },
-    aiRequestId: aiRequestId1,
-    jobId: 'job-cont',
-    taskId: 'task-c1',
-    agentId: 'agent-1'
-  },
-  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 aiRequestId2 = 'continuity-2';
-  const response2 = await gateway.invokeChat({
-    aiRequestId: aiRequestId2,
-    agentId: 'agent-1',
-    instructions: 'Continue from previous reasoning',
-    prompt: '{{input}}',
-    workingMemory: { input: 'Now apply this to Mars orbit' },
-    identity: {
-      sessionId: 's1',
-      instance: { instanceId: 'agent-1', type: 'test' },
-      aiRequestId: aiRequestId2,
-      jobId: 'job-cont',
-      taskId: 'task-c2',
-      agentId: 'agent-1'
-    },
-    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: `invoke()` validation (`actionType`, `actionRef`, `identity`, `input`)
-
-**Typical errors**: missing **`actionType`** / **`actionRef`**, missing **`identity.jobId`** / **`identity.taskId`**, or passing deprecated top-level **`input`** (use **`workingMemory.input`** with a **`prompt`** template).
-
-**Quick Fix Checklist**:
-
-1. ✅ **Structured calls must use `invoke()` with `AIInvokeRequest` fields**
-   ```typescript
-   const aiRequestId = 'fix-1';
-   await gateway.invoke({
-     aiRequestId,
-     agentId: 'agent-1',
-     actionType: 'skill',
-     actionRef: 'skills/professional-answer',
-     instructions: 'professional-answer/general',
-     prompt: '{{input}}',
-     workingMemory: { input: 'User question' },
-     identity: {
-       sessionId: 's1',
-       instance: { instanceId: 'agent-1', type: 'test' },
-       aiRequestId,
-       jobId: 'job-123',
-       taskId: 'task-1',
-       agentId: 'agent-1'
-     },
-     primaryObjectType: {
-       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 aiRequestId = 'chat-req-001';
-  const response = await gateway.invokeChat({
-    aiRequestId,
-    agentId: 'agent-1',
-    instructions: 'You are a helpful assistant',
-    prompt: '{{input}}',
-    workingMemory: { input: 'Hello!' },
-    identity: {
-      sessionId: 'sess-1',
-      instance: { instanceId: 'gw-1', type: 'gateway' },
-      aiRequestId,
-      jobId: 'job-123',
-      taskId: 'task-1',
-      agentId: 'agent-1'
-    }
-  });
-} 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** v7 (`@x12i/xronox-store`): Activity logging and tracking (`^7.1.0` in this package)
-- **@x12i/logxer**: Structured logging with correlation (`^4.2.1` in this package)
-- **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)
+MIT — see package metadata.