coaiajs 0.1.0

package/articles/technical/openai-sdk-modern.md

@@ -0,0 +1,231 @@
+# OpenAI Node.js SDK: Technical Assessment for CoAiA.js
+
+> Package selection brief — Unified LLM client for chat completions, streaming, and Whisper transcription replacing coaiapy's raw HTTP calls
+
+## Summary & Recommendation
+
+**Use `openai` v6.x SDK** (currently 6.27.0). The official SDK provides type-safe chat completions with streaming, Whisper audio transcription, and image generation — all features coaiajs needs. The SDK handles authentication, retry logic, rate limiting, and model-specific serialization. Combined with `@langfuse/openai` for automatic tracing, this eliminates all raw HTTP request code.
+
+**Pin:** `"openai": "^6.0.0"`
+
+## What We're Replacing
+
+Coaiapy uses raw HTTP requests for OpenAI API calls, scattered across multiple modules:
+
+```python
+# coaiapy pattern — manual HTTP to OpenAI
+import requests
+import json
+
+def call_openai(messages, model="gpt-4"):
+    headers = {
+        "Authorization": f"Bearer {os.getenv('OPENAI_API_KEY')}",
+        "Content-Type": "application/json"
+    }
+    response = requests.post(
+        "https://api.openai.com/v1/chat/completions",
+        headers=headers,
+        json={"model": model, "messages": messages}
+    )
+    return response.json()["choices"][0]["message"]["content"]
+```
+
+This pattern: no streaming, no automatic retry, no type safety, no token counting, no multimodal support, and requires manual header management per request.
+
+## Options Compared
+
+| Feature | openai SDK v6 | Raw fetch/requests | LangChain OpenAI |
+|---------|--------------|-------------------|------------------|
+| Type safety | Full TypeScript types | Manual interfaces | Via LangChain types |
+| Streaming | `stream: true` + async iterator | Manual SSE parsing | LangChain callbacks |
+| Whisper transcription | `client.audio.transcriptions.create()` | Manual multipart form | Not supported |
+| Image generation | `client.images.generate()` | Manual API call | Via LangChain |
+| Rate limit handling | Built-in retry with backoff | Manual retry loops | Via LangChain |
+| Token counting | Response includes usage | Manual counting | Via callbacks |
+| Langfuse integration | `@langfuse/openai` wrapper | Manual trace creation | `CallbackHandler` |
+| Realtime API | WebSocket support built-in | Manual WebSocket | N/A |
+| Bundle overhead | ~50KB | 0 | ~200KB+ |
+| Maintenance | Official, rapid updates | None | LangChain release cycle |
+
+## API Overview
+
+### Client Setup
+
+```typescript
+import OpenAI from 'openai';
+import { loadConfig } from '../config.js';
+
+const config = loadConfig();
+const openai = new OpenAI({
+  apiKey: config.openaiApiKey,
+  // Optional: custom base URL for Azure OpenAI or local models
+  baseURL: config.openaiBaseUrl,
+});
+```
+
+### Chat Completions (Standard)
+
+```typescript
+async function chatCompletion(
+  messages: OpenAI.ChatCompletionMessageParam[],
+  model = 'gpt-5.4'
+): Promise<string> {
+  const response = await openai.chat.completions.create({
+    model,
+    messages,
+    temperature: 0.7,
+  });
+  return response.choices[0]?.message?.content ?? '';
+}
+
+// Usage in coaiajs
+const analysis = await chatCompletion([
+  { role: 'system', content: 'You are a structural tension chart analyst.' },
+  { role: 'user', content: `Analyze this chart: ${JSON.stringify(chart)}` },
+]);
+```
+
+### Streaming Chat Completions
+
+```typescript
+async function* streamChat(
+  messages: OpenAI.ChatCompletionMessageParam[],
+  model = 'gpt-5.4'
+): AsyncGenerator<string> {
+  const stream = await openai.chat.completions.create({
+    model,
+    messages,
+    stream: true,
+  });
+
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content;
+    if (content) yield content;
+  }
+}
+
+// Usage in CLI for real-time output
+async function streamToTerminal(messages: OpenAI.ChatCompletionMessageParam[]) {
+  for await (const chunk of streamChat(messages)) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write('\n');
+}
+```
+
+### Whisper Transcription (replacing voice-to-text pipeline)
+
+```typescript
+import fs from 'fs';
+
+async function transcribeAudio(filePath: string, language = 'en'): Promise<string> {
+  const response = await openai.audio.transcriptions.create({
+    file: fs.createReadStream(filePath),
+    model: 'whisper-1',
+    language,
+    response_format: 'text',
+  });
+  return response;
+}
+
+// Verbose transcription with timestamps
+async function transcribeVerbose(filePath: string) {
+  const response = await openai.audio.transcriptions.create({
+    file: fs.createReadStream(filePath),
+    model: 'whisper-1',
+    response_format: 'verbose_json',
+    timestamp_granularities: ['segment'],
+  });
+  return response; // includes segments with start/end timestamps
+}
+```
+
+### Image Generation (for chart visualization)
+
+```typescript
+async function generateChartImage(description: string): Promise<string> {
+  const response = await openai.images.generate({
+    model: 'dall-e-3',
+    prompt: `Structural tension chart visualization: ${description}`,
+    n: 1,
+    size: '1024x1024',
+    response_format: 'url',
+  });
+  return response.data[0]?.url ?? '';
+}
+```
+
+### With Langfuse Tracing (automatic observability)
+
+```typescript
+import { observeOpenAI } from '@langfuse/openai';
+import OpenAI from 'openai';
+import { getLangfuse } from '../langfuse/client.js';
+
+// Wrap OpenAI client for automatic trace capture
+const tracedOpenai = observeOpenAI(new OpenAI(), {
+  langfuse: getLangfuse(),
+  generationName: 'coaia-generation',
+});
+
+// Every API call is automatically traced in Langfuse
+// with model, tokens, latency, cost tracking
+const response = await tracedOpenai.chat.completions.create({
+  model: 'gpt-5.4',
+  messages: [{ role: 'user', content: 'Evaluate this structural tension...' }],
+});
+```
+
+### Structured Output with Zod
+
+```typescript
+import { z } from 'zod';
+import { zodResponseFormat } from 'openai/helpers/zod';
+
+const ChartAnalysis = z.object({
+  tension_score: z.number().min(0).max(10),
+  recommendations: z.array(z.string()),
+  next_action: z.string(),
+});
+
+const response = await openai.beta.chat.completions.parse({
+  model: 'gpt-5.4',
+  messages: [{ role: 'user', content: `Analyze: ${JSON.stringify(chart)}` }],
+  response_format: zodResponseFormat(ChartAnalysis, 'chart_analysis'),
+});
+
+const analysis = response.choices[0]?.message?.parsed;
+// analysis is fully typed as { tension_score: number; recommendations: string[]; next_action: string }
+```
+
+## Integration Plan
+
+1. **Core client:** `src/openai/client.ts` — singleton, config-driven, with Langfuse wrapper
+2. **Chat module:** `src/openai/chat.ts` — standard + streaming completions
+3. **Audio module:** `src/openai/audio.ts` — Whisper transcription (replaces voice pipeline)
+4. **Structured output:** `src/openai/structured.ts` — Zod-validated responses
+5. **MCP tool integration:** Tools that call OpenAI for analysis, decomposition, evaluation
+6. **Pipeline steps:** `src/pipeline/generation-step.ts` — traced generation within pipelines
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 6.27.0 (March 2026) |
+| Weekly downloads | ~15M+ |
+| TypeScript | Full native types |
+| Node.js compat | ≥20 LTS |
+| Runtime support | Node.js, Deno, Bun, edge |
+| Streaming | SSE async iterator |
+| Structured output | Zod helper built-in |
+| Models supported | GPT-5.x, GPT-4.x, Whisper, DALL-E, Realtime |
+| Langfuse integration | `@langfuse/openai` drop-in wrapper |
+| License | Apache-2.0 |
+
+## References
+
+- npm: https://www.npmjs.com/package/openai
+- GitHub: https://github.com/openai/openai-node
+- API docs: https://developers.openai.com/api/docs/libraries/
+- DeepWiki: https://deepwiki.com/openai/openai-node
+- Releases: https://github.com/openai/openai-node/releases

