Update docs with updated info (#7714)

Co-authored-by: Robert Brennan <accounts@rbren.io>

docs/DOC_STYLE_GUIDE.md

@@ -32,6 +32,8 @@ For instructions or processes that need to be followed in a specific order, use
 
 Example:
   1. Step one: Do this.
+    - First this sub step.
+    - Then this sub step.
   2. Step two: Complete this action.
   3. Step three: Verify the result.
 
@@ -47,6 +49,14 @@ docker run -it \
     ...
 ```
 
+### Use of Note and Warning
+
+When adding a note or warning, use the built-in note and warning syntax.
+
+Example:
+:::note
+This section is for advanced users only.
+:::
 
 ### Referring to UI Elements
 

docs/modules/usage/cloud/openhands-cloud.md

@@ -4,9 +4,7 @@ OpenHands Cloud is the cloud hosted version of OpenHands by All Hands AI.
 
 ## Accessing OpenHands Cloud
 
-Currently, users are being admitted to access OpenHands Cloud in waves. To sign up,
-[join the waitlist](https://www.all-hands.dev/join-waitlist). Once you are approved, you will get an email with
-instructions on how to access it.
+OpenHands Cloud can be accessed at https://app.all-hands.dev/.
 
 ## Getting Started
 

docs/modules/usage/configuration-options.md

@@ -1,10 +1,8 @@
 # Configuration Options
 
-This guide details all configuration options available for OpenHands, helping you customize its behavior and integrate it with other services.
-
 :::note
-If you are running in [GUI Mode](https://docs.all-hands.dev/modules/usage/how-to/gui-mode), the settings available in the Settings UI will always
-take precedence.
+This page outlines all available configuration options for OpenHands, allowing you to customize its behavior and
+integrate it with other services. In GUI Mode, any settings applied through the Settings UI will take precedence.
 :::
 
 ## Core Configuration

docs/modules/usage/getting-started.mdx

@@ -3,109 +3,97 @@
 So you've [run OpenHands](./installation) and have
 [set up your LLM](./installation#setup). Now what?
 
-OpenHands can help you tackle a wide variety of engineering tasks. But the technology
-is still new, and we're a long way off from having agents that can take on large, complicated
-engineering tasks without any guidance. So it's important to get a feel for what the agent
-does well, and where it might need some help.
+OpenHands can assist with a range of engineering tasks. However, the technology is still new, and we’re far from having
+agents that can handle complex tasks independently. It’s important to understand what the agent does well and where it
+needs support.
 
 ## Hello World
 
-The first thing you might want to try is a simple "hello world" example.
-This can be more complicated than it sounds!
+Start with a simple "hello world" example. It might be trickier than it seems!
 
-Try prompting the agent with:
-> Please write a bash script hello.sh that prints "hello world!"
+Prompt the agent with:
+> Write a bash script hello.sh that prints "hello world!"
 
-You should see that the agent not only writes the script, it sets the correct
-permissions and runs the script to check the output.
+The agent will write the script, set the correct permissions, and run it to check the output.
 
 You can continue prompting the agent to refine your code. This is a great way to
 work with agents. Start simple, and iterate.
 
-> Please modify hello.sh so that it accepts a name as the first argument, but defaults to "world"
+> Modify hello.sh so that it accepts a name as the first argument, but defaults to "world"
 
-You can also work in any language you need, though the agent might need to spend some
-time setting up its environment!
+You can also use any language you need. The agent may need time to set up the environment.
 
 > Please convert hello.sh to a Ruby script, and run it
 
 ## Building From Scratch
 
-Agents do exceptionally well at "greenfield" tasks (tasks where they don't need
-any context about an existing codebase) and they can just start from scratch.
-
-It's best to start with a simple task, and then iterate on it. It's also best to be
-as specific as possible about what you want, what the tech stack should be, etc.
+Agents excel at "greenfield" tasks, where they don’t need context about existing code and
+they can start from scratch.
+Begin with a simple task and iterate from there. Be specific about what you want and the tech stack.
 
 For example, we might build a TODO app:
 
-> Please build a basic TODO list app in React. It should be frontend-only, and all state
-> should be kept in localStorage.
+> Build a frontend-only TODO app in React. All state should be stored in localStorage.
 
-We can keep iterating on the app once the skeleton is there:
+Once the basic structure is in place, continue refining:
 
-> Please allow adding an optional due date to every task.
+> Allow adding an optional due date to each task.
 
-Just like with normal development, it's good to commit and push your code frequently.
+Just like normal development, commit and push your code often.
 This way you can always revert back to an old state if the agent goes off track.
 You can ask the agent to commit and push for you:
 
-> Please commit the changes and push them to a new branch called "feature/due-dates"
-
+> Commit the changes and push them to a new branch called "feature/due-dates"
 
 ## Adding New Code
 
-OpenHands can also do a great job adding new code to an existing code base.
+OpenHands is great at adding new code to an existing codebase.
 
-For example, you can ask OpenHands to add a new GitHub action to your project
-which lints your code. OpenHands may take a peek at your codebase to see what language
-it should use and then drop a new file into `./github/workflows/lint.yml`.
+For instance, you can ask OpenHands to add a GitHub action that lints your code. It might check your codebase to
+determine the language, then create a new file in `./github/workflows/lint.yml`.
 
-> Please add a GitHub action that lints the code in this repository.
+> Add a GitHub action that lints the code in this repository.
 
-Some tasks might require a bit more context. While OpenHands can use `ls` and `grep`
-to search through your codebase, providing context up front allows it to move faster,
-and more accurately. And it'll cost you fewer tokens!
+Some tasks need more context. While OpenHands can use commands like ls and grep to search, providing context upfront
+speeds things up and reduces token usage.
 
-> Please modify ./backend/api/routes.js to add a new route that returns a list of all tasks.
+> Modify ./backend/api/routes.js to add a new route that returns a list of all tasks.
 
-> Please add a new React component that displays a list of Widgets to the ./frontend/components
-> directory. It should use the existing Widget component.
+> Add a new React component to the ./frontend/components directory to display a list of Widgets.
+> It should use the existing Widget component.
 
 ## Refactoring
 
-OpenHands does great at refactoring existing code, especially in small chunks.
-You probably don't want to try rearchitecting your whole codebase, but breaking up
-long files and functions, renaming variables, etc. tend to work very well.
+OpenHands does great at refactoring code in small chunks. Rather than rearchitecting the entire codebase,
+it's more effective to break up long files and functions or rename variables.
 
-> Please rename all the single-letter variables in ./app.go.
+> Rename all the single-letter variables in ./app.go.
 
-> Please break the function `build_and_deploy_widgets` into two functions, `build_widgets` and `deploy_widgets` in widget.php.
+> Split the `build_and_deploy_widgets` function into two functions, `build_widgets` and `deploy_widgets` in widget.php.
 
-> Please break ./api/routes.js into separate files for each route.
+> Break ./api/routes.js into separate files for each route.
 
 ## Bug Fixes
 
-OpenHands can also help you track down and fix bugs in your code. But as any
-developer knows, bug fixing can be extremely tricky, and often OpenHands will need more context.
-It helps if you've diagnosed the bug, but want OpenHands to figure out the logic.
+OpenHands can help track down and fix bugs, but bug fixing can be tricky and often requires more context.
+It’s helpful if you’ve already diagnosed the issue and just need OpenHands to handle the logic.
 
-> Currently the email field in the `/subscribe` endpoint is rejecting .io domains. Please fix this.
+> The email field in the `/subscribe` endpoint is rejecting .io domains. Fix this.
 
-> The `search_widgets` function in ./app.py is doing a case-sensitive search. Please make it case-insensitive.
+> The `search_widgets` function in ./app.py is doing a case-sensitive search. Make it case-insensitive.
 
-It often helps to do test-driven development when bug fixing with an agent.
-You can ask the agent to write a new test, and then iterate until it fixes the bug:
+For bug fixing, test-driven development can be really useful. You can ask the agent to write a new test and iterate
+until the bug is fixed:
 
-> The `hello` function crashes on the empty string. Please write a test that reproduces this bug, then fix the code so it passes.
+> The `hello` function crashes on the empty string. Write a test that reproduces this bug, then fix the code so it passes.
 
 ## More
 
-OpenHands is capable of helping out on just about any coding task but it takes some practice
-to get the most out of it. Remember to:
+OpenHands can assist with nearly any coding task, but it takes some practice to get the best results.
+Keep these tips in mind:
 * Keep your tasks small.
-* Be as specific as possible.
-* Provide as much context as possible.
+* Be specific.
+* Provide plenty of context.
 * Commit and push frequently.
 
 See [Prompting Best Practices](./prompting/prompting-best-practices) for more tips on how to get the most out of OpenHands.

docs/modules/usage/how-to/cli-mode.md

@@ -50,47 +50,3 @@ docker run -it \
 ```
 
 This command will start an interactive session in Docker where you can input tasks and receive responses from OpenHands.
-
-## Examples of CLI Commands and Expected Outputs
-
-Here are some examples of CLI commands and their expected outputs:
-
-### Example 1: Simple Task
-
-```bash
->> Write a Python script that prints "Hello, World!"
-```
-
-Expected Output:
-
-```bash
-🤖 Sure! Here is a Python script that prints "Hello, World!":
-
-❯ print("Hello, World!")
-```
-
-### Example 2: Bash Command
-
-```bash
->> Create a directory named "test_dir"
-```
-
-Expected Output:
-
-```bash
-🤖 Creating a directory named "test_dir":
-
-❯ mkdir test_dir
-```
-
-### Example 3: Error Handling
-
-```bash
->> Delete a non-existent file
-```
-
-Expected Output:
-
-```bash
-🤖 An error occurred. Please try again.
-```

docs/modules/usage/how-to/custom-sandbox-guide.md

@@ -1,5 +1,9 @@
 # Custom Sandbox
 
+:::note
+This guide is for users that would like to use their own custom Docker image for the runtime, e.g. with certain tools or programming languages pre-installed
+:::
+
 The sandbox is where the agent performs its tasks. Instead of running commands directly on your computer
 (which could be risky), the agent runs them inside a Docker container.
 

docs/modules/usage/how-to/github-action.md

@@ -1,6 +1,6 @@
 # Using the OpenHands GitHub Action
 
-This guide explains how to use the OpenHands GitHub Action, both within the OpenHands repository and in your own projects.
+This guide explains how to use the OpenHands GitHub Action in your own projects.
 
 ## Using the Action in the OpenHands Repository
 

docs/modules/usage/how-to/gui-mode.md

@@ -11,9 +11,10 @@ OpenHands provides a Graphical User Interface (GUI) mode for interacting with th
 
 ### Initial Setup
 
-1. Upon first launch, you'll see a settings page.
+1. Upon first launch, you'll see a settings popup.
 2. Select an `LLM Provider` and `LLM Model` from the dropdown menus. If the required model does not exist in the list,
-   toggle `Advanced` options and enter it with the correct prefix in the `Custom Model` text box.
+   select `see advanced settings`. Then toggle `Advanced` options and enter it with the correct prefix in the
+   `Custom Model` text box.
 3. Enter the corresponding `API Key` for your chosen provider.
 4. Click `Save Changes` to apply the settings.
 
@@ -32,7 +33,7 @@ OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if it
      - `repo` (Full control of private repositories)
    - **Fine-Grained Tokens**
      - All Repositories (You can select specific repositories, but this will impact what returns in repo search)
-     - Minimal Permissions ( Select **Meta Data = Read-only** read for search, **Pull Requests = Read and Write**, **Content = Read and Write** for branch creation)
+     - Minimal Permissions ( Select `Meta Data = Read-only` read for search, `Pull Requests = Read and Write` and `Content = Read and Write` for branch creation)
   2. **Enter Token in OpenHands**:
    - Click the Settings button (gear icon).
    - Navigate to the `GitHub Settings` section.

docs/modules/usage/installation.mdx

@@ -116,8 +116,6 @@ We use SemVer so `0.9` will automatically point to the latest `0.9.x` release, a
 - For the most up-to-date development version, replace $VERSION in `openhands:$VERSION` and `runtime:$VERSION`, with `main`.
 This version is unstable and is recommended for testing or development purposes only.
 
-You can choose the tag that best suits your needs based on stability requirements and desired features.
-
 For the development workflow, see [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
 
 Are you having trouble? Check out our [Troubleshooting Guide](https://docs.all-hands.dev/modules/usage/troubleshooting).

docs/modules/usage/key-features.md

@@ -1,60 +1,28 @@
-
 # OpenHands Feature Overview
 
-![overview](https://www.all-hands.dev/assets/product/product-slide-1.webp)
+![overview](/img/oh-features.png)
 
-## 1. Workspace
-The Workspace feature provides a comprehensive development environment with the following key capabilities:
-- File Explorer: Browse, view, and manage project files and directories
-- Project Management: Import, create, and navigate between different projects
-- Integrated Development Tools: Seamless integration with various development workflows
-- File Operations:
-  * View file contents
-  * Create new files and folders
+### Chat Panel
+- Displays the conversation between the user and OpenHands.
+- OpenHands explains its actions in this panel.
+
+### Workspace
+- Browse project files and directories.
+- Use the `Open in VS Code` option to:
+  * Modify files
   * Upload and download files
-  * Basic file manipulation
 
-## 2. Jupyter Notebook
-The Jupyter Notebook feature offers an interactive coding and data analysis environment:
-- Interactive Code Cells: Execute Python code in a cell-based interface
-- Input and Output Tracking: Maintain a history of code inputs and their corresponding outputs
-- Persistent Session: Preserve code execution context between cells
-- Supports various Python operations and data analysis tasks
-- Real-time code execution and result visualization
+### Jupyter
+- Shows all Python commands that were executed by OpenHands.
+- Particularly handy when using OpenHands to perform data visualization tasks.
 
-## 3. Browser (Beta)
-The Browser feature provides web interaction capabilities:
-- Web Page Navigation: Open and browse websites within the application
-- Screenshot Capture: Automatically generate screenshots of web pages
-- Interaction Tools:
-  * Click elements
-  * Fill out forms
-  * Scroll pages
-  * Navigate through web content
-- Supports 15 different browser interaction functions
+### App
+- Shows the web server when OpenHands runs an application.
+- Users can interact with the running application.
 
-## 4. Terminal
-The Terminal feature offers a command-line interface within the application:
-- Execute Shell Commands: Run bash and system commands
-- Command History: Track and recall previous commands
-- Environment Interaction: Interact directly with the system's command line
-- Support for various programming and system administration tasks
+### Browser
+- Used by OpenHands to browse websites.
+- The browser is non-interactive.
 
-## 5. Chat / AI Conversation
-The Chat interface provides an AI-powered conversational experience:
-- Interactive AI Assistant: Engage in natural language conversations
-- Context-Aware Responses: AI understands and responds to development-related queries
-- Action Suggestions: Provides actionable recommendations for tasks
-- Conversation Management: Create, delete, and manage different conversation threads
-
-## 6. App (Beta)
-The main application interface combines all these features:
-- Integrated Workspace: Seamless integration of workspace, browser, terminal, and AI chat
-- Configurable Layout: Customize the arrangement of different feature panels
-- State Management: Maintain context and state across different features
-- Security and Privacy Controls: Manage application settings and permissions
-
-### Additional Notes
-- The application is currently in beta, with ongoing improvements and feature additions
-- Supports various development workflows and AI-assisted coding
-- Designed to enhance developer productivity through integrated tools and AI assistance
+### Terminal
+- A space for OpenHands and users to run terminal commands.

docs/modules/usage/llms/llms.md

@@ -1,5 +1,9 @@
 # 🤖 LLM Backends
 
+:::note
+This section is for users who want to connect OpenHands to different LLMs.
+:::
+
 OpenHands can connect to any LLM supported by LiteLLM. However, it requires a powerful model to work.
 
 ## Model Recommendations

docs/modules/usage/prompting/prompting-best-practices.md

@@ -1,37 +1,38 @@
 # Prompting Best Practices
 
-When working with OpenHands AI software developer, it's crucial to provide clear and effective prompts. This guide outlines best practices for creating prompts that will yield the most accurate and useful responses.
+When working with OpenHands AI software developer, providing clear and effective prompts is key to getting accurate
+and useful responses. This guide outlines best practices for crafting effective prompts.
 
 ## Characteristics of Good Prompts
 
 Good prompts are:
 
-- **Concrete**: They explain exactly what functionality should be added or what error needs to be fixed.
-- **Location-specific**: If known, they explain the locations in the code base that should be modified.
-- **Appropriately scoped**: They should be the size of a single feature, typically not exceeding 100 lines of code.
+- **Concrete**: Clearly describe what functionality should be added or what error needs fixing.
+- **Location-specific**: Specify the locations in the codebase that should be modified, if known.
+- **Appropriately scoped**: Focus on a single feature, typically not exceeding 100 lines of code.
 
 ## Examples
 
 ### Good Prompt Examples
 
-- "Add a function `calculate_average` in `utils/math_operations.py` that takes a list of numbers as input and returns their average."
-- "Fix the TypeError in `frontend/src/components/UserProfile.tsx` occurring on line 42. The error suggests we're trying to access a property of undefined."
-- "Implement input validation for the email field in the registration form. Update `frontend/src/components/RegistrationForm.tsx` to check if the email is in a valid format before submission."
+- Add a function `calculate_average` in `utils/math_operations.py` that takes a list of numbers as input and returns their average.
+- Fix the TypeError in `frontend/src/components/UserProfile.tsx` occurring on line 42. The error suggests we're trying to access a property of undefined.
+- Implement input validation for the email field in the registration form. Update `frontend/src/components/RegistrationForm.tsx` to check if the email is in a valid format before submission.
 
 ### Bad Prompt Examples
 
-- "Make the code better." (Too vague, not concrete)
-- "Rewrite the entire backend to use a different framework." (Not appropriately scoped)
-- "There's a bug somewhere in the user authentication. Can you find and fix it?" (Lacks specificity and location information)
+- Make the code better. (Too vague, not concrete)
+- Rewrite the entire backend to use a different framework. (Not appropriately scoped)
+- There's a bug somewhere in the user authentication. Can you find and fix it? (Lacks specificity and location information)
 
 ## Tips for Effective Prompting
 
 - Be as specific as possible about the desired outcome or the problem to be solved.
 - Provide context, including relevant file paths and line numbers if available.
-- Break down large tasks into smaller, manageable prompts.
-- Include any relevant error messages or logs.
-- Specify the programming language or framework if it's not obvious from the context.
+- Break large tasks into smaller, manageable prompts.
+- Include relevant error messages or logs.
+- Specify the programming language or framework, if not obvious.
 
-Remember, the more precise and informative your prompt is, the better the AI can assist you in developing or modifying the OpenHands software.
+The more precise and informative your prompt, the better OpenHands can assist you.
 
 See [Getting Started with OpenHands](../getting-started) for more examples of helpful prompts.

docs/modules/usage/runtimes-index.md

@@ -1,5 +1,9 @@
 # Runtime Configuration
 
+:::note
+This section is for users that would like to use a runtime other than Docker for OpenHands.
+:::
+
 A Runtime is an environment where the OpenHands agent can edit files and run
 commands.
 

docs/modules/usage/troubleshooting/troubleshooting.md

@@ -20,25 +20,3 @@ Try these in order:
 * If using Docker Desktop, ensure `Settings > Advanced > Allow the default Docker socket to be used` is enabled.
 * Depending on your configuration you may need `Settings > Resources > Network > Enable host networking` enabled in Docker Desktop.
 * Reinstall Docker Desktop.
----
-
-# Development Workflow Specific
-### Error building runtime docker image
-
-**Description**
-
-Attempts to start a new session fail, and errors with terms like the following appear in the logs:
-```
-debian-security bookworm-security
-InRelease At least one invalid signature was encountered.
-```
-
-This seems to happen when the hash of an existing external library changes and your local docker instance has
-cached a previous version. To work around this, please try the following:
-
-* Stop any containers where the name has the prefix `openhands-runtime-` :
-  `docker ps --filter name=openhands-runtime- --filter status=running -aq | xargs docker stop`
-* Remove any containers where the name has the prefix `openhands-runtime-` :
-  `docker rmi $(docker images --filter name=openhands-runtime- -q --no-trunc)`
-* Stop and Remove any containers / images where the name has the prefix `openhands-runtime-`
-* Prune containers / images : `docker container prune -f && docker image prune -f`

docs/sidebars.ts

@@ -18,6 +18,23 @@ const sidebars: SidebarsConfig = {
       label: 'Key Features',
       id: 'usage/key-features',
     },
+    {
+      type: 'category',
+      label: 'OpenHands Cloud',
+      items: [
+        {
+          type: 'doc',
+          label: 'Openhands Cloud',
+          id: 'usage/cloud/openhands-cloud',
+        },
+
+        {
+          type: 'doc',
+          label: 'Cloud GitHub Resolver',
+          id: 'usage/cloud/cloud-github-resolver',
+        },
+      ],
+    },
     {
       type: 'category',
       label: 'Prompting',
@@ -27,6 +44,17 @@ const sidebars: SidebarsConfig = {
           label: 'Best Practices',
           id: 'usage/prompting/prompting-best-practices',
         },
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Customization',
+      items: [
+        {
+          type: 'doc',
+          label: 'Repository Customization',
+          id: 'usage/customization/repository',
+        },
         {
           type: 'category',
           label: 'Microagents',
@@ -55,17 +83,6 @@ const sidebars: SidebarsConfig = {
         },
       ],
     },
-    {
-      type: 'category',
-      label: 'Customization',
-      items: [
-        {
-          type: 'doc',
-          label: 'Repository Customization',
-          id: 'usage/customization/repository',
-        },
-      ],
-    },
     {
       type: 'category',
       label: 'Usage Methods',
@@ -90,23 +107,6 @@ const sidebars: SidebarsConfig = {
           label: 'Github Action',
           id: 'usage/how-to/github-action',
         },
-        {
-          type: 'category',
-          label: 'Cloud',
-          items: [
-            {
-              type: 'doc',
-              label: 'Openhands Cloud',
-              id: 'usage/cloud/openhands-cloud',
-            },
-
-            {
-              type: 'doc',
-              label: 'Cloud GitHub Resolver',
-              id: 'usage/cloud/cloud-github-resolver',
-            },
-          ],
-        },
       ],
     },
     {