Add Organizations documentation for OpenHands Cloud

[jpelletier1]

• I have read and reviewed the documentation changes to the best of my ability.
• If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

Summary of changes

This PR adds documentation for the Organizations feature, which is a commercial feature available with an OpenHands Cloud subscription or OpenHands Enterprise.

New Documentation Pages

1. openhands/usage/cloud/organizations/overview.mdx

• Introduction to Organizations feature
• Key features: multiple users, shared credits, default LLM configuration, Git organization claiming
• Notes that it's a commercial feature
• Explains that conversations remain private by default

2. openhands/usage/cloud/organizations/managing-members.mdx

• How to invite users via email
• How to change user roles (Owner, Admin, Member)
• How to remove members from an organization

3. openhands/usage/cloud/organizations/roles-permissions.mdx

• Complete permissions table showing what each role can do
• Detailed role descriptions (Member, Admin, Owner)
• Private settings explanation (MCP servers, Secrets, API keys, Git settings, Slack)

4. openhands/usage/cloud/organizations/settings.mdx

• LLM configuration setup for organizations
• Credits management
• Git organization claiming process

Navigation Update

Updated docs.json to add a new "Organizations" group in the Cloud tab with a building icon, positioned after "OpenHands Cloud" and before "Settings".

---

This PR was created by an AI agent (OpenHands) on behalf of the user.

@jpelletier1 can click here to continue refining the PR

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	Apr 28, 2026, 12:23 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[jpelletier1]

@OpenHands move the "Organizations" section under "Cloud" tab to just above the "Automations" section

[openhands-ai]

I'm on it! jpelletier1 can track my progress at all-hands.dev

[openhands-ai]

Summary of Work

I successfully completed the requested navigation change for PR #479.

Request Completion Checklist:

• ✅ Moved the "Organizations" section in the Cloud tab
• ✅ Positioned it just above the "Automations" section
• ✅ Committed the change with appropriate commit message
• ✅ Pushed the update to the PR branch

Changes Made:

The "Organizations" group in docs.json was repositioned within the Cloud tab navigation.

Previous order:

1. OpenHands Cloud
2. Organizations ← was here
3. Settings
4. Integrations
5. Automations (BETA)

New order:

1. OpenHands Cloud
2. Settings
3. Integrations
4. Organizations ← moved here
5. Automations (BETA)

Conciseness:

The change was minimal and precise - only the navigation group order was modified in docs.json. No content files were altered, and no extraneous changes were introduced.

The update has been pushed to PR #479 and is now live on the branch.

[all-hands-bot]

The documentation structure is solid, but there are critical consistency issues with UI navigation instructions that will confuse users. The terminology switches between "Org Members" tab/link, "Members" tab, and "Organization" link across different pages without clear distinction.

[all-hands-bot]

Review Summary

Taste Rating: 🟡 Acceptable - Good structure and comprehensive coverage, but navigation instructions need consistency work

---

[CRITICAL ISSUES] (Must fix before merge)

• [managing-members.mdx, Lines 12, 27, 43] Inconsistent Terminology: Switches between "Org Members" tab, "Org Members" link, and "Members" tab without clear distinction
• [settings.mdx, Line 37] Inconsistent Terminology: Uses "Organization" link while other pages use "Org Members" or "Members"
• [managing-members.mdx, Lines 10-14] Unclear Navigation Flow: Steps don't clearly connect - clarify what happens when the profile icon is clicked

[IMPROVEMENT OPPORTUNITIES] (Should fix)

• [settings.mdx, Lines 64-67] Awkward Phrasing: "click `Claim` next to the Git organization to claim" is unclear - rephrase to explain the actual UI flow

[TESTING GAPS]

• [PR Description] No Local Preview Verification: The checkbox for running the docs site locally is unchecked, and there's no evidence (screenshots) that pages render correctly. For documentation changes, especially new pages, verify local rendering to catch broken links, formatting issues, or navigation problems.

---

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟡 MEDIUM

This is documentation-only, so there's no risk of breaking functionality. However:

• User confusion risk: Inconsistent UI navigation terminology across pages will frustrate users trying to follow the instructions
• Accuracy risk: Without local preview verification, there could be broken links, rendering issues, or navigation problems
• Commercial feature impact: This documents a commercial feature, so accuracy and clarity are important for customer experience

Recommendation: Fix the terminology inconsistencies by verifying the actual UI labels and using them consistently across all four organization documentation pages. Run mint dev locally to verify pages render correctly and all internal links work.

---

VERDICT:
❌ Needs rework - Fix the inconsistent terminology before merging

KEY INSIGHT:
Documentation must use precise, consistent terminology that matches the actual UI - switching between "Org Members", "Members", and "Organization" for the same UI element creates unnecessary friction for users trying to navigate the product.

---

Improve this review? If any feedback above seems incorrect or irrelevant to this repository, you can teach the reviewer to do better:

1. Add a .agents/skills/custom-codereview-guide.md file to your branch (or edit it if one already exists) with the /codereview trigger and the context the reviewer is missing (e.g., "Security concerns about X do not apply here because Y"). See the customization docs for the required frontmatter format.
2. Re-request a review - the reviewer reads guidelines from the PR branch, so your changes take effect immediately.
3. When your PR is merged, the guideline file goes through normal code review by repository maintainers.