package/articles/technical/yaml-parsing-node.md

@@ -0,0 +1,266 @@
+# YAML Parsing in Node.js: Technical Assessment for CoAiA.js
+
+> Package selection brief — YAML parser for pipeline templates, session files, and config loading replacing coaiapy's PyYAML
+
+## Summary & Recommendation
+
+**Use `yaml` v2.x** (the npm package named simply `yaml`). Despite `js-yaml` having higher download numbers, the modern `yaml` package offers streaming support for large files, comment preservation (critical for human-edited pipeline templates), and a cleaner API. CoAiA pipeline templates are user-authored YAML that benefits from round-trip fidelity — comments survive parse→stringify cycles.
+
+**Pin:** `"yaml": "^2.6.0"`
+
+## What We're Replacing
+
+Coaiapy uses PyYAML for pipeline template loading:
+
+```python
+# coaiapy/pipeline.py — PyYAML pattern
+import yaml
+
+# Load pipeline template
+for template_file in search_path.glob("*.yaml"):
+    with open(yaml_file, 'r') as f:
+        data = yaml.safe_load(f)  # Parse YAML → dict
+
+# Pipeline template format:
+# name: "trace-session"
+# version: "1.0"
+# variables:
+#   - name: session_id
+#     type: string
+#     required: true
+# steps:
+#   - name: create_trace
+#     observation_type: SPAN
+```
+
+PyYAML's `safe_load` works well; the JavaScript equivalent needs the same safety guarantees plus TypeScript types.
+
+## Options Compared
+
+| Feature | yaml v2.6 | js-yaml v4.1 |
+|---------|-----------|-------------|
+| Weekly npm downloads | ~80M | ~130M |
+| GitHub stars | ~1,600 | ~6,500 |
+| Parse speed (typical files) | Good | Faster (~10%) |
+| Stringify speed | Faster | Slower |
+| Streaming support | ✅ Parse & stringify | ❌ Memory only |
+| Comment preservation | ✅ Round-trip fidelity | ❌ Comments lost |
+| Anchor/alias support | ✅ Full | ✅ Full |
+| Custom tags | ✅ Flexible API | ✅ Schema-based |
+| TypeScript | Native types | `@types/js-yaml` |
+| YAML 1.2 compliance | ✅ Full | ⚠️ Mostly |
+| Security (CVEs) | None known | CVE-2025-64718 (fixed in 4.1.1) |
+| API style | `parse(str)`, `stringify(obj)` | `load(str)`, `dump(obj)` |
+| Bundle size | ~45KB | ~30KB |
+| Dependencies | 0 | 0 |
+
+## API Overview
+
+### Basic Parse & Stringify
+
+```typescript
+import { parse, stringify } from 'yaml';
+import { readFile, writeFile } from 'fs/promises';
+
+// Parse YAML file
+async function loadYaml<T>(filePath: string): Promise<T> {
+  const content = await readFile(filePath, 'utf-8');
+  return parse(content) as T;
+}
+
+// Stringify to YAML
+async function saveYaml(filePath: string, data: unknown): Promise<void> {
+  const yamlStr = stringify(data, {
+    indent: 2,
+    lineWidth: 120,
+  });
+  await writeFile(filePath, yamlStr, 'utf-8');
+}
+```
+
+### Pipeline Template Loading (replacing pipeline.py)
+
+```typescript
+import { parse } from 'yaml';
+import { readFile } from 'fs/promises';
+import { glob } from 'glob';
+import { z } from 'zod';
+
+// Schema (validated with Zod after YAML parse)
+const PipelineTemplateSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().default('1.0'),
+  variables: z.array(z.object({
+    name: z.string().min(1),
+    type: z.enum(['string', 'number', 'boolean', 'list']).default('string'),
+    required: z.boolean().default(true),
+    default: z.unknown().optional(),
+    choices: z.array(z.unknown()).optional(),
+  })).default([]),
+  steps: z.array(z.object({
+    name: z.string().min(1),
+    observation_type: z.enum(['EVENT', 'SPAN', 'GENERATION']).default('EVENT'),
+    conditional: z.string().optional(),
+  })).min(1),
+});
+
+type PipelineTemplate = z.infer<typeof PipelineTemplateSchema>;
+
+async function loadPipelineTemplates(templateDir: string): Promise<Map<string, PipelineTemplate>> {
+  const templates = new Map<string, PipelineTemplate>();
+  const files = await glob('*.yaml', { cwd: templateDir, absolute: true });
+  
+  for (const file of files) {
+    const raw = parse(await readFile(file, 'utf-8'));
+    const template = PipelineTemplateSchema.parse(raw);
+    templates.set(template.name, template);
+  }
+  
+  return templates;
+}
+```
+
+### Comment-Preserving Round-Trip (unique to `yaml` package)
+
+```typescript
+import { parseDocument, stringify } from 'yaml';
+import { readFile, writeFile } from 'fs/promises';
+
+// Load, modify, save — preserving user comments
+async function updateTemplateVersion(filePath: string, newVersion: string): Promise<void> {
+  const content = await readFile(filePath, 'utf-8');
+  const doc = parseDocument(content);  // Preserves comments, anchors, formatting
+  
+  doc.set('version', newVersion);
+  
+  await writeFile(filePath, doc.toString(), 'utf-8');
+  // Original comments and formatting are preserved!
+}
+
+// Example input:
+// # Pipeline for session tracing
+// name: trace-session
+// version: "1.0"  # Bump this on changes
+// 
+// After update, the comment "# Bump this on changes" survives
+```
+
+### Session File Persistence
+
+```typescript
+import { parse, stringify } from 'yaml';
+import { readFile, writeFile } from 'fs/promises';
+
+interface SessionFile {
+  id: string;
+  created: string;
+  traces: { id: string; name: string; status: string }[];
+  charts: { id: string; outcome: string }[];
+  metadata: Record<string, unknown>;
+}
+
+async function saveSession(filePath: string, session: SessionFile): Promise<void> {
+  await writeFile(filePath, stringify(session, {
+    indent: 2,
+    lineWidth: 120,
+    sortMapEntries: false,  // Preserve insertion order
+  }), 'utf-8');
+}
+
+async function loadSession(filePath: string): Promise<SessionFile> {
+  const content = await readFile(filePath, 'utf-8');
+  return parse(content) as SessionFile;
+}
+```
+
+### Streaming for Large Files
+
+```typescript
+import { parseAllDocuments } from 'yaml';
+import { createReadStream } from 'fs';
+
+// Stream-parse a multi-document YAML file
+async function parseMultiDoc(filePath: string) {
+  const content = await readFile(filePath, 'utf-8');
+  const docs = parseAllDocuments(content);
+  
+  for (const doc of docs) {
+    if (doc.errors.length > 0) {
+      console.error(`Parse errors in ${filePath}:`, doc.errors);
+      continue;
+    }
+    yield doc.toJSON();
+  }
+}
+```
+
+### Config File Loading
+
+```typescript
+import { parse } from 'yaml';
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+
+// Load coaia.json or coaia.yaml config
+async function loadConfigFile(configPath: string): Promise<Record<string, unknown>> {
+  if (!existsSync(configPath)) return {};
+  
+  const content = await readFile(configPath, 'utf-8');
+  
+  if (configPath.endsWith('.yaml') || configPath.endsWith('.yml')) {
+    return parse(content) ?? {};
+  }
+  if (configPath.endsWith('.json')) {
+    return JSON.parse(content);
+  }
+  
+  // Try YAML first (superset of JSON)
+  try {
+    return parse(content) ?? {};
+  } catch {
+    return JSON.parse(content);
+  }
+}
+```
+
+## Integration Plan
+
+1. **Core utility:** `src/yaml.ts` — typed `loadYaml<T>()` and `saveYaml()` wrappers
+2. **Pipeline templates:** `src/pipeline/template-loader.ts` — YAML template discovery + Zod validation
+3. **Session files:** `src/session/file.ts` — YAML session persistence
+4. **Config loading:** `src/config.ts` — support `.yaml` config alongside `.json`
+5. **Round-trip editing:** Use `parseDocument()` for user-facing template modifications
+6. **Multi-doc:** Support `---` separated YAML documents for batch operations
+
+## Why Not js-yaml?
+
+1. **Comment preservation**: Pipeline templates are human-authored; losing comments on round-trip is unacceptable
+2. **Security**: CVE-2025-64718 (prototype pollution) was a recent concern; `yaml` has a clean record
+3. **YAML 1.2**: Full compliance matters for interop with other tools
+4. **Streaming**: Future-proofing for large narrative JSONL files converted to/from YAML
+5. **TypeScript**: Native types without DefinitelyTyped dependency
+
+The ~10% parse speed advantage of js-yaml is irrelevant for config/template files (sub-millisecond either way).
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 2.6.x (2026) |
+| Weekly downloads | ~80M |
+| TypeScript | Native types |
+| Dependencies | 0 |
+| YAML spec | 1.2 compliant |
+| Comment round-trip | ✅ Full support |
+| Streaming | ✅ Parse & stringify |
+| Node.js compat | ≥14 (we target ≥20) |
+| License | ISC |
+
+## References
+
+- npm: https://www.npmjs.com/package/yaml
+- GitHub: https://github.com/eemeli/yaml
+- js-yaml: https://www.npmjs.com/package/js-yaml
+- Comparison: https://npm-compare.com/js-yaml,yaml
+- Performance: https://github.com/eemeli/yaml/discussions/358
+- CVE-2025-64718: https://www.cvedetails.com/cve/CVE-2025-64718/

