diff --git a/extensions/diffs/src/tool.ts b/extensions/diffs/src/tool.ts
index fad94e6b864..8c1e40b528c 100644
--- a/extensions/diffs/src/tool.ts
+++ b/extensions/diffs/src/tool.ts
@@ -96,10 +96,13 @@ const DiffsToolSchema = Type.Object(
         maximum: 2400,
       }),
     ),
+    /** @deprecated Use fileQuality. */
     imageQuality: Type.Optional(
       stringEnum(DIFF_IMAGE_QUALITY_PRESETS, "Deprecated alias for fileQuality."),
     ),
+    /** @deprecated Use fileFormat. */
     imageFormat: Type.Optional(stringEnum(DIFF_OUTPUT_FORMATS, "Deprecated alias for fileFormat.")),
+    /** @deprecated Use fileScale. */
     imageScale: Type.Optional(
       Type.Number({
         description: "Deprecated alias for fileScale.",
@@ -107,6 +110,7 @@ const DiffsToolSchema = Type.Object(
         maximum: 4,
       }),
     ),
+    /** @deprecated Use fileMaxWidth. */
     imageMaxWidth: Type.Optional(
       Type.Number({
         description: "Deprecated alias for fileMaxWidth.",
diff --git a/extensions/matrix/src/types.ts b/extensions/matrix/src/types.ts
index 97296c239fa..b5b234ea6dd 100644
--- a/extensions/matrix/src/types.ts
+++ b/extensions/matrix/src/types.ts
@@ -193,7 +193,7 @@ export type MatrixConfig = {
   execApprovals?: MatrixExecApprovalConfig;
   /** Room config allowlist keyed by room ID or alias (names resolved to IDs when possible). */
   groups?: Record<string, MatrixRoomConfig>;
-  /** Room config allowlist keyed by room ID or alias. Legacy; use groups. */
+  /** @deprecated Use groups. */
   rooms?: Record<string, MatrixRoomConfig>;
   /** Per-action tool gating (default: true for all). */
   actions?: MatrixActionConfig;
diff --git a/extensions/qqbot/src/config-schema.ts b/extensions/qqbot/src/config-schema.ts
index 416fccbcaf2..28f7553b6b7 100644
--- a/extensions/qqbot/src/config-schema.ts
+++ b/extensions/qqbot/src/config-schema.ts
@@ -32,7 +32,7 @@ const QQBotStreamingSchema = z
       .object({
         /** "partial" (default) enables block streaming; "off" disables it. */
         mode: z.enum(["off", "partial"]).default("partial"),
-        /** Use QQ C2C official stream_messages API; legacy, prefer `streaming: true`. */
+        /** @deprecated Prefer `streaming: true`. */
         c2cStreamApi: z.boolean().optional(),
       })
       .passthrough(),
diff --git a/extensions/qqbot/src/engine/api/media-chunked.ts b/extensions/qqbot/src/engine/api/media-chunked.ts
index 9237fa162fa..1708d573f33 100644
--- a/extensions/qqbot/src/engine/api/media-chunked.ts
+++ b/extensions/qqbot/src/engine/api/media-chunked.ts
@@ -412,6 +412,8 @@ export class ChunkedMediaApi {
 // ============ Legacy functional facade ============
 
 /**
+ * @deprecated The chunked uploader is always implemented.
+ *
  * Legacy feature flag. The chunked uploader is fully implemented, so this
  * returns `true`. Retained so that older call sites can be converted
  * progressively.
diff --git a/extensions/qqbot/src/types.ts b/extensions/qqbot/src/types.ts
index 9263073d267..75e0f1b7367 100644
--- a/extensions/qqbot/src/types.ts
+++ b/extensions/qqbot/src/types.ts
@@ -113,6 +113,7 @@ export interface QQBotAccountConfig {
     | boolean
     | {
         mode?: "off" | "partial";
+        /** @deprecated Prefer `streaming: true`. */
         c2cStreamApi?: boolean;
       };
 }
diff --git a/extensions/voice-call/src/config.ts b/extensions/voice-call/src/config.ts
index f87187e3ed2..882ac46eaa5 100644
--- a/extensions/voice-call/src/config.ts
+++ b/extensions/voice-call/src/config.ts
@@ -351,7 +351,7 @@ export const VoiceCallConfigSchema = z
     /** Webhook server configuration */
     serve: VoiceCallServeConfigSchema,
 
-    /** Tailscale exposure configuration (legacy, prefer tunnel config) */
+    /** @deprecated Prefer tunnel config. */
     tailscale: VoiceCallTailscaleConfigSchema,
 
     /** Tunnel configuration (unified ngrok/tailscale) */
diff --git a/src/auto-reply/reply-payload.ts b/src/auto-reply/reply-payload.ts
index dbb34451e18..a2e2af3315d 100644
--- a/src/auto-reply/reply-payload.ts
+++ b/src/auto-reply/reply-payload.ts
@@ -16,7 +16,11 @@ export type ReplyPayload = {
   presentation?: MessagePresentation;
   /** Channel-agnostic delivery preferences, e.g. pin the sent message when supported. */
   delivery?: ReplyPayloadDelivery;
-  /** Internal legacy representation used by existing approval/reply helpers during migration. */
+  /**
+   * @deprecated Use presentation.
+   *
+   * Internal legacy representation used by existing approval/reply helpers during migration.
+   */
   interactive?: InteractiveReply;
   btw?: {
     question: string;
diff --git a/src/channels/plugins/types.core.ts b/src/channels/plugins/types.core.ts
index ccc59ed83cb..87050c36b7c 100644
--- a/src/channels/plugins/types.core.ts
+++ b/src/channels/plugins/types.core.ts
@@ -537,6 +537,8 @@ export type ChannelMessagingAdapter = {
     parentConversationCandidates?: string[];
   } | null;
   /**
+   * @deprecated Return parentConversationCandidates from resolveSessionConversation.
+   *
    * Legacy compatibility hook for parent fallbacks when a plugin does not need
    * to customize `id` or `threadId`. Core only uses this when
    * `resolveSessionConversation(...)` does not return
diff --git a/src/media/parse.ts b/src/media/parse.ts
index 8d832447bda..9d858f2e272 100644
--- a/src/media/parse.ts
+++ b/src/media/parse.ts
@@ -472,7 +472,8 @@ export function splitMediaFromOutput(
 ): {
   text: string;
   mediaUrls?: string[];
-  mediaUrl?: string; // legacy first item for backward compatibility
+  /** @deprecated Use mediaUrls[0]. */
+  mediaUrl?: string;
   audioAsVoice?: boolean; // true if [[audio_as_voice]] tag was found
   segments?: ParsedMediaOutputSegment[];
 } {
diff --git a/src/plugins/hook-before-agent-start.types.ts b/src/plugins/hook-before-agent-start.types.ts
index 34e5b8039b1..2878790d1ec 100644
--- a/src/plugins/hook-before-agent-start.types.ts
+++ b/src/plugins/hook-before-agent-start.types.ts
@@ -58,7 +58,11 @@ type AssertAllPluginPromptMutationResultFieldsListed =
 const assertAllPluginPromptMutationResultFieldsListed: AssertAllPluginPromptMutationResultFieldsListed = true;
 void assertAllPluginPromptMutationResultFieldsListed;
 
-// before_agent_start hook (legacy compatibility: combines both phases)
+/**
+ * @deprecated Use before_model_resolve and before_prompt_build.
+ *
+ * Legacy compatibility hook that combines both phases.
+ */
 export type PluginHookBeforeAgentStartEvent = {
   prompt: string;
   runId?: string;
@@ -66,9 +70,11 @@ export type PluginHookBeforeAgentStartEvent = {
   messages?: unknown[];
 };
 
+/** @deprecated Use before_model_resolve and before_prompt_build result types. */
 export type PluginHookBeforeAgentStartResult = PluginHookBeforePromptBuildResult &
   PluginHookBeforeModelResolveResult;
 
+/** @deprecated Use before_model_resolve override result types. */
 export type PluginHookBeforeAgentStartOverrideResult = Omit<
   PluginHookBeforeAgentStartResult,
   keyof PluginHookBeforePromptBuildResult
diff --git a/src/plugins/hook-types.ts b/src/plugins/hook-types.ts
index a661a07b8e5..7ef0e9c85d5 100644
--- a/src/plugins/hook-types.ts
+++ b/src/plugins/hook-types.ts
@@ -800,6 +800,7 @@ export type PluginHookHandlerMap = {
     event: PluginHookBeforePromptBuildEvent,
     ctx: PluginHookAgentContext,
   ) => Promise<PluginHookBeforePromptBuildResult | void> | PluginHookBeforePromptBuildResult | void;
+  /** @deprecated Use before_model_resolve and before_prompt_build. */
   before_agent_start: (
     event: PluginHookBeforeAgentStartEvent,
     ctx: PluginHookAgentContext,
diff --git a/src/plugins/hooks.ts b/src/plugins/hooks.ts
index d5e5b0ae6d2..4fb45c2db9f 100644
--- a/src/plugins/hooks.ts
+++ b/src/plugins/hooks.ts
@@ -723,6 +723,8 @@ export function createHookRunner(
   }
 
   /**
+   * @deprecated Use runBeforeModelResolve and runBeforePromptBuild.
+   *
    * Run before_agent_start hook.
    * Legacy compatibility hook that combines model resolve + prompt build phases.
    */