From 56f7646d8d0e8fe6e2329cb836f641e6471ed15e Mon Sep 17 00:00:00 2001
From: mamoodi <mamoodiha@gmail.com>
Date: Mon, 6 Oct 2025 18:31:37 -0400
Subject: [PATCH 1/6] Fix docs

---
 docs.json                                     |  19 +++++++++++-------
 openhands/usage/installation.mdx              |   2 +-
 .../{index.mdx => usage/introduction.mdx}     |   0
 .../index.mdx                                 |   0
 .../stories/2025-04-11-visual-ui/s1.png       | Bin
 .../2025-05-04-chrome-extension/s1.png        | Bin
 .../2025-05-04-chrome-extension/s2.png        | Bin
 .../stories/2025-06-02-swebench-score/s1.mp4  | Bin
 .../stories/2025-06-08-map/s1.png             | Bin
 .../stories/2025-06-11-infra-iam/s1.png       | Bin
 .../stories/2025-06-11-infra-iam/s2.png       | Bin
 .../stories/2025-06-13-show-love/v1.mp4       | Bin
 12 files changed, 13 insertions(+), 8 deletions(-)
 rename openhands/{index.mdx => usage/introduction.mdx} (100%)
 rename {openhands/success-stories => success-stories}/index.mdx (100%)
 rename {openhands/success-stories => success-stories}/stories/2025-04-11-visual-ui/s1.png (100%)
 rename {openhands/success-stories => success-stories}/stories/2025-05-04-chrome-extension/s1.png (100%)
 rename {openhands/success-stories => success-stories}/stories/2025-05-04-chrome-extension/s2.png (100%)
 rename {openhands/success-stories => success-stories}/stories/2025-06-02-swebench-score/s1.mp4 (100%)
 rename {openhands/success-stories => success-stories}/stories/2025-06-08-map/s1.png (100%)
 rename {openhands/success-stories => success-stories}/stories/2025-06-11-infra-iam/s1.png (100%)
 rename {openhands/success-stories => success-stories}/stories/2025-06-11-infra-iam/s2.png (100%)
 rename {openhands/success-stories => success-stories}/stories/2025-06-13-show-love/v1.mp4 (100%)

diff --git a/docs.json b/docs.json
index a0236462..3e280045 100644
--- a/docs.json
+++ b/docs.json
@@ -22,7 +22,7 @@
       {
         "tab": "Docs",
         "pages": [
-          "index",
+          "openhands/usage/introduction",
           "openhands/usage/installation",
           "openhands/usage/getting-started",
           "openhands/usage/key-features",
@@ -31,6 +31,7 @@
             "group": "OpenHands Cloud",
             "pages": [
               "openhands/usage/cloud/openhands-cloud",
+              "openhands/usage/cloud/pro-subscription",
               {
                 "group": "Integrations",
                 "pages": [
@@ -109,8 +110,7 @@
                 },
                 "openhands/usage/configuration-options",
                 "openhands/usage/how-to/custom-sandbox-guide",
-                "openhands/usage/search-engine-setup",
-                "openhands/usage/mcp"
+                "openhands/usage/search-engine-setup"
                 ]
               }
             ]
@@ -118,7 +118,13 @@
           {
             "group": "Customizations & Settings",
             "pages": [
-              "openhands/usage/common-settings",
+              {
+                "group": "OpenHands Settings",
+                "pages": [
+                  "openhands/usage/settings/secrets-settings",
+                  "openhands/usage/settings/mcp-settings"
+                ]
+              },
               "openhands/usage/prompting/repository",
               {
                 "group": "Microagents",
@@ -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": {
diff --git a/openhands/usage/installation.mdx b/openhands/usage/installation.mdx
index 3f755f6f..8ec8c185 100644
--- a/openhands/usage/installation.mdx
+++ b/openhands/usage/installation.mdx
@@ -15,6 +15,6 @@ icon: rocket
   <Tab title="Running OpenHands on Your Own">
     Run OpenHands on your local system and bring your own LLM and API key.
 
-    For more information see [running OpenHands on your own.](/usage/local-setup)
+    For more information see [running OpenHands on your own.](/openhands/usage/local-setup)
   </Tab>
 </Tabs>
diff --git a/openhands/index.mdx b/openhands/usage/introduction.mdx
similarity index 100%
rename from openhands/index.mdx
rename to openhands/usage/introduction.mdx
diff --git a/openhands/success-stories/index.mdx b/success-stories/index.mdx
similarity index 100%
rename from openhands/success-stories/index.mdx
rename to success-stories/index.mdx
diff --git a/openhands/success-stories/stories/2025-04-11-visual-ui/s1.png b/success-stories/stories/2025-04-11-visual-ui/s1.png
similarity index 100%
rename from openhands/success-stories/stories/2025-04-11-visual-ui/s1.png
rename to success-stories/stories/2025-04-11-visual-ui/s1.png
diff --git a/openhands/success-stories/stories/2025-05-04-chrome-extension/s1.png b/success-stories/stories/2025-05-04-chrome-extension/s1.png
similarity index 100%
rename from openhands/success-stories/stories/2025-05-04-chrome-extension/s1.png
rename to success-stories/stories/2025-05-04-chrome-extension/s1.png
diff --git a/openhands/success-stories/stories/2025-05-04-chrome-extension/s2.png b/success-stories/stories/2025-05-04-chrome-extension/s2.png
similarity index 100%
rename from openhands/success-stories/stories/2025-05-04-chrome-extension/s2.png
rename to success-stories/stories/2025-05-04-chrome-extension/s2.png
diff --git a/openhands/success-stories/stories/2025-06-02-swebench-score/s1.mp4 b/success-stories/stories/2025-06-02-swebench-score/s1.mp4
similarity index 100%
rename from openhands/success-stories/stories/2025-06-02-swebench-score/s1.mp4
rename to success-stories/stories/2025-06-02-swebench-score/s1.mp4
diff --git a/openhands/success-stories/stories/2025-06-08-map/s1.png b/success-stories/stories/2025-06-08-map/s1.png
similarity index 100%
rename from openhands/success-stories/stories/2025-06-08-map/s1.png
rename to success-stories/stories/2025-06-08-map/s1.png
diff --git a/openhands/success-stories/stories/2025-06-11-infra-iam/s1.png b/success-stories/stories/2025-06-11-infra-iam/s1.png
similarity index 100%
rename from openhands/success-stories/stories/2025-06-11-infra-iam/s1.png
rename to success-stories/stories/2025-06-11-infra-iam/s1.png
diff --git a/openhands/success-stories/stories/2025-06-11-infra-iam/s2.png b/success-stories/stories/2025-06-11-infra-iam/s2.png
similarity index 100%
rename from openhands/success-stories/stories/2025-06-11-infra-iam/s2.png
rename to success-stories/stories/2025-06-11-infra-iam/s2.png
diff --git a/openhands/success-stories/stories/2025-06-13-show-love/v1.mp4 b/success-stories/stories/2025-06-13-show-love/v1.mp4
similarity index 100%
rename from openhands/success-stories/stories/2025-06-13-show-love/v1.mp4
rename to success-stories/stories/2025-06-13-show-love/v1.mp4

From 52946c71a9c5ae8642d8a6e22b4e89156532edfe Mon Sep 17 00:00:00 2001
From: mamoodi <mamoodiha@gmail.com>
Date: Mon, 6 Oct 2025 19:31:00 -0400
Subject: [PATCH 2/6] Update doc structure

---
 docs.json                                     | 42 +++++++++----------
 .../{ => advanced}/configuration-options.mdx  |  0
 .../custom-sandbox-guide.mdx                  |  2 +-
 .../usage/cloud/bitbucket-installation.mdx    |  6 +--
 openhands/usage/cloud/cloud-ui.mdx            | 26 ++++++------
 openhands/usage/cloud/github-installation.mdx |  8 ++--
 openhands/usage/cloud/gitlab-installation.mdx |  4 +-
 openhands/usage/cloud/openhands-cloud.mdx     | 10 ++---
 openhands/usage/cloud/pro-subscription.mdx    |  6 +--
 .../repository.mdx                            |  2 +-
 .../{how-to => developers}/debugging.mdx      |  0
 .../development-overview.mdx                  |  0
 .../evaluation-harness.mdx                    |  0
 .../websocket-connection.mdx                  |  0
 openhands/usage/faqs.mdx                      | 28 ++++++-------
 openhands/usage/llms/azure-llms.mdx           |  4 +-
 openhands/usage/llms/custom-llm-configs.mdx   |  2 +-
 openhands/usage/llms/google-llms.mdx          |  2 +-
 openhands/usage/llms/llms.mdx                 | 20 ++++-----
 openhands/usage/llms/local-llms.mdx           |  4 +-
 openhands/usage/llms/openhands-llms.mdx       |  4 +-
 .../microagents-keyword.mdx                   |  0
 .../microagents-org.mdx                       |  2 +-
 .../microagents-overview.mdx                  |  6 +--
 .../microagents-public.mdx                    |  2 +-
 .../microagents-repo.mdx                      |  0
 .../{installation.mdx => quick-start.mdx}     |  4 +-
 .../{how-to => run-openhands}/cli-mode.mdx    |  2 +-
 .../github-action.mdx                         |  2 +-
 .../{how-to => run-openhands}/gui-mode.mdx    | 18 ++++----
 .../headless-mode.mdx                         |  2 +-
 .../usage/{ => run-openhands}/local-setup.mdx | 20 ++++-----
 openhands/usage/runtimes/docker.mdx           |  2 +-
 openhands/usage/runtimes/local.mdx            |  2 +-
 ...getting-started.mdx => start-building.mdx} |  4 +-
 .../prompting-best-practices.mdx              |  2 +-
 .../usage/{ => troubleshooting}/feedback.mdx  |  0
 sdk/index.mdx                                 |  4 +-
 38 files changed, 121 insertions(+), 121 deletions(-)
 rename openhands/usage/{ => advanced}/configuration-options.mdx (100%)
 rename openhands/usage/{how-to => advanced}/custom-sandbox-guide.mdx (96%)
 rename openhands/usage/{prompting => customization}/repository.mdx (91%)
 rename openhands/usage/{how-to => developers}/debugging.mdx (100%)
 rename openhands/usage/{how-to => developers}/development-overview.mdx (100%)
 rename openhands/usage/{how-to => developers}/evaluation-harness.mdx (100%)
 rename openhands/usage/{how-to => developers}/websocket-connection.mdx (100%)
 rename openhands/usage/{prompting => microagents}/microagents-keyword.mdx (100%)
 rename openhands/usage/{prompting => microagents}/microagents-org.mdx (92%)
 rename openhands/usage/{prompting => microagents}/microagents-overview.mdx (81%)
 rename openhands/usage/{prompting => microagents}/microagents-public.mdx (88%)
 rename openhands/usage/{prompting => microagents}/microagents-repo.mdx (100%)
 rename openhands/usage/{installation.mdx => quick-start.mdx} (88%)
 rename openhands/usage/{how-to => run-openhands}/cli-mode.mdx (98%)
 rename openhands/usage/{how-to => run-openhands}/github-action.mdx (98%)
 rename openhands/usage/{how-to => run-openhands}/gui-mode.mdx (91%)
 rename openhands/usage/{how-to => run-openhands}/headless-mode.mdx (96%)
 rename openhands/usage/{ => run-openhands}/local-setup.mdx (88%)
 rename openhands/usage/{getting-started.mdx => start-building.mdx} (94%)
 rename openhands/usage/{prompting => tips}/prompting-best-practices.mdx (94%)
 rename openhands/usage/{ => troubleshooting}/feedback.mdx (100%)

diff --git a/docs.json b/docs.json
index 3e280045..8e9c0caa 100644
--- a/docs.json
+++ b/docs.json
@@ -23,8 +23,8 @@
         "tab": "Docs",
         "pages": [
           "openhands/usage/introduction",
-          "openhands/usage/installation",
-          "openhands/usage/getting-started",
+          "openhands/usage/quick-start",
+          "openhands/usage/start-building",
           "openhands/usage/key-features",
           "openhands/usage/faqs",
           {
@@ -57,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": [
@@ -108,8 +108,8 @@
                     }
                   ]
                 },
-                "openhands/usage/configuration-options",
-                "openhands/usage/how-to/custom-sandbox-guide",
+                "openhands/usage/advanced/configuration-options",
+                "openhands/usage/advanced/custom-sandbox-guide",
                 "openhands/usage/search-engine-setup"
                 ]
               }
