Improve docs

Author: agu-z

docs/docs.json

@@ -59,7 +59,7 @@
           "protocol/terminals",
           "protocol/agent-plan",
           "protocol/session-modes",
-          "protocol/commands",
+          "protocol/slash-commands",
           "protocol/extensibility",
           "protocol/schema"
         ]

docs/protocol/overview.mdx

@@ -84,6 +84,14 @@ Agents are programs that use generative AI to autonomously modify code. They typ
   `loadSession` capability).
 </ResponseField>
 
+<ResponseField
+  name="session/set_mode"
+  post={[<a href="./schema#session%2Fset-mode">Schema</a>]}
+>
+  [Switch between agent operating
+  modes](./session-modes#setting-the-current-mode).
+</ResponseField>
+
 ### Notifications
 
 <ResponseField
@@ -167,8 +175,12 @@ Clients provide the interface between users and agents. They are typically code
   name="session/update"
   post={[<a href="./schema#session%2Fupdate">Schema</a>]}
 >
-  [Send progress updates](./prompt-turn#3-agent-reports-output) during prompt
-  processing (no response expected).
+  [Send session updates](./prompt-turn#3-agent-reports-output) to inform the
+  Client of changes (no response expected). This includes: - [Message
+  chunks](./content) (agent, user, thought) - [Tool calls and
+  updates](./tool-calls) - [Plans](./agent-plan) - [Available commands
+  updates](./slash-commands#advertising-commands) - [Mode
+  changes](./session-modes#from-the-agent)
 </ResponseField>
 
 ## Argument requirements

docs/protocol/schema.mdx

@@ -1108,7 +1108,7 @@ All text that was typed after the command name is provided as input.
 <Expandable title="Properties">
 
 <ResponseField name="hint" type={"string"} required>
-  A brief description of the expected input
+  A hint to display when the input hasn't been provided yet
 </ResponseField>
 
 </Expandable>

docs/protocol/commands.mdx docs/protocol/slash-commands.mdxdocs/protocol/commands.mdx renamed to docs/protocol/slash-commands.mdx

@@ -1,9 +1,9 @@
 ---
-title: "Commands"
+title: "Slash Commands"
 description: "Advertise available slash commands to clients"
 ---
 
-Agents can advertise a set of slash commands that users can invoke. These commands provide quick access to specific agent capabilities and workflows.
+Agents can advertise a set of slash commands that users can invoke. These commands provide quick access to specific agent capabilities and workflows. Commands are run as part of regular [prompt](./prompt-turn) requests where the Client includes the command text in the prompt.
 
 ## Advertising commands
 
@@ -65,31 +65,16 @@ After creating a session, the Agent **MAY** send a list of available commands vi
 Currently supports unstructured text input:
 
 <ResponseField name="hint" type="string" required>
-  A brief description of the expected input
+  A hint to display when the input hasn't been provided yet
 </ResponseField>
 
-## Command lifecycle
-
-1. **Discovery**: The Agent sends available commands after session creation
-2. **Display**: The Client displays these commands in its UI (e.g., in a slash command menu)
-3. **Invocation**: When the user selects a command, the Client includes it in the prompt
-4. **Execution**: The Agent processes the command as part of the prompt
-
-Commands are not a separate protocol mechanism - they are simply a way for the Agent to advertise what slash commands it understands. The actual command invocation happens through the regular prompt mechanism.
-
 ## Dynamic updates
 
-The Agent can update the list of available commands at any time during a session by sending another `available_commands_update` notification. This allows commands to be:
+The Agent can update the list of available commands at any time during a session by sending another `available_commands_update` notification. This allows commands to be added based on context, removed when no longer relevant, or modified with updated descriptions.
 
-- Added based on context (e.g., project type detection)
-- Removed when no longer relevant
-- Modified with updated descriptions or input hints
+## Running commands
 
-Clients may also add their own local commands (e.g., authentication commands) to the list before displaying them to users.
-
-## Example usage
-
-When a user types `/web climate change` in the Client, it would send:
+Commands are included as regular user messages in prompt requests:
 
 ```json
 {
@@ -98,12 +83,14 @@ When a user types `/web climate change` in the Client, it would send:
   "method": "session/prompt",
   "params": {
     "sessionId": "sess_abc123def456",
-    "prompt": {
-      "type": "text",
-      "text": "/web climate change"
-    }
+    "prompt": [
+      {
+        "type": "text",
+        "text": "/web agent client protocol"
+      }
+    ]
   }
 }
 ```
 
-The Agent recognizes the command prefix and processes it accordingly, potentially using web search tools to gather information about climate change.
+The Agent recognizes the command prefix and processes it accordingly. Commands may be accompanied by any other user message content types (images, audio, etc.) in the same prompt array.

rust/client.rs

@@ -247,7 +247,7 @@ pub enum AvailableCommandInput {
     /// All text that was typed after the command name is provided as input.
     #[schemars(rename = "UnstructuredCommandInput")]
     Unstructured {
-        /// A brief description of the expected input
+        /// A hint to display when the input hasn't been provided yet
         hint: String,
     },
 }

schema/schema.json

@@ -254,7 +254,7 @@
           "description": "All text that was typed after the command name is provided as input.",
           "properties": {
             "hint": {
-              "description": "A brief description of the expected input",
+              "description": "A hint to display when the input hasn't been provided yet",
               "type": "string"
             }
           },

typescript/schema.ts

@@ -1598,7 +1598,7 @@ export interface AvailableCommand {
  */
 export interface UnstructuredCommandInput {
   /**
-   * A brief description of the expected input
+   * A hint to display when the input hasn't been provided yet
    */
   hint: string;
 }