From a7c375532725cd135b0735b96f5f9fbc2dd1e4bb Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Tue, 28 Apr 2026 22:35:51 -0700
Subject: [PATCH] docs(plugin-sdk): mark compatibility facades deprecated

---
 src/plugin-sdk/channel-config-schema-legacy.ts | 2 +-
 src/plugin-sdk/discord.ts                      | 4 ++++
 src/plugin-sdk/telegram-account.ts             | 8 ++++++++
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/plugin-sdk/channel-config-schema-legacy.ts b/src/plugin-sdk/channel-config-schema-legacy.ts
index 890e4e491f7..a09fadd3bf6 100644
--- a/src/plugin-sdk/channel-config-schema-legacy.ts
+++ b/src/plugin-sdk/channel-config-schema-legacy.ts
@@ -1,5 +1,5 @@
 /**
- * Deprecated bundled-channel compatibility surface.
+ * @deprecated Compatibility surface for bundled channel schemas.
  *
  * OpenClaw-maintained bundled plugins should import
  * openclaw/plugin-sdk/bundled-channel-config-schema. Third-party plugins should
diff --git a/src/plugin-sdk/discord.ts b/src/plugin-sdk/discord.ts
index 7cb368f90ac..ed3c5d7c83e 100644
--- a/src/plugin-sdk/discord.ts
+++ b/src/plugin-sdk/discord.ts
@@ -12,6 +12,10 @@ import {
 } from "./facade-loader.js";
 import { getRuntimeConfig, getRuntimeConfigSnapshot } from "./runtime-config-snapshot.js";
 
+/**
+ * @deprecated Compatibility facade for the `openclaw/plugin-sdk/discord` subpath.
+ * New channel plugins should use generic channel SDK subpaths.
+ */
 export type { ChannelMessageActionAdapter, ChannelMessageActionName } from "./channel-contract.js";
 export type { ChannelPlugin } from "./channel-core.js";
 export type { OpenClawConfig } from "./config-types.js";
diff --git a/src/plugin-sdk/telegram-account.ts b/src/plugin-sdk/telegram-account.ts
index 341e487daa3..aee0d84ccf7 100644
--- a/src/plugin-sdk/telegram-account.ts
+++ b/src/plugin-sdk/telegram-account.ts
@@ -1,10 +1,18 @@
 import type { OpenClawConfig } from "./config-types.js";
 import { loadBundledPluginPublicSurfaceModuleSync } from "./facade-loader.js";
 
+/**
+ * @deprecated Compatibility type for the `openclaw/plugin-sdk/telegram-account` facade.
+ * New channel plugins should prefer injected runtime helpers and generic SDK subpaths.
+ */
 export type TelegramAccountConfig = NonNullable<
   NonNullable<OpenClawConfig["channels"]>["telegram"]
 >;
 
+/**
+ * @deprecated Compatibility type for the `openclaw/plugin-sdk/telegram-account` facade.
+ * New channel plugins should prefer injected runtime helpers and generic SDK subpaths.
+ */
 export type ResolvedTelegramAccount = {
   accountId: string;
   enabled: boolean;