@@ -125,15 +125,15 @@
                   "openhands/usage/settings/mcp-settings"
                 ]
               },
-              "openhands/usage/prompting/repository",
+              "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"
                 ]
               }
             ]
@@ -141,20 +141,20 @@
           {
             "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": [
@@ -162,9 +162,9 @@
                   "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"
             ]
           }
         ]
diff --git a/openhands/usage/configuration-options.mdx b/openhands/usage/advanced/configuration-options.mdx
similarity index 100%
rename from openhands/usage/configuration-options.mdx
rename to openhands/usage/advanced/configuration-options.mdx
diff --git a/openhands/usage/how-to/custom-sandbox-guide.mdx b/openhands/usage/advanced/custom-sandbox-guide.mdx
similarity index 96%
rename from openhands/usage/how-to/custom-sandbox-guide.mdx
rename to openhands/usage/advanced/custom-sandbox-guide.mdx
index b2380adc..62481621 100644
--- a/openhands/usage/how-to/custom-sandbox-guide.mdx
+++ b/openhands/usage/advanced/custom-sandbox-guide.mdx
@@ -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
diff --git a/openhands/usage/cloud/bitbucket-installation.mdx b/openhands/usage/cloud/bitbucket-installation.mdx
index 7f6e1559..80578a0e 100644
--- a/openhands/usage/cloud/bitbucket-installation.mdx
+++ b/openhands/usage/cloud/bitbucket-installation.mdx
@@ -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
 
@@ -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.
diff --git a/openhands/usage/cloud/cloud-ui.mdx b/openhands/usage/cloud/cloud-ui.mdx
index 4288f749..256110ec 100644
--- a/openhands/usage/cloud/cloud-ui.mdx
+++ b/openhands/usage/cloud/cloud-ui.mdx
@@ -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.
diff --git a/openhands/usage/cloud/github-installation.mdx b/openhands/usage/cloud/github-installation.mdx
index 68636ead..87067310 100644
--- a/openhands/usage/cloud/github-installation.mdx
+++ b/openhands/usage/cloud/github-installation.mdx
@@ -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
 
@@ -48,7 +48,7 @@ on `Launch` to start the conversation!
 ## 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.
diff --git a/openhands/usage/cloud/gitlab-installation.mdx b/openhands/usage/cloud/gitlab-installation.mdx
index 621d05ef..f41680ad 100644
--- a/openhands/usage/cloud/gitlab-installation.mdx
+++ b/openhands/usage/cloud/gitlab-installation.mdx
@@ -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
 
@@ -22,7 +22,7 @@ branch you'd like OpenHands to work on. Then click on `Launch` to start the conv
 ## 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.
 
diff --git a/openhands/usage/cloud/openhands-cloud.mdx b/openhands/usage/cloud/openhands-cloud.mdx
index 6c0e3634..d64fc2fa 100644
--- a/openhands/usage/cloud/openhands-cloud.mdx
+++ b/openhands/usage/cloud/openhands-cloud.mdx
@@ -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.
diff --git a/openhands/usage/cloud/pro-subscription.mdx b/openhands/usage/cloud/pro-subscription.mdx
index 65dfe64b..2c4876a6 100644
--- a/openhands/usage/cloud/pro-subscription.mdx
+++ b/openhands/usage/cloud/pro-subscription.mdx
@@ -37,7 +37,7 @@ Here are the key differences between Pay-as-you-go and Pro subscriptions:
 | Monthly price | None \- no commitment | $20/month |
 | Can I bring my own LLM key? | No | ✅ Yes |
 | Do I pay for LLM usage? | ✅ Yes | ✅ Yes |