Resolve with AI? Comment @openhands /iterate on this PR, or install the iterate skill in your own agent and run /iterate.

[openhands-ai]

I'm on it! all-hands-bot can track my progress at all-hands.dev

[all-hands-bot]

Review Feedback Addressed

All critical issues from the code review have been fixed in commits 312ab9c and 3dd9e26.

Changes Made

managing-members.mdx (commit 312ab9c):

• Inviting Users: Simplified flow — 'Hover over the profile icon → click Invite Organization Members' (uses the direct context menu button, matching the actual UI). Corrects the inaccurate label 'Invite Org Member' to the real button text 'Invite Organization Members'.
• Changing User Roles: Updated to 'Hover over profile icon → select Org Members' (consistent nav label).
• Removing Members: Fixed incorrect navigation ('organization's settings page' + 'Members tab') to 'Hover over profile icon → select Org Members'. Now all three sections use consistent terminology.

settings.mdx (commit 312ab9c):

• Managing Credits: Updated navigation to use hover pattern; corrected button label to + Add (actual UI text).
• Git Conversation Routing: Rephrased to 'Click Claim next to the Git organization you want to link'. Removed inaccurate steps (provider selection, org name entry, verification — these don't exist in the UI; organizations are listed automatically from connected GitHub/GitLab identities).
• Monitoring Usage: Changed backtick to bold for Organization nav label consistency.

roles-permissions.mdx (commit 3dd9e26):

• Fixed missing space before pipe character in the permissions table (line 21).

Note on 'Organization' vs 'Org Members'

The reviewer flagged these as inconsistent, but they are actually two distinct nav items in the OpenHands UI (verified against settings-nav.tsx):

• Organization → /settings/org (credits, org name, git routing)
• Org Members → /settings/org-members (member management)

Both labels are correct for their respective sections.

---

This comment was created by an AI agent (OpenHands) on behalf of the user.

[openhands-ai]

Summary of Work Done

All review feedback on PR #479 has been addressed. Here's a checklist of what was requested vs. what was completed:

Critical Issues (Must fix before merge)

• ✅ managing-members.mdx — Inconsistent Terminology: All three sections now consistently use "Org Members" (the actual nav item label from the UI). Previously the file switched between "Org Members tab", "Org Members link", and "Members tab" for the same element.

• ✅ settings.mdx — "Organization" link terminology: Verified against the OpenHands frontend source code (settings-nav.tsx) that "Organization" and "Org Members" are two distinct nav items pointing to different pages. No change was needed — both are correct in context. Thread resolved with explanation.

• ✅ managing-members.mdx — Unclear Navigation Flow: All three sections (Inviting, Changing Roles, Removing) now use a clear, consistent pattern: "Hover over the profile icon in the lower left — an account menu will appear." followed by the specific action. This also corrected an inaccurate button label ("Invite Org Member" → "Invite Organization Members", the real UI label).

Improvement Opportunities (Should fix)

• ✅ settings.mdx — Awkward Git Routing Phrasing: Rephrased to "Click Claim next to the Git organization you want to link to your OpenHands organization." Also removed 3 inaccurate steps (provider selection, org name entry, verification) that don't exist in the actual UI — organizations are listed automatically from connected GitHub/GitLab identities.

Bonus Fix (from review suggestion)

• ✅ roles-permissions.mdx — Missing space before pipe: Fixed the table formatting on line 21.

Conciseness

All changes are minimal and directly address the flagged issues. No extraneous changes were made.

Process

• Two commits pushed: 312ab9c and 3dd9e26
• All 5 unresolved review threads replied to and resolved on GitHub

[jpelletier1]

@mamoodi any chance I can get your 👁️ on this? Hoping to publish some initial docs on Orgs.

[all-hands-bot]

The documentation is well-structured and mostly clear. I've identified a few areas where navigation instructions are inconsistent or claims need verification. See inline comments for details.

[jpelletier1]

@OpenHands under the organization/settings page under "Monitoring Usage" remove "Credit usage over time" and "Usage breakdown by member". instead, reference the API "/api/organizations/{org_id}/members/financial"
for reporting on usage at a user level

[openhands-ai]

I'm on it! jpelletier1 can track my progress at all-hands.dev

[openhands-ai]

Summary of Work Done

I've successfully addressed the PR comment from @jpelletier1 on PR #479.

Request Completion Checklist:

• ✅ Removed "Credit usage over time" from the Monitoring Usage section
• ✅ Removed "Usage breakdown by member" from the Monitoring Usage section
• ✅ Added reference to the API endpoint /api/organizations/{org_id}/members/financial for user-level usage reporting
• ✅ Committed and pushed the changes to the PR branch

Changes Made:

File: openhands/usage/cloud/organizations/settings.mdx

The Monitoring Usage section was updated from a bullet list showing three items to a concise paragraph mentioning only the current credit balance, followed by API documentation for detailed user-level reporting.

Conciseness Check:

✅ The changes are minimal and focused — only the specific content requested was modified. No extraneous changes were made.

Commit: 7125bc1 — "Update Monitoring Usage section to reference financial API endpoint"

Resolved all recommendations