feat(providers): wire missing media handlers + fix video routing + add CartesiaTTS

Closes the gaps reported in NEUROLINK_SDK_GAPS.md from a downstream
consumer (Director). After v9.65.0, several shipped capabilities could
not be invoked through nl.generate(...) because:

- package.json exports map exposed only 7 subpaths; internal modules
  were blocked by Node ESM resolution.
- Music + Avatar handlers were registered only on ProviderRegistry's
  lazy path, so consumers importing MusicProcessor / AvatarProcessor
  directly saw an empty registry.
- FishAudioTTS shipped in dist/voice/providers/ but was never
  registered with TTSProcessor.
- Top-level package re-exports surfaced only GoogleTTSHandler; every
  other handler class was unreachable from import * as NL.
- handleVideoGeneration in baseProvider ignored output.video.provider
  and always called generateVideoWithVertex, so Kling/Runway/Replicate
  routing was dead.
- The Cartesia adapter in dist/ was a streaming WebSocket class, not a
  TTSHandler, so tts.provider:"cartesia" failed.

Changes
-------
* package.json: add 11 subpaths (./voice, ./music, ./avatar, ./image-gen,
  ./hitl, ./evaluation, ./workflow, ./rag, ./files, ./processors,
  ./processors/*, ./adapters/*).
* Module-level auto-registration in voice/music/avatar barrels; every
  shipped handler whose API key is in process.env registers itself at
  import time. Idempotent with ProviderRegistry's existing block.
* New src/lib/voice/providers/CartesiaTTS.ts: synchronous TTSHandler
  over Cartesia's /tts/bytes endpoint. CartesiaStream remains for the
  realtime voice server.
* providerRegistry.ts: add fish-audio and cartesia registration blocks
  alongside the other TTS handlers for architectural consistency.
* src/lib/index.ts: re-export every shipped TTS/STT/Realtime/Music/
  Avatar/Video handler + ImageGenService + HITLManager + STTProcessor +
  RealtimeProcessor + registerDefault* helpers.
* src/lib/types/{tts,music,avatar,multimodal}.ts: add TTSProviderName,
  MusicProviderName, AvatarProviderName, VideoProviderName unions with
  (string & {}) escape hatch.
* src/lib/core/baseProvider.ts: handleVideoGeneration now dispatches
  through VideoProcessor.generate(provider, ...) honoring output.video
  .provider; propagates real provider in logs + result.provider;
  rejects unknown providers with VIDEO_ERROR_CODES.PROVIDER_NOT_SUPPORTED
  instead of silently falling back to Vertex.

Tests
-----
* test/continuous-test-suite-tts.ts: registration assertions for
  fish-audio + cartesia plus live e2e tests (real Cartesia API call
  verified — 30 KB MP3 output).
* test/continuous-test-suite-media-gen.ts: video registration check,
  unknown-provider rejection (regression guard for the silent-vertex-
  fallback bug), per-provider routing tests for Kling/Runway/Replicate.
  Each PASSes either via a successful generation or via the handler's
  own typed error (which proves the dispatcher reached the right
  handler).

Docs
----
* New docs/getting-started/providers/cartesia.md provider guide.
* docs/features/tts.md: env-setup, Supported Providers table, CLI
  --tts-provider enum, and per-provider examples updated with Fish
  Audio + Cartesia.
* docs/features/video-generation.md: four-provider compatibility table,
  per-provider routing examples, and a Unknown Provider Behavior
  subsection documenting the new PROVIDER_NOT_SUPPORTED guard.
* docs/getting-started/provider-setup.md: new Fish Audio + Cartesia TTS
  configuration sections after Azure Speech.
* docs/getting-started/providers/index.md: Cartesia card under TTS plus
  provider feature-matrix row.
* README.md: TTS provider count 4 -> 6; tts.provider union widened.
* CLAUDE.md: project-overview line widened to include Fish Audio,
  Cartesia, and the media-gen handler set.

Verification
------------
- pnpm exec tsc --noEmit --strict: pass
- pnpm run lint: pass (0 errors, 15 pre-existing warnings)
- pnpm run build: pass; publint "All good!"
- pnpm run test:tts: 18/18 PASS (Fish Audio + Cartesia live e2e)
- pnpm run test:music: 12/12 PASS
- pnpm run test:avatar: 10/10 PASS
- pnpm run test:media: 23/23 PASS (Kling/Runway/Replicate routing)
- pnpm run test:bugfixes: 48/48 PASS
- pnpm run test:credentials: 15/15 PASS
- pnpm run test:unit: 7 sub-suites all PASS
- pnpm run test:ci: exit 0 (main + client 13/13 + hitl 4/4)

Author: murdore

.gitignore

@@ -176,3 +176,6 @@ docs-site/static/search-index.json
 
 # Local working notes for the AI SDK removal migration (not for upstream)
 memory-bank/native-runtime/
+
+# Consumer-supplied gap/spec docs we work from locally — not part of the repo
+NEUROLINK_SDK_GAPS.md

CLAUDE.md

@@ -16,7 +16,7 @@ Guidance for Claude Code when working in this repository.
 
 ## Project Overview
 
-NeuroLink is a unified AI development platform shipping as both a **TypeScript SDK** and **CLI**. It wraps 21+ AI providers (OpenAI, Anthropic, Google AI Studio, Vertex, AWS Bedrock, Azure, Mistral, LiteLLM, SageMaker, Hugging Face, Ollama, OpenAI-compatible, DeepSeek, NVIDIA NIM, LM Studio, llama.cpp, OpenRouter, ElevenLabs, Deepgram, Azure Speech, and more) behind a single consistent API, with full MCP support, multimodal file processing, voice (TTS/STT/realtime), RAG pipelines, observability, and a workflow engine.
+NeuroLink is a unified AI development platform shipping as both a **TypeScript SDK** and **CLI**. It wraps 21+ AI providers (OpenAI, Anthropic, Google AI Studio, Vertex, AWS Bedrock, Azure, Mistral, LiteLLM, SageMaker, Hugging Face, Ollama, OpenAI-compatible, DeepSeek, NVIDIA NIM, LM Studio, llama.cpp, OpenRouter, ElevenLabs, Deepgram, Azure Speech, Fish Audio, Cartesia, and more) behind a single consistent API, with full MCP support, multimodal file processing, voice (TTS/STT/realtime), media generation (image / video / music / avatar with Kling / Runway / Replicate / Beatoven / Lyria / D-ID / HeyGen handlers), RAG pipelines, observability, and a workflow engine.
 
 ---
 

README.md

@@ -43,7 +43,7 @@ Extracted from production systems at Juspay and battle-tested at enterprise scal
 | Feature                                      | Version | Description                                                                                                                                                                                                                                                                                                                                                                   | Guide                                                                                                                                   |
 | -------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | **Avatar / Music Modalities + 12 Providers** | next    | New `output: { mode: "avatar" \| "music" }` dispatch with handlers for D-ID, HeyGen, Replicate-MuseTalk (avatar) and Beatoven, ElevenLabs Music, Lyria, Replicate-MusicGen (music). Plus Fish Audio TTS, Kling/Runway/Replicate video, xAI/Groq/Cohere/Together/Fireworks/Perplexity/Cloudflare LLMs, Voyage/Jina embeddings, Stability/Ideogram/Recraft/Replicate image-gen. | [Provider Integration](docs/provider-integration/)                                                                                      |
-| **Multi-Provider Voice (TTS/STT)**           | v9.62.0 | 4 TTS providers (OpenAI TTS, ElevenLabs, Google TTS, Azure TTS) + 4 STT providers (Whisper, Deepgram, Azure STT, Google STT) + 2 realtime APIs (OpenAI Realtime, Gemini Live).                                                                                                                                                                                                | [TTS Guide](docs/features/tts.md) \| [STT Guide](docs/features/audio-input.md) \| [Realtime Guide](docs/features/real-time-services.md) |
+| **Multi-Provider Voice (TTS/STT)**           | v9.62.0 | 6 TTS providers (OpenAI TTS, ElevenLabs, Google TTS, Azure TTS, Fish Audio, Cartesia) + 4 STT providers (Whisper, Deepgram, Azure STT, Google STT) + 2 realtime APIs (OpenAI Realtime, Gemini Live).                                                                                                                                                                          | [TTS Guide](docs/features/tts.md) \| [STT Guide](docs/features/audio-input.md) \| [Realtime Guide](docs/features/real-time-services.md) |
 | **4 New Providers**                          | v9.60.0 | DeepSeek (V3/R1), NVIDIA NIM (400+ catalog), LM Studio (local), llama.cpp (GGUF local).                                                                                                                                                                                                                                                                                       | [Provider Setup](docs/getting-started/provider-setup.md)                                                                                |
 | **ModelAccessDeniedError**                   | v9.59.0 | Typed `ModelAccessDeniedError` + `sdk.checkCredentials()` API for proactive credential validation before first call.                                                                                                                                                                                                                                                          | [Error Reference](docs/reference/troubleshooting.md)                                                                                    |
 | **Provider Fallback Policy**                 | v9.58.0 | `providerFallback` callback + `modelChain` config for centralized multi-provider fallback logic.                                                                                                                                                                                                                                                                              | [Advanced Guide](docs/advanced/index.md)                                                                                                |
@@ -71,7 +71,7 @@ const result = await neurolink.generate({
     voice: "en-US-Neural2-C",
     format: "mp3",
     output: "./output.mp3", // optional: save to disk
-    provider: "elevenlabs", // optional override: openai-tts | elevenlabs | google-ai | vertex | azure-tts
+    provider: "elevenlabs", // optional override: openai-tts | elevenlabs | google-ai | vertex | azure-tts | fish-audio | cartesia
   },
 });
 // result.audio: { buffer: Buffer, format: "mp3", ... }
@@ -955,16 +955,16 @@ Full command and API breakdown lives in [`docs/cli/commands.md`](docs/cli/comman
 
 ## Platform Capabilities at a Glance
 
-| Capability               | Highlights                                                                                                               |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| **Provider unification** | 21+ providers with automatic fallback, cost-aware routing, `providerFallback` policy, `modelChain` config.               |
-| **Multimodal pipeline**  | Stream images + CSV data + PDF documents across providers with local/remote assets. Auto-detection for mixed file types. |
-| **Voice pipeline**       | TTS (4 providers) + STT (4 providers) + realtime voice APIs (OpenAI Realtime, Gemini Live).                              |
-| **Quality & governance** | Auto-evaluation engine (14 scorers), guardrails middleware, HITL workflows, audit logging.                               |
-| **Memory & context**     | Per-user condensed memory (S3/Redis/SQLite), Redis session export, 4-stage context compaction.                           |
-| **CLI tooling**          | Loop sessions, setup wizard, config validation, Redis auto-detect, JSON output, TTS/STT flags.                           |
-| **Enterprise ops**       | Claude proxy, OTLP observability, OpenObserve dashboard, regional routing, credential management.                        |
-| **Tool ecosystem**       | MCP auto discovery, HTTP/stdio/SSE/WebSocket transports, LiteLLM hub access, SageMaker custom deployment, web search.    |
+| Capability               | Highlights                                                                                                                                           |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Provider unification** | 21+ providers with automatic fallback, cost-aware routing, `providerFallback` policy, `modelChain` config.                                           |
+| **Multimodal pipeline**  | Stream images + CSV data + PDF documents across providers with local/remote assets. Auto-detection for mixed file types.                             |
+| **Voice pipeline**       | TTS (6 providers: Google, OpenAI, ElevenLabs, Azure, Fish Audio, Cartesia) + STT (4 providers) + realtime voice APIs (OpenAI Realtime, Gemini Live). |
+| **Quality & governance** | Auto-evaluation engine (14 scorers), guardrails middleware, HITL workflows, audit logging.                                                           |
+| **Memory & context**     | Per-user condensed memory (S3/Redis/SQLite), Redis session export, 4-stage context compaction.                                                       |
+| **CLI tooling**          | Loop sessions, setup wizard, config validation, Redis auto-detect, JSON output, TTS/STT flags.                                                       |
+| **Enterprise ops**       | Claude proxy, OTLP observability, OpenObserve dashboard, regional routing, credential management.                                                    |
+| **Tool ecosystem**       | MCP auto discovery, HTTP/stdio/SSE/WebSocket transports, LiteLLM hub access, SageMaker custom deployment, web search.                                |
 
 ## Documentation Map
 

docs-site/scripts/sync-docs.ts

@@ -1364,6 +1364,7 @@ const LINK_MAPPINGS: Record<string, string> = {
   "elevenlabs-music": "/getting-started/providers/elevenlabs-music",
   kling: "/getting-started/providers/kling",
   runway: "/getting-started/providers/runway",
+  cartesia: "/getting-started/providers/cartesia",
 
   // ── New provider-integration guides + their cross-refs ────────────────
   "00-architecture": "/provider-integration/00-architecture",