package/articles/technical/zod-runtime-validation.md

@@ -0,0 +1,212 @@
+# Zod Runtime Validation: Technical Assessment for CoAiA.js
+
+> Package selection brief — TypeScript-first schema validation replacing coaia-narrative's custom 181-line validation.ts
+
+## Summary & Recommendation
+
+**Use `zod` v4.x** as the unified validation layer for all coaiajs modules. Zod replaces coaia-narrative's custom `validation.ts` (181 lines of hand-rolled recursive validation) with a standard, composable, type-inferring schema library. The MCP SDK already requires Zod as a peer dependency for tool argument schemas — using it everywhere eliminates dual validation code.
+
+**Pin:** `"zod": "^4.0.0"` (v4.3.6 stable, required by `@modelcontextprotocol/sdk`)
+
+## What We're Replacing
+
+coaia-narrative has a custom `validation.ts` implementing recursive schema validation:
+
+```typescript
+// coaia-narrative/src/validation.ts — 181 lines of custom validation
+type ValidationType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date' | 'enum';
+
+interface ValidationRule {
+  type: ValidationType;
+  required?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: RegExp;
+  minValue?: number;
+  maxValue?: number;
+  enumValues?: (string | number)[];
+  items?: ValidationRule;         // array items schema
+  properties?: Record<string, ValidationRule>;  // object properties
+}
+
+export function validate(args: any, schema: ValidationSchema): { valid: boolean; error?: string }
+```
+
+Pre-built schemas: `stringArray()`, `entityArray()`, `relationArray()`, `isoDate()`, `nonEmptyString()`.
+
+This works but: no type inference, no composition, no transform/coerce, no JSON Schema export, and every new validation type requires manual code.
+
+## Options Compared
+
+| Feature | Zod v4 | Custom validation.ts | io-ts | Yup |
+|---------|--------|---------------------|-------|-----|
+| Type inference | ✅ Automatic `z.infer<>` | ❌ Manual types | ✅ (verbose) | ⚠️ Partial |
+| Schema composition | ✅ `.merge()`, `.extend()`, `.pick()` | ❌ Manual nesting | ✅ | ✅ |
+| MCP SDK compat | ✅ Required peer dep | ❌ N/A | ❌ | ❌ |
+| JSON Schema export | ✅ `toJSONSchema()` | ❌ N/A | ❌ | ❌ |
+| Transform/coerce | ✅ `.transform()`, `.coerce` | ❌ N/A | ❌ | ✅ |
+| Error messages | ✅ Structured `ZodError` | ⚠️ Single string | ⚠️ Verbose | ✅ |
+| Bundle size | ~2KB gzip (core) | ~3KB | ~15KB | ~12KB |
+| Weekly downloads | ~100M+ | N/A | ~8M | ~15M |
+| Performance (v4) | 14x faster strings, 7x faster arrays vs v3 | Adequate | Slower | Slower |
+
+## API Overview
+
+### Replacing Custom Schemas
+
+```typescript
+import { z } from 'zod';
+
+// Replaces: ValidationSchemas.nonEmptyString()
+const NonEmptyString = z.string().min(1);
+
+// Replaces: ValidationSchemas.isoDate()
+const IsoDate = z.string().datetime();
+
+// Replaces: ValidationSchemas.stringArray(minLength)
+const StringArray = (min = 0) => z.array(z.string()).min(min);
+
+// Replaces: ValidationSchemas.entityArray()
+const Entity = z.object({
+  name: z.string().min(1),
+  entityType: z.string().min(1),
+  observations: z.array(z.string()).default([]),
+});
+const EntityArray = z.array(Entity).min(1);
+
+// Replaces: ValidationSchemas.relationArray()
+const Relation = z.object({
+  from: z.string().min(1),
+  to: z.string().min(1),
+  relationType: z.string().min(1),
+});
+const RelationArray = z.array(Relation);
+```
+
+### Structural Tension Chart Schema
+
+```typescript
+const ChartSchema = z.object({
+  id: z.string().min(1),
+  desiredOutcome: z.string().min(1),
+  currentReality: z.string().min(1),
+  dueDate: z.string().datetime().optional(),
+  actionSteps: z.array(z.object({
+    title: z.string().min(1),
+    status: z.enum(['pending', 'in_progress', 'done', 'blocked']),
+    currentReality: z.string().optional(),
+  })).default([]),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+
+type Chart = z.infer<typeof ChartSchema>;  // TypeScript type auto-generated
+```
+
+### MCP Tool Argument Validation
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+const server = new McpServer({ name: 'coaiajs', version: '1.0.0' });
+
+// Zod schemas ARE the MCP tool input schemas — zero duplication
+server.tool(
+  'create_chart',
+  'Create a structural tension chart',
+  {
+    desiredOutcome: z.string().describe('What you want to CREATE'),
+    currentReality: z.string().describe('Factual assessment of current state'),
+    dueDate: z.string().datetime().optional().describe('Target date (ISO 8601)'),
+    actionSteps: z.array(z.string()).optional().describe('Initial action steps'),
+  },
+  async ({ desiredOutcome, currentReality, dueDate, actionSteps }) => {
+    // Arguments are already validated and typed
+    const chart = await createChart({ desiredOutcome, currentReality, dueDate, actionSteps });
+    return { content: [{ type: 'text', text: JSON.stringify(chart) }] };
+  }
+);
+```
+
+### Pipeline Template Validation
+
+```typescript
+// Replaces coaiapy's pipeline.py validate_variables()
+const PipelineVariable = z.object({
+  name: z.string().min(1),
+  type: z.enum(['string', 'number', 'boolean', 'list']).default('string'),
+  required: z.boolean().default(true),
+  default: z.unknown().optional(),
+  choices: z.array(z.unknown()).optional(),
+});
+
+const PipelineTemplate = z.object({
+  name: z.string().min(1),
+  version: z.string().default('1.0'),
+  variables: z.array(PipelineVariable).default([]),
+  steps: z.array(z.object({
+    name: z.string().min(1),
+    observation_type: z.enum(['EVENT', 'SPAN', 'GENERATION']).default('EVENT'),
+    conditional: z.string().optional(),
+  })).min(1),
+});
+
+// Validate and get typed result
+function loadTemplate(raw: unknown): PipelineTemplate {
+  return PipelineTemplate.parse(raw);  // throws ZodError on invalid
+}
+```
+
+### Error Handling
+
+```typescript
+import { z } from 'zod';
+
+function validateSafe<T>(schema: z.ZodSchema<T>, data: unknown): { valid: true; data: T } | { valid: false; error: string } {
+  const result = schema.safeParse(data);
+  if (result.success) {
+    return { valid: true, data: result.data };
+  }
+  // Structured error messages
+  const messages = result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`);
+  return { valid: false, error: messages.join('; ') };
+}
+```
+
+## Integration Plan
+
+1. **Shared schemas:** `src/schemas/` directory with reusable Zod schemas
+   - `chart.ts` — ChartSchema, ActionStepSchema
+   - `entity.ts` — Entity, Relation schemas (replaces validation.ts)
+   - `pipeline.ts` — PipelineTemplate, PipelineVariable
+   - `session.ts` — Session, Trace schemas
+2. **MCP tools:** Direct Zod schemas in tool definitions (no separate validation layer)
+3. **Config validation:** Zod for config file/env var validation at startup
+4. **JSON Schema export:** `toJSONSchema()` for documentation and interop
+5. **Migration:** Delete coaia-narrative's `validation.ts`, import from `@coaiajs/schemas`
+
+### @zod/mini for Future Frontend
+
+If coaiajs adds a web UI, use `@zod/mini` (~1.9KB) for client-side validation with the same schemas.
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 4.3.6 (Jan 2026) |
+| Weekly downloads | ~100M+ |
+| TypeScript | First-class, type inference is the core value |
+| Bundle size | ~2KB gzip (core), ~1.9KB (@zod/mini) |
+| MCP SDK | Required peer dependency |
+| JSON Schema | `toJSONSchema()` built-in |
+| Node.js compat | Any (zero native deps) |
+| License | MIT |
+
+## References
+
+- npm: https://www.npmjs.com/package/zod
+- GitHub: https://github.com/colinhacks/zod
+- v4 announcement: https://www.infoq.com/news/2025/08/zod-v4-available/
+- What's new in v4: https://basicutils.com/learn/zod/whats-new-in-zod-v4
+- MCP SDK peer dep: https://www.npmjs.com/package/@modelcontextprotocol/sdk