@@ -1,7 +1,29 @@
-# Documentation System Overview
+# OpenHands SDK Documentation Guidelines
 
-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.
+These instructions are ONLY for modifying the documentation associated with the agent SDK which mainly lives under the
+sdk folder.
 
+## Repository Structure
+
+Applicable files when modifying the agent SDK documentation:
+
+```
+docs/
+├── .openhands/microagents/sdk-guidelines.md     # Guidelines for changing SDK documentation (this file)
+├── .github/
+│   ├── scripts/
+│   │   └── sync_code_blocks.py # Code synchronization script
+│   └── workflows/              # CI/CD workflows
+├── sdk/                        # Agent SDK documentation
+│   ├── guides/                 # SDK tutorials and guides
+│   └── arch/                   # Architecture documentation
+└── docs.json                   # Mintlify navigation configuration
+```
+
+## Agent SDK 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
 
@@ -43,11 +65,12 @@ pattern = r'```python[^\n]*\s+(examples/[^\s]+\.py)\n(.*?)```'
 - Captures file path: `examples/01_standalone_sdk/02_custom_tools.py`
 - Captures code content between opening and closing ```
 
-
 ## MDX Documentation Format
 
 ### Standard Structure
-Documentation is deployed with Mintlify from GitHub. The files follow this pattern (see `docs/sdk/guides/custom-tools.mdx` and `docs/sdk/guides/mcp.mdx` as reference):
+
+Documentation is deployed with Mintlify from GitHub. The files follow this pattern 
+(see `docs/sdk/guides/custom-tools.mdx` and `docs/sdk/guides/mcp.mdx` as reference):
 
 1. **Frontmatter** - YAML metadata with title and description
 2. **Introduction** - Brief overview of the feature
@@ -170,7 +193,6 @@ This example is available on GitHub: [examples/01_standalone_sdk/02_custom_tools
 4. **Consistency**: Follow existing patterns
    - Use same icon/expandable syntax
    - Include "Running the Example" bash block
-   - Add <Note> component with GitHub link
    - Structure sections similarly to other guides
 
 5. **Testing**: Before committing documentation
@@ -213,6 +235,24 @@ 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.
+
+## 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
 
-You can check https://www.mintlify.com/docs for documentation on what our doc site supported.
+- For agent-sdk examples, ensure the file path in code blocks is correct
+- For short agent-sdk examples, you don't need `expandable` in example file
+- When you add new pages that need to refer to agent-sdk example script, you should create an empty block with correct block name (refer to the python example script correctly), then run `python .github/scripts/sync_code_blocks.py` to sync it