@x12i/ai-gateway 9.0.9 → 9.1.1

package/README.md

@@ -12,12 +12,21 @@ Every **`invoke`** / **`invokeChat`** request **must** include **`identity`**: t
 
 See [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md) and [Logger initialization](./docs/LOGGER_INITIALIZATION.md).
 
+### AI invoke payload (`gateway.invoke`)
+
+Use a single object typed as **`AIInvokeRequest`** (exported alias: **`AIRequest`**). Besides **`identity`** / **`aiRequestId`** / **`agentId`** / **`instructions`**, every **`invoke()`** call **must** include:
+
+- **`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` v6 (xronox-activitix), fixed Mongo collections `ai-activities` / `bad-requests`, validated root-level **`outer` / `inner`** I/O plus **`runContext`** for Activix 6
+- **📈 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
@@ -32,7 +41,7 @@ See [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md) and [Logger initiali
 - **🔄 Automatic Retry**: Intelligent retry logic for network errors, server errors (5xx), and throttling (429) with exponential backoff
 - **📚 Content Resolver (nx-content)**: Resolve instruction keys, prompt keys, and instructions blocks from local folder or git repo via **nx-content**. See [Content Resolver — Upstream Guide](./CONTENT_RESOLVER_UPSTREAM_GUIDE.md).
 - **📋 Instruction Metadata API**: Fetch structured metadata (outputType, schema, validation rules) for metadata-driven inference systems (v1.6.9+)
-- **🔧 Response Transformation Hooks**: Transform responses at different stages (preParse, postParse, preValidate, postValidate) for output mapping and data normalization (v1.6.9+)
+- **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+)
@@ -43,7 +52,7 @@ See [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md) and [Logger initiali
 - **📚 Standard Object Types**: Reference standard object types by name (e.g., `'sentiment-analysis'`) instead of defining schemas manually - includes examples, validation, and structured text instructions (v3.0.6+)
 - **🔍 Auto-Extraction of Output Formats**: Automatically extract output format specifications from instruction templates when using structured-text mode - no need to manually specify `flexMdFormat` or `primaryObjectType` (v3.3.3+)
 - **✅ Output Format Validation**: Validates output format specifications using flex-md SDK before sending to LLM, with configurable minimum compliance level (L0-L3)
-- **📋 Contract Output Parsing**: Parse AI responses against expected schemas and store results in activity records for compliance monitoring (v6.3.1+)
+- **📋 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
 
@@ -72,7 +81,7 @@ export AI_GATEWAY_DEBUG_REQUEST=true   # Detailed request structure
 export FLEX_MD_MIN_COMPLIANCE_LEVEL=L0 # Output format validation level (L0/L1/L2/L3, default: L0)
 ```
 
-This logs the exact request structure received by `invoke()`, including property descriptors, which is critical for debugging validation errors like "objectTypes is required".
+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`**).
 
 ### 🔍 Advanced Diagnostic Logging
 
@@ -132,11 +141,14 @@ gateway.register(new GrokProvider({
   apiKey: process.env.GROK_API_KEY
 }));
 
