diff --git a/docs/modules/usage/how-to/gui-mode.md b/docs/modules/usage/how-to/gui-mode.md
index 483f8869e9eb..e2727e36deee 100644
--- a/docs/modules/usage/how-to/gui-mode.md
+++ b/docs/modules/usage/how-to/gui-mode.md
@@ -26,72 +26,77 @@ OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if it
- **Locally (OSS)**: The user directly inputs their GitHub token.
- **Online (SaaS)**: The token is obtained through GitHub OAuth authentication.
-#### Setting Up a Local GitHub Token
-
-1. **Generate a Personal Access Token (PAT)**:
+Setting Up a Local GitHub Token
+ 1. **Generate a Personal Access Token (PAT)**:
- Go to GitHub Settings > Developer Settings > Personal Access Tokens > Tokens (classic).
- Click "Generate new token (classic)".
- Required scopes:
- `repo` (Full control of private repositories)
- `workflow` (Update GitHub Action workflows)
- `read:org` (Read organization data)
-
-2. **Enter Token in OpenHands**:
+ 2. **Enter Token in OpenHands**:
- Click the Settings button (gear icon) in the top right.
- Navigate to the "GitHub" section.
- Paste your token in the "GitHub Token" field.
- Click "Save" to apply the changes.
+Organizational Token Policies
-If you're working with organizational repositories, additional setup may be required:
+ If you're working with organizational repositories, additional setup may be required:
-1. **Check Organization Requirements**:
+ 1. **Check Organization Requirements**:
- Organization admins may enforce specific token policies.
- Some organizations require tokens to be created with SSO enabled.
- Review your organization's [token policy settings](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization).
-
-2. **Verify Organization Access**:
+ 2. **Verify Organization Access**:
- Go to your token settings on GitHub.
- Look for the organization under "Organization access".
- If required, click "Enable SSO" next to your organization.
- Complete the SSO authorization process.
+OAuth Authentication (Online Mode)
-When using OpenHands in online mode, the GitHub OAuth flow:
+ When using OpenHands in online mode, the GitHub OAuth flow:
-1. Requests the following permissions:
+ 1. Requests the following permissions:
- Repository access (read/write)
- Workflow management
- Organization read access
-2. Authentication steps:
+ 2. Authentication steps:
- Click "Sign in with GitHub" when prompted.
- Review the requested permissions.
- Authorize OpenHands to access your GitHub account.
- If using an organization, authorize organization access if prompted.
-
-#### Troubleshooting
-
-Common issues and solutions:
-
-- **Token Not Recognized**:
- - Ensure the token is properly saved in settings.
- - Check that the token hasn't expired.
- - Verify the token has the required scopes.
- - Try regenerating the token.
-
-- **Organization Access Denied**:
- - Check if SSO is required but not enabled.
- - Verify organization membership.
- - Contact organization admin if token policies are blocking access.
-
-- **Verifying Token Works**:
- - The app will show a green checkmark if the token is valid.
- - Try accessing a repository to confirm permissions.
- - Check the browser console for any error messages.
- - Use the "Test Connection" button in settings if available.
+Troubleshooting
+
+ Common issues and solutions:
+
+ - **Token Not Recognized**:
+ - Ensure the token is properly saved in settings.
+ - Check that the token hasn't expired.
+ - Verify the token has the required scopes.
+ - Try regenerating the token.
+
+ - **Organization Access Denied**:
+ - Check if SSO is required but not enabled.
+ - Verify organization membership.
+ - Contact organization admin if token policies are blocking access.
+
+ - **Verifying Token Works**:
+ - The app will show a green checkmark if the token is valid.
+ - Try accessing a repository to confirm permissions.
+ - Check the browser console for any error messages.
+ - Use the "Test Connection" button in settings if available.
+
+
+