jlav · Oct 27, 2026 · Oct 27, 2026 · Nov 3, 2026 · Nov 3, 2026 · Nov 3, 2026
diff --git a/.agents/skills/code-review.md b/.agents/skills/code-review.md
@@ -142,6 +142,21 @@ Match the event to the severity of your findings:
 - Check that internal links use absolute doc paths (e.g., `/overview/quickstart`)
 - Verify code blocks with file references use the correct sync format (see `sdk-guidelines.md`)
 
+### Make the reader the actor
+
+Write task-oriented sentences around what the reader does, not what a tool or product does. Put
+the reader's action or goal first, usually as an imperative ("Use X to…", "Give X…", "Run X…").
+Flag sentences where a tool or product is the subject and the reader is left out, especially in
+intros and step descriptions.
+
+| Avoid | Prefer |
+|-------|--------|
+| ngrok gives the Docker Compose stack a public HTTPS URL. | Use ngrok to give the Docker Compose stack a public HTTPS URL. |
+| The Docker Compose stack runs OpenHands Enterprise on a single machine. | Use Docker Compose to run OpenHands Enterprise on a single machine. |
+
+Describing what a component is, for example on an architecture page, is fine with the component as
+the subject. This rule applies when the sentence is about a task the reader performs.
+
 ### SDK guide file naming convention
 
 SDK guide files under `sdk/guides/` **must** use a category prefix:
@@ -151,3 +166,74 @@ SDK guide files under `sdk/guides/` **must** use a category prefix:
 - `convo-` for Conversation-related guides (e.g., `convo-async.mdx`, `convo-persistence.mdx`)
 
 Flag any new SDK guide that does not follow this naming convention.