-| Can I select from different LLMs without bringing my own LLM key? | No \- defaults to Claude Sonnet 4 | ✅ Yes \- via OpenHands LLM provider <br/><br/>[*See models and pricing*](https://docs.all-hands.dev/usage/llms/openhands-llms#pricing) |
+| Can I select from different LLMs without bringing my own LLM key? | No \- defaults to Claude Sonnet 4 | ✅ Yes \- via OpenHands LLM provider <br/><br/>[*See models and pricing*](/openhands/usage/llms/openhands-llms#pricing) |
 | How much am I charged for LLM usage? | **Marked up pricing** \- 2x Claude Sonnet 4 API prices. *This markup helps cover the cost of runtime compute.* | **No markup** \- 1x API prices. *The $20 monthly subscription covers the cost of runtime compute.* |
 
 
@@ -45,6 +45,6 @@ Here are the key differences between Pay-as-you-go and Pro subscriptions:
 The following applies to **both** the Pay-as-you-go and Pro subscription:
 |  | Pay-as-you-go or Pro Subscription |
 | :---- | :---- |
-| Do I have access to multiple models via the OpenHands LLM provider? | ✅ Yes <br/><br/> [*See models and pricing*](https://docs.all-hands.dev/usage/llms/openhands-llms#pricing) |
+| Do I have access to multiple models via the OpenHands LLM provider? | ✅ Yes <br/><br/> [*See models and pricing*](/openhands/usage/llms/openhands-llms#pricing) |
 | Can I generate and refresh OpenHands LLM API keys? | ✅ Yes |
-| How much am I charged for LLM usage when I use the OpenHands LLM provider in other AI coding tools?  | **No markup** \- pay 1x API prices <br/> [*See models and pricing*](https://docs.all-hands.dev/usage/llms/openhands-llms#pricing) <br/><br/> *Usage is deducted from your OpenHands Cloud credit balance.*  <br/><br/> *The OpenHands LLM provider is available to all OpenHands Cloud users, and LLM usage is billed at-cost (zero markup). Use these models with OpenHands CLI, running OpenHands on your own, or even other AI coding agents\! [Learn more.](https://www.all-hands.dev/blog/access-state-of-the-art-llm-models-at-cost-via-openhands-gui-and-cli)* |
+| How much am I charged for LLM usage when I use the OpenHands LLM provider in other AI coding tools?  | **No markup** \- pay 1x API prices <br/> [*See models and pricing*](/openhands/usage/llms/openhands-llms#pricing) <br/><br/> *Usage is deducted from your OpenHands Cloud credit balance.*  <br/><br/> *The OpenHands LLM provider is available to all OpenHands Cloud users, and LLM usage is billed at-cost (zero markup). Use these models with OpenHands CLI, running OpenHands on your own, or even other AI coding agents\! [Learn more.](https://www.all-hands.dev/blog/access-state-of-the-art-llm-models-at-cost-via-openhands-gui-and-cli)* |
diff --git a/openhands/usage/prompting/repository.mdx b/openhands/usage/customization/repository.mdx
similarity index 91%
rename from openhands/usage/prompting/repository.mdx
rename to openhands/usage/customization/repository.mdx
index 0bb64ee4..60a0ce7f 100644
--- a/openhands/usage/prompting/repository.mdx
+++ b/openhands/usage/customization/repository.mdx
@@ -6,7 +6,7 @@ description: You can customize how OpenHands interacts with your repository by c
 ## Microagents
 
 Microagents allow you to extend OpenHands prompts with information specific to your project and define how OpenHands
-should function. See [Microagents Overview](../prompting/microagents-overview) for more information.
+should function. See [Microagents Overview](/openhands/usage/microagents/microagents-overview) for more information.
 
 
 ## Setup Script
diff --git a/openhands/usage/how-to/debugging.mdx b/openhands/usage/developers/debugging.mdx
similarity index 100%
rename from openhands/usage/how-to/debugging.mdx
rename to openhands/usage/developers/debugging.mdx
diff --git a/openhands/usage/how-to/development-overview.mdx b/openhands/usage/developers/development-overview.mdx
similarity index 100%
rename from openhands/usage/how-to/development-overview.mdx
rename to openhands/usage/developers/development-overview.mdx
diff --git a/openhands/usage/how-to/evaluation-harness.mdx b/openhands/usage/developers/evaluation-harness.mdx
similarity index 100%
rename from openhands/usage/how-to/evaluation-harness.mdx
rename to openhands/usage/developers/evaluation-harness.mdx
diff --git a/openhands/usage/how-to/websocket-connection.mdx b/openhands/usage/developers/websocket-connection.mdx
similarity index 100%
rename from openhands/usage/how-to/websocket-connection.mdx
rename to openhands/usage/developers/websocket-connection.mdx
diff --git a/openhands/usage/faqs.mdx b/openhands/usage/faqs.mdx
index 0888994d..85b9f75b 100644
--- a/openhands/usage/faqs.mdx
+++ b/openhands/usage/faqs.mdx
@@ -8,12 +8,12 @@ icon: question
 
 ### I'm new to OpenHands. Where should I start?
 
-1. **Quick start**: Use [OpenHands Cloud](/usage/cloud/openhands-cloud) to get started quickly with
-  [GitHub](/usage/cloud/github-installation), [GitLab](/usage/cloud/gitlab-installation),
-  and [Slack](/usage/cloud/slack-installation) integrations.
-2. **Run on your own**: If you prefer to run it on your own hardware, follow our [Getting Started guide](/usage/local-setup).
-3. **First steps**: Read over the [start building guidelines](/usage/getting-started) and
-  [prompting best practices](/usage/prompting/prompting-best-practices) to learn the basics.
+1. **Quick start**: Use [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud) to get started quickly with
+  [GitHub](/openhands/usage/cloud/github-installation), [GitLab](/openhands/usage/cloud/gitlab-installation),
+  and [Slack](/openhands/usage/cloud/slack-installation) integrations.
+2. **Run on your own**: If you prefer to run it on your own hardware, follow our [Getting Started guide](/openhands/usage/run-openhands/local-setup).
+3. **First steps**: Read over the [start building guidelines](/openhands/usage/start-building) and
+  [prompting best practices](/openhands/usage/tips/prompting-best-practices) to learn the basics.
 
 ### Can I use OpenHands for production workloads?
 
@@ -38,7 +38,7 @@ input on our product roadmap.
 (called a "sandbox") that is separate from your host system. However, the safety depends on your configuration:
 
 **What's protected:**
-- Your host system files and programs (unless you mount them using [this feature](/usage/runtimes/docker#connecting-to-your-filesystem))
+- Your host system files and programs (unless you mount them using [this feature](/openhands/usage/runtimes/docker#connecting-to-your-filesystem))
 - Host system resources
 - Other containers and processes
 
@@ -48,9 +48,9 @@ input on our product roadmap.
 - Mounted files and directories can be modified or deleted.
 - Network requests can be made to external services.
 
-For detailed security information, see our [Runtime Architecture](/usage/architecture/runtime),
-[Security Configuration](/usage/configuration-options#security-configuration),
-and [Hardened Docker Installation](/usage/runtimes/docker#hardened-docker-installation) documentation.
+For detailed security information, see our [Runtime Architecture](/openhands/usage/architecture/runtime),
+[Security Configuration](/openhands/usage/advanced/configuration-options#security-configuration),
+and [Hardened Docker Installation](/openhands/usage/runtimes/docker#hardened-docker-installation) documentation.
 
 ## File Storage and Access
 
@@ -63,7 +63,7 @@ Your files are stored in different locations depending on how you've configured
 - These files are temporary and will be lost when the container is removed.
 - The agent works in the `/workspace` directory inside the runtime container.
 
-**When you mount your local filesystem (following [this](/usage/runtimes/docker#connecting-to-your-filesystem)):**
+**When you mount your local filesystem (following [this](/openhands/usage/runtimes/docker#connecting-to-your-filesystem)):**
 - Your local files are mounted into the container's `/workspace` directory.
 - Changes made by the agent are reflected in your local filesystem.
 - Files persist after the container is stopped.
@@ -80,9 +80,9 @@ OpenHands comes with a basic runtime environment that includes Python and Node.j
 It also has the ability to install any tools it needs, so usually it's sufficient to ask it to set up its environment.
 
 If you would like to set things up more systematically, you can:
-- **Use setup.sh**: Add a [setup.sh file](/usage/prompting/repository#setup-script) file to
+- **Use setup.sh**: Add a [setup.sh file](/openhands/usage/customization/repository#setup-script) file to
   your repository, which will be run every time the agent starts.
-- **Use a custom sandbox**: Use a [custom docker image](/usage/how-to/custom-sandbox-guide) to initialize the sandbox.
+- **Use a custom sandbox**: Use a [custom docker image](/openhands/usage/advanced/custom-sandbox-guide) to initialize the sandbox.
 
 ### Something's not working. Where can I get help?
 
@@ -91,6 +91,6 @@ If you would like to set things up more systematically, you can:
 2. **Join our community**: Get help from other users and developers:
    - [Slack community](https://dub.sh/openhands)
 3. **Check our troubleshooting guide**: Common issues and solutions are documented in
-  [Troubleshooting](/usage/troubleshooting/troubleshooting).
+  [Troubleshooting](/openhands/usage/troubleshooting/troubleshooting).
 4. **Report bugs**: If you've found a bug, please [create an issue](https://github.com/All-Hands-AI/OpenHands/issues/new)
   and fill in as much detail as possible.
diff --git a/openhands/usage/llms/azure-llms.mdx b/openhands/usage/llms/azure-llms.mdx
index d1dbb310..e5740128 100644
--- a/openhands/usage/llms/azure-llms.mdx
+++ b/openhands/usage/llms/azure-llms.mdx
@@ -6,7 +6,7 @@ description: OpenHands uses LiteLLM to make calls to Azure's chat models. You ca
 ## Azure OpenAI Configuration
 
 When running OpenHands, you'll need to set the following environment variable using `-e` in the
-[docker run command](../installation#running-openhands):
+docker run command:
 
 ```
 LLM_API_VERSION="<api-version>"              # e.g. "2023-05-15"
@@ -35,7 +35,7 @@ You will need your ChatGPT deployment name which can be found on the deployments
 ### Azure OpenAI Configuration
 
 When running OpenHands, set the following environment variable using `-e` in the
-[docker run command](../installation#running-openhands):
+docker run command:
 
 ```
 LLM_API_VERSION="<api-version>"                                    # e.g. "2024-02-15-preview"
diff --git a/openhands/usage/llms/custom-llm-configs.mdx b/openhands/usage/llms/custom-llm-configs.mdx
index 2a7af468..297d3612 100644
--- a/openhands/usage/llms/custom-llm-configs.mdx
+++ b/openhands/usage/llms/custom-llm-configs.mdx
@@ -57,7 +57,7 @@ Each named LLM configuration supports all the same options as the default LLM co
 - Token limits (`max_input_tokens`, `max_output_tokens`)
 - And all other LLM configuration options
 
-For a complete list of available options, see the LLM Configuration section in the [Configuration Options](../configuration-options) documentation.
+For a complete list of available options, see the LLM Configuration section in the [Configuration Options](/openhands/usage/advanced/configuration-options) documentation.
 
 ## Use Cases
 
diff --git a/openhands/usage/llms/google-llms.mdx b/openhands/usage/llms/google-llms.mdx
index d71c3151..6b789888 100644
--- a/openhands/usage/llms/google-llms.mdx
+++ b/openhands/usage/llms/google-llms.mdx
@@ -15,7 +15,7 @@ If the model is not in the list, enable `Advanced` options, and enter it in `Cus
 ## VertexAI - Google Cloud Platform Configs
 
 To use Vertex AI through Google Cloud Platform when running OpenHands, you'll need to set the following environment
-variables using `-e` in the [docker run command](../installation#running-openhands):
+variables using `-e` in the docker run command:
 
 ```
 GOOGLE_APPLICATION_CREDENTIALS="<json-dump-of-gcp-service-account-json>"
diff --git a/openhands/usage/llms/llms.mdx b/openhands/usage/llms/llms.mdx
index 19357a65..7989b528 100644
--- a/openhands/usage/llms/llms.mdx
+++ b/openhands/usage/llms/llms.mdx
@@ -74,15 +74,15 @@ using `-e`:
 
 We have a few guides for running OpenHands with specific model providers:
 
-- [Azure](/usage/llms/azure-llms)
-- [Google](/usage/llms/google-llms)
-- [Groq](/usage/llms/groq)
-- [Local LLMs with SGLang or vLLM](/usage/llms/local-llms)
-- [LiteLLM Proxy](/usage/llms/litellm-proxy)
-- [Moonshot AI](/usage/llms/moonshot)
-- [OpenAI](/usage/llms/openai-llms)
-- [OpenHands](/usage/llms/openhands-llms)
-- [OpenRouter](/usage/llms/openrouter)
+- [Azure](/openhands/usage/llms/azure-llms)
+- [Google](/openhands/usage/llms/google-llms)
+- [Groq](/openhands/usage/llms/groq)
+- [Local LLMs with SGLang or vLLM](/openhands/usage/llms/local-llms)
+- [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy)
+- [Moonshot AI](/openhands/usage/llms/moonshot)
+- [OpenAI](/openhands/usage/llms/openai-llms)
+- [OpenHands](/openhands/usage/llms/openhands-llms)
+- [OpenRouter](/openhands/usage/llms/openrouter)
 
 ## Model Customization
 
@@ -92,7 +92,7 @@ LLM providers have specific settings that can be customized to optimize their pe
 - **Native Tool Calling**: Toggle native function/tool calling capabilities.
 
 For detailed information about model customization, see
-[LLM Configuration Options](/usage/configuration-options#llm-configuration).
+[LLM Configuration Options](/openhands/usage/advanced/configuration-options#llm-configuration).
 
 ### API retries and rate limits
 
diff --git a/openhands/usage/llms/local-llms.mdx b/openhands/usage/llms/local-llms.mdx
index 97a5cc2e..1cdc408c 100644
--- a/openhands/usage/llms/local-llms.mdx
+++ b/openhands/usage/llms/local-llms.mdx
@@ -65,7 +65,7 @@ Download and install the LM Studio desktop app from [lmstudio.ai](https://lmstud
 
 ### 5. Start OpenHands
 
-1. Check [the installation guide](/usage/local-setup) and ensure all prerequisites are met before running OpenHands, then run:
+1. Check [the installation guide](/openhands/usage/run-openhands/local-setup) and ensure all prerequisites are met before running OpenHands, then run:
 
 ```bash
 docker pull docker.all-hands.dev/all-hands-ai/runtime:0.58-nikolaik
@@ -200,7 +200,7 @@ vllm serve mistralai/Devstral-Small-2505 \
 
 #### Using Docker
 
-Run OpenHands using [the official docker run command](../installation#start-the-app).
+Run OpenHands using [the official docker run command](/openhands/run-openhands/local-setup).
 
 #### Using Development Mode
 
diff --git a/openhands/usage/llms/openhands-llms.mdx b/openhands/usage/llms/openhands-llms.mdx
index ce151374..8cc4b5e2 100644
--- a/openhands/usage/llms/openhands-llms.mdx
+++ b/openhands/usage/llms/openhands-llms.mdx
@@ -5,7 +5,7 @@ description: OpenHands LLM provider with access to state-of-the-art (SOTA) agent
 
 ## Obtain Your OpenHands LLM API Key
 
-1. [Log in to OpenHands Cloud](/usage/cloud/openhands-cloud).
+1. [Log in to OpenHands Cloud](/openhands/usage/cloud/openhands-cloud).
 2. Go to the Settings page and navigate to the `API Keys` tab.
 3. Copy your `LLM API Key`.
 
@@ -20,7 +20,7 @@ When running OpenHands, you'll need to set the following in the OpenHands UI thr
 
 ## Using OpenHands LLM Provider in the CLI
 
-1. [Run OpenHands CLI](/usage/how-to/cli-mode).
+1. [Run OpenHands CLI](/openhands/usage/run-openhands/cli-mode).
 2. To select OpenHands as the LLM provider:
   - If this is your first time running the CLI, choose `openhands` and then select the model that you would like to use.
   - If you have previously run the CLI, run the `/settings` command and select to modify the `Basic` settings. Then
diff --git a/openhands/usage/prompting/microagents-keyword.mdx b/openhands/usage/microagents/microagents-keyword.mdx
similarity index 100%
rename from openhands/usage/prompting/microagents-keyword.mdx
rename to openhands/usage/microagents/microagents-keyword.mdx
diff --git a/openhands/usage/prompting/microagents-org.mdx b/openhands/usage/microagents/microagents-org.mdx
similarity index 92%
rename from openhands/usage/prompting/microagents-org.mdx
rename to openhands/usage/microagents/microagents-org.mdx
index 8a439b77..a851dbfb 100644
--- a/openhands/usage/prompting/microagents-org.mdx
+++ b/openhands/usage/microagents/microagents-org.mdx
@@ -5,7 +5,7 @@ description: Organizations and users can define microagents that apply to all re
 
 ## Usage
 
-These microagents can be [any type of microagent](./microagents-overview#microagent-types) and will be loaded
+These microagents can be [any type of microagent](/openhands/usage/microagents/microagents-overview#microagent-types) and will be loaded
 accordingly. However, they are applied to all repositories belonging to the organization or user.
 
 Add a `.openhands` repository under the organization or user and create a `microagents` directory and place the
diff --git a/openhands/usage/prompting/microagents-overview.mdx b/openhands/usage/microagents/microagents-overview.mdx
similarity index 81%
rename from openhands/usage/prompting/microagents-overview.mdx
rename to openhands/usage/microagents/microagents-overview.mdx
index abc13c2b..1a9d5bc3 100644
--- a/openhands/usage/prompting/microagents-overview.mdx
+++ b/openhands/usage/microagents/microagents-overview.mdx
@@ -7,11 +7,11 @@ description: Microagents are specialized prompts that enhance OpenHands with dom
 
 Currently OpenHands supports the following types of microagents:
 
-- [General Microagents](./microagents-repo): General guidelines for OpenHands about the repository.
-- [Keyword-Triggered Microagents](./microagents-keyword): Guidelines activated by specific keywords in prompts.
+- [General Microagents](/openhands/usage/microagents/microagents-repo): General guidelines for OpenHands about the repository.
+- [Keyword-Triggered Microagents](/openhands/usage/microagents/microagents-keyword): Guidelines activated by specific keywords in prompts.
 
 To customize OpenHands' behavior, create a .openhands/microagents/ directory in the root of your repository and
-add `<microagent_name>.md` files inside. For repository-specific guidelines, you can ask OpenHands to analyze your repository and create a comprehensive `repo.md` file (see [General Microagents](./microagents-repo) for details).
+add `<microagent_name>.md` files inside. For repository-specific guidelines, you can ask OpenHands to analyze your repository and create a comprehensive `repo.md` file (see [General Microagents](/openhands/usage/microagents/microagents-repo) for details).
 
 <Note>
 Loaded microagents take up space in the context window.
diff --git a/openhands/usage/prompting/microagents-public.mdx b/openhands/usage/microagents/microagents-public.mdx
similarity index 88%
rename from openhands/usage/prompting/microagents-public.mdx
rename to openhands/usage/microagents/microagents-public.mdx
index c1e2ca7a..b67098b2 100644
--- a/openhands/usage/prompting/microagents-public.mdx
+++ b/openhands/usage/microagents/microagents-public.mdx
@@ -1,6 +1,6 @@
 ---
 title: Global Microagents
-description: Global microagents are [keyword-triggered microagents](./microagents-keyword) that apply to all OpenHands users. A list of the current global microagents can be found [in the OpenHands repository](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents).
+description: Global microagents are [keyword-triggered microagents](/openhands/usage/microagents/microagents-keyword) that apply to all OpenHands users. A list of the current global microagents can be found [in the OpenHands repository](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents).
 ---
 
 ## Contributing a Global Microagent
diff --git a/openhands/usage/prompting/microagents-repo.mdx b/openhands/usage/microagents/microagents-repo.mdx
similarity index 100%
rename from openhands/usage/prompting/microagents-repo.mdx
rename to openhands/usage/microagents/microagents-repo.mdx
diff --git a/openhands/usage/installation.mdx b/openhands/usage/quick-start.mdx
similarity index 88%
rename from openhands/usage/installation.mdx
rename to openhands/usage/quick-start.mdx
index 8ec8c185..196ae5a3 100644
--- a/openhands/usage/installation.mdx
+++ b/openhands/usage/quick-start.mdx
@@ -10,11 +10,11 @@ icon: rocket
 
     To get started with OpenHands Cloud, visit [app.all-hands.dev](https://app.all-hands.dev).
 
-    For more information see [getting started with OpenHands Cloud.](/usage/cloud/openhands-cloud)
+    For more information see [getting started with OpenHands Cloud.](/openhands/usage/cloud/openhands-cloud)
   </Tab>
   <Tab title="Running OpenHands on Your Own">
     Run OpenHands on your local system and bring your own LLM and API key.
 
-    For more information see [running OpenHands on your own.](/openhands/usage/local-setup)
+    For more information see [running OpenHands on your own.](/openhands/usage/run-openhands/local-setup)
   </Tab>
 </Tabs>
diff --git a/openhands/usage/how-to/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
similarity index 98%
rename from openhands/usage/how-to/cli-mode.mdx
rename to openhands/usage/run-openhands/cli-mode.mdx
index 6ad9e89a..2f81cb15 100644
--- a/openhands/usage/how-to/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -4,7 +4,7 @@ description: The Command-Line Interface (CLI) provides a powerful interface that
   directly from your terminal.
 ---
 
-This mode is different from the [headless mode](/usage/how-to/headless-mode), which is non-interactive and better
+This mode is different from the [headless mode](/openhands/usage/run-openhands/headless-mode), which is non-interactive and better
 for scripting.
 
 <iframe
diff --git a/openhands/usage/how-to/github-action.mdx b/openhands/usage/run-openhands/github-action.mdx
similarity index 98%
rename from openhands/usage/how-to/github-action.mdx
rename to openhands/usage/run-openhands/github-action.mdx
index d35bf3ed..061de486 100644
--- a/openhands/usage/how-to/github-action.mdx
+++ b/openhands/usage/run-openhands/github-action.mdx
@@ -48,6 +48,6 @@ The customization options you can set are:
 | `LLM_MODEL`                      | Variable | Set the LLM to use with OpenHands                                                                   | `LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"` |
 | `OPENHANDS_MAX_ITER`             | Variable | Set max limit for agent iterations                                                                  | `OPENHANDS_MAX_ITER=10`                            |
 | `OPENHANDS_MACRO`                | Variable | Customize default macro for invoking the resolver                                                   | `OPENHANDS_MACRO=@resolveit`                       |
-| `OPENHANDS_BASE_CONTAINER_IMAGE` | Variable | Custom Sandbox ([learn more](/usage/how-to/custom-sandbox-guide))                                   | `OPENHANDS_BASE_CONTAINER_IMAGE="custom_image"`    |
+| `OPENHANDS_BASE_CONTAINER_IMAGE` | Variable | Custom Sandbox ([learn more](/openhands/usage/advanced/custom-sandbox-guide))                       | `OPENHANDS_BASE_CONTAINER_IMAGE="custom_image"`    |
 | `TARGET_BRANCH`                  | Variable | Merge to branch other than `main`                                                                   | `TARGET_BRANCH="dev"`                              |
 | `TARGET_RUNNER`                  | Variable | Target runner to execute the agent workflow (default ubuntu-latest)                                 | `TARGET_RUNNER="custom-runner"`                    |
diff --git a/openhands/usage/how-to/gui-mode.mdx b/openhands/usage/run-openhands/gui-mode.mdx
similarity index 91%
rename from openhands/usage/how-to/gui-mode.mdx
rename to openhands/usage/run-openhands/gui-mode.mdx
index 5359c756..db9f7b01 100644
--- a/openhands/usage/how-to/gui-mode.mdx
+++ b/openhands/usage/run-openhands/gui-mode.mdx
@@ -5,7 +5,7 @@ description: High level overview of the Graphical User Interface (GUI) in OpenHa
 
 ## Prerequisites
 
-- [OpenHands is running](/usage/local-setup)
+- [OpenHands is running](/openhands/usage/run-openhands/local-setup)
 
 ## Launching the GUI Server
 
@@ -14,7 +14,7 @@ description: High level overview of the Graphical User Interface (GUI) in OpenHa
 You can launch the OpenHands GUI server directly from the command line using the `serve` command:
 
 <Callout type="info">
-**Prerequisites**: You need to have the [OpenHands CLI installed](/usage/how-to/cli-mode) first, OR have `uv` installed and run `uvx --python 3.12 --from openhands-ai openhands serve`. Otherwise, you'll need to use Docker directly (see the [Docker section](#using-docker-directly) below).
+**Prerequisites**: You need to have the [OpenHands CLI installed](/usage/run-openhands/cli-mode) first, OR have `uv` installed and run `uvx --python 3.12 --from openhands-ai openhands serve`. Otherwise, you'll need to use Docker directly (see the [Docker section](#using-docker-directly) below).
 </Callout>
 
 ```bash
@@ -66,7 +66,7 @@ The CLI will automatically check these requirements and provide helpful error me
 
 ### Using Docker Directly
 
-Alternatively, you can run the GUI server using Docker directly. See the [local setup guide](/usage/local-setup) for detailed Docker instructions.
+Alternatively, you can run the GUI server using Docker directly. See the [local setup guide](/usage/run-openhands/local-setup) for detailed Docker instructions.
 
 ## Overview
 
@@ -86,8 +86,8 @@ You can use the Settings page at any time to:
 - Setup the LLM provider and model for OpenHands.
 - [Setup the search engine](/usage/search-engine-setup).
 - [Configure MCP servers](/usage/settings/mcp-settings).
-- [Connect to GitHub](/usage/how-to/gui-mode#github-setup), [connect to GitLab](/usage/how-to/gui-mode#gitlab-setup)
-  and [connect to Bitbucket](/usage/how-to/gui-mode#bitbucket-setup).
+- [Connect to GitHub](/usage/run-openhands/gui-mode#github-setup), [connect to GitLab](/usage/run-openhands/gui-mode#gitlab-setup)
+  and [connect to Bitbucket](/usage/run-openhands/gui-mode#bitbucket-setup).
 - Set application settings like your preferred language, notifications and other preferences.
 - [Manage custom secrets](/usage/settings/secrets-settings).
 
@@ -248,10 +248,10 @@ is loaded. Typically these include:
 
 ## Tips for Effective Use
 
-- Be specific in your requests to get the most accurate and helpful responses, as described in the [prompting best practices](../prompting/prompting-best-practices).
+- Be specific in your requests to get the most accurate and helpful responses, as described in the [prompting best practices](/openhands/usage/tips/prompting-best-practices).
 - Use one of the recommended models, as described in the [LLMs section](/usage/llms/llms).
 
 ## Other Ways to Run Openhands
-- [Run OpenHands in a scriptable headless mode.](/usage/how-to/headless-mode)
-- [Run OpenHands with a friendly CLI.](/usage/how-to/cli-mode)
-- [Run OpenHands on GitHub issues with a GitHub action.](/usage/how-to/github-action)
+- [Run OpenHands in a scriptable headless mode.](/openhands/usage/run-openhands/headless-mode)
+- [Run OpenHands with a friendly CLI.](/usage/run-openhands/cli-mode)
+- [Run OpenHands on GitHub issues with a GitHub action.](/usage/run-openhands/github-action)
diff --git a/openhands/usage/how-to/headless-mode.mdx b/openhands/usage/run-openhands/headless-mode.mdx
similarity index 96%
rename from openhands/usage/how-to/headless-mode.mdx
rename to openhands/usage/run-openhands/headless-mode.mdx
index 04ef87a9..22a4ad24 100644
--- a/openhands/usage/how-to/headless-mode.mdx
+++ b/openhands/usage/run-openhands/headless-mode.mdx
@@ -4,7 +4,7 @@ description: You can run OpenHands with a single command, without starting the w
   write scripts and automate tasks with OpenHands.
 ---
 
-This is different from [the CLI](./cli-mode), which is interactive, and better for active development.
+This is different from [the CLI](/openhands/usage/run-openhands/cli-mode), which is interactive, and better for active development.
 
 ## With Python
 
diff --git a/openhands/usage/local-setup.mdx b/openhands/usage/run-openhands/local-setup.mdx
similarity index 88%
rename from openhands/usage/local-setup.mdx
rename to openhands/usage/run-openhands/local-setup.mdx
index b457335d..3fddd7ba 100644
--- a/openhands/usage/local-setup.mdx
+++ b/openhands/usage/run-openhands/local-setup.mdx
@@ -10,7 +10,7 @@ description: Getting started with running OpenHands on your own.
 - MacOS with [Docker Desktop support](https://docs.docker.com/desktop/setup/install/mac-install/#system-requirements)
 - Linux
 - Windows with [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) and [Docker Desktop support](https://docs.docker.com/desktop/setup/install/windows-install/#system-requirements)
-- Windows without WSL (see [Windows Without WSL Guide](/usage/windows-without-wsl))
+- Windows without WSL (see [Windows Without WSL Guide](/openhands/usage/windows-without-wsl))
 
 A system with a modern processor and a minimum of **4GB RAM** is recommended to run OpenHands.
 
@@ -65,7 +65,7 @@ A system with a modern processor and a minimum of **4GB RAM** is recommended to
 
   **Alternative: Windows without WSL**
 
-  If you prefer to run OpenHands on Windows without WSL or Docker, see our [Windows Without WSL Guide](/usage/windows-without-wsl).
+  If you prefer to run OpenHands on Windows without WSL or Docker, see our [Windows Without WSL Guide](/openhands/usage/windows-without-wsl).
 
 </Accordion>
 
@@ -157,7 +157,7 @@ OpenHands requires an API key to access most language models. Here's how to get
 2. Go to the Settings page and navigate to the `API Keys` tab.
 3. Copy your `LLM API Key`.
 
-OpenHands provides access to state-of-the-art agentic coding models with competitive pricing. [Learn more about OpenHands LLM provider](/usage/llms/openhands-llms).
+OpenHands provides access to state-of-the-art agentic coding models with competitive pricing. [Learn more about OpenHands LLM provider](/openhands/usage/llms/openhands-llms).
 
 </Accordion>
 
@@ -201,7 +201,7 @@ Consider setting usage limits to control costs.
 Effective use of local models for agent tasks requires capable hardware, along with models specifically tuned for instruction-following and agent-style behavior.
 </Note>
 
-To run OpenHands with a locally hosted language model instead of a cloud provider, see the [Local LLMs guide](/usage/llms/local-llms) for setup instructions.
+To run OpenHands with a locally hosted language model instead of a cloud provider, see the [Local LLMs guide](/openhands/usage/llms/local-llms) for setup instructions.
 
 #### Setting Up Search Engine
 
@@ -212,11 +212,11 @@ To enable search functionality in OpenHands:
 1. Get a Tavily API key from [tavily.com](https://tavily.com/).
 2. Enter the Tavily API key in the Settings page under `LLM` tab > `Search API Key (Tavily)`
 
-For more details, see the [Search Engine Setup](/usage/search-engine-setup) guide.
+For more details, see the [Search Engine Setup](/openhands/usage/search-engine-setup) guide.
 
 ### Versions
 
-The [docker command above](/usage/local-setup#start-the-app) pulls the most recent stable release of OpenHands. You have other options as well:
+The [docker command above](/openhands/usage/run-openhands/local-setup#start-the-app) pulls the most recent stable release of OpenHands. You have other options as well:
 - For a specific release, replace `$VERSION` in `openhands:$VERSION` and `runtime:$VERSION`, with the version number.
 For example, `0.9` will automatically point to the latest `0.9.x` release, and `0` will point to the latest `0.x.x` release.
 - For the most up-to-date development version, replace `$VERSION` in `openhands:$VERSION` and `runtime:$VERSION`, with `main`.
@@ -224,7 +224,7 @@ This version is unstable and is recommended for testing or development purposes
 
 ## Next Steps
 
-- [Connect OpenHands to your local filesystem.](/usage/runtimes/docker#connecting-to-your-filesystem) to use OpenHands with your GitHub repositories
-- [Run OpenHands in a scriptable headless mode.](/usage/how-to/headless-mode)
-- [Run OpenHands with a friendly CLI.](/usage/how-to/cli-mode)
-- [Run OpenHands on tagged issues with a GitHub action.](/usage/how-to/github-action)
+- [Connect OpenHands to your local filesystem.](/openhands/usage/runtimes/docker#connecting-to-your-filesystem) to use OpenHands with your GitHub repositories
+- [Run OpenHands in a scriptable headless mode.](/openhands/usage/run-openhands/headless-mode)
+- [Run OpenHands with a friendly CLI.](/openhands/usage/run-openhands/cli-mode)
+- [Run OpenHands on tagged issues with a GitHub action.](/openhands/usage/run-openhands/github-action)
diff --git a/openhands/usage/runtimes/docker.mdx b/openhands/usage/runtimes/docker.mdx
index 77b6414d..143a15a1 100644
--- a/openhands/usage/runtimes/docker.mdx
+++ b/openhands/usage/runtimes/docker.mdx
@@ -6,7 +6,7 @@ description: This is the default Runtime that's used when you start OpenHands.
 ## Image
 The `SANDBOX_RUNTIME_CONTAINER_IMAGE` from nikolaik is a pre-built runtime image
 that contains our Runtime server, as well as some basic utilities for Python and NodeJS.
-You can also [build your own runtime image](../how-to/custom-sandbox-guide).
+You can also [build your own runtime image](/openhands/usage/advanced/custom-sandbox-guide).
 
 ## Connecting to Your filesystem
 A useful feature is the ability to connect to your local filesystem. To mount your filesystem into the runtime:
diff --git a/openhands/usage/runtimes/local.mdx b/openhands/usage/runtimes/local.mdx
index 4855d302..9dc32055 100644
--- a/openhands/usage/runtimes/local.mdx
+++ b/openhands/usage/runtimes/local.mdx
@@ -17,7 +17,7 @@ Before using the Local Runtime, ensure that:
 1. You can run OpenHands using the [Development workflow](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
 2. For Linux and Mac, tmux is available on your system.
 3. For Windows, PowerShell is available on your system.
-    - Only [CLI mode](../how-to/cli-mode) and [headless mode](../how-to/headless-mode) are supported in Windows with Local Runtime.
+    - Only [CLI mode](/openhands/usage/run-openhands/cli-mode) and [headless mode](/openhands/usage/run-openhands/headless-mode) are supported in Windows with Local Runtime.
 
 ## Configuration
 
diff --git a/openhands/usage/getting-started.mdx b/openhands/usage/start-building.mdx
similarity index 94%
rename from openhands/usage/getting-started.mdx
rename to openhands/usage/start-building.mdx
index 3f22e9bc..0ebf2189 100644
--- a/openhands/usage/getting-started.mdx
+++ b/openhands/usage/start-building.mdx
@@ -1,6 +1,6 @@
 ---
 title: Start Building
-description: So you've [run OpenHands](/usage/installation). Now what?
+description: So you've [run OpenHands](/openhands/usage/quick-start). Now what?
 icon: code
 ---
 
@@ -97,4 +97,4 @@ Keep these tips in mind:
 * 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.
+See [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) for more tips on how to get the most out of OpenHands.
diff --git a/openhands/usage/prompting/prompting-best-practices.mdx b/openhands/usage/tips/prompting-best-practices.mdx
similarity index 94%
rename from openhands/usage/prompting/prompting-best-practices.mdx
rename to openhands/usage/tips/prompting-best-practices.mdx
index 4802e85e..b296eb91 100644
--- a/openhands/usage/prompting/prompting-best-practices.mdx
+++ b/openhands/usage/tips/prompting-best-practices.mdx
@@ -35,4 +35,4 @@ Good prompts are:
 
 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.
+See [Getting Started with OpenHands](/openhands/usage/start-building) for more examples of helpful prompts.
diff --git a/openhands/usage/feedback.mdx b/openhands/usage/troubleshooting/feedback.mdx
similarity index 100%
rename from openhands/usage/feedback.mdx
rename to openhands/usage/troubleshooting/feedback.mdx
diff --git a/sdk/index.mdx b/sdk/index.mdx
index b5471246..43e033a0 100644
--- a/sdk/index.mdx
+++ b/sdk/index.mdx
@@ -52,12 +52,12 @@ conversation.run()
 ### Acquire and Set an LLM API Key
 
 Obtain an API key from your favorite LLM provider, any [provider supported by LiteLLM](https://docs.litellm.ai/docs/providers)
-is supported by the Agent SDK, although we have a set of [recommended models](https://docs.all-hands.dev/usage/llms/llms) that
+is supported by the Agent SDK, although we have a set of [recommended models](/openhands/usage/llms/llms) that
 work well with OpenHands agents.
 
 If you want to get started quickly, you can sign up for the [OpenHands Cloud](https://app.all-hands.dev) and go to the
 [API key page](https://app.all-hands.dev/settings/api-keys), which allows you to use most of our recommended models
-with no markup -- documentation is [here](https://docs.all-hands.dev/usage/llms/openhands-llms).
+with no markup -- documentation is [here](/openhands/usage/llms/openhands-llms).
 
 Once you do this, you can `export LLM_API_KEY=xxx` to use all the examples.
 

From 4e4e90fc9b4882ae1fb3ba5e0ce045e2447a1641 Mon Sep 17 00:00:00 2001
From: mamoodi <mamoodiha@gmail.com>
Date: Mon, 6 Oct 2025 19:34:07 -0400
Subject: [PATCH 3/6] Update path of images

---
 openhands/usage/cloud/bitbucket-installation.mdx          | 2 +-
 openhands/usage/cloud/github-installation.mdx             | 2 +-
 openhands/usage/cloud/gitlab-installation.mdx             | 2 +-
 .../cloud/project-management/jira-dc-integration.mdx      | 8 ++++----
 .../usage/cloud/project-management/jira-integration.mdx   | 8 ++++----
 .../usage/cloud/project-management/linear-integration.mdx | 8 ++++----
 openhands/usage/cloud/slack-installation.mdx              | 6 +++---
 openhands/usage/key-features.mdx                          | 2 +-
 openhands/usage/llms/openhands-llms.mdx                   | 4 ++--
 9 files changed, 21 insertions(+), 21 deletions(-)

diff --git a/openhands/usage/cloud/bitbucket-installation.mdx b/openhands/usage/cloud/bitbucket-installation.mdx
index 80578a0e..eeca4753 100644
--- a/openhands/usage/cloud/bitbucket-installation.mdx
+++ b/openhands/usage/cloud/bitbucket-installation.mdx
@@ -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
 
diff --git a/openhands/usage/cloud/github-installation.mdx b/openhands/usage/cloud/github-installation.mdx
index 87067310..ce4a5de9 100644
--- a/openhands/usage/cloud/github-installation.mdx
+++ b/openhands/usage/cloud/github-installation.mdx
@@ -43,7 +43,7 @@ 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
 
diff --git a/openhands/usage/cloud/gitlab-installation.mdx b/openhands/usage/cloud/gitlab-installation.mdx
index f41680ad..f1807dcf 100644
--- a/openhands/usage/cloud/gitlab-installation.mdx
+++ b/openhands/usage/cloud/gitlab-installation.mdx
@@ -17,7 +17,7 @@ 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
 
diff --git a/openhands/usage/cloud/project-management/jira-dc-integration.mdx b/openhands/usage/cloud/project-management/jira-dc-integration.mdx
index 1488bbf7..c7ce4c06 100644
--- a/openhands/usage/cloud/project-management/jira-dc-integration.mdx
+++ b/openhands/usage/cloud/project-management/jira-dc-integration.mdx
@@ -109,18 +109,18 @@ Here the workspace name is **jira.all-hands.dev**.
 
 <AccordionGroup>
 <Accordion title="Workspace link flow">
-![workspace-link.png](/static/img/jira-dc-user-link.png)
+![workspace-link.png](/openhands/static/img/jira-dc-user-link.png)
 </Accordion>
 
 <Accordion title="Workspace Configure flow">
-![workspace-link.png](/static/img/jira-dc-admin-configure.png)
+![workspace-link.png](/openhands/static/img/jira-dc-admin-configure.png)
 </Accordion>
 
 <Accordion title="Edit view as a user">
-![workspace-link.png](/static/img/jira-dc-user-unlink.png)
+![workspace-link.png](/openhands/static/img/jira-dc-user-unlink.png)
 </Accordion>
 
 <Accordion title="Edit view as the workspace creator">
-![workspace-link.png](/static/img/jira-dc-admin-edit.png)
+![workspace-link.png](/openhands/static/img/jira-dc-admin-edit.png)
 </Accordion>
 </AccordionGroup>
diff --git a/openhands/usage/cloud/project-management/jira-integration.mdx b/openhands/usage/cloud/project-management/jira-integration.mdx
index 68c3b524..6cdd567d 100644
--- a/openhands/usage/cloud/project-management/jira-integration.mdx
+++ b/openhands/usage/cloud/project-management/jira-integration.mdx
@@ -113,18 +113,18 @@ Here the workspace name is **all-hands**.
 
 <AccordionGroup>
 <Accordion title="Workspace link flow">
-![workspace-link.png](/static/img/jira-user-link.png)
+![workspace-link.png](/openhands/static/img/jira-user-link.png)
 </Accordion>
 
 <Accordion title="Workspace Configure flow">
-![workspace-link.png](/static/img/jira-admin-configure.png)
+![workspace-link.png](/openhands/static/img/jira-admin-configure.png)
 </Accordion>
 
 <Accordion title="Edit view as a user">
-![workspace-link.png](/static/img/jira-user-unlink.png)
+![workspace-link.png](/openhands/static/img/jira-user-unlink.png)
 </Accordion>
 
 <Accordion title="Edit view as the workspace creator">
-![workspace-link.png](/static/img/jira-admin-edit.png)
+![workspace-link.png](/openhands/static/img/jira-admin-edit.png)
 </Accordion>
 </AccordionGroup>
diff --git a/openhands/usage/cloud/project-management/linear-integration.mdx b/openhands/usage/cloud/project-management/linear-integration.mdx
index c01da4ae..b03de7fb 100644
--- a/openhands/usage/cloud/project-management/linear-integration.mdx
+++ b/openhands/usage/cloud/project-management/linear-integration.mdx
@@ -113,18 +113,18 @@ Here the workspace name is **allhands**.
 
 <AccordionGroup>
 <Accordion title="Workspace link flow">
-![workspace-link.png](/static/img/linear-user-link.png)
+![workspace-link.png](/openhands/static/img/linear-user-link.png)
 </Accordion>
 
 <Accordion title="Workspace Configure flow">
-![workspace-link.png](/static/img/linear-admin-configure.png)
+![workspace-link.png](/openhands/static/img/linear-admin-configure.png)
 </Accordion>
 
 <Accordion title="Edit view as a user">
-![workspace-link.png](/static/img/linear-admin-edit.png)
+![workspace-link.png](/openhands/static/img/linear-admin-edit.png)
 </Accordion>
 
 <Accordion title="Edit view as the workspace creator">
-![workspace-link.png](/static/img/workspace-admin-edit.png)
+![workspace-link.png](/openhands/static/img/workspace-admin-edit.png)
 </Accordion>
 </AccordionGroup>
diff --git a/openhands/usage/cloud/slack-installation.mdx b/openhands/usage/cloud/slack-installation.mdx
index 50e6d651..8ed86325 100644
--- a/openhands/usage/cloud/slack-installation.mdx
+++ b/openhands/usage/cloud/slack-installation.mdx
@@ -68,13 +68,13 @@ You must be the user who started the conversation.
 
 Conversation is started by mentioning `@openhands`.
 
-![slack-create-conversation.png](/static/img/slack-create-conversation.png)
+![slack-create-conversation.png](/openhands/static/img/slack-create-conversation.png)
 
 ### See agent response and send follow up messages
 
 Initial request is followed up by mentioning `@openhands` in a thread reply.
 
-![slack-results-and-follow-up.png](/static/img/slack-results-and-follow-up.png)
+![slack-results-and-follow-up.png](/openhands/static/img/slack-results-and-follow-up.png)
 
 ## Pro tip
 
@@ -86,4 +86,4 @@ You can mention a repo name when starting a new conversation in the following fo
 The repo match is case insensitive. If a repo name match is made, it will kick off the conversation.
 If the repo name partially matches against multiple repos, you'll be asked to select a repo from the filtered list.
 
-![slack-pro-tip.png](/static/img/slack-pro-tip.png)
+![slack-pro-tip.png](/openhands/static/img/slack-pro-tip.png)
diff --git a/openhands/usage/key-features.mdx b/openhands/usage/key-features.mdx
index 488a3930..e0bcb8ee 100644
--- a/openhands/usage/key-features.mdx
+++ b/openhands/usage/key-features.mdx
@@ -3,7 +3,7 @@ title: Key Features
 icon: bars
 ---
 
-![overview](/static/img/oh-features.png)
+![overview](/openhands/static/img/oh-features.png)
 
 ### Chat Panel
 - Displays the conversation between the user and OpenHands.
diff --git a/openhands/usage/llms/openhands-llms.mdx b/openhands/usage/llms/openhands-llms.mdx
index 8cc4b5e2..895f7192 100644
--- a/openhands/usage/llms/openhands-llms.mdx
+++ b/openhands/usage/llms/openhands-llms.mdx
@@ -9,7 +9,7 @@ description: OpenHands LLM provider with access to state-of-the-art (SOTA) agent
 2. Go to the Settings page and navigate to the `API Keys` tab.
 3. Copy your `LLM API Key`.
 
-![OpenHands LLM API Key](/static/img/openhands-llm-api-key.png)
+![OpenHands LLM API Key](/openhands/static/img/openhands-llm-api-key.png)
 
 ## Configuration
 
@@ -26,7 +26,7 @@ When running OpenHands, you'll need to set the following in the OpenHands UI thr
   - If you have previously run the CLI, run the `/settings` command and select to modify the `Basic` settings. Then
     choose `openhands` and finally the model.
 
-![OpenHands Provider in CLI](/static/img/openhands-provider-cli.png)
+![OpenHands Provider in CLI](/openhands/static/img/openhands-provider-cli.png)
 
 ## Pricing
 

From 5150f62d0daea262ab97deb0700d621457e1f8a9 Mon Sep 17 00:00:00 2001
From: mamoodi <mamoodiha@gmail.com>
Date: Tue, 7 Oct 2025 09:04:41 -0400
Subject: [PATCH 4/6] Fix broken links

---
 README.md                                                | 9 ++++-----
 docs.json                                                | 2 +-
 openhands/usage/advanced/configuration-options.mdx       | 4 ++--
 openhands/usage/{ => advanced}/search-engine-setup.mdx   | 0
 .../cloud/project-management/linear-integration.mdx      | 2 +-
 openhands/usage/llms/local-llms.mdx                      | 2 +-
 openhands/usage/run-openhands/cli-mode.mdx               | 6 +++---
 openhands/usage/run-openhands/gui-mode.mdx               | 2 +-
 openhands/usage/run-openhands/local-setup.mdx            | 2 +-
 9 files changed, 14 insertions(+), 15 deletions(-)
 rename openhands/usage/{ => advanced}/search-engine-setup.mdx (100%)

diff --git a/README.md b/README.md
index 770a927b..dda35e3d 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,10 @@ 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
 
@@ -14,8 +15,6 @@ 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
index 8e9c0caa..0079ca22 100644
--- a/docs.json
+++ b/docs.json
@@ -110,7 +110,7 @@
                 },
                 "openhands/usage/advanced/configuration-options",
                 "openhands/usage/advanced/custom-sandbox-guide",
-                "openhands/usage/search-engine-setup"
+                "openhands/usage/advanced/search-engine-setup"
                 ]
               }
             ]
diff --git a/openhands/usage/advanced/configuration-options.mdx b/openhands/usage/advanced/configuration-options.mdx
index fc3fcdb5..6fb41e51 100644
--- a/openhands/usage/advanced/configuration-options.mdx
+++ b/openhands/usage/advanced/configuration-options.mdx
@@ -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**
diff --git a/openhands/usage/search-engine-setup.mdx b/openhands/usage/advanced/search-engine-setup.mdx
similarity index 100%
rename from openhands/usage/search-engine-setup.mdx
rename to openhands/usage/advanced/search-engine-setup.mdx
diff --git a/openhands/usage/cloud/project-management/linear-integration.mdx b/openhands/usage/cloud/project-management/linear-integration.mdx
index b03de7fb..4887df50 100644
--- a/openhands/usage/cloud/project-management/linear-integration.mdx
+++ b/openhands/usage/cloud/project-management/linear-integration.mdx
@@ -125,6 +125,6 @@ Here the workspace name is **allhands**.
 </Accordion>
 
 <Accordion title="Edit view as the workspace creator">
-![workspace-link.png](/openhands/static/img/workspace-admin-edit.png)
+![workspace-link.png](/openhands/static/img/linear-admin-edit.png)
 </Accordion>
 </AccordionGroup>
diff --git a/openhands/usage/llms/local-llms.mdx b/openhands/usage/llms/local-llms.mdx
index 1cdc408c..7404158d 100644
--- a/openhands/usage/llms/local-llms.mdx
+++ b/openhands/usage/llms/local-llms.mdx
@@ -200,7 +200,7 @@ vllm serve mistralai/Devstral-Small-2505 \
 
 #### Using Docker
 
-Run OpenHands using [the official docker run command](/openhands/run-openhands/local-setup).
+Run OpenHands using [the official docker run command](/openhands/usage/run-openhands/local-setup).
 
 #### Using Development Mode
 
diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 2f81cb15..8c235ab4 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -104,7 +104,7 @@ The conversation history will be saved in `~/.openhands/sessions`.
 ### Running with Docker
 
 1. Set the following environment variables in your terminal:
-   - `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access ([See using SANDBOX_VOLUMES for more info](../runtimes/docker#using-sandbox_volumes))
+   - `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access ([See using SANDBOX_VOLUMES for more info](/openhands/usage/runtimes/docker#using-sandbox_volumes))
    - `LLM_MODEL` - the LLM model to use (e.g. `export LLM_MODEL="anthropic/claude-sonnet-4-20250514"` or `export LLM_MODEL="anthropic/claude-sonnet-4-5-20250929"`)
    - `LLM_API_KEY` - your API key (e.g. `export LLM_API_KEY="sk_test_12345"`)
 
@@ -187,7 +187,7 @@ type `/resume` at the prompt.
 
 #### MCP Server Management
 
-To configure Model Context Protocol (MCP) servers, you can refer to the documentation on [MCP servers](../mcp) and use the `/mcp` command in the CLI. This command provides an interactive interface for managing Model Context Protocol (MCP) servers:
+To configure Model Context Protocol (MCP) servers, you can refer to the documentation on [MCP servers](/openhands/usage/settings/mcp-settings) and use the `/mcp` command in the CLI. This command provides an interactive interface for managing Model Context Protocol (MCP) servers:
 
 - **List configured servers**: View all currently configured MCP servers (SSE, Stdio, and SHTTP)
 - **Add new server**: Interactively add a new MCP server with guided prompts
@@ -196,7 +196,7 @@ To configure Model Context Protocol (MCP) servers, you can refer to the document
 
 This command modifies your `~/.openhands/config.toml` file and will prompt you to restart OpenHands for changes to take effect.
 
-By default, the [Fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) will be automatically configured for OpenHands. You can also [enable search engine](../search-engine-setup) via the [Tavily MCP server](https://github.com/tavily-ai/tavily-mcp) by setting the `search_api_key` under the `[core]` section in the `~/.openhands/config.toml` file.
+By default, the [Fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) will be automatically configured for OpenHands. You can also [enable search engine](/openhands/usage/advanced/search-engine-setup) via the [Tavily MCP server](https://github.com/tavily-ai/tavily-mcp) by setting the `search_api_key` under the `[core]` section in the `~/.openhands/config.toml` file.
 
 ##### Example of the `config.toml` file with MCP server configuration:
 
diff --git a/openhands/usage/run-openhands/gui-mode.mdx b/openhands/usage/run-openhands/gui-mode.mdx
index db9f7b01..861d3d1c 100644
--- a/openhands/usage/run-openhands/gui-mode.mdx
+++ b/openhands/usage/run-openhands/gui-mode.mdx
@@ -84,7 +84,7 @@ Alternatively, you can run the GUI server using Docker directly. See the [local
 You can use the Settings page at any time to:
 
 - Setup the LLM provider and model for OpenHands.
-- [Setup the search engine](/usage/search-engine-setup).
+- [Setup the search engine](/openhands/usage/advanced/search-engine-setup).
 - [Configure MCP servers](/usage/settings/mcp-settings).
 - [Connect to GitHub](/usage/run-openhands/gui-mode#github-setup), [connect to GitLab](/usage/run-openhands/gui-mode#gitlab-setup)
   and [connect to Bitbucket](/usage/run-openhands/gui-mode#bitbucket-setup).
diff --git a/openhands/usage/run-openhands/local-setup.mdx b/openhands/usage/run-openhands/local-setup.mdx
index 3fddd7ba..1801cffc 100644
--- a/openhands/usage/run-openhands/local-setup.mdx
+++ b/openhands/usage/run-openhands/local-setup.mdx
@@ -212,7 +212,7 @@ To enable search functionality in OpenHands:
 1. Get a Tavily API key from [tavily.com](https://tavily.com/).
 2. Enter the Tavily API key in the Settings page under `LLM` tab > `Search API Key (Tavily)`
 
-For more details, see the [Search Engine Setup](/openhands/usage/search-engine-setup) guide.
+For more details, see the [Search Engine Setup](/openhands/usage/advanced/search-engine-setup) guide.
 
 ### Versions
 

From 6dc6568697b3a411b05bddc37ec78b8b6d7e3d27 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 13:16:26 +0000
Subject: [PATCH 5/6] Add redirects for file movements in PR

- Added redirects for all files that moved during documentation restructure
- Covers movements from usage/ to advanced/, customization/, developers/, microagents/, run-openhands/, tips/, and troubleshooting/
- Added redirect for openhands/ -> openhands/usage/introduction
- All redirects preserve the original URL structure
---
 docs.json | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/docs.json b/docs.json
index 0079ca22..dbca50b5 100644
--- a/docs.json
+++ b/docs.json
@@ -235,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" }
   ]
 }

From 8887232f5a510fc3a05831257a797526825babe5 Mon Sep 17 00:00:00 2001
From: mamoodi <mamoodiha@gmail.com>
Date: Tue, 7 Oct 2025 09:21:26 -0400
Subject: [PATCH 6/6] Small README update

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index dda35e3d..1ffaace3 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ This repository aggregates documentation from multiple All Hands AI repositories
 
 - `docs.json` - Mintlify configuration file that references docs in these repos.
 - `openhands/` - Main OpenHands docs.
-- `sdk` - Agent SDK docs.
+- `sdk/` - Agent SDK docs.
 - `success-stories/` - Success stories docs.
 
 ## Adding New Documentation Sources