OpenHands · mamoodi · Oct 7, 2025 · Oct 6, 2025 · Oct 6, 2025 · Oct 6, 2025
diff --git a/README.md b/README.md
@@ -4,18 +4,17 @@ This repository aggregates documentation from multiple All Hands AI repositories
 
 ## Structure
 
-- `docs.json` - Mintlify configuration file that references docs in these repos
-- `.github/workflows/` - GitHub Actions for automatic `docs` updates
-- `docs/` Folders synced from other repos, e.g., `openhands/`, `agent-sdk/`
+- `docs.json` - Mintlify configuration file that references docs in these repos.
+- `openhands/` - Main OpenHands docs.
+- `sdk/` - Agent SDK docs.
+- `success-stories/` - Success stories docs.
 
 ## Adding New Documentation Sources
 
 To add documentation from a new repository:
 
 1. Add workflow [like this](https://github.com/All-Hands-AI/agent-sdk/blob/main/.github/workflows/deploy-docs.yml) to the new repo.
 2. Update `docs.json` to include navigation for the new content (e.g., `new-repo/docs/`)
-3. Commit the changes and manually trigger the [update-docs workflow](.github/workflows/update-docs.yml)
-
 
 ## Local Development
 

diff --git a/docs.json b/docs.json
@@ -22,15 +22,16 @@
       {
         "tab": "Docs",
         "pages": [
-          "index",
-          "openhands/usage/installation",
-          "openhands/usage/getting-started",
+          "openhands/usage/introduction",
+          "openhands/usage/quick-start",
+          "openhands/usage/start-building",
           "openhands/usage/key-features",
           "openhands/usage/faqs",
           {
             "group": "OpenHands Cloud",
             "pages": [
               "openhands/usage/cloud/openhands-cloud",
+              "openhands/usage/cloud/pro-subscription",
               {
                 "group": "Integrations",
                 "pages": [
@@ -56,11 +57,11 @@
           {
             "group": "Run OpenHands on Your Own",
             "pages": [
-              "openhands/usage/local-setup",
-              "openhands/usage/how-to/gui-mode",
-              "openhands/usage/how-to/cli-mode",
-              "openhands/usage/how-to/headless-mode",
-              "openhands/usage/how-to/github-action",
+              "openhands/usage/run-openhands/local-setup",
+              "openhands/usage/run-openhands/gui-mode",
+              "openhands/usage/run-openhands/cli-mode",
+              "openhands/usage/run-openhands/headless-mode",
+              "openhands/usage/run-openhands/github-action",
               {
                 "group": "Advanced Configuration",
                 "pages": [
@@ -107,58 +108,63 @@
                     }
                   ]
                 },
-                "openhands/usage/configuration-options",
-                "openhands/usage/how-to/custom-sandbox-guide",
-                "openhands/usage/search-engine-setup",
-                "openhands/usage/mcp"
+                "openhands/usage/advanced/configuration-options",
+                "openhands/usage/advanced/custom-sandbox-guide",
+                "openhands/usage/advanced/search-engine-setup"
                 ]
               }
             ]
           },
           {
             "group": "Customizations & Settings",
             "pages": [
-              "openhands/usage/common-settings",
-              "openhands/usage/prompting/repository",
+              {
+                "group": "OpenHands Settings",
+                "pages": [
+                  "openhands/usage/settings/secrets-settings",
+                  "openhands/usage/settings/mcp-settings"
+                ]
+              },
+              "openhands/usage/customization/repository",
               {
                 "group": "Microagents",
                 "pages": [
-                  "openhands/usage/prompting/microagents-overview",
-                  "openhands/usage/prompting/microagents-repo",
-                  "openhands/usage/prompting/microagents-keyword",
-                  "openhands/usage/prompting/microagents-org",
-                  "openhands/usage/prompting/microagents-public"
+                  "openhands/usage/microagents/microagents-overview",
+                  "openhands/usage/microagents/microagents-repo",
+                  "openhands/usage/microagents/microagents-keyword",
+                  "openhands/usage/microagents/microagents-org",
+                  "openhands/usage/microagents/microagents-public"
                 ]
               }
             ]
           },
           {
             "group": "Tips and Tricks",
             "pages": [
-              "openhands/usage/prompting/prompting-best-practices"
+              "openhands/usage/tips/prompting-best-practices"
             ]
           },
           {
             "group": "Troubleshooting & Feedback",
             "pages": [
               "openhands/usage/troubleshooting/troubleshooting",
-              "openhands/usage/feedback"
+              "openhands/usage/troubleshooting/feedback"
             ]
           },
           {
             "group": "OpenHands Developers",
             "pages": [
-              "openhands/usage/how-to/development-overview",
+              "openhands/usage/developers/development-overview",
               {
                 "group": "Architecture",
                 "pages": [
                   "openhands/usage/architecture/backend",
                   "openhands/usage/architecture/runtime"
                 ]
               },
-              "openhands/usage/how-to/debugging",
-              "openhands/usage/how-to/evaluation-harness",
-              "openhands/usage/how-to/websocket-connection"
+              "openhands/usage/developers/debugging",
+              "openhands/usage/developers/evaluation-harness",
+              "openhands/usage/developers/websocket-connection"
             ]
           }
         ]
@@ -172,7 +178,7 @@
       {
         "tab": "Success Stories",
         "pages": [
-          "openhands/success-stories/index"
+          "success-stories/index"
         ]
       },
       {
@@ -215,8 +221,7 @@
   "footer": {
     "socials": {
       "slack": "https://dub.sh/openhands",
-      "github": "https://github.com/All-Hands-AI/OpenHands",
-      "discord": "https://discord.gg/ESHStjSjD4"
+      "github": "https://github.com/All-Hands-AI/OpenHands"
     }
   },
   "contextual": {
@@ -230,6 +235,29 @@
   "redirects": [
     { "source": "/modules/:slug*", "destination": "/:slug*"},
     { "source": "/success-stories/:slug*", "destination": "/openhands/success-stories/:slug*" },
-    { "source": "/usage/:slug*", "destination": "/openhands/usage/:slug*"}
+    { "source": "/usage/:slug*", "destination": "/openhands/usage/:slug*"},
+    { "source": "/openhands/usage/configuration-options", "destination": "/openhands/usage/advanced/configuration-options" },
+    { "source": "/openhands/usage/how-to/custom-sandbox-guide", "destination": "/openhands/usage/advanced/custom-sandbox-guide" },
+    { "source": "/openhands/usage/search-engine-setup", "destination": "/openhands/usage/advanced/search-engine-setup" },
+    { "source": "/openhands/usage/prompting/repository", "destination": "/openhands/usage/customization/repository" },
+    { "source": "/openhands/usage/how-to/debugging", "destination": "/openhands/usage/developers/debugging" },
+    { "source": "/openhands/usage/how-to/development-overview", "destination": "/openhands/usage/developers/development-overview" },
+    { "source": "/openhands/usage/how-to/evaluation-harness", "destination": "/openhands/usage/developers/evaluation-harness" },
+    { "source": "/openhands/usage/how-to/websocket-connection", "destination": "/openhands/usage/developers/websocket-connection" },
+    { "source": "/openhands", "destination": "/openhands/usage/introduction" },
+    { "source": "/openhands/usage/prompting/microagents-keyword", "destination": "/openhands/usage/microagents/microagents-keyword" },
+    { "source": "/openhands/usage/prompting/microagents-org", "destination": "/openhands/usage/microagents/microagents-org" },
+    { "source": "/openhands/usage/prompting/microagents-overview", "destination": "/openhands/usage/microagents/microagents-overview" },
+    { "source": "/openhands/usage/prompting/microagents-public", "destination": "/openhands/usage/microagents/microagents-public" },
+    { "source": "/openhands/usage/prompting/microagents-repo", "destination": "/openhands/usage/microagents/microagents-repo" },
+    { "source": "/openhands/usage/installation", "destination": "/openhands/usage/quick-start" },
+    { "source": "/openhands/usage/how-to/cli-mode", "destination": "/openhands/usage/run-openhands/cli-mode" },
+    { "source": "/openhands/usage/how-to/github-action", "destination": "/openhands/usage/run-openhands/github-action" },
+    { "source": "/openhands/usage/how-to/gui-mode", "destination": "/openhands/usage/run-openhands/gui-mode" },
+    { "source": "/openhands/usage/how-to/headless-mode", "destination": "/openhands/usage/run-openhands/headless-mode" },
+    { "source": "/openhands/usage/local-setup", "destination": "/openhands/usage/run-openhands/local-setup" },
+    { "source": "/openhands/usage/getting-started", "destination": "/openhands/usage/start-building" },
+    { "source": "/openhands/usage/prompting/prompting-best-practices", "destination": "/openhands/usage/tips/prompting-best-practices" },
+    { "source": "/openhands/usage/feedback", "destination": "/openhands/usage/troubleshooting/feedback" }
   ]
 }
@@ -10,7 +10,7 @@ description: This page outlines all available configuration options for OpenHand
 
 <Note>
    **Looking for Environment Variables?** All configuration options can also be set using environment variables. 
-   See the [Environment Variables Reference](./environment-variables) for a complete list with examples.
+   See the [Environment Variables Reference](/openhands/usage/environment-variables) for a complete list with examples.
 </Note>
 
 ## Location of the `config.toml` File
@@ -157,7 +157,7 @@ All LLM configuration options can be set as environment variables by prefixing w
 - `base_url` → `LLM_BASE_URL`
 
 <Note>
-For development setups, you can also define custom named LLM configurations. See [Custom LLM Configurations](./llms/custom-llm-configs) for details.
+For development setups, you can also define custom named LLM configurations. See [Custom LLM Configurations](/openhands/usage/llms/custom-llm-configs) for details.
 </Note>
 
 **AWS Credentials**

@@ -47,7 +47,7 @@ This will produce a new image called `custom-image`, which will be available in
 
 ## Using the Docker Command
 
-When running OpenHands using [the docker command](/usage/local-setup#start-the-app), replace
+When running OpenHands using [the docker command](/usage/run-openhands/local-setup#start-the-app), replace
 `-e SANDBOX_RUNTIME_CONTAINER_IMAGE=...` with `-e SANDBOX_BASE_CONTAINER_IMAGE=<custom image name>`:
 
 ```commandline

@@ -6,7 +6,7 @@ description: This guide walks you through the process of installing OpenHands Cl
 
 ## Prerequisites
 
-- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a Bitbucket account](/usage/cloud/openhands-cloud).
+- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a Bitbucket account](/openhands/usage/cloud/openhands-cloud).
 
 ## Adding Bitbucket Repository Access
 
@@ -17,7 +17,7 @@ Upon signing into OpenHands Cloud with a Bitbucket account, OpenHands will have
 After signing in with a Bitbucket account, use the `Open Repository` section to select the appropriate repository and
 branch you'd like OpenHands to work on. Then click on `Launch` to start the conversation!
 
-![Connect Repo](/static/img/connect-repo.png)
+![Connect Repo](/openhands/static/img/connect-repo.png)
 
 ## IP Whitelisting
 
@@ -45,5 +45,5 @@ OpenHands to access your repositories:
 
 ## Next Steps
 
-- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
-- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.
+- [Learn about the Cloud UI](/openhands/usage/cloud/cloud-ui).
+- [Use the Cloud API](/openhands/usage/cloud/cloud-api) to programmatically interact with OpenHands.
@@ -8,9 +8,9 @@ description: The Cloud UI provides a web interface for interacting with OpenHand
 
 The landing page is where you can:
 
-- [Select a GitHub repo](/usage/cloud/github-installation#working-with-github-repos-in-openhands-cloud),
-  [a GitLab repo](/usage/cloud/gitlab-installation#working-with-gitlab-repos-in-openhands-cloud) or
-  [a Bitbucket repo](/usage/cloud/bitbucket-installation#working-with-bitbucket-repos-in-openhands-cloud) to start working on.
+- [Select a GitHub repo](/openhands/usage/cloud/github-installation#working-with-github-repos-in-openhands-cloud),
+  [a GitLab repo](/openhands/usage/cloud/gitlab-installation#working-with-gitlab-repos-in-openhands-cloud) or
+  [a Bitbucket repo](/openhands/usage/cloud/bitbucket-installation#working-with-bitbucket-repos-in-openhands-cloud) to start working on.
 - Launch an empty conversation using `New Conversation`.
 - See `Suggested Tasks` for repositories that OpenHands has access to.
 - See your `Recent Conversations`.
@@ -22,33 +22,33 @@ Settings are divided across tabs, with each tab focusing on a specific area of c
 - `User`
   - Change your email address.
 - `Integrations`
-  - [Configure GitHub repository access](/usage/cloud/github-installation#modifying-repository-access) for OpenHands.
-  - [Install the OpenHands Slack app](/usage/cloud/slack-installation).
+  - [Configure GitHub repository access](/openhands/usage/cloud/github-installation#modifying-repository-access) for OpenHands.
+  - [Install the OpenHands Slack app](/openhands/usage/cloud/slack-installation).
 - `Application`
   - Set your preferred language, notifications and other preferences.
   - Toggle task suggestions on GitHub.
   - Toggle Solvability Analysis.
   - Set a maximum budget per conversation.
   - Configure the username and email that OpenHands uses for commits.
-- `LLM` (Available for [Pro subscription users](/usage/cloud/pro-subscription))
+- `LLM` (Available for [Pro subscription users](/openhands/usage/cloud/pro-subscription))
   - Choose to use another LLM or use different models from the OpenHands provider.
 - `Billing`
   - Add credits for using the OpenHands provider.
   - Cancel your `Pro subscription`.
 - `Secrets`
-  - [Manage secrets](/usage/settings/secrets-settings).
+  - [Manage secrets](/openhands/usage/settings/secrets-settings).
 - `API Keys`
-  - [Create API keys to work with OpenHands programmatically](/usage/cloud/cloud-api).
+  - [Create API keys to work with OpenHands programmatically](/openhands/usage/cloud/cloud-api).
 - `MCP`
-  - [Setup an MCP server](/usage/settings/mcp-settings)
+  - [Setup an MCP server](/openhands/usage/settings/mcp-settings)
 
 ## Key Features
 
-For an overview of the key features available inside a conversation, please refer to the [Key Features](/usage/key-features)
+For an overview of the key features available inside a conversation, please refer to the [Key Features](/openhands/usage/key-features)
 section of the documentation.
 
 ## Next Steps
 
-- [Install GitHub Integration](/usage/cloud/github-installation) to use OpenHands with your GitHub repositories.
-- [Install GitLab Integration](/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories.
-- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.
+- [Install GitHub Integration](/openhands/usage/cloud/github-installation) to use OpenHands with your GitHub repositories.
+- [Install GitLab Integration](/openhands/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories.
+- [Use the Cloud API](/openhands/usage/cloud/cloud-api) to programmatically interact with OpenHands.
@@ -6,7 +6,7 @@ description: This guide walks you through the process of installing OpenHands Cl
 
 ## Prerequisites
 
-- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a GitHub account](/usage/cloud/openhands-cloud).
+- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a GitHub account](/openhands/usage/cloud/openhands-cloud).
 
 ## Adding GitHub Repository Access
 
@@ -43,12 +43,12 @@ Once you've granted GitHub repository access, you can start working with your Gi
 `Open Repository` section to select the appropriate repository and branch you'd like OpenHands to work on. Then click
 on `Launch` to start the conversation!
 
-![Connect Repo](/static/img/connect-repo.png)
+![Connect Repo](/openhands/static/img/connect-repo.png)
 
 ## Working on GitHub Issues and Pull Requests Using Openhands
 
 To allow OpenHands to work directly from GitHub directly, you must
-[give OpenHands access to your repository](/usage/cloud/github-installation#modifying-repository-access). Once access is
+[give OpenHands access to your repository](/openhands/usage/cloud/github-installation#modifying-repository-access). Once access is
 given, you can use OpenHands by labeling the issue or by tagging `@openhands`.
 
 ### Working with Issues
@@ -75,5 +75,5 @@ permissions to access both repositories.
 
 ## Next Steps
 
-- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
-- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.
+- [Learn about the Cloud UI](/openhands/usage/cloud/cloud-ui).
+- [Use the Cloud API](/openhands/usage/cloud/cloud-api) to programmatically interact with OpenHands.
@@ -6,7 +6,7 @@ description: This guide walks you through the process of installing OpenHands Cl
 
 ## Prerequisites
 
-- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a GitLab account](/usage/cloud/openhands-cloud).
+- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a GitLab account](/openhands/usage/cloud/openhands-cloud).
 
 ## Adding GitLab Repository Access
 
@@ -17,12 +17,12 @@ Upon signing into OpenHands Cloud with a GitLab account, OpenHands will have acc
 After signing in with a Gitlab account, use the `Open Repository` section to select the appropriate repository and
 branch you'd like OpenHands to work on. Then click on `Launch` to start the conversation!
 
-![Connect Repo](/static/img/connect-repo.png)
+![Connect Repo](/openhands/static/img/connect-repo.png)
 
 ## Using Tokens with Reduced Scopes
 
 OpenHands requests an API-scoped token during OAuth authentication. By default, this token is provided to the agent.
-To restrict the agent's permissions, [you can define a custom secret](/usage/settings/secrets-settings) `GITLAB_TOKEN`,
+To restrict the agent's permissions, [you can define a custom secret](/openhands/usage/settings/secrets-settings) `GITLAB_TOKEN`,
 which will override the default token assigned to the agent. While the high-permission API token is still requested
 and used for other components of the application (e.g. opening merge requests), the agent will not have access to it.
 

@@ -20,8 +20,8 @@ You'll be prompted to connect with your GitHub, GitLab or Bitbucket account:
 
 Once you've connected your account, you can:
 
-- [Install GitHub Integration](/usage/cloud/github-installation) to use OpenHands with your GitHub repositories.
-- [Install GitLab Integration](/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories.
-- [Install Bitbucket Integration](/usage/cloud/bitbucket-installation) to use OpenHands with your Bitbucket repositories.
-- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
-- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.
+- [Install GitHub Integration](/openhands/usage/cloud/github-installation) to use OpenHands with your GitHub repositories.
+- [Install GitLab Integration](/openhands/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories.
+- [Install Bitbucket Integration](/openhands/usage/cloud/bitbucket-installation) to use OpenHands with your Bitbucket repositories.
+- [Learn about the Cloud UI](/openhands/usage/cloud/cloud-ui).
+- [Use the Cloud API](/openhands/usage/cloud/cloud-api) to programmatically interact with OpenHands.