docs(schema): put the text-content Markdown rule on the content page (#2562)

Author: benbrandt

agent-client-protocol-schema/src/v2/content.rs

@@ -89,7 +89,8 @@ pub enum ContentBlock {
     /// Text content. May be plain text or formatted with Markdown.
     ///
     /// All agents MUST support text content blocks in prompts.
-    /// Clients SHOULD render this text as Markdown.
+    /// Clients SHOULD render this text as CommonMark and MAY support GitHub Flavored Markdown
+    /// extensions.
     Text(TextContent),
     /// Images for visual context or analysis.
     ///

clippy.toml

@@ -4,3 +4,4 @@ allowed-duplicate-crates = [
     "schemars",
     "syn",
 ]
+doc-valid-idents = ["CommonMark", ".."]

docs/protocol/v1/content.mdx

@@ -19,7 +19,7 @@ ACP's `ContentBlock` is compatible with, and a superset of, the [Model Context P
 
 ### Text Content
 
-Plain text messages form the foundation of most interactions.
+Text may be plain text or Markdown. Clients **SHOULD** render it as Markdown. See [Rendering Agent Content](/protocol/v1/security#rendering-agent-content) for raw HTML.
 
 ```json
 {

docs/protocol/v1/draft/content.mdx

@@ -19,7 +19,7 @@ ACP's `ContentBlock` is compatible with, and a superset of, the [Model Context P
 
 ### Text Content
 
-Plain text messages form the foundation of most interactions.
+Text may be plain text or Markdown. Clients **SHOULD** render it as Markdown. See [Rendering Agent Content](/protocol/v1/draft/security#rendering-agent-content) for raw HTML.
 
 ```json
 {

docs/protocol/v2/content.mdx

@@ -23,7 +23,7 @@ Content block `type` values can be custom or future variants when the receiver c
 
 ### Text Content
 
-Plain text messages form the foundation of most interactions.
+Text may be plain text or Markdown. Clients **SHOULD** render it as [CommonMark](https://spec.commonmark.org/), and **MAY** support [GitHub Flavored Markdown](https://github.github.com/gfm/) extensions such as tables. This applies wherever a text block appears, including user messages, thoughts, and tool-call content. See [Rendering Agent Content](/protocol/v2/security#rendering-agent-content) for raw HTML.
 
 ```json
 {

docs/protocol/v2/draft/content.mdx

@@ -23,7 +23,7 @@ Content block `type` values can be custom or future variants when the receiver c
 
 ### Text Content
 
-Plain text messages form the foundation of most interactions.
+Text may be plain text or Markdown. Clients **SHOULD** render it as [CommonMark](https://spec.commonmark.org/), and **MAY** support [GitHub Flavored Markdown](https://github.github.com/gfm/) extensions such as tables. This applies wherever a text block appears, including user messages, thoughts, and tool-call content. See [Rendering Agent Content](/protocol/v2/draft/security#rendering-agent-content) for raw HTML.
 
 ```json
 {

docs/protocol/v2/draft/schema.mdx

@@ -2737,7 +2737,8 @@ See protocol docs: [Content](https://agentclientprotocol.com/protocol/v2/draft/c
 Text content. May be plain text or formatted with Markdown.
 
 All agents MUST support text content blocks in prompts.
-Clients SHOULD render this text as Markdown.
+Clients SHOULD render this text as CommonMark and MAY support GitHub Flavored Markdown
+extensions.
 
 <Expandable title="Properties">
 

docs/protocol/v2/schema.mdx

@@ -2272,7 +2272,8 @@ See protocol docs: [Content](https://agentclientprotocol.com/protocol/v2/content
 Text content. May be plain text or formatted with Markdown.
 
 All agents MUST support text content blocks in prompts.
-Clients SHOULD render this text as Markdown.
+Clients SHOULD render this text as CommonMark and MAY support GitHub Flavored Markdown
+extensions.
 
 <Expandable title="Properties">
 

schema/v2/schema.json

@@ -966,7 +966,7 @@
       "description": "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output reported through `session/update` notifications as\n  message updates or streamed chunks\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/v2/content)",
       "anyOf": [
         {
-          "description": "Text content. May be plain text or formatted with Markdown.\n\nAll agents MUST support text content blocks in prompts.\nClients SHOULD render this text as Markdown.",
+          "description": "Text content. May be plain text or formatted with Markdown.\n\nAll agents MUST support text content blocks in prompts.\nClients SHOULD render this text as CommonMark and MAY support GitHub Flavored Markdown\nextensions.",
           "type": "object",
           "properties": {
             "type": {

schema/v2/schema.unstable.json

@@ -1020,7 +1020,7 @@
       "description": "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output reported through `session/update` notifications as\n  message updates or streamed chunks\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/v2/draft/content)",
       "anyOf": [
         {
-          "description": "Text content. May be plain text or formatted with Markdown.\n\nAll agents MUST support text content blocks in prompts.\nClients SHOULD render this text as Markdown.",
+          "description": "Text content. May be plain text or formatted with Markdown.\n\nAll agents MUST support text content blocks in prompts.\nClients SHOULD render this text as CommonMark and MAY support GitHub Flavored Markdown\nextensions.",
           "type": "object",
           "properties": {
             "type": {