deprecation(#59): mark ImageProvider, ImageProviderConfig, IMAGE_MODELS as @deprecated

CHANGELOG.md

@@ -3,6 +3,11 @@
 All notable changes to `@stackbilt/llm-providers` are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/). Versions use [Semantic Versioning](https://semver.org/).
 
+## [1.6.2] — 2026-05-07
+
+### Deprecated
+- **`ImageProvider`, `ImageProviderConfig`, `IMAGE_MODELS`** — marked `@deprecated`. img-forge is the org's canonical image generation service; `ImageProvider` is a frozen snapshot of img-forge internals and will not track new models or providers. Use the img-forge API or MCP tools for image generation. Exports are retained for backward compatibility and will be removed in the next major version. `normalizeAiResponse` is not yet deprecated (under audit).
+
 ## [1.6.1] — 2026-05-06
 
 ### Added

README.md

@@ -16,11 +16,17 @@ A multi-provider LLM abstraction layer with automatic failover, graduated circui
 - **Provider-agnostic cache hints** -- `LLMRequest.cache` translates to provider-native caching (Anthropic `cache_control` breakpoints; automatic on OpenAI/Groq/Cerebras); cached token counts normalized into `TokenUsage`
 - **Schema drift detection** -- envelope validation on every provider response; streaming frames validated per-chunk; `SchemaDriftError` routes through fallback chain and fires `onSchemaDrift` hook
 - **Schema canary** -- `runCanaryCheck` / `extractShape` / `compareShapes` for comparing live response shapes against committed golden fixtures
-- **Image generation** -- Cloudflare Workers AI (SDXL, FLUX) and Google Gemini
+- **Image generation** -- `ImageProvider` is deprecated; use [img-forge](https://github.com/Stackbilt-dev/img-forge) instead
 - **Health monitoring** -- per-provider health checks, metrics, and circuit breaker state
 - **Structured logging** -- injectable `Logger` interface; silent by default, opt-in to console or custom loggers
 - **Zero runtime dependencies** -- no transitive dependency tree to audit
 
+## Deprecated APIs
+
+**`ImageProvider` is deprecated.** It was extracted from img-forge during an earlier phase when llm-providers and img-forge were more tightly coupled. img-forge is now the dedicated imagegen service with a full quality-tier registry, async orchestration, and quota metering. Use the [img-forge API](https://github.com/Stackbilt-dev/img-forge) or MCP tools for image generation. llm-providers handles text inference and vision understanding only.
+
+`ImageProvider`, `ImageProviderConfig`, and `IMAGE_MODELS` will be removed in the next major version. The `normalizeAiResponse` utility is under audit and may be retained as a standalone export.
+
 ## Installation
 
 ```bash
@@ -409,7 +415,7 @@ fs.writeFileSync('fixtures/openai.json', JSON.stringify(shape, null, 2));
 | `CreditLedger` | Monthly budgets, rate limits, burn rate projection, threshold events |
 | `CostOptimizer` | Static methods for optimal provider selection |
 | `MODEL_CATALOG` | Declarative model metadata for routing and recommendation |
-| `ImageProvider` | Multi-provider image generation (Cloudflare SDXL/FLUX, Google Gemini) |
+| `ImageProvider` | **[Deprecated]** Multi-provider image generation — use [img-forge](https://github.com/Stackbilt-dev/img-forge) instead |
 | `extractShape` | Walk a raw API response into a flat `path → type` shape map |
 | `compareShapes` | Diff two shape maps into `{ added, removed, changed }` |
 | `runCanaryCheck` | One-shot canary: extract live shape, compare against golden, return `CanaryReport` |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbilt/llm-providers",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "Multi-LLM failover with circuit breakers, cost tracking, and intelligent retry. Cloudflare Workers native.",
   "author": "Stackbilt <admin@stackbilt.dev>",
   "license": "Apache-2.0",

src/image/provider.ts

@@ -7,11 +7,19 @@
  *   - Google Gemini (Flash Image, Flash Image Preview)
  *
  * Extracted from img-forge production codebase. Battle-tested.
+ *
+ * @deprecated Use the img-forge service or the img-forge MCP tools instead.
+ * ImageProvider is a frozen snapshot of img-forge's internals and will not
+ * track new models or providers. For image generation from within a Worker,
+ * call the img-forge gateway via fetch or the GATEWAY service binding.
  */
 
 import type { ImageRequest, ImageResponse, ImageModelConfig } from './types.js';
 import { IMAGE_MODELS, getImageModel } from './types.js';
 
+/**
+ * @deprecated Use img-forge instead. See ImageProvider deprecation notice.
+ */
 export interface ImageProviderConfig {
   /** Cloudflare Workers AI binding (env.AI) */
   cloudflareAi?: unknown;
@@ -23,6 +31,12 @@ export interface ImageProviderConfig {
   models?: Record<string, ImageModelConfig>;
 }
 
+/**
+ * @deprecated Use the img-forge service or the img-forge MCP tools instead.
+ * ImageProvider is a frozen snapshot of img-forge's internals and will not
+ * track new models or providers. For image generation from within a Worker,
+ * call the img-forge gateway via fetch or the GATEWAY service binding.
+ */
 export class ImageProvider {
   private cloudflareAi: unknown;
   private geminiApiKey: string | null;

src/image/types.ts

@@ -44,6 +44,8 @@ export interface ImageResponse {
 /**
  * Built-in image model registry.
  * Quality tiers map to specific provider + model combinations.
+ *
+ * @deprecated Use img-forge instead. See ImageProvider deprecation notice.
  */
 export const IMAGE_MODELS: Record<string, ImageModelConfig> = {
   // Cloudflare Workers AI — fast, included in free tier