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

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`
 

packages/cli/src/services/BuiltinCommandLoader.test.ts

@@ -73,7 +73,17 @@ vi.mock('../ui/commands/agentsCommand.js', () => ({
 }));
 vi.mock('../ui/commands/bugCommand.js', () => ({ bugCommand: {} }));
 vi.mock('../ui/commands/chatCommand.js', () => ({
-  chatCommand: { name: 'chat', subCommands: [] },
+  chatCommand: {
+    name: 'chat',
+    subCommands: [
+      { name: 'list' },
+      { name: 'save' },
+      { name: 'resume' },
+      { name: 'delete' },
+      { name: 'share' },
+      { name: 'checkpoints', hidden: true, subCommands: [{ name: 'list' }] },
+    ],
+  },
   debugCommand: { name: 'debug' },
 }));
 vi.mock('../ui/commands/clearCommand.js', () => ({ clearCommand: {} }));
@@ -94,7 +104,19 @@ vi.mock('../ui/commands/modelCommand.js', () => ({
 }));
 vi.mock('../ui/commands/privacyCommand.js', () => ({ privacyCommand: {} }));
 vi.mock('../ui/commands/quitCommand.js', () => ({ quitCommand: {} }));
-vi.mock('../ui/commands/resumeCommand.js', () => ({ resumeCommand: {} }));
+vi.mock('../ui/commands/resumeCommand.js', () => ({
+  resumeCommand: {
+    name: 'resume',
+    subCommands: [
+      { name: 'list' },
+      { name: 'save' },
+      { name: 'resume' },
+      { name: 'delete' },
+      { name: 'share' },
+      { name: 'checkpoints', hidden: true, subCommands: [{ name: 'list' }] },
+    ],
+  },
+}));
 vi.mock('../ui/commands/statsCommand.js', () => ({ statsCommand: {} }));
 vi.mock('../ui/commands/themeCommand.js', () => ({ themeCommand: {} }));
 vi.mock('../ui/commands/toolsCommand.js', () => ({ toolsCommand: {} }));
@@ -256,7 +278,7 @@ describe('BuiltinCommandLoader', () => {
   });
 
   describe('chat debug command', () => {
-    it('should NOT add debug subcommand to chatCommand if not a nightly build', async () => {
+    it('should NOT add debug subcommand to chat/resume commands if not a nightly build', async () => {
       vi.mocked(isNightly).mockResolvedValue(false);
       const loader = new BuiltinCommandLoader(mockConfig);
       const commands = await loader.loadCommands(new AbortController().signal);
@@ -265,9 +287,30 @@ describe('BuiltinCommandLoader', () => {
       expect(chatCmd?.subCommands).toBeDefined();
       const hasDebug = chatCmd!.subCommands!.some((c) => c.name === 'debug');
       expect(hasDebug).toBe(false);
+
+      const resumeCmd = commands.find((c) => c.name === 'resume');
+      const resumeHasDebug =
+        resumeCmd?.subCommands?.some((c) => c.name === 'debug') ?? false;
+      expect(resumeHasDebug).toBe(false);
+
+      const chatCheckpointsCmd = chatCmd?.subCommands?.find(
+        (c) => c.name === 'checkpoints',
+      );
+      const chatCheckpointHasDebug =
+        chatCheckpointsCmd?.subCommands?.some((c) => c.name === 'debug') ??
+        false;
+      expect(chatCheckpointHasDebug).toBe(false);
+
+      const resumeCheckpointsCmd = resumeCmd?.subCommands?.find(
+        (c) => c.name === 'checkpoints',
+      );
+      const resumeCheckpointHasDebug =
+        resumeCheckpointsCmd?.subCommands?.some((c) => c.name === 'debug') ??
+        false;
+      expect(resumeCheckpointHasDebug).toBe(false);
     });
 
-    it('should add debug subcommand to chatCommand if it is a nightly build', async () => {
+    it('should add debug subcommand to chat/resume commands if it is a nightly build', async () => {
       vi.mocked(isNightly).mockResolvedValue(true);
       const loader = new BuiltinCommandLoader(mockConfig);
       const commands = await loader.loadCommands(new AbortController().signal);
@@ -276,6 +319,27 @@ describe('BuiltinCommandLoader', () => {
       expect(chatCmd?.subCommands).toBeDefined();
       const hasDebug = chatCmd!.subCommands!.some((c) => c.name === 'debug');
       expect(hasDebug).toBe(true);
+
+      const resumeCmd = commands.find((c) => c.name === 'resume');
+      const resumeHasDebug =
+        resumeCmd?.subCommands?.some((c) => c.name === 'debug') ?? false;
+      expect(resumeHasDebug).toBe(true);
+
+      const chatCheckpointsCmd = chatCmd?.subCommands?.find(
+        (c) => c.name === 'checkpoints',
+      );
+      const chatCheckpointHasDebug =
+        chatCheckpointsCmd?.subCommands?.some((c) => c.name === 'debug') ??
+        false;
+      expect(chatCheckpointHasDebug).toBe(true);
+
+      const resumeCheckpointsCmd = resumeCmd?.subCommands?.find(
+        (c) => c.name === 'checkpoints',
+      );
+      const resumeCheckpointHasDebug =
+        resumeCheckpointsCmd?.subCommands?.some((c) => c.name === 'debug') ??
+        false;
+      expect(resumeCheckpointHasDebug).toBe(true);
     });
   });
 });

packages/cli/src/services/BuiltinCommandLoader.ts

@@ -78,6 +78,41 @@ export class BuiltinCommandLoader implements ICommandLoader {
     const handle = startupProfiler.start('load_builtin_commands');
 
     const isNightlyBuild = await isNightly(process.cwd());
+    const addDebugToChatResumeSubCommands = (
+      subCommands: SlashCommand[] | undefined,
+    ): SlashCommand[] | undefined => {
+      if (!subCommands) {
+        return subCommands;
+      }
+
+      const withNestedCompatibility = subCommands.map((subCommand) => {
+        if (subCommand.name !== 'checkpoints') {
+          return subCommand;
+        }
+
+        return {
+          ...subCommand,
+          subCommands: addDebugToChatResumeSubCommands(subCommand.subCommands),
+        };
+      });
+
+      if (!isNightlyBuild) {
+        return withNestedCompatibility;
+      }
+
+      return withNestedCompatibility.some(
+        (cmd) => cmd.name === debugCommand.name,
+      )
+        ? withNestedCompatibility
+        : [
+            ...withNestedCompatibility,
+            { ...debugCommand, suggestionGroup: 'checkpoints' },
+          ];
+    };
+
+    const chatResumeSubCommands = addDebugToChatResumeSubCommands(
+      chatCommand.subCommands,
+    );
 
     const allDefinitions: Array<SlashCommand | null> = [
       aboutCommand,
@@ -86,9 +121,7 @@ export class BuiltinCommandLoader implements ICommandLoader {
       bugCommand,
       {
         ...chatCommand,
-        subCommands: isNightlyBuild
-          ? [...(chatCommand.subCommands || []), debugCommand]
-          : chatCommand.subCommands,
+        subCommands: chatResumeSubCommands,
       },
       clearCommand,
       commandsCommand,
@@ -155,7 +188,10 @@ export class BuiltinCommandLoader implements ICommandLoader {
       ...(isDevelopment ? [profileCommand] : []),
       quitCommand,
       restoreCommand(this.config),
-      resumeCommand,
+      {
+        ...resumeCommand,
+        subCommands: addDebugToChatResumeSubCommands(resumeCommand.subCommands),
+      },
       statsCommand,
       themeCommand,
       toolsCommand,

packages/cli/src/ui/commands/chatCommand.test.ts

@@ -99,8 +99,11 @@ describe('chatCommand', () => {
 
   it('should have the correct main command definition', () => {
     expect(chatCommand.name).toBe('chat');
-    expect(chatCommand.description).toBe('Manage conversation history');
-    expect(chatCommand.subCommands).toHaveLength(5);
+    expect(chatCommand.description).toBe(
+      'Browse auto-saved conversations and manage chat checkpoints',
+    );
+    expect(chatCommand.autoExecute).toBe(true);
+    expect(chatCommand.subCommands).toHaveLength(6);
   });
 
   describe('list subcommand', () => {
@@ -158,7 +161,7 @@ describe('chatCommand', () => {
       expect(result).toEqual({
         type: 'message',
         messageType: 'error',
-        content: 'Missing tag. Usage: /chat save <tag>',
+        content: 'Missing tag. Usage: /resume save <tag>',
       });
     });
 
@@ -252,7 +255,7 @@ describe('chatCommand', () => {
       expect(result).toEqual({
         type: 'message',
         messageType: 'error',
-        content: 'Missing tag. Usage: /chat resume <tag>',
+        content: 'Missing tag. Usage: /resume resume <tag>',
       });
     });
 
@@ -386,7 +389,7 @@ describe('chatCommand', () => {
       expect(result).toEqual({
         type: 'message',
         messageType: 'error',
-        content: 'Missing tag. Usage: /chat delete <tag>',
+        content: 'Missing tag. Usage: /resume delete <tag>',
       });
     });