diff --git a/@omniroute/opencode-provider/README.md b/@omniroute/opencode-provider/README.md
index 624fddbb6e..c69669619a 100644
--- a/@omniroute/opencode-provider/README.md
+++ b/@omniroute/opencode-provider/README.md
@@ -1,5 +1,23 @@
 # @omniroute/opencode-provider
 
+> ## ⚠️ Deprecated — use [`@omniroute/opencode-plugin`](https://www.npmjs.com/package/@omniroute/opencode-plugin) instead
+>
+> This package writes a **static** `provider.omniroute` block to `opencode.json` from a hardcoded default model list, so it **drifts behind your live OmniRoute catalog** — adding a model in OmniRoute won't show up in OpenCode until you re-run the generator, and OpenCode Desktop/Web only surfaces a subset of the static models.
+>
+> **`@omniroute/opencode-plugin`** solves this by fetching `GET /v1/models` from your OmniRoute instance at OpenCode startup, so the model list is always live (see [#3419](https://github.com/diegosouzapw/OmniRoute/issues/3419)). It is now the recommended path.
+>
+> **One-line migration** — replace the static `provider.omniroute` block in `opencode.json` with a single plugin entry:
+>
+> ```jsonc
+> // opencode.json
+> {
+>   "$schema": "https://opencode.ai/config.json",
+>   "plugin": ["@omniroute/opencode-plugin"]
+> }
+> ```
+>
+> This package is **not removed** and still works for static/offline config generation, but it is no longer actively recommended and won't track new models automatically.
+
 Helper for connecting [OpenCode](https://opencode.ai) to a running [OmniRoute](https://github.com/diegosouzapw/OmniRoute) AI gateway.
 
 The package emits a **schema-valid entry** for `opencode.json` (`https://opencode.ai/config.json`) that delegates the actual runtime to [`@ai-sdk/openai-compatible`](https://www.npmjs.com/package/@ai-sdk/openai-compatible). It does not ship any new HTTP client — OmniRoute already exposes an OpenAI-compatible surface, and OpenCode already speaks it through the AI SDK.
diff --git a/@omniroute/opencode-provider/package.json b/@omniroute/opencode-provider/package.json
index 62aafc4b5a..572643a6d5 100644
--- a/@omniroute/opencode-provider/package.json
+++ b/@omniroute/opencode-provider/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@omniroute/opencode-provider",
   "version": "0.1.0",
-  "description": "OpenCode provider helper for the OmniRoute AI Gateway. Generates a schema-valid provider entry for opencode.json that delegates the runtime to @ai-sdk/openai-compatible.",
+  "description": "DEPRECATED — use @omniroute/opencode-plugin instead (it fetches the live OmniRoute /v1/models catalog at startup, so models never drift). This static-config generator still works but is no longer the recommended path. OpenCode provider helper for the OmniRoute AI Gateway.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
diff --git a/@omniroute/opencode-provider/tests/index.test.ts b/@omniroute/opencode-provider/tests/index.test.ts
index aac6e7a27b..ae3c11c45b 100644
--- a/@omniroute/opencode-provider/tests/index.test.ts
+++ b/@omniroute/opencode-provider/tests/index.test.ts
@@ -2,6 +2,9 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { createServer } from "node:http";
 import type { Server } from "node:http";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 
 import {
   buildOmniRouteOpenCodeConfig,
@@ -667,3 +670,17 @@ test("createOmniRouteModesBlock honours numeric overrides limited to OC schema",
   assert.equal(block.build.temperature, 0.7);
   assert.equal(block.build.top_p, 0.9);
 });
+
+// #3419 — soft-deprecation in favour of @omniroute/opencode-plugin. Guard the
+// deprecation notice so it can't be silently dropped while the package is kept
+// publishing (it still works; it is just no longer the recommended path).
+test("package is marked deprecated in favour of @omniroute/opencode-plugin (#3419)", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+  assert.match(pkg.description, /DEPRECATED/);
+  assert.match(pkg.description, /@omniroute\/opencode-plugin/);
+
+  const readme = readFileSync(join(here, "..", "README.md"), "utf8");
+  assert.match(readme, /Deprecated/i);
+  assert.match(readme, /@omniroute\/opencode-plugin/);
+});
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 96692064ac..7def6c3718 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
 ### ♻️ Code Quality
 
 - **refactor(chatCore):** extract the chatCore request phases — idempotency check, semantic cache check, common request sanitization, and memory/skills injection — into dedicated `open-sse/handlers/chatCore/` modules (`idempotency.ts`, `semanticCache.ts`, `sanitization.ts`, `memorySkillsInjection.ts`), slimming the monolithic handler with no behavior change. (Maintainer follow-up: re-derive `idempotencyKey` at the Phase 9.2 save site after the check moved into the module, fixing a `ReferenceError` on successful non-cached responses.) ([#3598](https://github.com/diegosouzapw/OmniRoute/pull/3598) — thanks @oyi77)
+- **docs(opencode-provider):** soft-deprecate `@omniroute/opencode-provider` in favour of `@omniroute/opencode-plugin`. The provider package writes a **static** model list to `opencode.json` that drifts behind the live OmniRoute catalog, whereas the plugin fetches `/v1/models` at OpenCode startup. The package keeps working (no code/behavior change), but its npm description and README now carry a deprecation banner with the one-line migration, and a guard test pins the notice. ([#3419](https://github.com/diegosouzapw/OmniRoute/issues/3419) — thanks @herjarsa)
 
 ### 🔧 Bug Fixes