Update repo.md

.openhands/microagents/repo.md

@@ -1,7 +1,44 @@
-# Documentation System Overview
+# OpenHands Documentation Repository
 
-The documentation for this project follows a synchronized approach where code examples in the docs are automatically kept in sync with the actual example files in the agent-sdk repository.
+This repository contains the official documentation for OpenHands, including guides for the core application and the Agent SDK. The documentation is deployed using Mintlify and features an automated code synchronization system.
 
+## Repository Purpose
+
+- **OpenHands Docs**: User guides, tutorials, and reference documentation for OpenHands core application
+- **Agent SDK Docs**: Developer documentation for the OpenHands Agent SDK
+
+
+## Repository Structure
+
+```
+docs/
+├── .openhands/microagents/     # Repository microagents (like this file)
+├── .github/
+│   ├── scripts/
+│   │   └── sync_code_blocks.py # Code synchronization script
+│   └── workflows/              # CI/CD workflows
+├── openhands/                  # OpenHands core documentation
+│   └── usage/
+│       ├── microagents/        # Microagent documentation
+│       ├── cloud/              # Cloud service docs
+│       ├── settings/           # Settings documentation
+│       └── ...
+├── sdk/                        # Agent SDK documentation
+│   ├── guides/                 # SDK tutorials and guides
+│   └── arch/                   # Architecture documentation
+└── docs.json                   # Mintlify navigation configuration
+```
+
+### Key Files
+
+- **`docs.json`**: Mintlify configuration including navigation structure, theme, and redirects
+- **Microagent docs**: `openhands/usage/microagents/microagents-*.mdx`
+- **Sync script**: `.github/scripts/sync_code_blocks.py`
+- **This microagent**: `.openhands/microagents/repo.md`
+
+## Documentation System Overview
+
+The documentation follows a synchronized approach where code examples are automatically kept in sync with actual example files in the agent-sdk repository.
 
 ## Automatic Code Synchronization
 
@@ -213,6 +250,44 @@ name: Example Workflow
 on: [push]
 ```
 
-## Mintlify documentation
+## Mintlify Documentation
+
+You can check https://www.mintlify.com/docs for documentation on what our doc site supports.
+
+## Working with Microagent Documentation
+
+When modifying microagent-related documentation files:
+
+1. **Location**: Microagent documentation is in `openhands/usage/microagents/`
+2. **Navigation**: Update `docs.json` if adding new pages to the microagents section
+3. **Consistency**: Follow the existing structure in microagent documentation files
+4. **Cross-references**: Link between related microagent pages using relative paths
+5. **Examples**: Include practical examples with proper code blocks (non-synced)
+
+### Key Microagent Documentation Files
+
+- `microagents-overview.mdx`: Introduction and types of microagents
+- `microagents-repo.mdx`: General microagents (always loaded)
+- `microagents-keyword.mdx`: Keyword-triggered microagents
+- `microagents-org.mdx`: Organization and user microagents
+- `microagents-public.mdx`: Global microagents (contributing guide)
+
+## CI/CD Workflows
+
+### Code Synchronization Workflow
+- **File**: `.github/workflows/sync-docs-code-blocks.yml`
+- **Triggers**: Push to any branch, daily at 2 AM UTC, manual dispatch
+- **Purpose**: Keeps code blocks in sync with agent-sdk examples
+- **Actions**: Checks out both repositories, runs sync script, commits changes if needed
+
+### OpenAPI Sync Workflow
+- **File**: `.github/workflows/sync-agent-sdk-openapi.yml`
+- **Purpose**: Syncs OpenAPI specifications for API documentation
+
+## Notes for Contributors
 
-You can check https://www.mintlify.com/docs for documentation on what our doc site supported.
+- Microagents take up context window space - keep them focused and concise
+- Test keyword triggers to ensure they activate appropriately
+- For agent-sdk examples, ensure the file path in code blocks is correct
+- When adding new microagent types, update both the code and documentation
+- Remember: this repo.md file is itself a microagent example!