Merge branch 'main' into openhands-fix-issue-5803

docs/build.log

@@ -0,0 +1,108 @@
+
+> docs@0.0.0 build
+> docusaurus build
+
+[INFO] Website will be built for all these locales: 
+- en
+- fr
+- zh-Hans
+[INFO] [en] Creating an optimized production build...
+[webpackbar] ℹ Compiling Client
+[webpackbar] ℹ Compiling Server
+[webpackbar] ✔ Server: Compiled successfully in 15.10s
+[webpackbar] ✔ Client: Compiled successfully in 2.79m
+[WARNING] Docusaurus found broken anchors!
+
+Please check the pages of your site in the list below, and make sure you don't reference any anchor that does not exist.
+Note: it's possible to ignore broken anchors with the 'onBrokenAnchors' Docusaurus configuration, and let the build pass.
+
+Exhaustive list of all broken anchors found:
+- Broken anchor on source page path = /modules/usage/configuration-options:
+   -> linking to #api-keys (resolved as: /modules/usage/configuration-options#api-keys)
+   -> linking to #workspace (resolved as: /modules/usage/configuration-options#workspace)
+   -> linking to #debugging-and-logging (resolved as: /modules/usage/configuration-options#debugging-and-logging)
+   -> linking to #session-management (resolved as: /modules/usage/configuration-options#session-management)
+   -> linking to #trajectories (resolved as: /modules/usage/configuration-options#trajectories)
+   -> linking to #file-store (resolved as: /modules/usage/configuration-options#file-store)
+   -> linking to #task-management (resolved as: /modules/usage/configuration-options#task-management)
+   -> linking to #miscellaneous (resolved as: /modules/usage/configuration-options#miscellaneous)
+   -> linking to #aws-credentials (resolved as: /modules/usage/configuration-options#aws-credentials)
+   -> linking to #api-configuration (resolved as: /modules/usage/configuration-options#api-configuration)
+   -> linking to #custom-llm-provider (resolved as: /modules/usage/configuration-options#custom-llm-provider)
+   -> linking to #embeddings (resolved as: /modules/usage/configuration-options#embeddings)
+   -> linking to #message-handling (resolved as: /modules/usage/configuration-options#message-handling)
+   -> linking to #model-selection (resolved as: /modules/usage/configuration-options#model-selection)
+   -> linking to #retrying (resolved as: /modules/usage/configuration-options#retrying)
+   -> linking to #advanced-options (resolved as: /modules/usage/configuration-options#advanced-options)
+   -> linking to #microagent-configuration (resolved as: /modules/usage/configuration-options#microagent-configuration)
+   -> linking to #memory-configuration (resolved as: /modules/usage/configuration-options#memory-configuration)
+   -> linking to #llm-configuration-2 (resolved as: /modules/usage/configuration-options#llm-configuration-2)
+   -> linking to #actionspace-configuration (resolved as: /modules/usage/configuration-options#actionspace-configuration)
+   -> linking to #microagent-usage (resolved as: /modules/usage/configuration-options#microagent-usage)
+   -> linking to #sandbox-configuration-2 (resolved as: /modules/usage/configuration-options#sandbox-configuration-2)
+   -> linking to #execution (resolved as: /modules/usage/configuration-options#execution)
+   -> linking to #container-image (resolved as: /modules/usage/configuration-options#container-image)
+   -> linking to #networking (resolved as: /modules/usage/configuration-options#networking)
+   -> linking to #linting-and-plugins (resolved as: /modules/usage/configuration-options#linting-and-plugins)
+   -> linking to #dependencies-and-environment (resolved as: /modules/usage/configuration-options#dependencies-and-environment)
+   -> linking to #evaluation (resolved as: /modules/usage/configuration-options#evaluation)
+   -> linking to #confirmation-mode (resolved as: /modules/usage/configuration-options#confirmation-mode)
+   -> linking to #security-analyzer (resolved as: /modules/usage/configuration-options#security-analyzer)
+
+[SUCCESS] Generated static files in "build".
+[INFO] [fr] Creating an optimized production build...
+[webpackbar] ℹ Compiling Client
+[webpackbar] ℹ Compiling Server
+[webpackbar] ✔ Server: Compiled successfully in 12.21s
+[webpackbar] ✔ Client: Compiled successfully in 1.38m
+[WARNING] Docusaurus found broken anchors!
+
+Please check the pages of your site in the list below, and make sure you don't reference any anchor that does not exist.
+Note: it's possible to ignore broken anchors with the 'onBrokenAnchors' Docusaurus configuration, and let the build pass.
+
+Exhaustive list of all broken anchors found:
+- Broken anchor on source page path = /fr/modules/usage/configuration-options:
+   -> linking to #api-keys (resolved as: /fr/modules/usage/configuration-options#api-keys)
+   -> linking to #workspace (resolved as: /fr/modules/usage/configuration-options#workspace)
+   -> linking to #debugging-and-logging (resolved as: /fr/modules/usage/configuration-options#debugging-and-logging)
+   -> linking to #session-management (resolved as: /fr/modules/usage/configuration-options#session-management)
+   -> linking to #trajectories (resolved as: /fr/modules/usage/configuration-options#trajectories)
+   -> linking to #file-store (resolved as: /fr/modules/usage/configuration-options#file-store)
+   -> linking to #task-management (resolved as: /fr/modules/usage/configuration-options#task-management)
+   -> linking to #miscellaneous (resolved as: /fr/modules/usage/configuration-options#miscellaneous)
+   -> linking to #aws-credentials (resolved as: /fr/modules/usage/configuration-options#aws-credentials)
+   -> linking to #api-configuration (resolved as: /fr/modules/usage/configuration-options#api-configuration)
+   -> linking to #custom-llm-provider (resolved as: /fr/modules/usage/configuration-options#custom-llm-provider)
+   -> linking to #embeddings (resolved as: /fr/modules/usage/configuration-options#embeddings)
+   -> linking to #message-handling (resolved as: /fr/modules/usage/configuration-options#message-handling)
+   -> linking to #model-selection (resolved as: /fr/modules/usage/configuration-options#model-selection)
+   -> linking to #retrying (resolved as: /fr/modules/usage/configuration-options#retrying)
+   -> linking to #advanced-options (resolved as: /fr/modules/usage/configuration-options#advanced-options)
+   -> linking to #microagent-configuration (resolved as: /fr/modules/usage/configuration-options#microagent-configuration)
+   -> linking to #memory-configuration (resolved as: /fr/modules/usage/configuration-options#memory-configuration)
+   -> linking to #llm-configuration-2 (resolved as: /fr/modules/usage/configuration-options#llm-configuration-2)
+   -> linking to #actionspace-configuration (resolved as: /fr/modules/usage/configuration-options#actionspace-configuration)
+   -> linking to #microagent-usage (resolved as: /fr/modules/usage/configuration-options#microagent-usage)
+   -> linking to #sandbox-configuration-2 (resolved as: /fr/modules/usage/configuration-options#sandbox-configuration-2)
+   -> linking to #execution (resolved as: /fr/modules/usage/configuration-options#execution)
+   -> linking to #container-image (resolved as: /fr/modules/usage/configuration-options#container-image)
+   -> linking to #networking (resolved as: /fr/modules/usage/configuration-options#networking)
+   -> linking to #linting-and-plugins (resolved as: /fr/modules/usage/configuration-options#linting-and-plugins)
+   -> linking to #dependencies-and-environment (resolved as: /fr/modules/usage/configuration-options#dependencies-and-environment)
+   -> linking to #evaluation (resolved as: /fr/modules/usage/configuration-options#evaluation)
+   -> linking to #confirmation-mode (resolved as: /fr/modules/usage/configuration-options#confirmation-mode)
+   -> linking to #security-analyzer (resolved as: /fr/modules/usage/configuration-options#security-analyzer)
+- Broken anchor on source page path = /fr/modules/usage/getting-started:
+   -> linking to ./installation#setup (resolved as: /fr/modules/usage/installation#setup)
+- Broken anchor on source page path = /fr/modules/usage/llms:
+   -> linking to /fr/modules/usage/installation#start-the-app
+- Broken anchor on source page path = /fr/modules/usage/llms/azure-llms:
+   -> linking to /fr/modules/usage/installation#start-the-app
+- Broken anchor on source page path = /fr/modules/usage/llms/google-llms:
+   -> linking to /fr/modules/usage/installation#start-the-app
+
+[SUCCESS] Generated static files in "build/fr".
+[INFO] [zh-Hans] Creating an optimized production build...
+[webpackbar] ℹ Compiling Client
+[webpackbar] ℹ Compiling Server
+[webpackbar] ✔ Server: Compiled successfully in 12.00s

