docs: reconcile stable and draft protocol pages (#2541)

* docs: reconcile stable and draft protocol pages and check them in CI

The stable and draft copies of each protocol page had drifted:
clarifications for stable features existed only in the draft, and some
stable text was missing from the draft.

Reconciled (v1 and v2):
- Backported to stable: the tool `name` description, the auth-flow and
  notice bullets in the overviews, the notice and compaction fallback
  sentences, the terminal-auth initialize example, the model_config
  context_size example, v1 session-setup notes, and the v1 file-system
  roots note.
- Forwarded to draft: the v1 Conventions section and Message IDs
  heading, the v2 extension-capabilities sentence, and the current
  cancellation wording.
- Fixed v2 links to initialization#prompt-capabilities, which is
  #session-prompt-capabilities.

scripts/check_draft_docs.py compares each pair after normalizing link
prefixes, wrapping and table padding, and checks the remaining
differences against a committed baseline in scripts/draft-differences/.
It runs in npm run check and CI.

* docs: drop the draft docs CI check, keep the reconciliation

Author: benbrandt

AGENTS.md

@@ -33,6 +33,7 @@ All paths in the protocol should be absolute
 ## Updating existing methods, their params, or output
 
 - Update the mintlify docs and guides in the `docs` directory
+- Make the same change in both the stable page and its `draft/` copy, unless the change is draft-only
 - Run `npm run check` to make sure the json and zod schemas gets generated properly
 
 Never write readme files related to the conversation unless explicitly asked to.

docs/protocol/v1/draft/cancellation.mdx

@@ -11,7 +11,7 @@ The JSON-RPC specification doesn't define any standard mechanism for request can
 
 In order to provide a consistent approach to cancellation, ACP defines a `$/cancel_request` notification that can be sent to cancel requests.
 
-Cancellation will remain optional as it might not be implementable in all clients or servers. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a `$/cancel_request` notification.
+Cancellation remains optional as it might not be implementable in all clients or servers. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a `$/cancel_request` notification.
 
 When a `$/cancel_request` notification is received by a supporting implementation, the implementation:
 
@@ -23,7 +23,7 @@ When a `$/cancel_request` notification is received by a supporting implementatio
 
 The calling side **MAY** implement graceful cancellation processing by waiting for the response from the remote side.
 
-Cancellation **MAY** also be done explicitly on a per-feature basis within the protocol to cover specific scenarios (e.g., cancellation of a [prompt turn](/protocol/v1/draft/prompt-turn#cancellation))
+Cancellation **MAY** also be done explicitly on a per-feature basis within the protocol to cover specific scenarios, such as cancellation of a [prompt turn](/protocol/v1/draft/prompt-turn#cancellation).
 
 ## Internal Cancellation
 

docs/protocol/v1/draft/overview.mdx

@@ -240,6 +240,10 @@ All methods follow standard JSON-RPC 2.0 [error handling](https://www.jsonrpc.or
 
 See [Errors](/protocol/v1/draft/error) for the error codes ACP uses and when to use them.
 
+## Conventions
+
+Unless explicitly defined otherwise in the schema, ACP-defined JSON object property keys use `camelCase`. String values carried by discriminator fields use `snake_case`. The JSON-RPC envelope fields (`jsonrpc`, `id`, `method`, `params`, `result`, and `error`) follow the JSON-RPC 2.0 specification.
+
 ## Extensibility
 
 The protocol provides built-in mechanisms for adding custom functionality while maintaining compatibility:

docs/protocol/v1/draft/prompt-turn.mdx

@@ -261,6 +261,8 @@ The Agent then reports text responses from the model:
 }
 ```
 
+#### Message IDs
+
 The Agent **MAY** include an opaque, unique `messageId` on message chunks. Chunks with the same `messageId` belong to the same message; a changed `messageId` indicates a new message.
 
 If the model requested tool calls, these are also reported immediately:

docs/protocol/v1/draft/session-setup.mdx

@@ -136,15 +136,16 @@ To load an existing session, Clients **MUST** call the `session/load` method wit
 The Agent **MUST** replay the entire conversation to the Client in the form of
 `session/update` notifications (like `session/prompt`).
 
-- [Session compactions](/protocol/v1/draft/prompt-turn#session-compaction) are
-  replayed using the same update, chunk, and patch semantics as live delivery.
-  The Client's `session.compaction` capability is required for replay as well as
-  live delivery.
-- Live-only [notices](/protocol/v1/draft/prompt-turn#session-notices) are not
-  conversation history and **SHOULD NOT** be replayed. If the underlying
-  condition is still relevant after loading finishes, the Agent may emit a new
-  notice as a new live event, subject to the Client's `session.notices`
-  capability.
+[Session compactions](/protocol/v1/draft/prompt-turn#session-compaction) are
+replayed using the same update, chunk, and patch semantics as live delivery.
+The Client's `session.compaction` capability is required for replay as well as
+live delivery.
+
+Live-only [notices](/protocol/v1/draft/prompt-turn#session-notices) are not
+conversation history and **SHOULD NOT** be replayed. If the underlying
+condition is still relevant after loading finishes, the Agent may emit a new
+notice as a new live event, subject to the Client's `session.notices`
+capability.
 
 For example, a user message from the conversation history:
 

docs/protocol/v1/file-system.mdx

@@ -47,7 +47,8 @@ The `fs/read_text_file` method allows Agents to read text file contents from the
 ```
 
 <ParamField path="sessionId" type="SessionId" required>
-  The [Session ID](/protocol/v1/session-setup#session-id) for this request
+  The [Session ID](/protocol/v1/session-setup#session-id) for this request. The
+  session determines which filesystem roots are in scope for the path.
 </ParamField>
 
 <ParamField path="path" type="string" required>
@@ -92,7 +93,8 @@ The `fs/write_text_file` method allows Agents to write or update text files in t
 ```
 
 <ParamField path="sessionId" type="SessionId" required>
-  The [Session ID](/protocol/v1/session-setup#session-id) for this request
+  The [Session ID](/protocol/v1/session-setup#session-id) for this request. The
+  session determines which filesystem roots are in scope for the path.
 </ParamField>
 
 <ParamField path="path" type="string" required>

docs/protocol/v1/initialization.mdx

@@ -36,6 +36,9 @@ They **SHOULD** also provide a name and version to the Agent.
   "params": {
     "protocolVersion": 1,
     "clientCapabilities": {
+      "auth": {
+        "terminal": true
+      },
       "fs": {
         "readTextFile": true,
         "writeTextFile": true

docs/protocol/v1/overview.mdx

@@ -20,7 +20,9 @@ A typical flow follows this pattern:
 <Step title="Initialization Phase">
 
 - Client → Agent: `initialize` to establish connection
-- Client → Agent: `authenticate` if required by the Agent
+- Client: completes an advertised authentication flow if required; for example,
+  `authenticate` for an Agent-handled method or launch and reconnect for a
+  terminal method
 
 </Step>
 
@@ -33,7 +35,7 @@ A typical flow follows this pattern:
 
 <Step title="Prompt Turn">
    - Client → Agent: `session/prompt` to send user message
-   - Agent → Client: `session/update` notifications for progress updates
+   - Agent → Client: `session/update` notifications for progress updates and user-facing notices
    - Agent → Client: File operations or permission requests as needed
    - Client → Agent: `session/cancel` to interrupt processing if needed
    - Turn ends and the Agent sends the `session/prompt` response with a stop reason

docs/protocol/v1/session-config-options.mdx

@@ -3,7 +3,7 @@ title: "Session Config Options"
 description: "Flexible configuration selectors for agent sessions"
 ---
 
-Agents can provide an arbitrary list of configuration options for a session, allowing Clients to offer users customizable selectors for things like models, modes, reasoning levels, and more.
+Agents can provide an arbitrary list of configuration options for a session, allowing Clients to offer users customizable selectors for things like models, model parameters, modes, reasoning levels, and more.
 
 <Info>
   Session Config Options are the preferred way to expose session-level
@@ -61,6 +61,23 @@ During [Session Setup](/protocol/v1/session-setup) the Agent **MAY** return a li
             "description": "The most powerful model"
           }
         ]
+      },
+      {
+        "id": "context_size",
+        "name": "Context Size",
+        "category": "model_config",
+        "type": "select",
+        "currentValue": "200k",
+        "options": [
+          {
+            "value": "200k",
+            "name": "200K"
+          },
+          {
+            "value": "1m",
+            "name": "1M"
+          }
+        ]
       }
     ]
   }
@@ -327,6 +344,23 @@ The Agent **MUST** respond with the complete list of all configuration options a
             "description": "The most powerful model"
           }
         ]
+      },
+      {
+        "id": "context_size",
+        "name": "Context Size",
+        "category": "model_config",
+        "type": "select",
+        "currentValue": "200k",
+        "options": [
+          {
+            "value": "200k",
+            "name": "200K"
+          },
+          {
+            "value": "1m",
+            "name": "1M"
+          }
+        ]
       }
     ]
   }
@@ -391,6 +425,23 @@ The Agent can also change configuration options and notify the Client by sending
               "description": "The most powerful model"
             }
           ]
+        },
+        {
+          "id": "context_size",
+          "name": "Context Size",
+          "category": "model_config",
+          "type": "select",
+          "currentValue": "200k",
+          "options": [
+            {
+              "value": "200k",
+              "name": "200K"
+            },
+            {
+              "value": "1m",
+              "name": "1M"
+            }
+          ]
         }
       ]
     }

docs/protocol/v1/session-setup.mdx

@@ -7,6 +7,8 @@ Sessions represent a specific conversation or thread between the [Client](/proto
 
 Before creating a session, Clients **MUST** first complete the [initialization](/protocol/v1/initialization) phase to establish protocol compatibility and capabilities.
 
+If the Agent requires authentication, `session/new` may fail with an `auth_required` error until the Client completes the [authentication flow](/protocol/v1/authentication).
+
 <br />
 
 ```mermaid
@@ -82,7 +84,7 @@ The Agent **MUST** respond with a unique [Session ID](#session-id) that identifi
 
 ## Loading Sessions
 
-Agents that support the `loadSession` capability allow Clients to resume previous conversations. This feature enables persistence across restarts and sharing sessions between different Client instances.
+Agents that support the `loadSession` capability allow Clients to resume previous conversations with history replay. This feature enables persistence across restarts and sharing sessions between different Client instances.
 
 ### Checking Support
 
@@ -196,6 +198,8 @@ When **all** the conversation entries have been streamed to the Client, the Agen
 }
 ```
 
+The response **MAY** also include initial mode, model, or session configuration state when those features are supported by the Agent.
+
 The Client can then continue sending prompts as if the session was never interrupted.
 
 ## Resuming Sessions