-// Invoke with mandatory runtime identity (upstream job/task correlation)
+// Invoke with mandatory runtime identity + action classification (Activix / tracing)
 const response = await gateway.invoke({
   aiRequestId: 'call-001',
   agentId: 'agent-456',
+  actionType: 'skill',
+  actionRef: 'skills/quick-reply',
   instructions: 'Reply briefly.',
+  prompt: '{{input}}',
   identity: {
     sessionId: 'run-1',
     instance: { instanceId: 'agent-456', type: 'ai-reasoner' },
@@ -145,8 +157,9 @@ const response = await gateway.invoke({
     taskId: 'task-789',
     agentId: 'agent-456'
   },
-  workingMemory: { input: 'Hello!' }
-  // … primaryObjectType / flexMdFormat / messages as required by your request type
+  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`)
@@ -271,9 +284,9 @@ DEBUG=my-app                       # elevates verbose/debug when package is not
 
 **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 v6)
+### 2. Activity Tracking Configuration (xronox-activitix via @x12i/activix v7)
 
-**Activix version:** This gateway targets **`@x12i/activix` v6.x** (built on `@xronoces/xronox-store`). The dependency range is declared in `package.json` (currently `^6.5.1`). Activity I/O is stored at the **document root** as **`outer`** (and optional **`inner`**); the deprecated nested **`structure`** wrapper is not used.
+**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`
@@ -283,11 +296,39 @@ DEBUG=my-app                       # elevates verbose/debug when package is not
 
 **✅ Centralized configuration**
 
-The gateway resolves activity tracking from environment variables via `src/config/activity-tracking-config.ts`. **Main and bad-request collection names are fixed at the package level** (not overridden by env): **`ai-activities`** for normal runs and **`bad-requests`** for failed/invalid requests. **`skill-executions`** is used for skill-related flows when applicable.
+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`**. Success adds **`response`**, **`endTime`**, **`duration`**, **`cost`**, refreshed **`status`**, and sets **`outer.output`** to the completion payload. Failure adds error details (and may attach **`outer.output`** for certain failure modes such as response parsing).
 
-**Environment variable priority (connection only):**
-- **Database**: `MONGO_LOGS_DB` → `MONGO_DB` (no default, must be provided)
-- **URI**: `MONGO_URI` (required)
+**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. 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**
 
@@ -296,6 +337,7 @@ The gateway resolves activity tracking from environment variables via `src/confi
 - **`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):**
 
@@ -332,13 +374,13 @@ See [Runtime Objects Observability Methodology](./docs/RUNTIME_OBJECTS_OBSERVABI
 import { AIGateway } from '@x12i/ai-gateway';
 import { OpenAIProvider } from '@x12i/ai-provider-openai';
 
-// Set environment variables:
+// Set environment variables (before creating the gateway):
 // MONGO_URI=mongodb://localhost:27017
-// MONGO_LOGS_DB=logs-db
+// 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-activities / bad-requests / skill-executions
+  // Activix is auto-configured; writes use collections ai-actions / bad-requests / skill-executions
 });
 
 gateway.register(new OpenAIProvider({
@@ -346,7 +388,7 @@ gateway.register(new OpenAIProvider({
 }));
 ```
 
-**Advanced (custom Activix v6 instance):**
+**Advanced (custom Activix v7 instance):**
 
 If you pass your own `Activix`, configure **the same collection names** the gateway expects so routing matches persistence:
 
@@ -364,7 +406,7 @@ const statusValues = {
 
 const activityTracker = new Activix({
   collections: [
-    { name: 'ai-activities', statusValues },
+    { name: 'ai-actions', statusValues },
     { name: 'skill-executions', statusValues },
     { name: 'bad-requests', statusValues }
   ]
@@ -376,13 +418,16 @@ const gateway = new AIGateway({
 });
 ```
 
+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` object (instructions, prompt, input, messages, workingMemory)
-- **Config data**: Stored in `config` object (model, provider, temperature, maxTokens)
-- **Response data**: Stored in `response` object (content, metadata)
-- **Cost**: Calculated and stored per activity
+- **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**: Calculated and stored per activity on success
 
 **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
@@ -398,12 +443,12 @@ const gateway = new AIGateway({
 
 **Default:** Activity tracking is enabled by default; without DB config it will log but not persist.
 
-**✅ Activix v6 integration**
+**✅ Activix v7 integration**
 
 1. **Configuration** (`activity-tracking-config.ts`):
-   - Mongo connection from env; **collection names** `ai-activities` and `bad-requests` are fixed for consistency across deployments.
+   - 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` v6):
+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)
@@ -431,14 +476,27 @@ When executing skills (instruction keys starting with `skills/`), the gateway au
 **Example: Basic Skill Execution**
 
 ```typescript
+const aiRequestId = 'skill-pa-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  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
-  input: { question: 'What is...' },
-  primaryObjectType: 'professional-answer'
+  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' }
 });
 
 // Get the activity ID for linking child skills
@@ -448,24 +506,52 @@ const activityId = response.metadata?.activityId;
 **Example: Nested Skill Execution (Skill Calling Another Skill)**
 
 ```typescript
+const parentAiRequestId = 'skill-parent-1';
 // Parent skill execution
 const parentResponse = await gateway.invoke({
-  jobId: 'job-123',
+  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'
+  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' }
 });
 
+const childAiRequestId = 'skill-child-1';
 // When parent skill calls child skill, pass parent's activityId and skillId
 const childResponse = await gateway.invoke({
-  jobId: 'job-123', // ✅ Same jobId (links activities)
+  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
+  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' }
 });
 ```
 
@@ -536,11 +622,23 @@ const gateway = new AIGateway({
 
 **Step 3: Request-level override:**
 ```typescript
+const aiRequestId = 'cfg-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-456',
+  actionType: 'skill',
+  actionRef: 'skills/helpful',
   instructions: 'You are helpful',
-  input: 'Hello',
+  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
@@ -642,9 +740,12 @@ const gateway = new AIGateway({
 **How to configure:**
 
 ```typescript
+const aiRequestId = 'tpl-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  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
@@ -652,13 +753,21 @@ const response = await gateway.invoke({
   // Prompts can be a key (resolved from content resolver) or text (parsed as template)
   prompt: 'professional-answer.prompt',  // Key with suffix
   // OR: prompt: 'Analyze this {{type}}: {{input}}',  // Text with template variables
-  input: 'This is a review',
   workingMemory: {
     role: 'helpful',
     project: 'AI Gateway',
     type: 'product review',
     input: 'This is a review'
-  }
+  },
+  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' }
 });
 ```
 
@@ -679,7 +788,7 @@ const response = await gateway.invoke({
 **Gateway template options (passthrough)**
 
 - **`GatewayConfig.templateRendering`** — default `TemplateRenderOptions` for every `invoke()` render path (merged after packaged **`src/defaults/template-rendering.json`**, which ships with **`subPathSearch.enabled: false`**). Your gateway config overrides that JSON.
-- **`templateRenderOptions` on the request** (`ChatRequest` / `AIRequest`) — merged on top of the gateway default for that call only (per-field override; `subPathSearch` fields merge with request winning).
+- **`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).
 - Supported fields match the parser: **`templateId`**, **`subPathSearch`** (`enabled`, `roots`), **`silentMissingMustTokens`** (legacy Handlebars-style silence for missing MUST paths).
 - **Sub-path root priority:** `subPathSearch.roots` is an **ordered** list. The parser tries roots in **array order**; **the first root that resolves the leaf path wins** (see ISSUE-005). There is no separate “priority” field—the order of `roots` *is* the priority. Omit `roots` when `enabled` is true to use **`@x12i/rendrix`** packaged defaults.
 
@@ -694,7 +803,7 @@ new AIGateway({
   }
 });
 ```
-- **Memory overlay priority** for value resolution (highest first): **`templateTokens`** (merged into short-term before render) → **`shortTermMemory`** → **`workingMemory`** → **`experienceMemory`** → **`knowledgeMemory`**.
+- **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:**
@@ -811,7 +920,7 @@ const statusValues = {
 
 const activityTracker = new Activix({
   collections: [
-    { name: 'ai-activities', statusValues },
+    { name: 'ai-actions', statusValues },
     { name: 'skill-executions', statusValues },
     { name: 'bad-requests', statusValues }
   ]
@@ -870,60 +979,44 @@ For each configuration option, priority is (highest to lowest):
 
 ## Enhanced Gateway Features
 
-### 1. Context Propagation (Job ID)
+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)
 
-The gateway automatically propagates `jobId` through the entire request lifecycle for distributed tracing.
+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({
-  // Minimum required fields
-  jobId: 'job-123',           // required
-  agentId: 'agent-456',       // required
-  instructions: 'You are a helpful assistant.', // required
-
-  // Provide either messages OR prompt/input
-  messages: [{ role: 'user', content: 'What is AI?' }],
-  // OR:
-  // prompt: 'professional-answer.prompt',  // Key resolved from content resolver (nx-content)
-  // input: 'What is AI?',
-  // Optional extra context inserted between instructions and user prompt/input
-  // context: 'Only answer with a single sentence.',
-
-  // Optional
-  taskId: 'task-789',
-  taskTypeId: 'question-answering',  // Or auto-generated from instructions MD5 hash
-  graphId: 'graph-123',              // Optional: Graph execution context
-  nodeId: 'node-456',                // Optional: Node execution context
-  config: { model: 'gpt-5-nono' }
+  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' }
 });
-
-// jobId is automatically:
-// - Attached to request metadata
-// - Included in response metadata
-// - Logged in all log entries
-// - Tracked in activity logs
 ```
 
-**Request requirements:** 
-- **Required fields**: `jobId`, `agentId`, and `instructions` are mandatory
-- **Content field (choose one)**:
-  - `messages` array (for tool calling or custom message sequences)
-  - OR `prompt` + `input` (prompt template resolved from content resolver or parsed with template variables)
-  - OR `input` alone (uses default prefix from instructionsBlocks)
-- **Optional fields**: `context` (inserted as system message between instructions and user content), `workingMemory` (for template variables), `graphId`/`nodeId`/`coreSkillId` (for graph execution context - see [Graph Execution Support](./docs/GRAPH_EXECUTION_SUPPORT.md))
-- **Model requirement**: `config.model` must be supplied per request (no default model)
-
-**Important Notes:**
-- `instructions` is **always required**, even when using `messages` array
-- When `messages` is provided, the gateway constructs system messages from `instructions` (and `context` if provided), then appends your `messages` array
-- `context` is inserted as a separate system message between instructions and the user prompt/input
-- **Template-Based Instructions and Prompts**: Both `instructions` and `prompt` can be resolved from the content resolver (nx-content) using keys (e.g., `professional-answer.instructions` and `professional-answer.prompt`). Both receive the same memory context for template rendering. See [Content Resolver — Upstream Guide](./CONTENT_RESOLVER_UPSTREAM_GUIDE.md) and [Prompt Template Usage Guide](./docs/PROMPT_TEMPLATE_USAGE.md).
-- All template fields (`instructions`, `context`, `prompt`) support template variables via `workingMemory`
+**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:**
-- Full request traceability across distributed systems
-- Correlate logs, activities, and metrics by jobId
-- Debug complex multi-step AI workflows
+- Stable tracing across logs and Activix
+- Clear separation between chat (`invokeChat`) and structured invoke (`invoke`)
 
 ### 2. Usage Tier Tracking (RPM/TPM Limits)
 
@@ -956,9 +1049,9 @@ console.log(`RPM Limit: ${tierInfo?.rpm}, TPM Limit: ${tierInfo?.tpm}`);
 - `tier-4`: 10,000 RPM, 4M TPM
 - `tier-5`: 15,000 RPM, 40M TPM
 
-### 3. Activity Tracking (xronox-activitix via @x12i/activix v6)
+### 3. Activity Tracking (xronox-activitix via @x12i/activix v7)
 
-The gateway uses **`@x12i/activix` v6** (xronox-activitix) for full lifecycle logging. Recommended: enable MongoDB persistence so tracking is automatic. Default collections: **`ai-activities`**, **`bad-requests`**, **`skill-executions`** (see section 2).
+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
 
@@ -970,23 +1063,21 @@ The gateway uses **`@x12i/activix` v6** (xronox-activitix) for full lifecycle lo
    - **`jobTypeId`**, **`taskTypeId`**: Optional aggregation fields (same ideas as before).
    - **Activity**: Each individual LLM request is a separate **activity** with its own unique record.
 
-2. **Mongo `_id` is the unique row key**
-   - **`jobId`** / **`taskId`** on the row mirror upstream **`identity`** for correlation; multiple activities may share a **`jobId`** when you intend grouping.
-   - Activix updates rows by the **record id** from the start phase, not by `jobId`.
+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 v6)**
-   - **Phase 1 (start)**: Creates a NEW database record with unique `_id`
-     - Sends request-side data: `request`, `config`, `runContext`, root-level **`outer`** (and optional **`inner`**) I/O, `startTime`, `status: 'started'` (plus other gateway metadata)
-     - Returns metadata containing the unique record id for completion
-   - **Phase 2 (complete / fail)**: Updates the SAME record by that id
-     - Sends response/error data: `response`, `endTime`, `duration`, `cost`, `status`
-     - Does not re-send full request payload
+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`**, **`cost`**, **`endTime`**, **`duration`**, **`status`**, and **`outer.output`** set to the completion **`response`** payload (request/config are **not** re-sent).
+     - Failure: error payload and timing; optional **`response`** / **`outer.output`** only for specific failure kinds.
 
-4. **Data structure (v2.6.0+):**
-   - Request fields (`messages`, `instructions`, `prompt`, `input`, `context`, `workingMemory`) → **ONLY in `request` object**
-   - Config fields (`model`, `provider`, `temperature`, `maxTokens`) → **ONLY in `config` object**
-   - Response fields (`content`, `metadata`) → **ONLY in `response` object**
-   - **NO duplication**: Fields are NOT at root level, only in their structured objects
+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**
 
@@ -1001,31 +1092,49 @@ function md5(text: string): string {
 
 const jobTypeId = md5('data-processing-job');
 
-const identityBase = {
-  jobId: 'job-123',
-  sessionId: 'sess-1',
-  instance: { instanceId: 'inst-1', type: 'gateway' }
-};
-
 await gateway.invoke({
   aiRequestId: 'req-001',
-  identity: { ...identityBase, taskId: 'task-001' },
-  jobTypeId,
   agentId: 'agent-1',
-  // objectTypes, messages, ...
+  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',
-  identity: { ...identityBase, taskId: 'task-002' },
-  jobTypeId,
   agentId: 'agent-1',
-  // objectTypes, messages, ...
+  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-activities):
-// db.getCollection('ai-activities').find({ 'runContext.aiRequestId': 'req-001' })
-// db.getCollection('ai-activities').find({ 'runContext.jobId': 'job-123' })
+// 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
@@ -1043,7 +1152,7 @@ const statusValues = {
 
 const activityTracker = new Activix({
   collections: [
-    { name: 'ai-activities', statusValues },
+    { name: 'ai-actions', statusValues },
     { name: 'skill-executions', statusValues },
     { name: 'bad-requests', statusValues }
   ]
@@ -1064,12 +1173,19 @@ const gateway = new AIGateway({
 
 #### 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
 {
-  // Unique identifier (MongoDB auto-generated)
-  _id: ObjectId('693970636e8d0f171e4aa528'),  // ← UNIQUE per activity
-  
-  // Activix v6: canonical correlation BSON object `runContext` (same reference as `request.identity`, merged with gateway fields)
+  // 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' },
@@ -1096,9 +1212,15 @@ const gateway = new AIGateway({
   graphId: 'graph-456',
   nodeId: 'node-789',
 
-  // Required activity I/O: root-level `outer` (optional `inner[]` for steps) — Activix v6 (see @x12i/activix docs)
-  outer: { input: { ... }, output: { ... } | null, metadata: { ... } },
-  // inner: [ { input, output, metadata, startedAt, endedAt, ... }, ... ],
+  // 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: normalized gateway response object */ },
+    metadata: { /* tier metadata / aiRequestId routing — see @x12i/activix */ }
+  },
+  // inner: optional step array for multi-step flows (see @x12i/activix docs)
   
   // Timing
   startTime: 1765372020804,
@@ -1116,11 +1238,10 @@ const gateway = new AIGateway({
     parsed: { 
       instructions,  // Parsed instructions (after template parsing with workingMemory)
       context,       // Parsed context (after template parsing with workingMemory)
-      prompt         // Parsed prompt (after template parsing with workingMemory, includes input if provided)
+      prompt         // Parsed prompt (after template parsing with workingMemory)
     },
-    input: "...",     // Original input text
     messages: [...],  // Final constructed messages array
-    workingMemory: {...}  // Working memory used for template parsing
+    workingMemory: {...}  // Template/user payload (e.g. { input: '…' } for '{{input}}'); not a separate root `input` field
   },
   
   // Config data (from startActivity - ONLY in config object)
@@ -1148,13 +1269,13 @@ const gateway = new AIGateway({
 ```
 
 **Key points:**
-- ✅ Each activity = separate record with unique `_id`
+- ✅ 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 data sent once at activity start; response data on completion
-- ✅ Updates use Activix record id / `_id`, not `jobId`
+- ✅ Request/config sent at **start**; response/timing/cost at **complete**
+- ✅ Updates target **`activityId`** from **`startRecord`**, not **`jobId`**
 
-#### Retry Tracking (@x12i/activix v6)
+#### 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.
 
@@ -1232,12 +1353,24 @@ The gateway returns a comprehensive response structure that captures the full li
 #### Complete Response Structure
 
 ```typescript
+const aiRequestId = 'resp-shape-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-456',
+  actionType: 'skill',
+  actionRef: 'skills/qa',
   instructions: 'You are a helpful assistant.',
-  input: 'What is AI?',
-  config: { model: 'gpt-5-nano' }
+  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:
@@ -1330,14 +1463,25 @@ const response = await gateway.invoke({
 #### Example: Full Response
 
 ```typescript
+const aiRequestId = 'cls-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-456',
+  actionType: 'skill',
+  actionRef: 'skills/sentiment',
   instructions: 'Classify sentiment',
-  input: 'I love this product!',
+  prompt: '{{input}}',
+  workingMemory: { input: 'I love this product!' },
   inferenceType: 'classification',
-  parseOptions: { classes: ['positive', 'negative', 'neutral'] },
-  config: { model: 'gpt-5-nano' }
+  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:
@@ -1411,12 +1555,12 @@ const gateway = new AIGateway({
 
 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 you specify an `inferenceType` in your request, the gateway automatically:
-1. Parses the response into a typed output object
-2. Validates against JSON Schema (optional)
-3. Provides type-safe access to structured data
+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
 
@@ -1446,89 +1590,37 @@ npm install --legacy-peer-deps
 - `recommendation` - Generate recommendations with priorities
 - `transformation` - Transform data between formats
 
-#### Basic Usage
-
-```typescript
-import { AIGateway } from '@x12i/ai-gateway';
-import type { ClassificationOutput } from '@x12i/ai-gateway';
-
-const gateway = new AIGateway({
-  defaultProvider: 'openai'
-});
-
-// Request with inference type
-const response = await gateway.invoke({
-  jobId: 'job-123',
-  agentId: 'agent-456',
-  instructions: 'Classify the sentiment of the text.',
-  input: 'This product is amazing!',
-  inferenceType: 'classification',
-  parseOptions: {
-    classes: ['positive', 'negative', 'neutral']
-  }
-});
-
-// Access parsed output
-const classification = response.metadata.parsedOutput as ClassificationOutput;
-console.log(classification.classes); // ['positive', 'negative', 'neutral']
-console.log(classification.confidence); // { positive: 0.85, negative: 0.1, neutral: 0.05 }
-```
+#### Basic usage (`invoke` + `inferenceType`)
 
-#### With Schema Validation
+`parseOptions` / `validateOutputSchema` / `strictValidation` are **not** request fields. Supply **`aiRequestId`**, **`identity`**, **`actionType`**, **`actionRef`**, **`prompt`**, **`workingMemory`**, and optionally **`inferenceType`** for activity metadata.
 
 ```typescript
-const response = await gateway.invoke({
+const aiRequestId = 'cls-1';
+const identity = {
+  sessionId: 's1',
+  instance: { instanceId: 'agent-456', type: 'test' },
+  aiRequestId,
   jobId: 'job-123',
-  agentId: 'agent-456',
-  instructions: 'Extract user information.',
-  input: 'Name: John Doe, Email: john@example.com',
-  inferenceType: 'extraction',
-  validateOutputSchema: true  // Enable validation
-});
-
-// Check validation errors (if any)
-if (response.metadata.outputValidationErrors) {
-  console.warn('Validation errors:', response.metadata.outputValidationErrors);
-}
-
-// Access parsed output
-const extraction = response.metadata.parsedOutput as ExtractionOutput;
-console.log(extraction.extracted); // { name: 'John Doe', email: 'john@example.com' }
-```
-
-#### Question-Answer Example
+  taskId: 'task-1',
+  agentId: 'agent-456'
+};
 
-```typescript
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-456',
-  instructions: 'Answer the question based on the context.',
-  input: 'What is the capital of France?',
-  inferenceType: 'question-answer',
-  parseOptions: {
-    question: 'What is the capital of France?'
-  }
+  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' }
 });
-
-const qa = response.metadata.parsedOutput as QuestionAnswerOutput;
-console.log(qa.answer); // 'The capital of France is Paris.'
-console.log(qa.confidence); // 0.95
 ```
 
-#### Extraction Example
-
-```typescript
-const response = await gateway.invoke({
-  jobId: 'job-123',
-  agentId: 'agent-456',
-  instructions: 'Extract structured data from the text.',
-  input: 'User: John Doe, Age: 30, Location: New York',
-  inferenceType: 'extraction'
-});
+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.
 
-const extraction = response.metadata.parsedOutput as ExtractionOutput;
-console.log(extraction.extracted); // { user: 'John Doe', age: 30, location: 'New York' }
-```
 
 #### Response Structure
 
@@ -1653,12 +1745,25 @@ The gateway will:
 //   }
 // }
 
+const aiRequestId = 'schema-guide-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-456',
-  instructions: 'extraction/user-data',  // Instruction key with outputSchema
-  input: 'John Doe, john@example.com, 30 years old',
-  inferenceType: 'extraction'
+  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:
@@ -1687,71 +1792,12 @@ Add `outputObjectPrefix` to `instructions-blocks.json`:
 
 This prefix is automatically appended to instructions when `outputType` or `outputSchema` is available.
 
-#### Schema Validation (v1.7.0+)
-
-The gateway supports enhanced schema validation with strict/non-strict modes and automatic schema resolution from instruction metadata.
-
-**Validation Options:**
-
-```typescript
-const response = await gateway.invoke({
-  jobId: 'job-123',
-  agentId: 'agent-456',
-  instructions: 'classification/vulnerability-severity',
-  input: 'CVE-2024-1234: Critical RCE',
-  inferenceType: 'classification',
-  validateOutputSchema: true,      // Enable validation
-  strictValidation: false          // Non-strict: log warnings, don't throw (default)
-});
-```
-
-**Strict Validation Mode:**
-
-```typescript
-const response = await gateway.invoke({
-  jobId: 'job-123',
-  agentId: 'agent-456',
-  instructions: 'classification/vulnerability-severity',
-  input: 'CVE-2024-1234: Critical RCE',
-  inferenceType: 'classification',
-  validateOutputSchema: true,
-  strictValidation: true            // Strict: throw error if validation fails
-});
-
-// If validation fails, throws error:
-// Error: Schema validation failed for inference type 'classification': ...
-```
+#### Schema validation (request flags removed)
 
-**Automatic Schema Resolution:**
-
-When `inferenceType` is provided and instruction metadata is available, the gateway automatically:
-1. Checks instruction metadata for `outputSchema`
-2. Uses it for validation (overrides default schema from outputs-library)
-3. Falls back to outputs-library schema registry if not found
-
-```typescript
-// Instruction metadata has:
-// {
-//   instructionKey: 'classification/vulnerability-severity',
-//   outputSchema: { /* custom schema */ }
-// }
-
-const response = await gateway.invoke({
-  jobId: 'job-123',
-  agentId: 'agent-456',
-  instructions: 'classification/vulnerability-severity',  // Instruction key
-  input: 'CVE-2024-1234: Critical RCE',
-  inferenceType: 'classification',
-  validateOutputSchema: true
-  // Gateway automatically uses outputSchema from metadata
-});
-```
+**`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`**).
 
-**Validation Error Handling:**
+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.
 
-- **Non-strict mode (default)**: Validation failures log warnings but continue
-- **Strict mode**: Validation failures throw errors and stop execution
-- **Validation results** are always available in `response.metadata.outputValidationErrors` and `response.metadata.outputValidationPassed`
 
 #### Output Structure Audit (v2.1.1+)
 
@@ -1769,16 +1815,28 @@ When `outputSchema` is available (from instruction metadata or provided directly
 **Audit Results:**
 
 ```typescript
+const aiRequestId = 'audit-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-456',
+  actionType: 'skill',
+  actionRef: 'skills/extraction-user-data',
   instructions: 'extraction/user-data',
-  input: 'John Doe, john@example.com',
+  prompt: '{{input}}',
+  workingMemory: { input: 'John Doe, john@example.com' },
   inferenceType: 'extraction',
-  validateOutputSchema: true
+  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' }
 });
 
-// Audit results in metadata (always available when schema exists)
+// When present, `outputAudit` is informational (see types / runtime behavior)
 console.log(response.metadata.outputAudit);
 // {
 //   hasAllRequiredFields: true,
@@ -1924,342 +1982,99 @@ All errors are logged with clear messages indicating the issue and the fallback
 - **Integration**: Seamlessly integrated into gateway responses
 - **Graceful Degradation**: Automatic fallback when outputs library unavailable (v1.7.0+)
 
-### 7. Response Transformation Hooks (v1.6.9+)
+### 7. Response transformation hooks (removed from request)
 
-The gateway supports transformation hooks that allow you to modify responses at different stages of processing: before parsing, after parsing, before validation, and after validation. This enables output mapping, data normalization, computed fields, and custom transformations.
+**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.
 
-#### Overview
+**What to use instead:**
 
-Transformation hooks are provided via the `transformations` field in `ChatRequest` or `AIRequest`. Each hook receives the data at a specific stage and returns the transformed data.
+- 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`.
 
-**Available Hooks:**
+Historical examples in older docs or forks that show `transformations` on `invoke()` payloads should be ignored or migrated.
 
-1. **`preParse`**: Transform raw text before parsing (applied to `rawText`)
-2. **`postParse`**: Transform parsed content after parsing (applied to `parsedOutput` or `parsedContent`)
-3. **`preValidate`**: Transform parsed content before schema validation
-4. **`postValidate`**: Transform validated content after validation
+### 8. Content Registry Integration (Instruction Keys)
 
-#### Interface
+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.
 
-```typescript
-interface ResponseTransformationConfig {
-  preParse?: (rawText: string, metadata: any) => string;
-  postParse?: (parsed: any, metadata: any) => any;
-  preValidate?: (parsed: any, schema: any) => any;
-  postValidate?: (validated: any, metadata: any) => any;
-}
-```
+#### Overview: Two Modes for Instructions
 
-**Metadata Object:**
+The gateway supports **two modes** for providing instructions to LLMs:
 
-The `metadata` parameter passed to hooks contains:
+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`
 
-```typescript
-{
-  jobId: string;
-  agentId: string;
-  taskId?: string;
-  taskTypeId?: string;
-  instructionKey: string;  // The instruction key or text
-  inferenceType?: string;
-}
-```
+Both modes work seamlessly - the gateway automatically detects which mode you're using based on the instruction format.
 
-#### Basic Usage
+#### Installation
 
-```typescript
-const response = await gateway.invoke({
-  jobId: 'job-1',
-  agentId: 'agent-1',
-  instructions: 'classification/basic',
-  input: 'This is great!',
-  config: { model: 'gpt-4o' },
-  inferenceType: 'classification',
-  transformations: {
-    // Clean raw text before parsing
-    preParse: (rawText, metadata) => {
-      return rawText.trim().replace(/\s+/g, ' ');
-    },
-    
-    // Transform parsed output
-    postParse: (parsed, metadata) => {
-      return {
-        ...parsed,
-        transformed: true,
-        timestamp: Date.now()
-      };
-    },
-    
-    // Apply output mapping before validation
-    preValidate: (parsed, schema) => {
-      // Map fields to standardized names
-      return {
-        label: parsed.class,
-        score: parsed.confidence,
-        ...parsed
-      };
-    },
-    
-    // Add computed fields after validation
-    postValidate: (validated, metadata) => {
-      return {
-        ...validated,
-        computed: {
-          isHighConfidence: validated.confidence > 0.8,
-          category: validated.class === 'positive' ? 'positive' : 'negative'
-        }
-      };
-    }
-  }
-});
+```bash
+npm install @xronoces/content-registry
 ```
 
-#### Use Cases
-
-**1. Output Field Mapping**
+**Note**: `@xronoces/content-registry` (v2.14.0+) is automatically installed as a dependency. This version includes simplified APIs for easier integration. 
 
-Map output fields to standardized names:
+**Configuration**: Content registry is used when `contentRegistryConfig` is provided in the gateway configuration.
 
-```typescript
-transformations: {
-  postParse: (parsed, metadata) => {
-    // Map from LLM output to standardized format
-    const mapping = {
-      'class': 'label',
-      'confidence': 'score',
-      'reason': 'explanation'
-    };
-    
-    const mapped: Record<string, any> = {};
-    for (const [key, value] of Object.entries(parsed)) {
-      const mappedKey = mapping[key] || key;
-      mapped[mappedKey] = value;
-    }
-    
-    return { ...parsed, ...mapped };
-  }
-}
-```
+**For Internal Use**: Content-registry auto-initializes from environment variables if available, enabling instructionsBlocks resolution without requiring explicit configuration.
 
-**2. Data Normalization**
+**See**: [Content Resolver — Upstream Guide](./CONTENT_RESOLVER_UPSTREAM_GUIDE.md) for configuration, environment variables, content layout, and upstream checklist.
 
-Normalize data formats across different providers:
+#### Configuration
 
 ```typescript
-transformations: {
-  postParse: (parsed, metadata) => {
-    // Normalize confidence scores to 0-1 range
-    if (parsed.confidence && parsed.confidence > 1) {
-      parsed.confidence = parsed.confidence / 100;
-    }
-    
-    // Normalize class names to lowercase
-    if (parsed.class) {
-      parsed.class = parsed.class.toLowerCase();
-    }
-    
-    return parsed;
-  }
-}
-```
-
-**3. Add Computed Fields**
-
-Add derived/computed fields:
+import { AIGateway } from '@x12i/ai-gateway';
 
-```typescript
-transformations: {
-  postValidate: (validated, metadata) => {
-    return {
-      ...validated,
-      metadata: {
-        ...validated.metadata,
-        computed: {
-          isPositive: validated.class === 'positive',
-          confidenceLevel: validated.confidence > 0.8 ? 'high' : 'low',
-          processedAt: new Date().toISOString()
-        }
-      }
-    };
+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
   }
-}
+});
 ```
 
-**4. Response Structure Transformation**
+#### Mode 1: Text Mode (Automatic - Has Spaces)
+
+**How it works**: Automatically detected when instructions contain whitespace. Used as literal text without any resolution.
 
-Restructure response data:
+**When used automatically**:
+- Instructions contain spaces, tabs, or newlines
+- No content registry lookup performed
+- Fast processing with no external dependencies
 
+**Example**:
 ```typescript
-transformations: {
-  postParse: (parsed, metadata) => {
-    // Transform flat structure to nested
-    return {
-      result: {
-        classification: {
-          label: parsed.class,
-          confidence: parsed.confidence
-        },
-        metadata: {
-          jobId: metadata.jobId,
-          agentId: metadata.agentId
-        }
-      }
-    };
-  }
-}
-```
-
-**5. Clean Raw Text**
-
-Clean and normalize raw text before parsing:
-
-```typescript
-transformations: {
-  preParse: (rawText, metadata) => {
-    // Remove markdown code blocks if present
-    let cleaned = rawText.replace(/```json\n?/g, '').replace(/```\n?/g, '');
-    
-    // Remove leading/trailing whitespace
-    cleaned = cleaned.trim();
-    
-    // Fix common JSON issues
-    cleaned = cleaned.replace(/,(\s*[}\]])/g, '$1'); // Remove trailing commas
-    
-    return cleaned;
-  }
-}
-```
-
-#### Error Handling
-
-Transformation hooks have built-in error handling - if a transformation fails, the gateway logs a warning and continues with the original (untransformed) data. This ensures that transformation errors don't break the request.
-
-```typescript
-// If transformation throws an error, gateway logs:
-// "postParse transformation failed, using original parsed output"
-// and continues with the original data
-```
-
-#### Integration with Instruction Metadata
-
-Combine transformation hooks with instruction metadata for fully metadata-driven systems:
-
-```typescript
-// Fetch metadata
-const metadata = await gateway.getInstructionMetadata('classification/basic');
-
-if (metadata?.defaultOutputMapping) {
-  // Use metadata to configure transformation
-  const response = await gateway.invoke({
-    jobId: 'job-1',
-    agentId: 'agent-1',
-    instructions: 'classification/basic',
-    input: 'This is great!',
-    config: { model: 'gpt-4o' },
-    inferenceType: metadata.outputType,
-    transformations: {
-      postParse: (parsed, reqMetadata) => {
-        // Apply output mapping from metadata
-        const mapped: Record<string, any> = {};
-        for (const [key, mappedKey] of Object.entries(metadata.defaultOutputMapping!)) {
-          if (key in parsed) {
-            mapped[mappedKey] = (parsed as any)[key];
-          }
-        }
-        return { ...parsed, ...mapped };
-      }
-    }
-  });
-}
-```
-
-#### Processing Order
-
-Transformations are applied in this order:
-
-1. **preParse**: Raw text → Transformed raw text
-2. **Parsing**: Transformed raw text → Parsed output (if `inferenceType` provided)
-3. **postParse**: Parsed output → Transformed parsed output
-4. **preValidate**: Transformed parsed output → Pre-validated output (if validation enabled)
-5. **Validation**: Pre-validated output → Validated output (if validation enabled)
-6. **postValidate**: Validated output → Final transformed output
-
-If no `inferenceType` is provided, `postParse` is applied to `parsedContent` instead.
-
-### 8. Content Registry Integration (Instruction Keys)
-
-The gateway integrates with `@xronoces/content-registry` to fetch instructions by key instead of hardcoding them. This enables centralized content management, versioning, and zero-deploy updates.
-
-#### Overview: Two Modes for Instructions
-
-The gateway supports **two modes** for providing instructions to LLMs:
-
-1. **Text Mode (Default)**: Instructions are actual text strings embedded in code
-2. **Key Mode (New)**: Instructions are keys that reference content stored in `@xronoces/content-registry`
-
-Both modes work seamlessly - the gateway automatically detects which mode you're using based on the instruction format.
-
-#### Installation
-
-```bash
-npm install @xronoces/content-registry
-```
-
-**Note**: `@xronoces/content-registry` (v2.14.0+) is automatically installed as a dependency. This version includes simplified APIs for easier integration. 
-
-**Configuration**: Content registry is used when `contentRegistryConfig` is provided in the gateway configuration.
-
-**For Internal Use**: Content-registry auto-initializes from environment variables if available, enabling instructionsBlocks resolution without requiring explicit configuration.
-
-**See**: [Content Resolver — Upstream Guide](./CONTENT_RESOLVER_UPSTREAM_GUIDE.md) for configuration, environment variables, content layout, and upstream checklist.
-
-#### Configuration
-
-```typescript
-import { AIGateway } from '@x12i/ai-gateway';
-
-const gateway = new AIGateway({
-  defaultProvider: 'openai',
-  // Enable content-registry mode
-  enableContentRegistry: true,
-  // Configure content registry
-  contentRegistryConfig: {
-    s3Bucket: 'my-content-registry-bucket',
-    cacheTTL: 3600,  // Cache content for 1 hour
-    redis: {
-      host: 'localhost',
-      port: 6379,
-      password: process.env.REDIS_PASSWORD
-    },
-    // ... other content-registry config options
-  }
-});
-```
-
-#### Mode 1: Text Mode (Automatic - Has Spaces)
-
-**How it works**: Automatically detected when instructions contain whitespace. Used as literal text without any resolution.
-
-**When used automatically**:
-- Instructions contain spaces, tabs, or newlines
-- No content registry lookup performed
-- Fast processing with no external dependencies
-
-**Example**:
-```typescript
-// Text mode - instructions as plain text
+// Text mode - instructions as plain text (structured invoke path resolves templates from workingMemory)
+const aiRequestId = 'text-mode-1';
 const response = await gateway.invoke({
-  messages: [
-    {
-      role: 'system',
-      content: 'You are a helpful assistant that classifies text into categories: positive, negative, or neutral.'
-    },
-    {
-      role: 'user',
-      content: 'Classify: "This product is amazing!"'
-    }
-  ],
-  jobId: 'job-123'
+  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' }
 });
 ```
 
@@ -2280,24 +2095,29 @@ const response = await gateway.invoke({
 
 **Example**:
 ```typescript
-// Key mode - instructions as keys to content-registry
+// Key mode — pass the instruction key on `instructions`; user text via `prompt` + `workingMemory`
+const aiRequestId = 'key-mode-1';
 const response = await gateway.invoke({
-  messages: [
-    {
-      role: 'system',
-      content: 'classification/basic'  // ✅ Key - will be resolved from content-registry
-    },
-    {
-      role: 'user',
-      content: 'Classify: "This product is amazing!"'
-    }
-  ],
-  jobId: 'job-123',
-  // Optional: variables for template rendering
-  contentVariables: {
+  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' }
 });
 ```
 
@@ -2308,23 +2128,37 @@ const response = await gateway.invoke({
    - `content/instructions/{contentId}` (primary pattern)
    - Handles consolidated vs individual file resolution
 4. Content-registry returns raw template content with full metadata envelope
-5. Instructions parser renders template with `contentVariables` using Rendrix
+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({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-456',
-  instructions: 'professional-answer.instructions',  // Key with suffix
-  prompt: 'professional-answer.prompt',              // Key with suffix
-  input: 'What is the capital of France?',
+  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' }
 });
 ```
 
@@ -2419,21 +2253,28 @@ Provide confidence scores and reasoning.
 
 **Code**:
 ```typescript
+const aiRequestId = 'tpl-vars-1';
 const response = await gateway.invoke({
-  messages: [
-    {
-      role: 'system',
-      content: 'classification/basic'  // Key - will be resolved
-    },
-    {
-      role: 'user',
-      content: 'Classify: "This product is amazing!"'
-    }
-  ],
-  contentVariables: {
+  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' }
 });
 ```
 
@@ -2450,46 +2291,44 @@ Provide confidence scores and reasoning.
 - A/B testing with different variable values
 - Centralized template management
 
-#### Mixed Mode (Text + Keys)
+#### 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.
 
-You can mix text and keys in the same request. The gateway automatically handles both:
+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 response = await gateway.invoke({
+const aiRequestId = 'mix-chat-1';
+const response = await gateway.invokeChat({
+  aiRequestId,
+  agentId: 'agent-1',
+  instructions: '',
   messages: [
     {
       role: 'system',
-      content: 'classification/basic'  // ✅ Key - resolved from content-registry
-    },
-    {
-      role: 'user',
-      content: 'You are analyzing product reviews.'  // ✅ Text - used as-is
-    },
-    {
-      role: 'assistant',
-      content: 'I understand.'
+      content:
+        '…system prompt text (resolve content-registry keys beforehand if needed)…'
     },
-    {
-      role: 'user',
-      content: 'Classify: "This product is amazing!"'
-    }
+    { role: 'user', content: 'You are analyzing product reviews.' },
+    { role: 'assistant', content: 'I understand.' },
+    { role: 'user', content: 'Classify: "This product is amazing!"' }
   ],
-  jobId: 'job-123',
-  contentVariables: {
-    task: 'classification'
-  }
+  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' }
 });
 ```
 
-**What happens**:
-- `'classification/basic'` → Detected as key → Resolved from content-registry
-- `'You are analyzing product reviews.'` → Detected as text → Used as-is
-- Other messages → Used as-is
-
 **Use cases**:
-- Mix static instructions (text) with dynamic instructions (keys)
-- Gradually migrate from text mode to key mode
-- Use keys for complex instructions, text for simple ones
+- 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
 
@@ -2599,20 +2438,26 @@ if (metadata) {
     throw new Error(`Missing required variables: ${missingVars.join(', ')}`);
   }
   
-  // Use metadata to configure inference
+  // 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({
-    jobId: 'job-1',
+    aiRequestId,
     agentId: 'agent-1',
+    actionType: 'skill',
+    actionRef: metadata.instructionKey || 'skills/classification',
     instructions: 'classification/basic',
-    input: 'This is great!',
-    config: { model: 'gpt-4o' },
-    // Use metadata to configure parsing
+    prompt: '{{input}}',
+    workingMemory: { input: 'This is great!', ...variables },
     inferenceType: metadata.outputType,
-    parseOptions: {
-      ...metadata.parseOptions,
-      classes: variables.classes || metadata.parseOptions?.classes
+    identity: {
+      sessionId: 's1',
+      instance: { instanceId: 'agent-1', type: 'test' },
+      aiRequestId,
+      jobId: 'job-1',
+      taskId: 'task-1',
+      agentId: 'agent-1'
     },
-    validateOutputSchema: !!metadata.outputSchema
+    config: { model: 'gpt-4o', provider: 'openai' }
   });
   
   // Apply output mapping if provided
@@ -2715,22 +2560,29 @@ const gateway = new AIGateway({
   }
 });
 
-// Use key instead of text
+// Use instruction key on invoke() (resolved via content-registry)
+const aiRequestId = 'registry-step2-1';
 const response = await gateway.invoke({
-  messages: [
-    {
-      role: 'system',
-      content: 'classification/basic'  // ✅ Key - automatically resolved
-    },
-    {
-      role: 'user',
-      content: 'Classify: "This is great!"'
-    }
-  ],
-  contentVariables: {
+  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' }
 });
 ```
 
@@ -2761,7 +2613,7 @@ await registry.createPrompt({
 - **A/B Testing**: Test different instruction versions
 - **Template Support**: Use Handlebars templates with variables
 - **Caching**: Instructions are cached for performance (Redis via content-registry)
-- **Backward Compatible**: Text mode still works (default) - no breaking changes
+- **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
@@ -2769,19 +2621,31 @@ await registry.createPrompt({
 If a key cannot be resolved, the gateway falls back to using the key as text and logs a warning:
 
 ```typescript
-// If key 'invalid/key' doesn't exist in registry:
-const response = await gateway.invoke({
-  messages: [
-    {
-      role: 'system',
-      content: 'invalid/key'  // Will fallback to using 'invalid/key' as text
-    }
-  ]
-});
-
-// Gateway logs:
-// WARN: Failed to resolve instruction key: invalid/key
-// The key will be used as-is (text mode)
+// 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
@@ -2808,145 +2672,24 @@ const instructions = await resolver.resolveInstructions(
 console.log(instructions);  // Resolved instruction text
 ```
 
-### 9. Contract Output Parsing (v6.3.1+)
-
-The gateway supports contract output parsing and validation, where AI responses are parsed against expected schemas and the results are stored in activity records for compliance monitoring and debugging.
-
-#### How It Works
-
-1. **Schema Input**: Provide an optional `expectedSchema` parameter in your gateway calls
-2. **Response Parsing**: AI responses are automatically parsed using flex-md against the expected schema
-3. **Activity Storage**: Parsed results are stored in activity records under `content.contractOutput`
-4. **Status Tracking**: Compliance status is tracked in `content.outputStatus`
-
-#### Basic Usage
-
-```typescript
-import { AIGateway } from '@x12i/ai-gateway';
-
-const gateway = new AIGateway({ /* config */ });
-
-// Call with expected schema for contract validation
-const response = await gateway.invoke({
-  jobId: 'job-123',
-  agentId: 'agent-456',
-  instructions: 'Analyze the following text and provide structured output.',
-
-  // Provide expected schema for contract output parsing
-  expectedSchema: {
-    description: "Analysis results with key insights and recommendations",
-    formatHint: "### Key Insights\n[insights]\n\n### Recommendations\n[recommendations]"
-  },
-
-  messages: [{ role: 'user', content: 'Analyze this product review...' }]
-});
-
-// Activity record will contain:
-// content.contractOutput: { keyInsights: "...", recommendations: "..." }
-// content.outputStatus: "different" (parsed successfully)
-```
-
-#### Schema Format
+### 9. Contract hints (`StructuredTextSpec`) vs gateway parsing
 
-The `expectedSchema` parameter accepts a `StructuredTextSpec`:
+**`ChatRequest`** still includes an optional **`expectedSchema?: StructuredTextSpec`** field for typing and forward compatibility:
 
 ```typescript
 interface StructuredTextSpec {
-  description: string;        // Human-readable description of expected output
-  formatHint?: string;        // Optional flex-md format specification
-}
-```
-
-#### Activity Record Structure
-
-When contract output parsing is enabled, activity records include additional fields:
-
-```json
-{
-  "content": {
-    "contractOutput": {
-      // Parsed structured data from AI response
-      // Empty object {} if parsing fails
-    },
-    "outputStatus": "ok" | "different" | undefined
-  }
+  description: string;
+  formatHint?: string;
 }
 ```
 
-#### Status Values
+**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.
 
-- `"ok"`: Contract output matches expected schema structure perfectly
-- `"different"`: Contract output parsed successfully but differs from expected schema
-- `undefined`: No schema validation performed (when `expectedSchema` not provided)
+**Recommended patterns:**
 
-#### Use Cases
-
-**Contract Compliance Monitoring:**
-```typescript
-// Ensure AI responses follow expected structure
-const result = await gateway.call({
-  messages: [...],
-  expectedSchema: {
-    description: "Professional answer with short summary and detailed analysis",
-    formatHint: "### Short Answer\n[summary]\n\n### Full Answer\n[analysis]"
-  }
-});
-```
-
-**Debugging Response Parsing:**
-```typescript
-// When AI doesn't follow expected format, contractOutput will be {}
-// Check activity records to debug parsing issues
-const result = await gateway.call({
-  messages: [...],
-  expectedSchema: { /* schema */ }
-});
-// If parsing fails: content.contractOutput = {}
-// If parsing succeeds: content.contractOutput = { parsed: "data" }
-```
-
-#### Integration with Activity Tracking
-
-Contract output parsing integrates seamlessly with `@x12i/activix` v6 (xronox-activitix):
-
-- **Automatic Processing**: Parsing happens automatically when `expectedSchema` is provided
-- **Error Resilience**: Parsing failures don't break activity recording
-- **Performance**: Minimal overhead when schema is provided
-- **Backward Compatibility**: Existing calls work unchanged
-
-#### Advanced Configuration
-
-```typescript
-// Detailed schema specification
-const schema = {
-  description: "Structured analysis with multiple sections",
-  formatHint: `### Executive Summary
-[summary]
-
-### Detailed Analysis
-[analysis]
-
-### Recommendations
-[recommendations]
-
-### Confidence Level
-[level]`
-};
-
-const response = await gateway.invoke({
-  aiRequestId: 'analysis-req-001',
-  identity: {
-    jobId: 'analysis-123',
-    taskId: 'analysis-task-001',
-    sessionId: 'sess-analyzer',
-    instance: { instanceId: 'analyzer-1', type: 'gateway' }
-  },
-  agentId: 'analyzer-bot',
-  instructions: 'Analyze the provided data...',
-  expectedSchema: schema,
-  messages: [{ role: 'user', content: data }]
-});
-```
+- 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
 
@@ -2970,7 +2713,7 @@ interface GatewayConfig extends RouterConfig {
   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 v6 instance (match collection names: ai-activities, bad-requests, skill-executions)
+  activityTracker?: Activix;           // Custom Activix v7 instance (match collection names: ai-actions, bad-requests, skill-executions)
   packageName?: string;               // Default: 'AI_GATEWAY'
   // ... all RouterConfig options
 }
@@ -2982,8 +2725,8 @@ interface GatewayConfig extends RouterConfig {
 - `unregister(providerName: LLMProvider): void` - Unregister a provider
 - `getProvider(providerName: LLMProvider)` - Get a provider instance
 - `listProviders(): LLMProvider[]` - List all registered providers
-- `invoke(request: AIRequest): Promise<EnhancedLLMResponse>` - Invoke with structured output (requires `objectTypes`)
-- `invokeChat(request: ChatRequest): Promise<EnhancedLLMResponse>` - Invoke for chat/conversational requests (optional `objectTypes`)
+- `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
@@ -3003,109 +2746,68 @@ interface GatewayConfig extends RouterConfig {
 - `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
+### ChatRequest and AIRequest / AIInvokeRequest
 
-**⚠️ BREAKING CHANGE**: The old `EnhancedLLMRequest` type has been removed. Use `ChatRequest` or `AIRequest` instead.
+**Naming**
 
-**Two Request Types:**
+- **`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).
 
-1. **`ChatRequest`** - For chat/conversational requests where `objectTypes` is optional
-2. **`AIRequest`** - For structured output requests where `objectTypes` is required
+**Mandatory on `invoke()` (`AIInvokeRequest`)**
 
-#### StructuredTextSpec (v6.3.1+)
+| 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. |
 
-Interface for defining expected output schemas used in contract output parsing:
+These are validated by **`validateAIRequest`**, merged into **`request.identity`** ( **`runContext`** for Activix ), and duplicated on activity root fields **`actionType`** / **`actionRef`** when activity tracking runs.
 
-```typescript
-interface StructuredTextSpec {
-  description: string;        // Human-readable description of expected output structure
-  formatHint?: string;        // Optional flex-md format specification for parsing guidance
-}
-```
+**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:
 
-#### ChatRequest
+- **`taskConfig`**, **`templateTokens`**, **`validateOutputSchema`**, **`strictValidation`**, **`transformations`**, **`parseOptions`** (request-level).
 
-Base request interface for chat/conversational requests. Use with `invokeChat()` method.
+Use **`InstructionMetadata.parseOptions`** only as **instruction-catalog metadata**, not as invoke payload fields.
+
+**Exports**
 
 ```typescript
-interface ChatRequest extends Omit<LLMRequest, 'messages'> {
-  jobId: string;                     // Required for context propagation and activity tracking
-  agentId: string;                   // Required agent identifier
-  instructions: string;              // Required instructions (key or text)
-  taskId?: string;                   // Optional task identifier
-  taskTypeId?: string;               // Optional task type ID (auto-generated from instructions MD5 if not provided)
-  graphId?: string;                  // Optional graph identifier for graph execution context
-  nodeId?: string;                   // Optional node identifier for graph execution context
-  coreSkillId?: string;              // Optional alternative node identifier for graph execution context
-  prompt?: string;                   // Optional prompt key or text (resolved from content-registry if key, parsed as template if text)
-  input?: string;                    // Optional input text
-  context?: string;                   // Optional context text (template with workingMemory)
-  workingMemory?: unknown;            // Optional template variables for Rendrix
-  expectedSchema?: StructuredTextSpec; // Optional schema for contract output parsing (v6.3.1+)
-  inferenceType?: string;             // Optional inference type for outputs library parsing
-  parseOptions?: Record<string, unknown>;  // Optional parse options for outputs library
-  validateOutputSchema?: boolean;     // Optional schema validation flag
-  transformations?: ResponseTransformationConfig;  // Optional response transformation hooks (v1.6.9+)
-  config?: any;                      // LLM config (model, temperature, etc.)
-  modelConfig?: ModelConfig;          // Model configuration (modelConfig > config > gateway defaults)
-  objectTypes?: Array<{              // Optional object types for structured output
-    type: string;
-    schema?: Record<string, unknown>;
-    whenToUse: string;
-    description?: string;
-  }>;
-}
+import type {
+  ChatRequest,
+  AIInvokeRequest,
+  AIRequest,           // alias of AIInvokeRequest
+  GatewayActionType,    // 'skill' | 'preSkill' | 'postSkill'
+  ActivityIdentity,
+  EnhancedLLMResponse
+} from '@x12i/ai-gateway';
 ```
 
-#### AIRequest
+**Structured output helpers**
 
-Request interface for structured output requests. **Extends `BaseLLMRequest`** with required `objectTypes`. Use with `invoke()` method.
+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`**.
 
-```typescript
-interface AIRequest extends BaseLLMRequest {
-  // REQUIRED - main expected output structure
-  // Can be string (standard type name) or object (custom type with schema)
-  primaryObjectType: string | {
-    type: string;                    // Required: object type identifier
-    schema?: Record<string, unknown>; // Optional: JSON schema (required for custom types)
-    whenToUse: string;               // Required: guidance on when to use this type
-    description?: string;            // Optional: description
-  };
+**Key differences**
 
-  expectedSchema?: StructuredTextSpec; // Optional schema for contract output parsing (v6.3.1+)
-  
-  // Optional - alternative output structures
-  // Each item can be string (standard type name) or object (custom type with schema)
-  secondaryObjectTypes?: Array<string | {
-    type: string;
-    schema?: Record<string, unknown>;
-    whenToUse: string;
-    description?: string;
-  }>;
-  
-  // Output mode configuration (v3.0.5+)
-  outputMode?: 'json' | 'structured-text' | 'two-step';  // Default: 'json'
-  instructionFormat?: 'json-schema' | 'structured-text-spec';  // Default: 'json-schema'
-  structuredTextSpec?: {             // Required when instructionFormat is 'structured-text-spec'
-    description: string;              // Free-form description of output structure
-    formatHint?: string;              // Optional format hint (markdown, yaml, etc.)
-  };
-  conversionInstructions?: string;   // Optional custom conversion instructions for two-step mode
-  
-  // Optional graph execution fields (also available via BaseLLMRequest)
-  masterSkillId?: string;            // Optional graph identifier (maps to runContext.graphId when persisted)
-  skillId?: string;                  // Optional node identifier (maps to runContext.nodeId when persisted)
-  masterSkillActivityId?: string;    // Optional parent skill activity ID (preserved in identity)
-}
-```
+- **`invokeChat(request)`** — `ChatRequest`; does **not** require **`actionType`** / **`actionRef`**.
+- **`invoke(request)`** — `AIInvokeRequest`; **requires** **`actionType`** and **`actionRef`**.
 
-**Note:** `AIRequest` extends `BaseLLMRequest`, which includes optional graph execution fields (`graphId`, `nodeId`, `coreSkillId`). For graph execution context, you can use either `masterSkillId`/`skillId` (AIRequest only) or `graphId`/`nodeId` (available on all request types). See [Graph Execution Support](./docs/GRAPH_EXECUTION_SUPPORT.md) for details.
+#### StructuredTextSpec (chat / contract hints)
 
-**Key Differences:**
-- `ChatRequest`: `objectTypes` is **NOT supported** - use with `invokeChat()` for conversational requests
-- `AIRequest`: `objectTypes` is **REQUIRED** - use with `invoke()` for structured output
+Used by **`ChatRequest.expectedSchema`** when you attach optional contract structured-text hints:
 
-**⚠️ BREAKING CHANGE**: `invoke()` now requires `objectTypes`. For requests without structured output, use `invokeChat()` instead.
+```typescript
+interface StructuredTextSpec {
+  description: string;
+  formatHint?: string;
+}
+```
 
 **Output Modes (v3.0.5+):**
 
@@ -3139,17 +2841,28 @@ The gateway supports three output modes, each with two instruction formats:
    - Example: "a story with character, setting, and conflict"
    - Requires `structuredTextSpec` field
 
-**Minimal AIRequest Example (Custom Type):**
+**Minimal AIInvokeRequest example (custom `primaryObjectType`):**
 ```typescript
+const aiRequestId = 'req-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-1',
+  actionType: 'skill',
+  actionRef: 'skills/professional-answer',
   instructions: 'professional-answer/general', // Content registry key
-  input: 'What is the capital of France?',
+  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'
-    // schema is optional
   },
   modelConfig: {
     model: 'gpt-4o',
@@ -3158,14 +2871,25 @@ const response = await gateway.invoke({
 });
 ```
 
-**Using modelConfig for Model Selection:**
+**Using modelConfig for model selection:**
 ```typescript
-// modelConfig provides structured model configuration
-// Priority: modelConfig > config > gateway defaults
+const aiRequestId = 'req-2';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  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',
@@ -3177,35 +2901,57 @@ const response = await gateway.invoke({
 });
 ```
 
-**modelConfig Overrides config:**
+**modelConfig overrides `config`:**
 ```typescript
-// modelConfig takes precedence over config
+const aiRequestId = 'req-3';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  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',  // This will be overridden
-    temperature: 0.5  // This will be overridden
+    model: 'gpt-3.5-turbo',
+    temperature: 0.5
   },
   modelConfig: {
-    model: 'gpt-4-turbo',  // This takes precedence
-    temperature: 0.9  // This takes precedence
+    model: 'gpt-4-turbo',
+    temperature: 0.9
   }
 });
-// Result: Uses gpt-4-turbo with temperature 0.9
 ```
 
-**Standard Object Type Example (v3.0.6+):**
+**Standard object type example (v3.0.6+):**
 ```typescript
-// Use standard type from @x12i/outputs-library by name
+const aiRequestId = 'req-4';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-1',
+  actionType: 'skill',
+  actionRef: 'skills/sentiment-analysis',
   instructions: 'Analyze the sentiment of this text',
-  input: 'I love this product!',
-  primaryObjectType: 'sentiment-analysis', // Standard type name - no schema needed!
+  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'
@@ -3267,11 +3013,23 @@ The gateway uses **flex-md (Markdown-based format)** for all LLM communication,
 **Example:**
 
 ```typescript
+const aiRequestId = 'flex-md-ex-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-1',
+  actionType: 'skill',
+  actionRef: 'skills/sentiment',
   instructions: 'Classify the sentiment of this text',
-  input: 'This product is amazing!',
+  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: {
@@ -3436,14 +3194,26 @@ The `instructions-blocks.json` file supports nested objects that get automatical
 - **Template Variables**: All `{{variable}}` placeholders are resolved using request context
 - **Nested Access**: Dot notation (e.g., `output.complianceLevels.L2`) automatically traverses nested objects
 
-**AIRequest with Schema:**
+**AIInvokeRequest with object types / schema (invoke):**
 ```typescript
+const aiRequestId = 'pa-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-1',
+  actionType: 'skill',
+  actionRef: 'skills/professional-answer',
   instructions: 'professional-answer/general',
-  input: 'User question here',
+  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',
@@ -3460,44 +3230,50 @@ const response = await gateway.invoke({
       }
     }
   ],
-  validateOutputSchema: true,
   config: {
     model: 'gpt-4o',
     provider: 'openai'
   }
 });
+// Validate against schema in your app if needed — `validateOutputSchema` is not a request field.
 ```
 
-**Content Registry + AIRequest Pattern (Recommended):**
+**Content registry + AIInvokeRequest (recommended):**
 
-When using content-registry with AIRequest, the gateway automatically:
+When using content-registry with **`invoke()`**, the gateway typically:
 1. Resolves instruction keys from content-registry
-2. Fetches instruction metadata (outputType, outputSchema)
-3. Enforces JSON response format (`response_format: { type: 'json_object' }`)
-4. Validates responses against schema if `validateOutputSchema: true`
+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
-// Instruction stored in content-registry at: content/instructions/professional-answer/general.md
-// Metadata can include: outputType, outputSchema, validationRules
-
+const aiRequestId = 'pa-2';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-1',
-  instructions: 'professional-answer/general', // Content registry key
-  input: 'User question',
+  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 can come from instruction metadata or be provided here
       schema: instructionMetadata?.outputSchema || {
         type: 'object',
         properties: { answer: { type: 'string' } }
       }
     }
   ],
-  validateOutputSchema: true,
   config: {
     model: 'gpt-4o',
     provider: 'openai'
@@ -3509,11 +3285,23 @@ const response = await gateway.invoke({
 
 **1. JSON Output Mode (Default):**
 ```typescript
+const aiRequestId = 'out-json-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'agent-1',
+  actionType: 'skill',
+  actionRef: 'skills/qa',
   instructions: 'Answer the question',
-  prompt: 'What is the capital of France?',
+  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: {
@@ -3531,11 +3319,23 @@ const response = await gateway.invoke({
 
 **2. Structured Text Output Mode:**
 ```typescript
+const aiRequestId = 'out-st-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'story-teller',
+  actionType: 'skill',
+  actionRef: 'skills/story',
   instructions: 'Write a short story',
-  prompt: 'Create a story about a brave knight',
+  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'
@@ -3554,11 +3354,23 @@ const response = await gateway.invoke({
 
 **3. Two-Step Conversion Mode:**
 ```typescript
+const aiRequestId = 'out-2step-1';
 const response = await gateway.invoke({
-  jobId: 'job-123',
+  aiRequestId,
   agentId: 'story-converter',
+  actionType: 'skill',
+  actionRef: 'skills/story-convert',
   instructions: 'Write a detailed story',
-  prompt: 'Create a story about space exploration',
+  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: {
@@ -3591,11 +3403,11 @@ const response = await gateway.invoke({
 - **Structured Text Spec + Structured Text Mode**: Instructions describe structure in free-form, expects structured text
 - **Structured Text Spec + Two-Step Mode**: Instructions describe structure in free-form, gets structured text first, then converts to JSON
 
-**Troubleshooting**: If you see `"objectTypes is required for invoke()"`:
-1. Verify you're calling `invoke()`, not `invokeChat()`
-2. Ensure `primaryObjectType` is provided
-3. Use `validateAIRequest()` from troubleshooting helper before sending
-4. Enable `AI_GATEWAY_DEBUG_REQUEST=true` to see request at entry point
+**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)
@@ -3631,14 +3443,26 @@ 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({
-    jobId: `job-${record.id}`,
+    aiRequestId,
     agentId: 'sentiment-analyzer',
+    actionType: 'skill',
+    actionRef: 'skills/sentiment-batch',
     instructions: question,
-    input: record.text,
-    taskTypeId,  // Same for all records
-    objectTypes: [ /* REQUIRED for invoke() */ ],
-    config: { model: 'gpt-5-nano' }
+    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' }
   });
 }
 ```
@@ -3710,7 +3534,7 @@ interface EnhancedLLMResponse extends LLMResponse {
 
 ### Custom Activix instance
 
-Use the same **`collections`** names the gateway writes to (`ai-activities`, `skill-executions`, `bad-requests`) and the same **`statusValues`** mapping as in section 2.
+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';
@@ -3725,7 +3549,7 @@ const statusValues = {
 
 const customTracker = new Activix({
   collections: [
-    { name: 'ai-activities', statusValues },
+    { name: 'ai-actions', statusValues },
     { name: 'skill-executions', statusValues },
     { name: 'bad-requests', statusValues }
   ]
@@ -3832,14 +3656,23 @@ const gateway = new AIGateway({
 
 // 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({
-    jobId,  // Propagate jobId
+    aiRequestId,
     agentId: task.agentId,
     instructions: task.instructions,
-    input: task.input,
-    taskId: task.id,
-    taskTypeId: task.typeId  // Or use MD5 hash of question/instruction for consistent identification
+    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 {
@@ -3867,11 +3700,21 @@ if (model) {
     defaultProvider: model.provider
   });
   
+  const aiRequestId = 'xmodels-1';
   const response = await gateway.invokeChat({
-    jobId: 'job-123',
+    aiRequestId,
     agentId: 'agent-1',
     instructions: 'You are a helpful assistant',
-    input: 'Hello!',
+    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
     }
@@ -3886,11 +3729,21 @@ The gateway supports unified reasoning/thoughts configuration through the OpenRo
 #### Request Configuration
 
 ```typescript
+const aiRequestId = 'reasoning-example';
 const response = await gateway.invokeChat({
-  jobId: 'reasoning-example',
+  aiRequestId,
   agentId: 'agent-1',
   instructions: 'Solve this step-by-step',
-  input: 'What is 15 * 23?',
+  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',
@@ -3967,11 +3820,21 @@ interface EnhancedLLMResponse {
 
 **Basic Reasoning Request:**
 ```typescript
+const aiRequestId = 'basic-reasoning';
 const response = await gateway.invokeChat({
-  jobId: 'basic-reasoning',
+  aiRequestId,
   agentId: 'agent-1',
   instructions: 'Explain your reasoning step by step',
-  input: 'Why is the sky blue?',
+  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',
@@ -3991,11 +3854,21 @@ 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({
-  jobId: 'continuity-1',
+  aiRequestId: aiRequestId1,
   agentId: 'agent-1',
   instructions: 'Solve this complex problem',
-  input: 'Calculate the trajectory of a satellite',
+  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
@@ -4013,11 +3886,21 @@ if (encryptedArtifacts && encryptedArtifacts.length > 0) {
 
   // 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({
-    jobId: 'continuity-2',
+    aiRequestId: aiRequestId2,
     agentId: 'agent-1',
     instructions: 'Continue from previous reasoning',
-    input: 'Now apply this to Mars orbit',
+    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',
@@ -4067,26 +3950,35 @@ import {
 
 **See**: [TROUBLESHOOTING_TOOLBOX.md](./TROUBLESHOOTING_TOOLBOX.md) for complete API documentation.
 
-### Common Issue: "objectTypes is required for invoke()"
+### Common Issue: `invoke()` validation (`actionType`, `actionRef`, `identity`, `input`)
 
-**Error**: `Request validation failed: objectTypes is required for invoke()`
+**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. ✅ **Verify you're calling `invoke()`, not `invokeChat()`**
+1. ✅ **Structured calls must use `invoke()` with `AIInvokeRequest` fields**
    ```typescript
-   // ✅ Correct for structured output
+   const aiRequestId = 'fix-1';
    await gateway.invoke({
-     jobId: 'job-123',
+     aiRequestId,
      agentId: 'agent-1',
+     actionType: 'skill',
+     actionRef: 'skills/professional-answer',
      instructions: 'professional-answer/general',
-     input: 'User question',
-     objectTypes: [
-       {
-         type: 'professional-answer',
-         whenToUse: 'For professional Q&A responses'
-       }
-     ],
+     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' }
    });
    ```
@@ -4142,14 +4034,21 @@ The gateway throws specific error types:
 import { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-gateway';
 
 try {
+  const aiRequestId = 'chat-req-001';
   const response = await gateway.invokeChat({
-    aiRequestId: 'chat-req-001',
-    sessionId: 'sess-1',
-    instance: { instanceId: 'gw-1', type: 'gateway' },
-    jobId: 'job-123',
+    aiRequestId,
     agentId: 'agent-1',
     instructions: 'You are a helpful assistant',
-    input: 'Hello!'
+    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) {
@@ -4168,7 +4067,7 @@ 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** v6 (xronox-activitix): Activity logging and tracking (`^6.5.1` in this package)
+- **@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)