docs: Update Usage group with Best Practices and Custom Rules pages (#646)

* Apply patch [skip ci]

* Apply patch [skip ci]

* Apply patch [skip ci]

* Apply patch [skip ci]

* Apply patch [skip ci]

* Apply patch [skip ci]

* Empty commit to trigger CI

* cr

---------

Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
Co-authored-by: bracesproul <braceasproul@gmail.com>

apps/docs/docs.json

@@ -17,13 +17,16 @@
             "group": "Get Started",
             "pages": ["index"]
           },
-          {
-            "group": "Examples",
-            "pages": ["examples"]
-          },
           {
             "group": "Usage",
-            "pages": ["usage/intro", "usage/ui", "usage/github"]
+            "pages": [
+              "usage/intro",
+              "usage/ui",
+              "usage/github",
+              "usage/examples",
+              "usage/best-practices",
+              "usage/custom-rules"
+            ]
           },
           {
             "group": "Development Setup",

apps/docs/usage/best-practices.mdx

@@ -0,0 +1,83 @@
+---
+title: Best Practices
+description: Guidelines for effective use of Open SWE
+---
+
+# Best Practices
+
+Follow these guidelines to get the best results from Open SWE.
+
+## Prompting Tips
+
+### Be Clear and Direct
+
+- Include specific file paths and function names in your requests. Open SWE preforms best when its given a clear starting point.
+- Provide concrete examples of what you want to achieve. Describe the end state you want to reach so Open SWE knows what it's working towards.
+
+### Create Custom Rules
+
+Create an `AGENTS.md` file in your repository root to provide project-specific context. This helps Open SWE understand your codebase conventions and requirements.
+
+<Tip>
+  See the [Custom Rules](/labs/swe/usage/custom-rules) page for detailed guidance on
+  setting up your `AGENTS.md` file.
+</Tip>
+
+### Keep Tasks Well-Scoped
+
+- Focus on one specific feature or fix per request
+- Break large changes into smaller, manageable tasks
+- Avoid combining multiple unrelated changes in a single request
+
+### Avoid Multiple Tasks
+
+Submit separate requests for different features or fixes. This allows Open SWE to:
+
+- Generate more focused plans
+- Provide better error handling
+- Make changes easier to review
+
+## Model Selection
+
+- **Claude Sonnet 4 (Default)**: The default model for planning, writing code, and reviewing changes. This model offers the best balance of performance, speed and cost.
+- **Claude Opus 4**: A larger, more powerful model for difficult, or open-ended tasks. Opus 4 is more expensive and slower, but will provide better results for complex tasks.
+
+### Avoid Other Models
+
+Although Open SWE allows you to select any model from Anthropic, OpenAI and Google, its prompts are tuned specifically for Anthropic models, and other providers will not preform as well.
+
+## Mode Selection
+
+### `open-swe` vs `open-swe-max`
+
+**`open-swe`**: Uses Claude Sonnet 4
+
+- Suitable for most development tasks
+- Faster execution
+- Cost-effective
+
+**`open-swe-max`**: Uses Claude Opus 4 (only for the planning and code writing agents)
+
+- For complex tasks requiring advanced reasoning
+- Higher quality output for challenging problems
+- More expensive but better for difficult tasks
+
+### Auto vs Manual Labels
+
+**Auto Mode (`-auto` labels)**
+
+It's recommended to use the auto mode for most tasks. Open SWE is very good at planning, and in most cases it does not need a manual review before execution.
+
+If you're running Open SWE against an open-ended or very complex task, you may want to use manual mode to review the plan before execution.
+
+## Label Reference
+
+- `open-swe`: Manual mode with Sonnet 4
+- `open-swe-auto`: Auto mode with Sonnet 4
+- `open-swe-max`: Manual mode with Opus 4
+- `open-swe-max-auto`: Auto mode with Opus 4
+
+<Note>
+  In development environments, append `-dev` to all labels (e.g.,
+  `open-swe-dev`, `open-swe-auto-dev`).
+</Note>

apps/docs/usage/custom-rules.mdx

@@ -0,0 +1,165 @@
+---
+title: Custom Rules
+description: Configure Open SWE with project-specific rules using `AGENTS.md`
+---
+
+# Custom Rules
+
+Custom rules allow you to provide project-specific context and guidelines to Open SWE through a markdown file in your repository root.
+
+## Getting Started
+
+The easiest way to get started is to have Open SWE itself write this file for you! The Open SWE UI provides a "Generate `AGENTS.md`" quick action which will insert a predefined prompt into the input. This prompt has been designed to generate a well-formatted `AGENTS.md` file from the agent.
+
+![Quick Action Generate AGENTS.md](/images/quick_action_generate_agents_md.png)
+
+## What is `AGENTS.md`?
+
+`AGENTS.md` is a markdown file that tells Open SWE about your project's:
+
+- Coding standards and conventions
+- Repository structure and architecture
+- Dependencies and installation procedures
+- Testing frameworks and practices
+- Pull request formatting requirements
+
+## Why Use Custom Rules?
+
+Custom rules help Open SWE:
+
+- Follow your project's specific conventions
+- Understand your codebase architecture
+- Use the correct package managers and tools
+- Write tests that match your testing patterns
+- Generate properly formatted pull requests
+
+Without custom rules, Open SWE uses generic best practices that may not align with your project.
+
+## Supported Sections
+
+### `<general_rules>`
+
+Project-specific coding standards and conventions:
+
+- Package manager preferences (e.g., "Always use Yarn")
+- Code style requirements
+- Import/export patterns
+- Architectural guidelines
+- Common scripts, and how to run them
+
+Example: "Run `yarn test` to run tests", or "Run `yarn build` to build the project"
+
+### `<repository_structure>`
+
+Description of your codebase organization:
+
+- Monorepo vs single package structure
+- Key directories and their purposes
+- Package relationships and dependencies
+- Build system configuration
+
+Include context about where/how to create new files, apps, packages, etc. in this section.
+
+Example: "When creating new packages, place them inside the `packages` directory."
+
+### `<dependencies_and_installation>`
+
+Package management and setup instructions:
+
+- Package manager commands
+- Installation procedures
+- Key dependencies and their purposes
+- Workspace configuration details
+
+This section should include information about the package manager(s) used in the project, and how/where to install dependencies.
+
+Example: "Always install dependencies inside the specific app/package where they're used, never in the root `package.json` unless adding a resolution."
+
+### `<testing_instructions>`
+
+Testing framework and practices:
+
+- Test runner configuration (Jest, Vitest, etc.)
+- Test file naming conventions
+- How to run different test types
+- Testing best practices for your project (e.g. what types of tests to write)
+
+Example: "Always run `yarn test` after making changes."
+
+### `<pull_request_formatting>`
+
+PR creation and formatting guidelines:
+
+- Title and description templates
+- Required sections or checklists
+- Review process requirements
+- Linking conventions
+
+Example: "The pull request body should include a `Testing Steps` section which includes bullet points describing how to test the changes."
+
+## File Names
+
+Open SWE reads custom rules from these files (in order of precedence):
+
+1. `AGENTS.md` (recommended)
+2. `AGENT.md`
+3. `CLAUDE.md`
+4. `CURSOR.md`
+
+<Note>
+  Use `AGENTS.md` as the standard filename for consistency across projects.
+</Note>
+
+## Missing Sections
+
+If your custom rules file doesn't include XML section tags, the entire file content will be passed to the prompt inside a custom rules section.
+
+## Formatting Example
+
+If your custom rules file does include the proper XML section tags, only the content from inside the known tags will be passed to the system prompt.
+
+Known tags:
+- `<general_rules>`
+- `<repository_structure>`
+- `<dependencies_and_installation>`
+- `<testing_instructions>`
+- `<pull_request_formatting>`
+
+Each tag _must_ contain a proper closing tag. If a tag is missing a closing tag, the entire file content will be passed to the prompt inside a custom rules section.
+
+Here is an example showing what your `AGENTS.md` file should look like:
+
+```markdown
+<general_rules>
+
+- Always use Yarn as the package manager
+- Follow strict TypeScript practices
+- Use ESLint and Prettier for code quality
+  </general_rules>
+
+<repository_structure>
+This is a Yarn workspace monorepo with three main packages:
+
+- apps/web: Next.js frontend
+- apps/api: Express backend
+- packages/shared: Common utilities
+  </repository_structure>
+
+<dependencies_and_installation>
+Run `yarn install` from the repository root to install all dependencies.
+Key dependencies include React 18, TypeScript, and Jest for testing.
+</dependencies_and_installation>
+
+<testing_instructions>
+
+- Run `yarn test` for unit tests
+- Run `yarn test:e2e` for end-to-end tests
+- Test files use `.test.ts` extension
+- Use Jest with React Testing Library
+  </testing_instructions>
+
+<pull_request_formatting>
+PR titles should follow: "feat: description" or "fix: description"
+Include a brief description and link any related issues.
+</pull_request_formatting>
+```

apps/docs/usage/github.mdx

@@ -3,6 +3,10 @@ title: "From Github"
 description: "How to use Open SWE from Github"
 ---
 
+<Warning>
+  GitHub webhooks are _not_ available via the demo application. To use GitHub webhooks, you must set up your own instance of Open SWE following the [development setup guide](/labs/swe/setup/development).
+</Warning>
+
 # GitHub Webhook Integration
 
 Open SWE integrates seamlessly with GitHub through webhooks, allowing you to trigger automated code changes directly from GitHub issues. This provides a streamlined workflow where you can request code changes by simply adding labels to issues in repositories where Open SWE is installed.