+
+## Enterprise
+
+Apply these checks to changes under `enterprise/` and to the Enterprise tab in `docs.json`. Unless
+a change states something inaccurate, these are non-blocking: use `COMMENT` with a suggested rewrite.
+
+### Deployment positioning
+
+- Recommend **Docker Compose for trials and proofs of concept** and **Kubernetes (Helm) for
+  production**. Flag content that presents them differently.
+- Enterprise docs cover self-hosted options only. Flag content that offers OpenHands Cloud as a
+  deployment option.
+- The VM install is a last resort. Flag new content that suggests or links to it as a deployment
+  path. Existing VM install pages stay in the navigation.
+
+### Tone: inspire confidence
+
+- State a limitation once, in plain inline text. Flag caveats that repeat across sections or pages
+  (for example, a "use Kubernetes for production" reminder in the intro, a callout, and a closing
+  "Next steps" section on the same page).
+- Flag excessive `<Note>`, `<Warning>`, and `<Info>` blocks. Most information belongs in the body
+  text. Reserve callouts for something the reader would otherwise get wrong.
+
+### Keep instructions simple
+
+- Prefer the shortest path that works. For the Docker Compose install, that is
+  `git clone https://github.com/OpenHands/enterprise.git`, `cd enterprise`, and
+  `docker compose up --wait`. Flag version lookups, file downloads, or extra flags that add steps
+  without adding value.
+- Point readers at the product's own flows instead of describing every click. For example, "Open
+  `http://localhost:9043` and follow the onboarding flow to create your first user and configure
+  your LLM provider" beats deep links to sign-up URLs or instructions to open Settings.
+- Keep prerequisite lists short: name the tool or credential (Git, Docker and Docker Compose, an LLM
+  API key) without explaining it.
+- Verify Docker Compose and Helm claims (ports, variables, commands) against
+  [`OpenHands/enterprise`](https://github.com/OpenHands/enterprise).
+
+### Navigation
+
+- The Enterprise tab has six top-level sections. New pages must go in the section that matches
+  what the reader is doing:
+  - **Get Started**: learning what OpenHands Enterprise is and how it's built.
+  - **Deployment**: sizing and installing OpenHands Enterprise.
+  - **Configuration**: platform settings that apply to any install method, such as SSO, LLM
+    gateways, sandbox images, the database, and observability.
+  - **Integrations**: connecting third-party tools, such as source control, project management,
+    and Slack.
+  - **Features**: what users do in OpenHands Enterprise, such as conversations, automations,
+    skills and plugins, and organizations.
+  - **Administration**: troubleshooting and release notes.
+- Flag new top-level sections, pages added as long flat lists, and pages in an unrelated section.
+  Mintlify always expands top-level sections, so each one lengthens the sidebar for every reader.
+- In Deployment, the Sizing Guide comes first, followed by one nested group per install method.
+  - Pages that apply to a single install method go in that method's group. For example, Admin
+    Console settings belong in VM Install, and enabling automations with Helm belongs in
+    Kubernetes. Pages that apply to every install method go outside those groups.
+  - Order pages in an install method's group in the order the reader works through them.
+    Prerequisites (cloud provider setup, Sysbox, DNS and TLS) come before the install guide, and
+    day-2 pages (resource limits, automations, upgrades) come after it.
+  - Mark an experimental install method with `"tag": "Experimental"` on its group. Flag a separate
+    Experimental section.
+- Group related pages into nested groups, which Mintlify collapses by default. In Integrations,
+  group tools by category (Source Control, Project Management). A tool without a category, such as
+  Slack, stays a single page.
+- Flag new groups that list their overview page as a separate entry. Set the overview page as the
+  group's `root` instead.
+- Add new release notes at the top of the Release Notes group, so the newest version comes first.
+- Keep sidebar labels short enough to fit on one line. When a page title is long, add a
+  `sidebarTitle` to the frontmatter rather than shortening the page title (for example,
+  "Running Docker in the Agent Sandbox" uses `sidebarTitle: "Docker in the Sandbox"`). A label can
+  rely on its group for context, such as "Sysbox" in Kubernetes or "AWS" in VM Install.
diff --git a/.agents/skills/ohe-release-notes.md b/.agents/skills/ohe-release-notes.md
@@ -309,9 +309,11 @@ Released <Month Day, Year>.
 
 ### 7. Update navigation
 
-Add the new release page to `docs.json` under the Enterprise tab in a "Release Notes" group.
+Add the new release page to `docs.json` in the "Release Notes" group, which is nested in the
+Administration section of the Enterprise tab.
 
-**First time setup:** If there's no "Release Notes" group yet in the Enterprise tab, create one:
+**First time setup:** If there's no "Release Notes" group yet, create one at the end of the
+Administration section:
 
 ```json
 {
@@ -336,9 +338,6 @@ so the most recent release appears first in the navigation:
 }
 ```
 
-The "Release Notes" group should appear after the other Enterprise documentation groups (like
-"OpenHands Enterprise" and "Integrations") in the Enterprise tab navigation.
-
 ### 8. Commit
 
 ```bash

diff --git a/docs.json b/docs.json
@@ -431,17 +431,96 @@
         "tab": "Enterprise",
         "pages": [
           {
-            "group": "OpenHands Enterprise",
+            "group": "Get Started",
+            "pages": [
+              {
+                "group": "Why Enterprise",
+                "icon": "building",
+                "root": "enterprise/index",
+                "pages": [
+                  "enterprise/enterprise-vs-oss"
+                ]
+              },
+              "enterprise/architecture"
+            ]
+          },
+          {
+            "group": "Deployment",
             "pages": [
-              "enterprise/index",
-              "enterprise/enterprise-vs-oss",
-              "enterprise/architecture",
               "enterprise/sizing-guide",
+              {
+                "group": "Kubernetes",
+                "icon": "dharmachakra",
+                "root": "enterprise/k8s-install/index",
+                "pages": [
+                  {
+                    "group": "Cloud Providers",
+                    "icon": "cloud",
+                    "pages": [
+                      "enterprise/k8s-install/eks",
+                      "enterprise/k8s-install/aks",
+                      "enterprise/k8s-install/gke"
+                    ]
+                  },
+                  "enterprise/k8s-install/sysbox",
+                  "enterprise/k8s-install/dns-and-tls",
+                  "enterprise/k8s-install/installation",
+                  "enterprise/k8s-install/resource-limits",
+                  "enterprise/k8s-install/automations",
+                  "enterprise/k8s-install/upgrade-guidance"
+                ]
+              },
+              {
+                "group": "VM Install",
+                "icon": "server",
+                "pages": [
+                  "enterprise/vm-install/generic-vm",
+                  "enterprise/vm-install/aws",
+                  "enterprise/vm-install/google",
+                  "enterprise/vm-install/azure",
+                  "enterprise/vm-install/admin-console-configuration",
+                  "enterprise/vm-install/log-collection",
+                  "enterprise/vm-install/scaling"
+                ]
+              },
+              {
+                "group": "Compose",
+                "icon": "docker",
+                "tag": "Experimental",
+                "root": "enterprise/docker-compose",
+                "pages": [
+                  "enterprise/docker-compose/https",
+                  "enterprise/docker-compose/ngrok"
+                ]
+              }
+            ]
+          },
+          {
+            "group": "Configuration",
+            "pages": [
+              {
+                "group": "Authentication (SSO)",
+                "icon": "shield-check",
+                "pages": [
+                  "enterprise/integrations/saml-sso",
+                  "enterprise/integrations/saml-providers/authentik"
+                ]
+              },
+              {
+                "group": "LLM Gateways",
+                "icon": "route",
+                "root": "enterprise/integrations/external-llm-gateways",
+                "pages": [
+                  "enterprise/integrations/azure-llm-gateway",
+                  "enterprise/integrations/aws-bedrock-llm-gateway",
+                  "enterprise/integrations/google-llm-gateway"
+                ]
+              },
               {
                 "group": "Custom Sandbox Images",
                 "icon": "box",
+                "root": "enterprise/custom-sandbox-images/index",
                 "pages": [
-                  "enterprise/custom-sandbox-images/index",
                   "enterprise/custom-sandbox-images/building-custom-images",
                   "enterprise/custom-sandbox-images/multiple-images-warm-pools",
                   "enterprise/custom-sandbox-images/single-image-admin-console",
@@ -450,11 +529,43 @@
               },
               "enterprise/docker-in-sandbox",
               "enterprise/external-postgres",
-              "enterprise/troubleshooting"
+              {
+                "group": "Observability",
+                "icon": "chart-line",
+                "pages": [
+                  "enterprise/analytics",
+                  "enterprise/integrations/observability-platforms"
+                ]
+              }
             ]
           },
           {
-            "group": "Feature Guides",
+            "group": "Integrations",
+            "pages": [
+              "enterprise/integrations/overview",
+              {
+                "group": "Source Control",
+                "icon": "code-branch",
+                "pages": [
+                  "enterprise/integrations/github",
+                  "enterprise/integrations/gitlab",
+                  "enterprise/integrations/azure-devops",
+                  "enterprise/integrations/bitbucket-data-center"
+                ]
+              },
+              {
+                "group": "Project Management",
+                "icon": "list-check",
+                "pages": [
+                  "enterprise/integrations/jira-cloud",
+                  "enterprise/integrations/jira-data-center"
+                ]
+              },
+              "enterprise/integrations/slack"
+            ]
+          },
+          {
+            "group": "Features",
             "pages": [
               "enterprise/conversations-and-sandboxes",
               {
@@ -467,7 +578,6 @@
               },
               "enterprise/skills-and-plugins",
               "enterprise/plugin-marketplace",
-              "enterprise/analytics",
               {
                 "group": "Organizations",
                 "icon": "building",
@@ -479,7 +589,13 @@
                   "openhands/usage/cloud/organizations/settings",
                   "openhands/usage/cloud/organizations/budgets"
                 ]
-              },
+              }
+            ]
+          },
+          {
+            "group": "Administration",
+            "pages": [
+              "enterprise/troubleshooting",
               {
                 "group": "Release Notes",
                 "icon": "rocket",
@@ -501,73 +617,6 @@
                 ]
               }
             ]
-          },
-          {
-            "group": "Integrations",
-            "pages": [
-              "enterprise/integrations/overview",
-              "enterprise/integrations/github",
-              "enterprise/integrations/gitlab",
-              "enterprise/integrations/azure-devops",
-              "enterprise/integrations/bitbucket-data-center",
-              "enterprise/integrations/jira-cloud",
-              "enterprise/integrations/jira-data-center",
-              {
-                "group": "SAML SSO",
-                "icon": "shield-check",
-                "pages": [
-                  "enterprise/integrations/saml-sso",
-                  "enterprise/integrations/saml-providers/authentik"
-                ]
-              },
-              "enterprise/integrations/slack",
-              "enterprise/integrations/external-llm-gateways",
-              "enterprise/integrations/azure-llm-gateway",
-              "enterprise/integrations/aws-bedrock-llm-gateway",
-              "enterprise/integrations/google-llm-gateway",
-              "enterprise/integrations/observability-platforms"
-            ]
-          },
-          {
-            "group": "VM Install",
-            "pages": [
-              "enterprise/vm-install/generic-vm",
-              "enterprise/vm-install/aws",
-              "enterprise/vm-install/google",
-              "enterprise/vm-install/azure",
-              "enterprise/vm-install/admin-console-configuration",
-              "enterprise/vm-install/log-collection",
-              "enterprise/vm-install/scaling"
-            ]
-          },
-          {
-            "group": "K8s Install",
-            "pages": [
-              "enterprise/k8s-install/index",
-              "enterprise/k8s-install/installation",
-              "enterprise/k8s-install/automations",
-              "enterprise/k8s-install/sysbox",
-              "enterprise/k8s-install/dns-and-tls",
-              "enterprise/k8s-install/resource-limits",
-              "enterprise/k8s-install/upgrade-guidance",
-              "enterprise/k8s-install/eks",
-              "enterprise/k8s-install/aks",
-              "enterprise/k8s-install/gke"
-            ]
-          },
-          {
-            "group": "Experimental",
-            "pages": [
-              {
-                "group": "Docker Compose",
-                "icon": "docker",
-                "root": "enterprise/docker-compose",
-                "pages": [
-                  "enterprise/docker-compose/https",
-                  "enterprise/docker-compose/ngrok"
-                ]
-              }
-            ]
           }
         ]
       },

diff --git a/enterprise/conversations-and-sandboxes.mdx b/enterprise/conversations-and-sandboxes.mdx
@@ -1,5 +1,6 @@
 ---
 title: Conversations And Sandboxes
+sidebarTitle: "Conversations"
 description: Understand and manage conversation execution, sandbox placement, sharing, and lifecycle in OpenHands Enterprise.
 icon: boxes-stacked
 ---
@@ -144,7 +145,7 @@
 | --- | --- | --- |
 | `observability_span_name` | string | Creates a named child span under the root `conversation` span. Use stable, low-cardinality names for grouping and signal routing. |
 | `observability_tags` | string array | Adds tags to the conversation root observability span. |
 | `observability_metadata` | object | Adds trace-level metadata. Values must be scalars or homogeneous scalar arrays, such as strings, numbers, booleans, `string[]`, `number[]`, or `boolean[]`. |

 ```json
 {
@@ -158,10 +159,10 @@
    ],
    "run": true
  },
  "selected_repository": "yourorganization/yourrepository",
  "observability_span_name": "wb_rubric_eval",
  "observability_tags": ["wb-rubric", "evaluation"],
  "observability_metadata": {
    "evaluation": "wb",
    "attempt": 1,
    "replay": false

diff --git a/enterprise/custom-sandbox-images/building-custom-images.mdx b/enterprise/custom-sandbox-images/building-custom-images.mdx
@@ -1,5 +1,6 @@
 ---
 title: Building a Custom Sandbox Image
+sidebarTitle: "Building Images"
 description: How to build, version, and push a custom sandbox image for use with OpenHands Enterprise.
 icon: docker
 ---
@@ -91,11 +92,11 @@

 ## What to Bake In

 Good candidates for prebaking:

 - Pinned repository checkouts
 - Package manager caches and installed dependencies (`node_modules`, Python virtualenvs, etc.)
 - Compiled or transpiled output
 - Native system packages (`xvfb`, `libkrb5-dev`, `pkg-config`, etc.)
 - Browser or Electron artifacts
 - Stable helper scripts such as `prepare-*` and `*-verify` wrappers
@@ -163,7 +164,7 @@
 ```

 An accompanying `prepare-repo` script (fetches and fast-forwards without
 losing the prebaked dependency cache):

 ```bash
 #!/usr/bin/env bash
@@ -190,7 +191,7 @@

 **Helm installs:** use node-level registry access where available. An EKS
 node role with ECR read access can pull a private ECR image without a pull
 secret. Otherwise, create a pull secret in the sandbox namespace and add its
 name to the runtime-api `RUNTIME_IMAGE_PULL_SECRETS` environment variable
 (comma-separated list of secret names). Verify that the custom warm pod
 reaches `Ready` before selecting the image.
diff --git a/enterprise/custom-sandbox-images/multiple-images-warm-pools.mdx b/enterprise/custom-sandbox-images/multiple-images-warm-pools.mdx
@@ -1,5 +1,6 @@
 ---
 title: Configuring Custom Sandbox Images
+sidebarTitle: "Multiple Images"
 description: Configure custom sandbox images through the Runtime API, each kept ready in its own warm pool and independently selectable by users.
 icon: layer-group
 ---
@@ -22,7 +23,7 @@
 2. **Register images via the API.** Use the helper script below to give each
   image a name and tell OpenHands where to pull it from. OpenHands pulls the
   image from the registry you specify and keeps a pool of ready sandboxes for
   it. No restarts or redeployments are needed — new images become available
   within about a minute.

 3. **Users choose their environment.** Each registered image appears in the
@@ -168,7 +169,7 @@
  </Tab>
  <Tab title="Helm">
    The [Kubernetes installation guide](/enterprise/k8s-install/installation#step-3-configure-values)
    enables Runtime API ingress. Use its configured hostname and read the
    admin password from the secret created in Step 1:

    ```bash
@@ -209,7 +210,7 @@
  `/api/warm-runtime-configs`. Export `API_KEY` explicitly if you would
  rather skip the extra login round trip on reads. See the plugin's
  [`SKILL.md`](https://github.com/OpenHands/extensions/blob/main/plugins/runtime-api-configs/SKILL.md)
  for the full subcommand reference.
 </Note>

 ---
@@ -218,7 +219,7 @@

 Do not write configurations from scratch. The default configuration contains
 install-specific values (callback URLs, CA bundles, workspace paths) that
 sandboxes need to function. The CLI's `template` subcommand fetches an
 existing configuration, strips the identity fields, and lets you override the
 image and pool size in one step.

@@ -271,7 +272,7 @@
 | `run_as_user` | integer | No | Copy from the installer default so warm pods match application start requests |
 | `run_as_group` | integer | No | Copy from the installer default so warm pods match application start requests |
 | `fs_group` | integer | No | Copy from the installer default so warm pods match application start requests |
 | `fuse_s3_mount` | boolean | No | Use the fusey S3 workspace instead of a PVC. Copy from the installer default when unsure — most installs do not set it. |

 The configuration name comes from the URL path (the `save <name>` argument),
 not the body. A `source` field appears in list responses (`file` for
@@ -493,15 +494,15 @@

 ## Advanced: bootstrap from Kubernetes

 The CLI's `bootstrap` subcommand pulls `RUNTIME_API_URL`, `API_KEY`, and
 `ADMIN_PASSWORD` from Kubernetes secrets in one step. It is optional — the
 HTTPS-only flow in Step 2 is preferred for interactive administration. Use
 `bootstrap` when you have `kubectl` access anyway and want a single
 one-liner for a CI job or an operator runbook.

 <Tabs>
  <Tab title="VM Install">
    The Replicated embedded k0s cluster stores its kubeconfig at
    `/var/lib/k0s/pki/admin.conf`, which is root-owned. Run under `sudo -E`
    so the CLI's `kubectl` calls can read it:


diff --git a/enterprise/custom-sandbox-images/single-image-admin-console.mdx b/enterprise/custom-sandbox-images/single-image-admin-console.mdx
@@ -1,5 +1,6 @@
 ---
 title: Single Image via Admin Console
+sidebarTitle: "Admin Console"
 description: Configure a single custom sandbox image for the whole installation through the Replicated Admin Console.
 icon: triangle-exclamation
 ---