docs/modules/usage/prompting/repo-specific-customization.md

@@ -0,0 +1,83 @@
+# Repository-Specific Prompt Customization
+
+OpenHands provides two powerful ways to customize its behavior for specific repositories:
+
+1. `.openhands_instructions` file for repository-wide guidelines
+2. `.openhands` directory for custom micro-agents
+
+## The `.openhands_instructions` File
+
+The `.openhands_instructions` file is a simple text file placed in the root directory of your repository that provides repository-specific context and guidelines to OpenHands. This file's contents are automatically injected into the prompt when OpenHands processes issues or pull requests.
+
+### What to Include
+
+Your `.openhands_instructions` file can contain information like the following:
+
+1. **Repository Overview**: A brief description of your project's purpose and architecture
+2. **Directory Structure**: Key directories and their purposes
+3. **Development Guidelines**: Project-specific coding standards and practices
+4. **Testing Requirements**: How to run tests and what types of tests are required
+5. **Setup Instructions**: Steps needed to build and run the project
+
+### Example `.openhands_instructions` File
+
+Your `.openhands_instructions` file can contain information like the following:
+
+```plaintext
+This repository is a Python package that provides utilities for data processing.
+
+Key directories:
+- src/data_utils/: Core data processing modules
+- tests/: Test files organized by module
+- docs/: API documentation and usage guides
+
+Development setup:
+1. Create a virtual environment: python -m venv venv
+2. Activate: source venv/bin/activate (Linux/Mac) or venv\Scripts\activate (Windows)
+3. Install dev dependencies: pip install -e ".[dev]"
+
+Code guidelines:
+- Follow PEP 8 style guide
+- All new code must have type hints
+- Maintain 90% test coverage for new features
+- Document public APIs using Google docstring format
+
+Testing:
+- Run tests: pytest tests/
+- Run type checks: mypy src/
+- Run linting: flake8 src/
+
+Common gotchas:
+- The data_loader module requires pandas>=2.0
+- Test data files must be placed in tests/fixtures/
+- Large data operations should use chunked processing
+```
+
+### Best Practices
+
+1. **Keep Instructions Updated**: Regularly update the file as your project evolves
+2. **Be Specific**: Include specific paths, patterns, and requirements unique to your project
+3. **Document Dependencies**: List all tools and dependencies required for development
+4. **Include Examples**: Provide examples of good code patterns from your project
+5. **Specify Conventions**: Document naming conventions, file organization, and code style preferences
+
+## The `.openhands` Directory
+
+The `.openhands` directory allows you to create repository-specific micro-agents that extend OpenHands' capabilities for your project. For detailed information about creating and using micro-agents, please refer to the [Micro-Agents documentation](../micro-agents.md).
+
+## Using Both Features Together
+
+The `.openhands_instructions` file and `.openhands` directory complement each other:
+
+- Use `.openhands_instructions` for repository-wide guidelines and context
+- Use `.openhands` directory for specialized, task-specific agents
+
+For example:
+1. `.openhands_instructions` defines your project's overall structure and standards
+2. Custom micro-agents in `.openhands` handle specific tasks like testing, deployment, or domain-specific operations
+
+This combination allows OpenHands to:
+- Understand your project's context and requirements (via `.openhands_instructions`)
+- Handle specialized tasks effectively (via custom micro-agents)
+- Maintain consistency with your project's standards
+- Automate repository-specific workflows

docs/sidebars.ts

@@ -27,6 +27,11 @@ const sidebars: SidebarsConfig = {
           label: 'Micro-Agents',
           id: 'usage/micro-agents',
         },
+        {
+          type: 'doc',
+          label: 'Repository-Specific Customization',
+          id: 'usage/prompting/repo-specific-customization',
+        },
       ],
     },
     {