docs: move detailed usage to separate page

- Move detailed usage instructions from getting-started to new usage.rst
- Make getting-started more concise and focused
- Add documentation for resume feature (-r flag)
- Update index to include new usage page

docs/examples.rst

@@ -38,6 +38,9 @@ To see example output without running the commands yourself, check out the :doc:
     gptme 'make a change' - 'test it' - 'commit it'
     gptme 'show me something cool in the python repl' - 'something cooler' - 'something even cooler'
 
+    # resume the last conversation
+    gptme -r
+
 Do you have a cool example? Share it with us in the `Discussions <https://github.com/ErikBjare/gptme/discussions>`_!
 
 .. toctree::

docs/getting-started.rst

@@ -1,12 +1,12 @@
 Getting Started
 ===============
 
-This guide will assist you in beginning your journey with gptme.
+This guide will help you get started with gptme.
 
 Installation
 ------------
 
-To install gptme, we recommend using pipx:
+To install gptme, we recommend using ``pipx``:
 
 .. code-block:: bash
 
@@ -25,74 +25,25 @@ If pipx is not installed, you can install it using pip:
 Usage
 -----
 
-To initiate a new chat or select an existing one, execute:
+To start your first chat, simply run:
 
 .. code-block:: bash
 
     gptme
 
-This will show you a list of past chats, allowing you to select one or start a new one.
+It will then start an interactive chat session where you can talk with the AI assistant.
 
-.. rubric:: Writing a file
+If you haven't set a :doc:`LLM provider <providers>` API key in the environment or :doc:`configuration <config>`, you will be prompted for one which will be saved in the configuration file.
 
-You can then interact with the assistant. Lets start by asking it to write code.
+For detailed usage instructions and examples, see :doc:`usage`.
 
-.. chat::
+Next Steps
+----------
 
-   User: create a new file named life.py implementing the game of life
-
-   Assistant: Certainly! I'll create a new file named `life.py` implementing Conway's Game of Life. This implementation will use NumPy for efficient array operations and Matplotlib for visualization. Here's the code:
-   ```life.py
-   import numpy as np
-   import matplotlib.pyplot as plt
-   from matplotlib.animation import FuncAnimation
-   ...
-   ```
-
-   System: Saved to life.py
-
-The assistant will prompt for your confirmation and save the file, as requested.
-
-.. rubric:: Making changes
-
-We can also start chats and request changes directly from the command line. The contents of any mentioned text files will be included as context, and the assistant will generate patches to apply the requested changes:
-
-.. code-block:: bash
-
-   gptme 'make improvements to life.py so that dead cells fade out over time'
-
-.. chat::
-
-   User: make improvements to life.py so that dead cells fade out over time
-   ```life.py
-   ...
-   ```
-
-   Assistant: To make alive cells green and dead cells black in the Game of Life simulation, we need to modify the colormap and how we represent the cell states. Here's the updated `life.py` script with these changes:
-   ```patch life.py
-   ...
-   ```
-
-   System: Patch applied
-
-.. note::
-    With the :ref:`tools:browser` extras installed, the assistant can also process URLs included in the prompt.
-
-More tools
-**********
-
-You can read about all the other tools on the :doc:`tools` page.
-
-Including :ref:`tools:shell`, :ref:`tools:python`, how to set up :ref:`tools:browser`, and use :ref:`tools:vision`.
-
-Interfaces
-**********
-
-There are several ways to interact with gptme:
-
-- :doc:`CLI <cli>`
-- :ref:`server:web ui`
-- :doc:`bot`
+- Read the :doc:`usage` guide for detailed usage instructions and examples
+- Learn about available :doc:`tools`
+- Explore different :doc:`providers`
+- Set up the :doc:`server` for web access
 
 Support
 -------

docs/index.rst

@@ -19,6 +19,7 @@ See the `README <https://github.com/ErikBjare/gptme/blob/master/README.md>`_ fil
    :caption: User Guide
 
    getting-started
+   usage
    examples
    tools
    config

docs/usage.rst

@@ -0,0 +1,104 @@
+Usage
+=====
+
+This guide covers common usage patterns and examples for gptme.
+
+To start a new chat or select an existing one, run:
+
+.. code-block:: bash
+
+    gptme
+
+This will show you a list of past chats, allowing you to select one or start a new one.
+
+To get inspiration for your first prompt, see the :doc:`examples`.
+
+Features
+--------
+
+.. rubric:: Tools
+
+gptme comes with a variety of tools for different tasks:
+
+- :ref:`tools:shell` - Execute shell commands
+- :ref:`tools:python` - Run Python code
+- :ref:`tools:browser` - Browse and interact with web content
+- :ref:`tools:vision` - Process and analyze images
+
+See the :doc:`tools` page for a complete list of available tools.
+
+.. rubric:: Writing Files
+
+You can ask the assistant to create new files or modify existing ones:
+
+.. chat::
+
+   User: create a new file named life.py implementing the game of life
+
+   Assistant: Certainly! I'll create a new file named `life.py` implementing Conway's Game of Life. This implementation will use NumPy for efficient array operations and Matplotlib for visualization. Here's the code:
+   ```life.py
+   import numpy as np
+   import matplotlib.pyplot as plt
+   from matplotlib.animation import FuncAnimation
+   ...
+   ```
+
+   System: Saved to life.py
+
+.. rubric:: Making Changes
+
+You can start chats and request changes directly from the command line. The contents of any mentioned text files will be included as context, and the assistant will generate patches to apply the requested changes:
+
+.. code-block:: bash
+
+   gptme 'make improvements to life.py so that dead cells fade out over time'
+
+.. chat::
+
+   User: make improvements to life.py so that dead cells fade out over time
+   ```life.py
+   ...
+   ```
+
+   Assistant: To make alive cells green and dead cells black in the Game of Life simulation, we need to modify the colormap and how we represent the cell states. Here's the updated `life.py` script with these changes:
+   ```patch life.py
+   ...
+   ```
+
+   System: Patch applied
+
+.. rubric:: Browser Integration
+
+With the :ref:`tools:browser` extras installed, the assistant can process URLs included in the prompt and interact with web content.
+
+Commands
+--------
+
+.. TODO: use autodoc from source, like cli reference
+
+During a chat session, you can use these slash-commands for various actions:
+
+- ``/undo`` - Undo the last action
+- ``/log`` - Show the conversation log
+- ``/tools`` - Show available tools
+- ``/edit`` - Edit the conversation in your editor
+- ``/rename`` - Rename the conversation
+- ``/fork`` - Create a copy of the conversation
+- ``/summarize`` - Summarize the conversation
+- ``/replay`` - Re-execute codeblocks in the conversation
+- ``/help`` - Show help message
+- ``/exit`` - Exit the program
+
+Interfaces
+----------
+
+Besides the CLI, gptme can be used through:
+
+- :ref:`server:web ui` - A web-based interface
+- :doc:`bot` - GitHub bot integration
+
+For more detailed information about specific features, check out:
+
+- :doc:`tools` - Available tools and their usage
+- :doc:`providers` - Supported LLM providers
+- :doc:`server` - Web UI and API server setup