diff --git a/packages/core/src/shared/context.ts b/packages/core/src/shared/context.ts
index 533317488..9c06919ff 100644
--- a/packages/core/src/shared/context.ts
+++ b/packages/core/src/shared/context.ts
@@ -180,8 +180,18 @@ export type BaseContext = {
     };
 
     /**
-     * Extension slot. Adapters and middleware populate keys here; handlers cast to the
-     * extension's declared type to read them. Core never reads or writes this field.
+     * Extension slot (SEP-2133 mechanism). Dispatch middleware registered via
+     * `use()` populates keys here under the extension's reverse-DNS
+     * namespace; handlers read via the extension's typed accessor (e.g.
+     * `taskContext(ctx)` for `tasksPlugin`). Core never reads or writes this field.
+     *
+     * @example
+     * ```ts
+     * // In a DispatchMiddleware:
+     * env.ext = { ...env.ext, 'io.modelcontextprotocol/task': { id, store } };
+     * // In a handler:
+     * const task = taskContext(ctx); // typed read of ctx.ext['io.modelcontextprotocol/task']
+     * ```
      */
     ext?: Record<string, unknown>;
 };