Reference docs from doc comments

Author: agu-z

docs/protocol/schema.mdx

@@ -1020,6 +1020,11 @@ An environment variable to set when launching an MCP server.
 
 Request parameters for extension method calls.
 
+Used with the `_method` extension point to add custom request-response functionality
+to the protocol while maintaining compatibility.
+
+See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
+
 **Type:** Object
 
 **Properties:**
@@ -1039,9 +1044,18 @@ methods with a unique identifier such as domain name.
 
 Response from extension method calls.
 
+Contains the result of a custom extension method request.
+
+See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
+
 ## <span class="font-mono">ExtNotification</span>
 
-Extension notification parameters
+Extension notification parameters.
+
+Used with the `_notification` extension point to add custom one-way messages
+to the protocol while maintaining compatibility.
+
+See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
 
 **Type:** Object
 

rust/agent.rs

@@ -118,18 +118,24 @@ pub trait Agent {
     /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)
     fn cancel(&self, args: CancelNotification) -> impl Future<Output = Result<(), Error>>;
 
-    /// Extension method
+    /// Handles extension method requests from the client.
     ///
-    /// Allows the Client to send an arbitrary request that is not part of the ACP spec.
+    /// Extension methods provide a way to add custom functionality while maintaining
+    /// protocol compatibility.
+    ///
+    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
     fn ext_method(
         &self,
         method: Arc<str>,
         params: serde_json::Value,
     ) -> impl Future<Output = Result<serde_json::Value, Error>>;
 
-    /// Extension notification
+    /// Handles extension notifications from the client.
+    ///
+    /// Extension notifications provide a way to send one-way messages for custom functionality
+    /// while maintaining protocol compatibility.
     ///
-    /// Allows the Client to send an arbitrary notification that is not part of the ACP spec.
+    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
     fn ext_notification(
         &self,
         method: Arc<str>,

rust/client.rs

@@ -124,18 +124,26 @@ pub trait Client {
     #[cfg(feature = "unstable")]
     fn kill_terminal(&self, args: KillTerminalRequest) -> impl Future<Output = Result<(), Error>>;
 
-    /// Extension method
+    /// Handles extension method requests from the agent.
     ///
     /// Allows the Agent to send an arbitrary request that is not part of the ACP spec.
+    /// Extension methods provide a way to add custom functionality while maintaining
+    /// protocol compatibility.
+    ///
+    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
     fn ext_method(
         &self,
         method: Arc<str>,
         params: serde_json::Value,
     ) -> impl Future<Output = Result<serde_json::Value, Error>>;
 
-    /// Extension notification
+    /// Handles extension notifications from the agent.
+    ///
+    /// Allows the Agent to send an arbitrary notification that is not part of the ACP spec.
+    /// Extension notifications provide a way to send one-way messages for custom functionality
+    /// while maintaining protocol compatibility.
     ///
-    /// Allows the Agent to send an arbitrary notifiation that is not part of the ACP spec.
+    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
     fn ext_notification(
         &self,
         method: Arc<str>,

rust/ext.rs

@@ -10,6 +10,11 @@ pub const EXT_METHOD_NAME: &str = "_method";
 pub const EXT_NOTIFICATION_NAME: &str = "_notification";
 
 /// Request parameters for extension method calls.
+///
+/// Used with the `_method` extension point to add custom request-response functionality
+/// to the protocol while maintaining compatibility.
+///
+/// See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[schemars(extend("x-method" = "_method"))]
 #[serde(rename_all = "camelCase")]
@@ -24,12 +29,21 @@ pub struct ExtMethodRequest {
 }
 
 /// Response from extension method calls.
+///
+/// Contains the result of a custom extension method request.
+///
+/// See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[schemars(extend("x-method" = "_method"))]
 #[serde(transparent)]
 pub struct ExtMethodResponse(pub serde_json::Value);
 
-/// Extension notification parameters
+/// Extension notification parameters.
+///
+/// Used with the `_notification` extension point to add custom one-way messages
+/// to the protocol while maintaining compatibility.
+///
+/// See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[schemars(extend("x-method" = "_notification"))]
 #[serde(rename_all = "camelCase")]

schema/schema.json

@@ -672,7 +672,7 @@
       "type": "object"
     },
     "ExtMethodRequest": {
-      "description": "Request parameters for extension method calls.",
+      "description": "Request parameters for extension method calls.\n\nUsed with the `_method` extension point to add custom request-response functionality\nto the protocol while maintaining compatibility.\n\nSee protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)",
       "properties": {
         "method": {
           "description": "The identifier for the extension method.\n\nTo help avoid conflicts, it's a good practice to prefix extension\nmethods with a unique identifier such as domain name.",
@@ -687,11 +687,11 @@
       "x-method": "_method"
     },
     "ExtMethodResponse": {
-      "description": "Response from extension method calls.",
+      "description": "Response from extension method calls.\n\nContains the result of a custom extension method request.\n\nSee protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)",
       "x-method": "_method"
     },
     "ExtNotification": {
-      "description": "Extension notification parameters",
+      "description": "Extension notification parameters.\n\nUsed with the `_notification` extension point to add custom one-way messages\nto the protocol while maintaining compatibility.\n\nSee protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)",
       "properties": {
         "method": {
           "description": "The identifier for the extension method.\n\nTo help avoid conflicts, it's a good practice to prefix extension\nmethods with a unique identifier such as domain name.",

typescript/schema.ts

@@ -720,6 +720,11 @@ export interface KillTerminalRequest {
 }
 /**
  * Request parameters for extension method calls.
+ *
+ * Used with the `_method` extension point to add custom request-response functionality
+ * to the protocol while maintaining compatibility.
+ *
+ * See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
  */
 export interface ExtMethodRequest {
   /**
@@ -815,6 +820,10 @@ export interface WaitForTerminalExitResponse {
 }
 /**
  * Response from extension method calls.
+ *
+ * Contains the result of a custom extension method request.
+ *
+ * See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
  */
 export interface ExtMethodResponse {
   [k: string]: unknown;
@@ -851,7 +860,12 @@ export interface CancelNotification {
   sessionId: string;
 }
 /**
- * Extension notification parameters
+ * Extension notification parameters.
+ *
+ * Used with the `_notification` extension point to add custom one-way messages
+ * to the protocol while maintaining compatibility.
+ *
+ * See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
  */
 export interface ExtNotification {
   /**
@@ -1114,6 +1128,11 @@ export interface PromptRequest {
 }
 /**
  * Request parameters for extension method calls.
+ *
+ * Used with the `_method` extension point to add custom request-response functionality
+ * to the protocol while maintaining compatibility.
+ *
+ * See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
  */
 export interface ExtMethodRequest1 {
   /**
@@ -1357,6 +1376,10 @@ export interface PromptResponse {
 }
 /**
  * Response from extension method calls.
+ *
+ * Contains the result of a custom extension method request.
+ *
+ * See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
  */
 export interface ExtMethodResponse1 {
   [k: string]: unknown;
@@ -1583,7 +1606,12 @@ export interface UnstructuredCommandInput {
   hint: string;
 }
 /**
- * Extension notification parameters
+ * Extension notification parameters.
+ *
+ * Used with the `_notification` extension point to add custom one-way messages
+ * to the protocol while maintaining compatibility.
+ *
+ * See protocol docs: [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods)
  */
 export interface ExtNotification1 {
   /**