feat(cli): unify /chat and /resume command UX (#20256)

docs/cli/session-management.md

@@ -61,6 +61,15 @@ Browser**:
 /resume
 ```
 
+When typing `/resume` (or `/chat`) in slash completion, commands are grouped
+under titled separators:
+
+- `-- auto --` (session browser)
+  - `list` is selectable and opens the session browser
+- `-- checkpoints --` (manual tagged checkpoint commands)
+
+Unique prefixes such as `/resum` and `/cha` resolve to the same grouped menu.
+
 The Session Browser provides an interactive interface where you can perform the
 following actions:
 
@@ -72,6 +81,21 @@ following actions:
 - **Select:** Press **Enter** to resume the selected session.
 - **Esc:** Press **Esc** to exit the Session Browser.
 
+### Manual chat checkpoints
+
+For named branch points inside a session, use chat checkpoints:
+
+```text
+/resume save decision-point
+/resume list
+/resume resume decision-point
+```
+
+Compatibility aliases:
+
+- `/chat ...` works for the same commands.
+- `/resume checkpoints ...` also remains supported during migration.
+
 ## Managing sessions
 
 You can list and delete sessions to keep your history organized and manage disk

docs/cli/tutorials/session-management.md

@@ -89,9 +89,9 @@ Gemini gives you granular control over the undo process. You can choose to:
 Sometimes you want to try two different approaches to the same problem.
 
 1.  Start a session and get to a decision point.
-2.  Save the current state with `/chat save decision-point`.
+2.  Save the current state with `/resume save decision-point`.
 3.  Try your first approach.
-4.  Later, use `/chat resume decision-point` to fork the conversation back to
+4.  Later, use `/resume resume decision-point` to fork the conversation back to
     that moment and try a different approach.
 
 This creates a new branch of history without losing your original work.
@@ -101,5 +101,5 @@ This creates a new branch of history without losing your original work.
 - Learn about [Checkpointing](../../cli/checkpointing.md) to understand the
   underlying safety mechanism.
 - Explore [Task planning](task-planning.md) to keep complex sessions organized.
-- See the [Command reference](../../reference/commands.md) for all `/chat` and
-  `/resume` options.
+- See the [Command reference](../../reference/commands.md) for `/resume`
+  options, grouped checkpoint menus, and `/chat` compatibility aliases.

docs/reference/commands.md

@@ -28,24 +28,33 @@ Slash commands provide meta-level control over the CLI itself.
 
 ### `/chat`
 
-- **Description:** Save and resume conversation history for branching
-  conversation state interactively, or resuming a previous state from a later
-  session.
+- **Description:** Alias for `/resume`. Both commands now expose the same
+  session browser action and checkpoint subcommands.
+- **Menu layout when typing `/chat` (or `/resume`)**:
+  - `-- auto --`
+    - `list` (selecting this opens the auto-saved session browser)
+  - `-- checkpoints --`
+    - `list`, `save`, `resume`, `delete`, `share` (manual tagged checkpoints)
+  - **Note:** Unique prefixes (for example `/cha` or `/resum`) resolve to the
+    same grouped menu.
 - **Sub-commands:**
   - **`debug`**
     - **Description:** Export the most recent API request as a JSON payload.
   - **`delete <tag>`**
     - **Description:** Deletes a saved conversation checkpoint.
+    - **Equivalent:** `/resume delete <tag>`
   - **`list`**
-    - **Description:** Lists available tags for chat state resumption.
+    - **Description:** Lists available tags for manually saved checkpoints.
     - **Note:** This command only lists chats saved within the current project.
       Because chat history is project-scoped, chats saved in other project
       directories will not be displayed.
+    - **Equivalent:** `/resume list`
   - **`resume <tag>`**
     - **Description:** Resumes a conversation from a previous save.
     - **Note:** You can only resume chats that were saved within the current
       project. To resume a chat from a different project, you must run the
       Gemini CLI from that project's directory.
+    - **Equivalent:** `/resume resume <tag>`
   - **`save <tag>`**
     - **Description:** Saves the current conversation history. You must add a
       `<tag>` for identifying the conversation state.
@@ -60,10 +69,12 @@ Slash commands provide meta-level control over the CLI itself.
         conversation states. For automatic checkpoints created before file
         modifications, see the
         [Checkpointing documentation](../cli/checkpointing.md).
+      - **Equivalent:** `/resume save <tag>`
   - **`share [filename]`**
     - **Description** Writes the current conversation to a provided Markdown or
       JSON file. If no filename is provided, then the CLI will generate one.
     - **Usage** `/chat share file.md` or `/chat share file.json`.
+    - **Equivalent:** `/resume share [filename]`
 
 ### `/clear`
 
@@ -314,10 +325,13 @@ Slash commands provide meta-level control over the CLI itself.
 
 ### `/resume`
 
-- **Description:** Browse and resume previous conversation sessions. Opens an
-  interactive session browser where you can search, filter, and select from
-  automatically saved conversations.
+- **Description:** Browse and resume previous conversation sessions, and manage
+  manual chat checkpoints.
 - **Features:**
+  - **Auto sessions:** Run `/resume` to open the interactive session browser for
+    automatically saved conversations.
+  - **Chat checkpoints:** Use checkpoint subcommands directly (`/resume save`,
+    `/resume resume`, etc.).
   - **Management:** Delete unwanted sessions directly from the browser
   - **Resume:** Select any session to resume and continue the conversation
   - **Search:** Use `/` to search through conversation content across all
@@ -328,6 +342,23 @@ Slash commands provide meta-level control over the CLI itself.
 - **Note:** All conversations are automatically saved as you chat - no manual
   saving required. See [Session Management](../cli/session-management.md) for
   complete details.
+- **Alias:** `/chat` provides the same behavior and subcommands.
+- **Sub-commands:**
+  - **`list`**
+    - **Description:** Lists available tags for manual chat checkpoints.
+  - **`save <tag>`**
+    - **Description:** Saves the current conversation as a tagged checkpoint.
+  - **`resume <tag>`** (alias: `load`)
+    - **Description:** Loads a previously saved tagged checkpoint.
+  - **`delete <tag>`**
+    - **Description:** Deletes a tagged checkpoint.
+  - **`share [filename]`**
+    - **Description:** Exports the current conversation to Markdown or JSON.
+  - **`debug`**
+    - **Description:** Export the most recent API request as JSON payload
+      (nightly builds).
+  - **Compatibility alias:** `/resume checkpoints ...` is still accepted for the
+    same checkpoint commands.
 
 ### `/settings`