From e09f2523b9a37378f0ea25d9666fd418792743a7 Mon Sep 17 00:00:00 2001 From: Joe Laverty Date: Tue, 27 Oct 2026 09:18:18 -0400 Subject: [PATCH 1/7] Reorganize enterprise nav and shorten sidebar labels --- .agents/skills/code-review.md | 62 ++++++ docs.json | 202 +++++++++++------- enterprise/conversations-and-sandboxes.mdx | 1 + .../building-custom-images.mdx | 1 + .../multiple-images-warm-pools.mdx | 1 + .../single-image-admin-console.mdx | 1 + .../using-custom-images.mdx | 1 + enterprise/docker-in-sandbox.mdx | 1 + enterprise/enterprise-vs-oss.mdx | 1 + .../integrations/aws-bedrock-llm-gateway.mdx | 1 + enterprise/integrations/azure-llm-gateway.mdx | 1 + .../integrations/google-llm-gateway.mdx | 1 + .../integrations/observability-platforms.mdx | 1 + enterprise/integrations/overview.mdx | 1 + enterprise/k8s-install/automations.mdx | 1 + enterprise/k8s-install/installation.mdx | 1 + enterprise/k8s-install/sysbox.mdx | 1 + .../admin-console-configuration.mdx | 1 + enterprise/vm-install/aws.mdx | 1 + enterprise/vm-install/azure.mdx | 1 + enterprise/vm-install/generic-vm.mdx | 1 + enterprise/vm-install/google.mdx | 1 + enterprise/vm-install/scaling.mdx | 1 + .../configuring-organizations.mdx | 1 + .../cloud/organizations/managing-members.mdx | 1 + .../usage/cloud/organizations/overview.mdx | 1 + .../usage/cloud/organizations/settings.mdx | 1 + 27 files changed, 212 insertions(+), 77 deletions(-) diff --git a/.agents/skills/code-review.md b/.agents/skills/code-review.md index 4dbbe3214..55ae03bcc 100644 --- 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,50 @@ 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, at the end of the Deployment section. + +### 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 ``, ``, and `` 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 is organized into Get Started, Deployment, Configuration, Integrations, + Features, and Administration. New pages must go in the matching section. Flag pages added as + long flat lists or in an unrelated section. +- Group related pages into nested groups, which Mintlify collapses by default. When a group has an + overview page, set it as the group's `root` instead of listing it as a separate page. +- 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"`). diff --git a/docs.json b/docs.json index 1158637af..4132589d8 100644 --- a/docs.json +++ b/docs.json @@ -433,17 +433,95 @@ "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": [ + { + "group": "Docker Compose", + "icon": "docker", + "root": "enterprise/docker-compose", + "pages": [ + "enterprise/docker-compose/ngrok", + "enterprise/docker-compose/https" + ] + }, + { + "group": "Kubernetes", + "icon": "dharmachakra", + "root": "enterprise/k8s-install/index", + "pages": [ + "enterprise/sizing-guide", + "enterprise/k8s-install/installation", + "enterprise/k8s-install/sysbox", + "enterprise/k8s-install/dns-and-tls", + "enterprise/k8s-install/resource-limits", + "enterprise/k8s-install/automations", + "enterprise/k8s-install/upgrade-guidance", + { + "group": "Cloud Providers", + "icon": "cloud", + "pages": [ + "enterprise/k8s-install/eks", + "enterprise/k8s-install/aks", + "enterprise/k8s-install/gke" + ] + } + ] + }, + { + "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": "Configuration", "pages": [ - "enterprise/index", - "enterprise/enterprise-vs-oss", - "enterprise/architecture", - "enterprise/sizing-guide", + { + "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", @@ -452,11 +530,43 @@ }, "enterprise/docker-in-sandbox", "enterprise/external-postgres", - "enterprise/troubleshooting" + { + "group": "Observability", + "icon": "chart-line", + "pages": [ + "enterprise/analytics", + "enterprise/integrations/observability-platforms" + ] + } + ] + }, + { + "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": "Feature Guides", + "group": "Features", "pages": [ "enterprise/conversations-and-sandboxes", { @@ -470,7 +580,6 @@ "enterprise/secrets-management", "enterprise/skills-and-plugins", "enterprise/plugin-marketplace", - "enterprise/analytics", { "group": "Organizations", "icon": "building", @@ -482,7 +591,13 @@ "openhands/usage/cloud/organizations/settings", "openhands/usage/cloud/organizations/budgets" ] - }, + } + ] + }, + { + "group": "Administration", + "pages": [ + "enterprise/troubleshooting", { "group": "Release Notes", "icon": "rocket", @@ -504,73 +619,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 index fec6f53a3..841285c20 100644 --- 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 --- diff --git a/enterprise/custom-sandbox-images/building-custom-images.mdx b/enterprise/custom-sandbox-images/building-custom-images.mdx index 1d0255640..ce68b560f 100644 --- 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 --- diff --git a/enterprise/custom-sandbox-images/multiple-images-warm-pools.mdx b/enterprise/custom-sandbox-images/multiple-images-warm-pools.mdx index dff95a01b..90336bfc6 100644 --- 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 --- diff --git a/enterprise/custom-sandbox-images/single-image-admin-console.mdx b/enterprise/custom-sandbox-images/single-image-admin-console.mdx index 0d97b00ba..a4281ecba 100644 --- 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 --- diff --git a/enterprise/custom-sandbox-images/using-custom-images.mdx b/enterprise/custom-sandbox-images/using-custom-images.mdx index ebf756224..ed7b75fda 100644 --- a/enterprise/custom-sandbox-images/using-custom-images.mdx +++ b/enterprise/custom-sandbox-images/using-custom-images.mdx @@ -1,5 +1,6 @@ --- title: Using Custom Images +sidebarTitle: "Using Images" description: How users select a custom sandbox image and how to target a specific image per conversation via the API. icon: play --- diff --git a/enterprise/docker-in-sandbox.mdx b/enterprise/docker-in-sandbox.mdx index 0dc4bef88..96ae56e76 100644 --- a/enterprise/docker-in-sandbox.mdx +++ b/enterprise/docker-in-sandbox.mdx @@ -1,5 +1,6 @@ --- title: Running Docker in the Agent Sandbox +sidebarTitle: "Docker in the Sandbox" description: Let agents run containers, Docker Compose, and image builds inside their isolated sandbox—safely, without privileged access to your cluster. icon: docker --- diff --git a/enterprise/enterprise-vs-oss.mdx b/enterprise/enterprise-vs-oss.mdx index 7f5c4f4cd..e092ea86f 100644 --- a/enterprise/enterprise-vs-oss.mdx +++ b/enterprise/enterprise-vs-oss.mdx @@ -1,5 +1,6 @@ --- title: Enterprise vs. Open Source +sidebarTitle: "Enterprise vs. OSS" description: Compare OpenHands Enterprise and Open Source offerings to choose the right option for your team icon: scale-balanced --- diff --git a/enterprise/integrations/aws-bedrock-llm-gateway.mdx b/enterprise/integrations/aws-bedrock-llm-gateway.mdx index d0a729bda..72ab15e3b 100644 --- a/enterprise/integrations/aws-bedrock-llm-gateway.mdx +++ b/enterprise/integrations/aws-bedrock-llm-gateway.mdx @@ -1,5 +1,6 @@ --- title: AWS Bedrock LLM Gateway +sidebarTitle: "AWS Bedrock" description: Connect Amazon Bedrock models through the OpenHands Enterprise LLM gateway. icon: cloud --- diff --git a/enterprise/integrations/azure-llm-gateway.mdx b/enterprise/integrations/azure-llm-gateway.mdx index 5debfa08d..367a39783 100644 --- a/enterprise/integrations/azure-llm-gateway.mdx +++ b/enterprise/integrations/azure-llm-gateway.mdx @@ -1,5 +1,6 @@ --- title: Azure LLM Gateway +sidebarTitle: "Azure" description: Connect Azure OpenAI and Azure AI Foundry models through the OpenHands Enterprise LLM gateway. icon: /enterprise/images/azure-logo.svg --- diff --git a/enterprise/integrations/google-llm-gateway.mdx b/enterprise/integrations/google-llm-gateway.mdx index ae4818bbe..a55d7b518 100644 --- a/enterprise/integrations/google-llm-gateway.mdx +++ b/enterprise/integrations/google-llm-gateway.mdx @@ -1,5 +1,6 @@ --- title: Google LLM Gateway +sidebarTitle: "Google" description: Connect Google AI Studio and Vertex AI models through the OpenHands Enterprise LLM gateway. icon: google --- diff --git a/enterprise/integrations/observability-platforms.mdx b/enterprise/integrations/observability-platforms.mdx index 425ccf6d0..d6590ef52 100644 --- a/enterprise/integrations/observability-platforms.mdx +++ b/enterprise/integrations/observability-platforms.mdx @@ -1,5 +1,6 @@ --- title: External Observability Platforms +sidebarTitle: "External Platforms" description: Send OpenHands Enterprise conversation traces to your own OTLP-compatible observability platform such as Langfuse, Honeycomb, or Tempo. icon: chart-line --- diff --git a/enterprise/integrations/overview.mdx b/enterprise/integrations/overview.mdx index dad7695b7..03cb44a2d 100644 --- a/enterprise/integrations/overview.mdx +++ b/enterprise/integrations/overview.mdx @@ -1,5 +1,6 @@ --- title: Integrations Overview +sidebarTitle: "Overview" description: Compare built-in integrations and MCP server integrations in OpenHands Enterprise, and see what each integration supports. icon: puzzle-piece --- diff --git a/enterprise/k8s-install/automations.mdx b/enterprise/k8s-install/automations.mdx index ce1d951ac..142a1a39d 100644 --- a/enterprise/k8s-install/automations.mdx +++ b/enterprise/k8s-install/automations.mdx @@ -1,5 +1,6 @@ --- title: Enable Automations with Helm +sidebarTitle: "Automations" description: Configure the OpenHands Enterprise automation service on a Kubernetes installation. icon: clock --- diff --git a/enterprise/k8s-install/installation.mdx b/enterprise/k8s-install/installation.mdx index 96ef9af43..cbba1b0a2 100644 --- a/enterprise/k8s-install/installation.mdx +++ b/enterprise/k8s-install/installation.mdx @@ -1,5 +1,6 @@ --- title: Install with Helm +sidebarTitle: "Install with Helm" description: End-to-end installation of OpenHands Enterprise on Kubernetes using Helm icon: ship --- diff --git a/enterprise/k8s-install/sysbox.mdx b/enterprise/k8s-install/sysbox.mdx index 70659f62f..fdddf02b0 100644 --- a/enterprise/k8s-install/sysbox.mdx +++ b/enterprise/k8s-install/sysbox.mdx @@ -1,5 +1,6 @@ --- title: Installing Sysbox +sidebarTitle: "Sysbox" description: Install the Sysbox runtime so agent sandboxes can run securely icon: cube --- diff --git a/enterprise/vm-install/admin-console-configuration.mdx b/enterprise/vm-install/admin-console-configuration.mdx index d08f96446..0a175275c 100644 --- a/enterprise/vm-install/admin-console-configuration.mdx +++ b/enterprise/vm-install/admin-console-configuration.mdx @@ -1,5 +1,6 @@ --- title: Admin Console Configuration +sidebarTitle: "Admin Console" description: Configure an OpenHands Enterprise VM deployment from the Replicated Admin Console. icon: sliders --- diff --git a/enterprise/vm-install/aws.mdx b/enterprise/vm-install/aws.mdx index 22d40e3d6..a1f3d07ff 100644 --- a/enterprise/vm-install/aws.mdx +++ b/enterprise/vm-install/aws.mdx @@ -1,5 +1,6 @@ --- title: AWS Quick Start +sidebarTitle: "AWS" description: Install OpenHands Enterprise on AWS using Terraform and the Replicated Admin Console. icon: aws --- diff --git a/enterprise/vm-install/azure.mdx b/enterprise/vm-install/azure.mdx index 1d2f450fb..c9a49238c 100644 --- a/enterprise/vm-install/azure.mdx +++ b/enterprise/vm-install/azure.mdx @@ -1,5 +1,6 @@ --- title: Azure Quick Start +sidebarTitle: "Azure" description: Provision an Azure Linux VM and install OpenHands Enterprise with Replicated, starting with Anthropic inference. icon: microsoft --- diff --git a/enterprise/vm-install/generic-vm.mdx b/enterprise/vm-install/generic-vm.mdx index 5f00b1a99..cb255bd06 100644 --- a/enterprise/vm-install/generic-vm.mdx +++ b/enterprise/vm-install/generic-vm.mdx @@ -1,5 +1,6 @@ --- title: Generic VM Quick Start +sidebarTitle: "Generic VM" description: Install OpenHands Enterprise on a Linux VM using the Replicated installer and Admin Console. icon: server --- diff --git a/enterprise/vm-install/google.mdx b/enterprise/vm-install/google.mdx index 2cc34ff85..11b7013aa 100644 --- a/enterprise/vm-install/google.mdx +++ b/enterprise/vm-install/google.mdx @@ -1,5 +1,6 @@ --- title: Google Cloud Quick Start +sidebarTitle: "Google Cloud" description: Install OpenHands Enterprise on Google Compute Engine with Replicated Embedded Cluster and configure Vertex AI. icon: google --- diff --git a/enterprise/vm-install/scaling.mdx b/enterprise/vm-install/scaling.mdx index 4559c7ddd..f15e6df06 100644 --- a/enterprise/vm-install/scaling.mdx +++ b/enterprise/vm-install/scaling.mdx @@ -1,5 +1,6 @@ --- title: Scaling the Cluster +sidebarTitle: "Scaling" description: Add machines to an OpenHands Enterprise VM deployment to increase capacity, and run sandboxes on dedicated machines. icon: server --- diff --git a/openhands/usage/cloud/organizations/configuring-organizations.mdx b/openhands/usage/cloud/organizations/configuring-organizations.mdx index 92852df52..aa89de006 100644 --- a/openhands/usage/cloud/organizations/configuring-organizations.mdx +++ b/openhands/usage/cloud/organizations/configuring-organizations.mdx @@ -1,5 +1,6 @@ --- title: Configuring Organizations +sidebarTitle: "Configuration" description: Settings that control the default organization, personal workspaces, and user provisioning, and how to move an existing installation to organizations. --- diff --git a/openhands/usage/cloud/organizations/managing-members.mdx b/openhands/usage/cloud/organizations/managing-members.mdx index e68a22b4e..e1a35023d 100644 --- a/openhands/usage/cloud/organizations/managing-members.mdx +++ b/openhands/usage/cloud/organizations/managing-members.mdx @@ -1,5 +1,6 @@ --- title: Managing Members +sidebarTitle: "Members" description: How to invite users and manage team members in your organization. --- diff --git a/openhands/usage/cloud/organizations/overview.mdx b/openhands/usage/cloud/organizations/overview.mdx index c77b2cd7b..202af961d 100644 --- a/openhands/usage/cloud/organizations/overview.mdx +++ b/openhands/usage/cloud/organizations/overview.mdx @@ -1,5 +1,6 @@ --- title: Organizations Overview +sidebarTitle: "Overview" description: Manage teams and collaborate with shared resources in OpenHands Cloud or OpenHands Enterprise. --- diff --git a/openhands/usage/cloud/organizations/settings.mdx b/openhands/usage/cloud/organizations/settings.mdx index 081c2c941..0c717faff 100644 --- a/openhands/usage/cloud/organizations/settings.mdx +++ b/openhands/usage/cloud/organizations/settings.mdx @@ -1,5 +1,6 @@ --- title: Organization Settings +sidebarTitle: "Settings" description: Configure shared resources and settings for your OpenHands organization. --- From 13998bf7285c1fcbd5422b6dd39a3a82747141d8 Mon Sep 17 00:00:00 2001 From: Joe Laverty Date: Tue, 27 Oct 2026 09:22:22 -0400 Subject: [PATCH 2/7] Keep docker compose in experimental nav group --- docs.json | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs.json b/docs.json index 4132589d8..a53d75092 100644 --- a/docs.json +++ b/docs.json @@ -449,15 +449,6 @@ { "group": "Deployment", "pages": [ - { - "group": "Docker Compose", - "icon": "docker", - "root": "enterprise/docker-compose", - "pages": [ - "enterprise/docker-compose/ngrok", - "enterprise/docker-compose/https" - ] - }, { "group": "Kubernetes", "icon": "dharmachakra", @@ -619,6 +610,20 @@ ] } ] + }, + { + "group": "Experimental", + "pages": [ + { + "group": "Docker Compose", + "icon": "docker", + "root": "enterprise/docker-compose", + "pages": [ + "enterprise/docker-compose/https", + "enterprise/docker-compose/ngrok" + ] + } + ] } ] }, From 09600f2ae90d2486a46ccdddb747c78da391a2dc Mon Sep 17 00:00:00 2001 From: Joe Laverty Date: Tue, 3 Nov 2026 08:04:06 -0500 Subject: [PATCH 3/7] Move sizing guide and cluster prep ahead of Helm install --- docs.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs.json b/docs.json index a53d75092..e714c4321 100644 --- a/docs.json +++ b/docs.json @@ -449,18 +449,12 @@ { "group": "Deployment", "pages": [ + "enterprise/sizing-guide", { "group": "Kubernetes", "icon": "dharmachakra", "root": "enterprise/k8s-install/index", "pages": [ - "enterprise/sizing-guide", - "enterprise/k8s-install/installation", - "enterprise/k8s-install/sysbox", - "enterprise/k8s-install/dns-and-tls", - "enterprise/k8s-install/resource-limits", - "enterprise/k8s-install/automations", - "enterprise/k8s-install/upgrade-guidance", { "group": "Cloud Providers", "icon": "cloud", @@ -469,7 +463,13 @@ "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" ] }, { From 3474b1d5d37867a450760e47ef9b031a5eae2730 Mon Sep 17 00:00:00 2001 From: Joe Laverty Date: Tue, 3 Nov 2026 08:09:13 -0500 Subject: [PATCH 4/7] Move docker compose into deployment nav group --- docs.json | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs.json b/docs.json index e714c4321..7d7cb5db9 100644 --- a/docs.json +++ b/docs.json @@ -484,6 +484,16 @@ "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" + ] } ] }, @@ -610,20 +620,6 @@ ] } ] - }, - { - "group": "Experimental", - "pages": [ - { - "group": "Docker Compose", - "icon": "docker", - "root": "enterprise/docker-compose", - "pages": [ - "enterprise/docker-compose/https", - "enterprise/docker-compose/ngrok" - ] - } - ] } ] }, From ac6f04e34b05e281e653451010685a01446798da Mon Sep 17 00:00:00 2001 From: Joe Laverty Date: Tue, 3 Nov 2026 08:22:48 -0500 Subject: [PATCH 5/7] Align code review nav rules with enterprise nav --- .agents/skills/code-review.md | 38 ++++++++++++++++++++++++++++------- 1 file changed, 31 insertions(+), 7 deletions(-) diff --git a/.agents/skills/code-review.md b/.agents/skills/code-review.md index 55ae03bcc..292295535 100644 --- a/.agents/skills/code-review.md +++ b/.agents/skills/code-review.md @@ -179,7 +179,7 @@ a change states something inaccurate, these are non-blocking: use `COMMENT` with - 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, at the end of the Deployment section. + path. Existing VM install pages stay in the navigation. ### Tone: inspire confidence @@ -205,11 +205,35 @@ a change states something inaccurate, these are non-blocking: use `COMMENT` with ### Navigation -- The Enterprise tab is organized into Get Started, Deployment, Configuration, Integrations, - Features, and Administration. New pages must go in the matching section. Flag pages added as - long flat lists or in an unrelated section. -- Group related pages into nested groups, which Mintlify collapses by default. When a group has an - overview page, set it as the group's `root` instead of listing it as a separate page. +- 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"`). + "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. From 1e12b57fd9bab4a8ea77180e2ce2ebfddd92f161 Mon Sep 17 00:00:00 2001 From: Joe Laverty Date: Tue, 3 Nov 2026 08:22:48 -0500 Subject: [PATCH 6/7] Point release notes skill at Administration section --- .agents/skills/ohe-release-notes.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/.agents/skills/ohe-release-notes.md b/.agents/skills/ohe-release-notes.md index 433bbe28f..3cca7c9b5 100644 --- a/.agents/skills/ohe-release-notes.md +++ b/.agents/skills/ohe-release-notes.md @@ -309,9 +309,11 @@ Released . ### 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 From 79c5883a720dd6a516668636705da13d5cf55aca Mon Sep 17 00:00:00 2001 From: Joe Laverty Date: Thu, 5 Nov 2026 14:28:19 -0500 Subject: [PATCH 7/7] Shorten secrets management title --- enterprise/secrets-management.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/enterprise/secrets-management.mdx b/enterprise/secrets-management.mdx index 6e1240c90..fca669623 100644 --- a/enterprise/secrets-management.mdx +++ b/enterprise/secrets-management.mdx @@ -1,5 +1,5 @@ --- -title: Enterprise Secrets Management +title: Secrets Management description: Store and use personal and organization-wide secrets in OpenHands Enterprise. icon: key ---