diff --git a/docs-navigation-proposal.md b/docs-navigation-proposal.md
new file mode 100644
index 00000000..08607d04
--- /dev/null
+++ b/docs-navigation-proposal.md
@@ -0,0 +1,518 @@
+# OpenHands Documentation Navigation Restructure Proposal
+
+## Executive Summary
+
+This document proposes a restructured navigation for OpenHands documentation that aligns with Devin.ai's documentation structure. The key changes include:
+
+1. **Merging CLI and Web tabs** into a single "Documentation" section
+2. **Creating a new "Use Cases" tab** for tutorials and examples
+3. **Reorganizing content** into logical groupings similar to Devin's approach
+4. **Identifying gaps** that should be filled with new pages
+
+---
+
+## Current Structure Comparison
+
+### Devin.ai Documentation Tabs
+| Tab | Description |
+|-----|-------------|
+| **Documentation** | Main product documentation (Get Started, Guidelines, Onboarding, Working with Devin, Product Guides, Integrations, Admin) |
+| **Use Cases & Tutorials** | Examples, use cases, prompts, tutorials |
+| **API Reference** | REST API documentation with versions |
+| **Release Notes** | Product changelog |
+| **Enterprise** | Enterprise-specific features |
+
+### OpenHands Current Tabs
+| Tab | Description |
+|-----|-------------|
+| **Overview** | Introduction, quick start, FAQs, community |
+| **Web** | Cloud, Local GUI, REST API, settings, advanced config |
+| **CLI** | Installation, ways to run, cloud, extensions |
+| **SDK** | Python SDK documentation |
+
+---
+
+## Proposed New Navigation Structure
+
+### Tab 1: Getting Started
+*Mirrors Devin's "Get Started" section within Documentation*
+
+```
+Getting Started
+├── Introduction
+├── Quick Start
+├── First Projects
+├── FAQs
+├── Community
+└── Contributing
+```
+
+### Tab 2: Documentation
+*Merged CLI + Web with unified content*
+
+```
+Documentation
+├── Setup & Installation
+│   ├── OpenHands Cloud                    [EXISTING: openhands/usage/cloud/openhands-cloud]
+│   ├── Local Installation (CLI)           [EXISTING: openhands/usage/cli/installation]
+│   ├── Local GUI Setup                    [EXISTING: openhands/usage/run-openhands/local-setup]
+│   └── Configuration Options              [EXISTING: openhands/usage/advanced/configuration-options]
+│
+├── Running OpenHands
+│   ├── Terminal (TUI)                     [EXISTING: openhands/usage/cli/terminal]
+│   ├── Web Interface                      [EXISTING: openhands/usage/cli/web-interface]
+│   ├── Headless Mode                      [EXISTING: openhands/usage/cli/headless]
+│   ├── GUI Server                         [EXISTING: openhands/usage/cli/gui-server]
+│   └── IDE Integration (ACP)
+│       ├── Overview                       [EXISTING: openhands/usage/cli/ide/overview]
+│       ├── VS Code                        [EXISTING: openhands/usage/cli/ide/vscode]
+│       ├── JetBrains                      [EXISTING: openhands/usage/cli/ide/jetbrains]
+│       ├── Zed                            [EXISTING: openhands/usage/cli/ide/zed]
+│       └── Toad                           [EXISTING: openhands/usage/cli/ide/toad]
+│
+├── Integrations                           [Mirrors Devin's Integrations section]
+│   ├── Integrations Overview              [GAP: NEW PAGE NEEDED]
+│   ├── GitHub                             [EXISTING: openhands/usage/cloud/github-installation]
+│   ├── GitLab                             [EXISTING: openhands/usage/cloud/gitlab-installation]
+│   ├── Bitbucket                          [EXISTING: openhands/usage/cloud/bitbucket-installation]
+│   ├── Slack                              [EXISTING: openhands/usage/cloud/slack-installation]
+│   ├── Project Management
+│   │   ├── Jira                           [EXISTING: openhands/usage/cloud/project-management/jira-integration]
+│   │   └── Linear                         [EXISTING: openhands/usage/cloud/project-management/linear-integration]
+│   └── MCP Servers                        [EXISTING: openhands/usage/cli/mcp-servers]
+│
+├── Features & Configuration
+│   ├── Key Features                       [EXISTING: openhands/usage/key-features]
+│   ├── Skills (Microagents)
+│   │   ├── Overview                       [EXISTING: overview/skills]
+│   │   ├── Repository Skills              [EXISTING: overview/skills/repo]
+│   │   ├── Keyword Skills                 [EXISTING: overview/skills/keyword]
+│   │   ├── Organization Skills            [EXISTING: overview/skills/org]
+│   │   └── Public Skills                  [EXISTING: overview/skills/public]
+│   ├── Model Context Protocol (MCP)       [EXISTING: overview/model-context-protocol]
+│   ├── Repository Customization           [EXISTING: openhands/usage/customization/repository]
+│   └── Critic Extension                   [EXISTING: openhands/usage/cli/critic]
+│
+├── Settings                               [Unified settings section]
+│   ├── Application Settings               [EXISTING: openhands/usage/settings/application-settings]
+│   ├── LLM Settings                       [EXISTING: openhands/usage/settings/llm-settings]
+│   ├── Integrations Settings              [EXISTING: openhands/usage/settings/integrations-settings]
+│   ├── Secrets Settings                   [EXISTING: openhands/usage/settings/secrets-settings]
+│   ├── API Keys Settings                  [EXISTING: openhands/usage/settings/api-keys-settings]
+│   └── MCP Settings                       [EXISTING: openhands/usage/settings/mcp-settings]
+│
+├── Advanced Configuration
+│   ├── LLM Configuration
+│   │   ├── Overview                       [EXISTING: openhands/usage/llms/llms]
+│   │   └── Providers
+│   │       ├── OpenHands LLMs             [EXISTING: openhands/usage/llms/openhands-llms]
+│   │       ├── Azure                      [EXISTING: openhands/usage/llms/azure-llms]
+│   │       ├── Google                     [EXISTING: openhands/usage/llms/google-llms]
+│   │       ├── Groq                       [EXISTING: openhands/usage/llms/groq]
+│   │       ├── Local LLMs                 [EXISTING: openhands/usage/llms/local-llms]
+│   │       ├── LiteLLM Proxy              [EXISTING: openhands/usage/llms/litellm-proxy]
+│   │       ├── Moonshot                   [EXISTING: openhands/usage/llms/moonshot]
+│   │       ├── OpenAI                     [EXISTING: openhands/usage/llms/openai-llms]
+│   │       └── OpenRouter                 [EXISTING: openhands/usage/llms/openrouter]
+│   ├── Runtime Configuration
+│   │   ├── Overview                       [EXISTING: openhands/usage/runtimes/overview]
+│   │   └── Providers
+│   │       ├── Docker                     [EXISTING: openhands/usage/runtimes/docker]
+│   │       ├── Remote                     [EXISTING: openhands/usage/runtimes/remote]
+│   │       ├── Local                      [EXISTING: openhands/usage/runtimes/local]
+│   │       └── Third-Party
+│   │           ├── Modal                  [EXISTING: openhands/usage/runtimes/modal]
+│   │           ├── Daytona                [EXISTING: openhands/usage/runtimes/daytona]
+│   │           ├── Runloop                [EXISTING: openhands/usage/runtimes/runloop]
+│   │           └── E2B                    [EXISTING: openhands/usage/runtimes/e2b]
+│   ├── Custom Sandbox                     [EXISTING: openhands/usage/advanced/custom-sandbox-guide]
+│   └── Search Engine Setup                [EXISTING: openhands/usage/advanced/search-engine-setup]
+│
+├── Best Practices                         [Mirrors Devin's Essential Guidelines]
+│   ├── Prompting Best Practices           [EXISTING: openhands/usage/tips/prompting-best-practices]
+│   ├── When to Use OpenHands              [GAP: NEW PAGE NEEDED - mirrors Devin's "When to Use Devin"]
+│   ├── Writing Effective Instructions     [GAP: NEW PAGE NEEDED - mirrors "Instructing Devin Effectively"]
+│   └── Good vs Bad Instructions           [GAP: NEW PAGE NEEDED - mirrors Devin's examples]
+│
+├── Cloud Features                         [Cloud-specific features]
+│   ├── Cloud UI                           [EXISTING: openhands/usage/cloud/cloud-ui]
+│   ├── Cloud API                          [EXISTING: openhands/usage/cloud/cloud-api]
+│   └── CLI Cloud Mode                     [EXISTING: openhands/usage/cli/cloud]
+│
+├── Reference
+│   ├── Command Reference                  [EXISTING: openhands/usage/cli/command-reference]
+│   └── Resume Conversations               [EXISTING: openhands/usage/cli/resume]
+│
+└── Help
+    ├── Troubleshooting                    [EXISTING: openhands/usage/troubleshooting/troubleshooting]
+    └── Feedback                           [EXISTING: openhands/usage/troubleshooting/feedback]
+```
+
+### Tab 3: Use Cases
+*NEW TAB - Mirrors Devin's "Use Cases & Tutorials"*
+
+```
+Use Cases
+├── Overview                               [GAP: NEW PAGE NEEDED]
+├── Best Practices                         [GAP: NEW PAGE NEEDED]
+│
+├── Use Cases                              [GAP: NEW SECTION NEEDED]
+│   ├── Code Migrations                    [GAP: NEW PAGE NEEDED]
+│   ├── Test Coverage Improvement          [GAP: NEW PAGE NEEDED]
+│   ├── Bug Fixing & Debugging             [GAP: NEW PAGE NEEDED]
+│   ├── Documentation Generation           [GAP: NEW PAGE NEEDED]
+│   ├── Code Refactoring                   [GAP: NEW PAGE NEEDED]
+│   └── API Integration                    [GAP: NEW PAGE NEEDED]
+│
+├── Tutorials
+│   ├── First Projects                     [EXISTING: overview/first-projects - move here]
+│   ├── Building a REST API                [GAP: NEW PAGE NEEDED]
+│   ├── Adding Test Coverage               [GAP: NEW PAGE NEEDED]
+│   ├── Containerizing Applications        [GAP: NEW PAGE NEEDED]
+│   └── Frontend Development               [GAP: NEW PAGE NEEDED]
+│
+└── Prompt Library                         [GAP: NEW SECTION NEEDED]
+    ├── Testing & Refactoring              [GAP: NEW PAGE NEEDED]
+    ├── Data & Analysis                    [GAP: NEW PAGE NEEDED]
+    └── Web Development                    [GAP: NEW PAGE NEEDED]
+```
+
+### Tab 4: SDK / API Reference
+*Enhanced SDK section with REST API integrated*
+
+```
+SDK / API Reference
+├── Software Agent SDK                     [EXISTING: sdk/index]
+├── Getting Started                        [EXISTING: sdk/getting-started]
+├── FAQ                                    [EXISTING: sdk/faq]
+│
+├── Guides
+│   ├── Hello World                        [EXISTING: sdk/guides/hello-world]
+│   ├── Custom Tools                       [EXISTING: sdk/guides/custom-tools]
+│   ├── MCP Integration                    [EXISTING: sdk/guides/mcp]
+│   ├── Skills & Context                   [EXISTING: sdk/guides/skill]
+│   ├── Plugins                            [EXISTING: sdk/guides/plugins]
+│   ├── Persistence                        [EXISTING: sdk/guides/convo-persistence]
+│   ├── Context Condenser                  [EXISTING: sdk/guides/context-condenser]
+│   ├── Sub-Agent Delegation               [EXISTING: sdk/guides/agent-delegation]
+│   ├── Iterative Refinement               [EXISTING: sdk/guides/iterative-refinement]
+│   ├── Security & Action Confirmation     [EXISTING: sdk/guides/security]
+│   ├── Metrics Tracking                   [EXISTING: sdk/guides/metrics]
+│   ├── Observability & Tracing            [EXISTING: sdk/guides/observability]
+│   ├── Secret Registry                    [EXISTING: sdk/guides/secrets]
+│   ├── Hooks                              [EXISTING: sdk/guides/hooks]
+│   ├── Critic                             [EXISTING: sdk/guides/critic]
+│   ├── Agent Configurations
+│   │   ├── Custom Agent                   [EXISTING: sdk/guides/agent-custom]
+│   │   ├── Browser Use                    [EXISTING: sdk/guides/agent-browser-use]
+│   │   ├── ToM Agent                      [EXISTING: sdk/guides/agent-tom-agent]
+│   │   ├── Interactive Terminal           [EXISTING: sdk/guides/agent-interactive-terminal]
+│   │   └── Stuck Detector                 [EXISTING: sdk/guides/agent-stuck-detector]
+│   ├── Conversation Management
+│   │   ├── Async Conversations            [EXISTING: sdk/guides/convo-async]
+│   │   ├── Pause and Resume               [EXISTING: sdk/guides/convo-pause-and-resume]
+│   │   ├── Send Message While Running     [EXISTING: sdk/guides/convo-send-message-while-running]
+│   │   ├── Ask Agent                      [EXISTING: sdk/guides/convo-ask-agent]
+│   │   └── Custom Visualizer              [EXISTING: sdk/guides/convo-custom-visualizer]
+│   ├── LLM Configuration
+│   │   ├── Registry                       [EXISTING: sdk/guides/llm-registry]
+│   │   ├── Routing                        [EXISTING: sdk/guides/llm-routing]
+│   │   ├── Streaming                      [EXISTING: sdk/guides/llm-streaming]
+│   │   ├── Reasoning                      [EXISTING: sdk/guides/llm-reasoning]
+│   │   ├── Image Input                    [EXISTING: sdk/guides/llm-image-input]
+│   │   └── Error Handling                 [EXISTING: sdk/guides/llm-error-handling]
+│   ├── Agent Server
+│   │   ├── Overview                       [EXISTING: sdk/guides/agent-server/overview]
+│   │   ├── Local Server                   [EXISTING: sdk/guides/agent-server/local-server]
+│   │   ├── Docker Sandbox                 [EXISTING: sdk/guides/agent-server/docker-sandbox]
+│   │   ├── Apptainer Sandbox              [EXISTING: sdk/guides/agent-server/apptainer-sandbox]
+│   │   ├── API Sandbox                    [EXISTING: sdk/guides/agent-server/api-sandbox]
+│   │   ├── Cloud Workspace                [EXISTING: sdk/guides/agent-server/cloud-workspace]
+│   │   └── Custom Tools                   [EXISTING: sdk/guides/agent-server/custom-tools]
+│   └── GitHub Workflows
+│       ├── PR Review                      [EXISTING: sdk/guides/github-workflows/pr-review]
+│       ├── TODO Management                [EXISTING: sdk/guides/github-workflows/todo-management]
+│       └── Assign Reviews                 [EXISTING: sdk/guides/github-workflows/assign-reviews]
+│
+├── Architecture
+│   ├── Overview                           [EXISTING: sdk/arch/overview]
+│   ├── Design Principles                  [EXISTING: sdk/arch/design]
+│   ├── SDK Overview                       [EXISTING: sdk/arch/sdk]
+│   └── Components
+│       ├── Agent                          [EXISTING: sdk/arch/agent]
+│       ├── Agent Server                   [EXISTING: sdk/arch/agent-server]
+│       ├── Conversation                   [EXISTING: sdk/arch/conversation]
+│       ├── Tool System                    [EXISTING: sdk/arch/tool-system]
+│       ├── Events                         [EXISTING: sdk/arch/events]
+│       ├── Workspace                      [EXISTING: sdk/arch/workspace]
+│       ├── LLM                            [EXISTING: sdk/arch/llm]
+│       ├── MCP                            [EXISTING: sdk/arch/mcp]
+│       ├── Skill                          [EXISTING: sdk/arch/skill]
+│       ├── Condenser                      [EXISTING: sdk/arch/condenser]
+│       └── Security                       [EXISTING: sdk/arch/security]
+│
+├── Python API Reference
+│   ├── openhands.sdk.agent                [EXISTING: sdk/api-reference/openhands.sdk.agent]
+│   ├── openhands.sdk.conversation         [EXISTING: sdk/api-reference/openhands.sdk.conversation]
+│   ├── openhands.sdk.event                [EXISTING: sdk/api-reference/openhands.sdk.event]
+│   ├── openhands.sdk.llm                  [EXISTING: sdk/api-reference/openhands.sdk.llm]
+│   ├── openhands.sdk.security             [EXISTING: sdk/api-reference/openhands.sdk.security]
+│   ├── openhands.sdk.tool                 [EXISTING: sdk/api-reference/openhands.sdk.tool]
+│   ├── openhands.sdk.utils                [EXISTING: sdk/api-reference/openhands.sdk.utils]
+│   └── openhands.sdk.workspace            [EXISTING: sdk/api-reference/openhands.sdk.workspace]
+│
+└── REST API                               [Moved from Web tab]
+    └── OpenAPI Reference                  [EXISTING: openapi/openapi.json]
+```
+
+---
+
+## Gap Analysis
+
+### Devin Documentation Structure Overview
+
+Devin's Documentation section is organized into these key areas:
+
+| Section | Purpose |
+|---------|---------|
+| **Get Started** | Introduction, First Session, Tutorial Library |
+| **Essential Guidelines** | When to use, Effective instructions, Good vs bad examples, SDLC integration |
+| **Onboarding** | Repo setup, Indexing, VPN, Knowledge onboarding, AGENTS.md |
+| **Working with Agent** | Session tools, Slash commands, Ask mode, Advanced mode |
+| **Product Guides** | Knowledge, Session insights, Secrets, Playbooks, Deployments, Team management |
+| **Integrations** | All platform integrations (GitHub, Slack, Jira, etc.) |
+| **Admin** | Security, Billing, Common issues |
+
+---
+
+### 🔴 HIGH PRIORITY Gaps - Core Onboarding & Workflow
+
+These pages are **critical** for user success and enterprise adoption:
+
+| Missing Page | Devin Equivalent | Why It's Critical |
+|--------------|------------------|-------------------|
+| **Your First Session** | `/get-started/first-run` | Step-by-step guide for starting first session, understanding interface, @ mentions, slash commands. Currently only partially covered in `quickstart.mdx`. |
+| **SDLC Integration** | `/essential-guidelines/sdlc-integration` | How OpenHands fits into existing dev workflows (planning → dev → test → review → deploy). **Critical for enterprise adoption.** |
+| **Workspace & Session Tools** | `/work-with-devin/devin-session-tools` | Understanding IDE, Browser, Shell tools during sessions; how to take over tasks, monitor progress. **Users need this to understand the workspace.** |
+| **Repository Setup Guide** | `/onboard-devin/repo-setup` | Comprehensive guide for setting up lint commands, test commands, dependencies, environment variables. Current `repository.mdx` is incomplete. |
+
+#### Recommended New Pages (HIGH Priority)
+
+**1. Your First Session** (`overview/your-first-session.mdx`)
+```
+Content:
+- Understanding the OpenHands interface (Chat, Terminal, Browser, Code Editor)
+- Starting your first task
+- Monitoring agent progress
+- Taking over from the agent
+- Common first-task examples with sample prompts
+- Tips for successful first sessions
+```
+
+**2. SDLC Integration** (`openhands/usage/sdlc-integration.mdx`)
+```
+Content:
+- Overview: Where OpenHands fits in your development workflow
+- Planning phase: Codebase exploration, task scoping
+- Development phase: Delegating tasks, parallel execution
+- Testing phase: Running tests, generating test coverage
+- Code review: PR creation and automated review
+- Deployment: CI/CD integration
+- Best practices for team integration
+```
+
+**3. Workspace & Session Tools** (`openhands/usage/workspace-tools.mdx`)
+```
+Content:
+- Understanding the OpenHands workspace
+- Terminal/Shell usage and monitoring
+- Code editor integration
+- Browser tool for web testing
+- Progress tracking and session timeline
+- Taking over a session
+- Running your own commands
+- Best practices for collaboration
+```
+
+**4. Repository Setup Guide** (`openhands/usage/repo-setup.mdx` - enhance existing)
+```
+Content:
+- Setting up test commands
+- Setting up lint commands  
+- Configuring environment variables
+- Dependencies management
+- Custom setup scripts
+- Per-repo configuration
+- Troubleshooting common setup issues
+```
+
+---
+
+### 🟠 MEDIUM PRIORITY Gaps - Feature Documentation
+
+| Missing Page | Devin Equivalent | Description |
+|--------------|------------------|-------------|
+| **Playbooks / Reusable Prompts** | `/product-guides/creating-playbooks` | Reusable prompt templates for repeated tasks. Valuable for power users and teams. |
+| **Slash Commands** | `/work-with-devin/slash-commands` | Built-in command shortcuts (/plan, /review, /test). If OpenHands supports similar, needs documentation. |
+| **Ask Mode / Q&A Mode** | `/work-with-devin/ask-devin` | Lightweight mode for exploring codebase without making changes. Different interaction paradigm. |
+| **Session Insights / Analytics** | `/product-guides/session-insights` | Analytics and debugging for sessions. Helpful for troubleshooting and improvement. |
+| **Index a Repository** | `/onboard-devin/index-repo` | How the agent indexes and understands a codebase. Important for understanding capabilities. |
+| **Limitations & Best Fit Tasks** | (from `/get-started/devin-intro`) | Clear documentation of current limitations and what tasks work best. |
+
+#### Recommended New Pages (MEDIUM Priority)
+
+**5. Limitations & Best Fit Tasks** (`openhands/usage/tips/limitations.mdx`)
+```
+Content:
+- What OpenHands excels at (list with examples)
+- Current limitations (honest assessment)
+- Tasks to avoid or break down
+- How to scope tasks appropriately
+- Task complexity guidelines
+```
+
+**6. Playbooks / Reusable Prompts** (`openhands/usage/playbooks.mdx`)
+```
+Content:
+- What are playbooks?
+- Creating effective playbooks
+- Sharing playbooks with your team
+- Example playbooks for common tasks
+- Best practices for playbook design
+```
+
+---
+
+### 🟡 LOWER PRIORITY Gaps - Advanced Features
+
+| Missing Page | Devin Equivalent | Description |
+|--------------|------------------|-------------|
+| **Advanced Mode / Batch Sessions** | `/work-with-devin/advanced-mode` | Running multiple sessions in parallel |
+| **Deployments** | `/product-guides/deployment-capabilities` | How to deploy code the agent creates |
+| **PR Templates** | `/integrations/pr-templates` | Customizing PR format for agent-created PRs |
+| **VPN Configuration** | `/onboard-devin/vpn` | Connecting to private networks |
+| **Team Management** | `/product-guides/invite-team` | Team invitations and permissions (Cloud-specific) |
+| **Security Practices** | `/admin/security` | Security practices and compliance documentation |
+| **Billing & Usage** | `/admin/billing` | Pricing and usage information (Cloud-specific) |
+| **Common Issues** | `/admin/common-issues` | FAQ-style troubleshooting for common problems |
+
+---
+
+### Pages Already Created in This PR
+
+The following gap pages have already been created:
+
+| Page | Status |
+|------|--------|
+| ✅ Integrations Overview | `openhands/usage/integrations/overview.mdx` |
+| ✅ When to Use OpenHands | `openhands/usage/tips/when-to-use-openhands.mdx` |
+| ✅ Writing Effective Instructions | `openhands/usage/tips/effective-instructions.mdx` |
+| ✅ Good vs Bad Instructions | `openhands/usage/tips/good-vs-bad-instructions.mdx` |
+| ✅ Use Cases Overview | `use-cases/overview.mdx` |
+| ✅ Use Cases Best Practices | `use-cases/best-practices.mdx` |
+| ✅ Code Migrations Example | `use-cases/examples/code-migrations.mdx` |
+| ✅ Test Coverage Example | `use-cases/examples/test-coverage.mdx` |
+| ✅ Bug Fixing Example | `use-cases/examples/bug-fixing.mdx` |
+| ✅ Documentation Example | `use-cases/examples/documentation.mdx` |
+| ✅ Refactoring Example | `use-cases/examples/refactoring.mdx` |
+| ✅ API Integration Example | `use-cases/examples/api-integration.mdx` |
+| ✅ Tutorials (5 pages) | `use-cases/tutorials/*.mdx` |
+| ✅ Prompt Library (3 pages) | `use-cases/prompts/*.mdx` |
+
+### Pages Still Needed (Prioritized)
+
+| Priority | Page | Recommended Path |
+|----------|------|------------------|
+| 🔴 HIGH | Your First Session | `overview/your-first-session.mdx` |
+| 🔴 HIGH | SDLC Integration | `openhands/usage/sdlc-integration.mdx` |
+| 🔴 HIGH | Workspace & Session Tools | `openhands/usage/workspace-tools.mdx` |
+| 🔴 HIGH | Repository Setup Guide (enhanced) | `openhands/usage/repo-setup.mdx` |
+| 🟠 MEDIUM | Limitations & Best Fit Tasks | `openhands/usage/tips/limitations.mdx` |
+| 🟠 MEDIUM | Playbooks / Reusable Prompts | `openhands/usage/playbooks.mdx` |
+| 🟡 LOW | Security Practices | `openhands/usage/admin/security.mdx` |
+| 🟡 LOW | Common Issues | `openhands/usage/admin/common-issues.mdx` |
+
+---
+
+## CLI/Web Merge Strategy
+
+### Features Available in Both CLI and Web
+For these features, create a single unified page with platform-specific callouts:
+
+```markdown
+<Callout type="info" title="Platform Availability">
+This feature is available in both the CLI and Web interface.
+</Callout>
+```
+
+**Unified Features:**
+- MCP Configuration
+- LLM Settings
+- Secrets Management
+- Repository Customization
+- Headless Mode execution
+
+### CLI-Only Features
+Add callout indicating CLI exclusivity:
+
+```markdown
+<Callout type="note" title="CLI Only">
+This feature is currently only available in the OpenHands CLI.
+</Callout>
+```
+
+**CLI-Only Features:**
+- Terminal (TUI) mode
+- IDE Integration (ACP)
+- Command reference
+- Resume conversations
+- Critic extension
+
+### Web/Cloud-Only Features
+Add callout indicating Web/Cloud exclusivity:
+
+```markdown
+<Callout type="note" title="Cloud/Web Only">
+This feature is only available in OpenHands Cloud or the Local GUI.
+</Callout>
+```
+
+**Web/Cloud-Only Features:**
+- Cloud UI interface
+- Cloud API
+- Slack integration
+- Project management integrations (Jira, Linear)
+- GitHub/GitLab/Bitbucket deep integrations
+
+---
+
+## Proposed docs.json Configuration
+
+See the `docs-navigation-new.json` file for the complete Mintlify configuration.
+
+---
+
+## Implementation Notes
+
+### Phase 1: Restructure Navigation
+1. Update `docs.json` with new tab structure
+2. Move existing pages to new locations (using redirects)
+3. Add platform availability callouts to merged pages
+
+### Phase 2: Fill High-Priority Gaps
+1. Create Integrations Overview page
+2. Create "When to Use OpenHands" page
+3. Create "Writing Effective Instructions" page
+4. Create "Good vs Bad Instructions" page
+5. Create Use Cases Overview page
+
+### Phase 3: Add Use Cases Content
+1. Create tutorial content based on existing "First Projects"
+2. Add code migration examples
+3. Add test coverage tutorial
+4. Create prompt library section
+
+### Phase 4: Polish and Redirects
+1. Set up redirects for moved pages
+2. Update internal links
+3. Test navigation flow
diff --git a/docs.json b/docs.json
index 3738b767..514c25d8 100644
--- a/docs.json
+++ b/docs.json
@@ -20,108 +20,112 @@
   "navigation": {
     "tabs": [
       {
-        "tab": "Overview",
+        "tab": "Getting Started",
         "pages": [
           {
-            "group": "Overview",
+            "group": "Getting Started",
             "pages": [
               "overview/introduction",
               "overview/quickstart",
+              "overview/your-first-session",
               "overview/first-projects",
-              "overview/faqs",
-              "overview/community",
-              "overview/contributing"
-            ]
-          },
-          {
-            "group": "Common Features",
-            "pages": [
-              "overview/model-context-protocol",
-              {
-                "group": "Skills",
-                "pages": [
-                  "overview/skills",
-                  "overview/skills/repo",
-                  "overview/skills/keyword",
-                  "overview/skills/org",
-                  "overview/skills/public"
-                ]
-              }
+              "overview/faqs"
             ]
           },
           {
-            "group": "Tips and Tricks",
+            "group": "Best Practices",
             "pages": [
-              "openhands/usage/tips/prompting-best-practices"
+              "openhands/usage/tips/prompting-best-practices",
+              "openhands/usage/tips/when-to-use-openhands",
+              "openhands/usage/tips/effective-instructions",
+              "openhands/usage/tips/good-vs-bad-instructions",
+              "openhands/usage/tips/limitations"
             ]
           },
           {
-            "group": "Help",
+            "group": "Community",
             "pages": [
-              "openhands/usage/troubleshooting/troubleshooting",
-              "openhands/usage/troubleshooting/feedback"
+              "overview/community",
+              "overview/contributing"
             ]
           }
         ]
       },
       {
-        "tab": "Web",
+        "tab": "Documentation",
         "pages": [
           {
-            "group": "Key Features",
+            "group": "Setup & Installation",
             "pages": [
-              "openhands/usage/key-features"
+              "openhands/usage/cli/installation",
+              "openhands/usage/run-openhands/local-setup",
+              "openhands/usage/advanced/configuration-options"
             ]
           },
           {
-            "group": "OpenHands Cloud",
+            "group": "Running OpenHands",
             "pages": [
-              "openhands/usage/cloud/openhands-cloud",
               {
-                "group": "Integrations",
+                "group": "Terminal (TUI)",
                 "pages": [
-                  "openhands/usage/cloud/bitbucket-installation",
-                  "openhands/usage/cloud/github-installation",
-                  "openhands/usage/cloud/gitlab-installation",
-                  "openhands/usage/cloud/slack-installation",
-                  {
-                    "group": "Project Management Tools",
-                    "pages": [
-                      "openhands/usage/cloud/project-management/jira-integration"
-                    ]
-                  }
+                  "openhands/usage/cli/terminal",
+                  "openhands/usage/cli/web-interface",
+                  "openhands/usage/cloud/openhands-cloud"
                 ]
               },
-              "openhands/usage/cloud/cloud-ui",
-              "openhands/usage/cloud/cloud-api"
+              "openhands/usage/cli/local-gui",
+              "openhands/usage/cli/headless",
+              {
+                "group": "IDE Integration (ACP)",
+                "pages": [
+                  "openhands/usage/cli/ide/overview",
+                  "openhands/usage/cli/ide/vscode",
+                  "openhands/usage/cli/ide/jetbrains",
+                  "openhands/usage/cli/ide/zed",
+                  "openhands/usage/cli/ide/toad"
+                ]
+              }
             ]
           },
           {
-            "group": "Local GUI",
+            "group": "Integrations",
             "pages": [
-              "openhands/usage/run-openhands/local-setup",
-              "openhands/usage/run-openhands/gui-mode"
+              "openhands/usage/integrations/overview",
+              "openhands/usage/cli/mcp-servers"
             ]
           },
           {
-            "group": "REST API",
-            "openapi": "openapi/openapi.json"
-          },
-          {
-            "group": "Customizations & Settings",
+            "group": "Features & Configuration",
             "pages": [
+              "openhands/usage/key-features",
+              "openhands/usage/workspace-tools",
+              "openhands/usage/sdlc-integration",
+              "openhands/usage/repo-setup",
+              "openhands/usage/playbooks",
               {
-                "group": "OpenHands Settings",
+                "group": "Skills",
                 "pages": [
-                  "openhands/usage/settings/application-settings",
-                  "openhands/usage/settings/llm-settings",
-                  "openhands/usage/settings/integrations-settings",
-                  "openhands/usage/settings/secrets-settings",
-                  "openhands/usage/settings/api-keys-settings",
-                  "openhands/usage/settings/mcp-settings"
+                  "overview/skills",
+                  "overview/skills/repo",
+                  "overview/skills/keyword",
+                  "overview/skills/org",
+                  "overview/skills/public"
                 ]
               },
-              "openhands/usage/customization/repository"
+              "overview/model-context-protocol",
+              "openhands/usage/customization/repository",
+              "openhands/usage/cli/critic"
+            ]
+          },
+          {
+            "group": "Settings",
+            "pages": [
+              "openhands/usage/settings/application-settings",
+              "openhands/usage/settings/llm-settings",
+              "openhands/usage/settings/integrations-settings",
+              "openhands/usage/settings/secrets-settings",
+              "openhands/usage/settings/api-keys-settings",
+              "openhands/usage/settings/mcp-settings"
             ]
           },
           {
@@ -170,61 +174,97 @@
                   }
                 ]
               },
-              "openhands/usage/advanced/configuration-options",
               "openhands/usage/advanced/custom-sandbox-guide",
               "openhands/usage/advanced/search-engine-setup"
             ]
+          },
+          {
+            "group": "Reference",
+            "pages": [
+              "openhands/usage/cli/command-reference",
+              "openhands/usage/cli/resume"
+            ]
+          },
+          {
+            "group": "Help",
+            "pages": [
+              "openhands/usage/troubleshooting/troubleshooting",
+              "openhands/usage/troubleshooting/feedback"
+            ]
           }
         ]
       },
       {
-        "tab": "CLI",
+        "tab": "Use Cases",
         "pages": [
           {
-            "group": "Getting Started",
+            "group": "Overview",
             "pages": [
-              "openhands/usage/cli/installation",
-              "openhands/usage/cli/quick-start"
+              "use-cases/overview",
+              "use-cases/best-practices"
             ]
           },
           {
-            "group": "Ways to Run",
+            "group": "Use Cases",
             "pages": [
-              "openhands/usage/cli/terminal",
-              "openhands/usage/cli/headless",
-              "openhands/usage/cli/web-interface",
-              "openhands/usage/cli/gui-server",
-              {
-                "group": "IDE Integration (ACP)",
-                "pages": [
-                  "openhands/usage/cli/ide/overview",
-                  "openhands/usage/cli/ide/zed",
-                  "openhands/usage/cli/ide/toad",
-                  "openhands/usage/cli/ide/vscode",
-                  "openhands/usage/cli/ide/jetbrains"
-                ]
-              }
+              "use-cases/examples/code-migrations",
+              "use-cases/examples/test-coverage",
+              "use-cases/examples/bug-fixing",
+              "use-cases/examples/documentation",
+              "use-cases/examples/refactoring",
+              "use-cases/examples/api-integration"
             ]
           },
           {
-            "group": "Cloud",
+            "group": "Tutorials",
             "pages": [
-              "openhands/usage/cli/cloud"
+              "use-cases/tutorials/getting-started",
+              "use-cases/tutorials/rest-api",
+              "use-cases/tutorials/test-coverage",
+              "use-cases/tutorials/containerization",
+              "use-cases/tutorials/frontend-development"
             ]
           },
           {
-            "group": "Extensions",
+            "group": "Prompt Library",
             "pages": [
-              "openhands/usage/cli/mcp-servers",
-              "openhands/usage/cli/critic"
+              "use-cases/prompts/testing-refactoring",
+              "use-cases/prompts/data-analysis",
+              "use-cases/prompts/web-development"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "OpenHands Cloud",
+        "pages": [
+          {
+            "group": "Getting Started",
+            "pages": [
+              "openhands/usage/cloud/cloud-ui",
+              "openhands/usage/cloud/cloud-api",
+              "openhands/usage/cli/cloud"
             ]
           },
           {
-            "group": "Reference",
+            "group": "Integrations",
             "pages": [
-              "openhands/usage/cli/command-reference",
-              "openhands/usage/cli/resume"
+              "openhands/usage/cloud/github-installation",
+              "openhands/usage/cloud/gitlab-installation",
+              "openhands/usage/cloud/bitbucket-installation",
+              "openhands/usage/cloud/slack-installation",
+              {
+                "group": "Project Management",
+                "pages": [
+                  "openhands/usage/cloud/project-management/jira-integration",
+                  "openhands/usage/cloud/project-management/linear-integration"
+                ]
+              }
             ]
+          },
+          {
+            "group": "REST API",
+            "openapi": "openapi/openapi.json"
           }
         ]
       },
@@ -305,9 +345,9 @@
               {
                 "group": "GitHub Workflows",
                 "pages": [
-                  "sdk/guides/github-workflows/assign-reviews",
                   "sdk/guides/github-workflows/pr-review",
-                  "sdk/guides/github-workflows/todo-management"
+                  "sdk/guides/github-workflows/todo-management",
+                  "sdk/guides/github-workflows/assign-reviews"
                 ]
               }
             ]
@@ -411,6 +451,10 @@
       "source": "/usage/:slug*",
       "destination": "/openhands/usage/:slug*"
     },
+    {
+      "source": "/openhands/usage/cli/gui-server",
+      "destination": "/openhands/usage/cli/local-gui"
+    },
     {
       "source": "/openhands/usage/configuration-options",
       "destination": "/openhands/usage/advanced/configuration-options"
@@ -459,10 +503,6 @@
       "source": "/openhands/usage/prompting/microagents-public",
       "destination": "/openhands/usage/microagents/microagents-public"
     },
-    {
-      "source": "/openhands/usage/prompting/microagents-repo",
-      "destination": "/openhands/usage/microagents/microagents-repo"
-    },
     {
       "source": "/openhands/usage/installation",
       "destination": "/openhands/usage/quick-start"
@@ -580,4 +620,4 @@
       "destination": "/openhands/usage/cli/resume"
     }
   ]
-}
\ No newline at end of file
+}
diff --git a/openhands/usage/cli/gui-server.mdx b/openhands/usage/cli/local-gui.mdx
similarity index 99%
rename from openhands/usage/cli/gui-server.mdx
rename to openhands/usage/cli/local-gui.mdx
index cbbeebb1..5233c9c0 100644
--- a/openhands/usage/cli/gui-server.mdx
+++ b/openhands/usage/cli/local-gui.mdx
@@ -1,5 +1,5 @@
 ---
-title: GUI Server
+title: Local GUI
 description: Launch the full OpenHands web GUI using Docker
 ---
 
diff --git a/openhands/usage/cli/quick-start.mdx b/openhands/usage/cli/quick-start.mdx
index d0fe1dde..86030beb 100644
--- a/openhands/usage/cli/quick-start.mdx
+++ b/openhands/usage/cli/quick-start.mdx
@@ -12,7 +12,7 @@ The OpenHands CLI provides multiple ways to interact with the OpenHands AI agent
 | [Terminal (TUI)](/openhands/usage/cli/terminal) | `openhands` | Interactive development |
 | [Headless](/openhands/usage/cli/headless) | `openhands --headless` | Scripts & automation |
 | [Web Interface](/openhands/usage/cli/web-interface) | `openhands web` | Browser-based TUI |
-| [GUI Server](/openhands/usage/cli/gui-server) | `openhands serve` | Full web GUI |
+| [Local GUI](/openhands/usage/cli/local-gui) | `openhands serve` | Full web GUI |
 | [IDE Integration](/openhands/usage/cli/ide/overview) | `openhands acp` | Zed, VS Code, JetBrains |
 
 <iframe
diff --git a/openhands/usage/cli/web-interface.mdx b/openhands/usage/cli/web-interface.mdx
index 9d3e0fdc..d998cc75 100644
--- a/openhands/usage/cli/web-interface.mdx
+++ b/openhands/usage/cli/web-interface.mdx
@@ -93,7 +93,7 @@ Run the web interface on a shared server for team access:
 openhands web --host 0.0.0.0 --port 8080
 ```
 
-## Comparison: Web Interface vs GUI Server
+## Comparison: Web Interface vs Local GUI
 
 | Feature | `openhands web` | `openhands serve` |
 |---------|-----------------|-------------------|
@@ -105,5 +105,5 @@ openhands web --host 0.0.0.0 --port 8080
 ## See Also
 
 - [Terminal Mode](/openhands/usage/cli/terminal) - Direct terminal usage
-- [GUI Server](/openhands/usage/cli/gui-server) - Full web GUI with Docker
+- [Local GUI](/openhands/usage/cli/local-gui) - Full web GUI with Docker
 - [Command Reference](/openhands/usage/cli/command-reference) - All CLI options
diff --git a/openhands/usage/integrations/overview.mdx b/openhands/usage/integrations/overview.mdx
new file mode 100644
index 00000000..ec17e45d
--- /dev/null
+++ b/openhands/usage/integrations/overview.mdx
@@ -0,0 +1,76 @@
+---
+title: "Integrations Overview"
+sidebarTitle: "Overview"
+description: "Connect OpenHands to your existing tools and workflows"
+---
+
+# Integrations Overview
+
+OpenHands integrates with your existing development tools to fit seamlessly into your workflow.
+
+## Source Control
+
+Connect OpenHands to your repositories for seamless code management.
+
+<CardGroup cols={3}>
+  <Card title="GitHub" icon="github" href="/openhands/usage/cloud/github-installation">
+    Connect to GitHub repositories
+  </Card>
+  <Card title="GitLab" icon="gitlab" href="/openhands/usage/cloud/gitlab-installation">
+    Connect to GitLab repositories
+  </Card>
+  <Card title="Bitbucket" icon="bitbucket" href="/openhands/usage/cloud/bitbucket-installation">
+    Connect to Bitbucket repositories
+  </Card>
+</CardGroup>
+
+## Communication
+
+Stay connected with your team through integrated messaging platforms.
+
+<CardGroup cols={2}>
+  <Card title="Slack" icon="slack" href="/openhands/usage/cloud/slack-installation">
+    Interact with OpenHands from Slack
+  </Card>
+</CardGroup>
+
+## Project Management
+
+Track tasks and issues with your preferred project management tools.
+
+<CardGroup cols={2}>
+  <Card title="Jira" icon="jira" href="/openhands/usage/cloud/project-management/jira-integration">
+    Connect to Jira for issue tracking
+  </Card>
+  <Card title="Linear" icon="square-kanban" href="/openhands/usage/cloud/project-management/linear-integration">
+    Connect to Linear for project management
+  </Card>
+</CardGroup>
+
+## Extensions
+
+Extend OpenHands functionality with additional tools.
+
+<CardGroup cols={2}>
+  <Card title="MCP Servers" icon="plug" href="/openhands/usage/cli/mcp-servers">
+    Add Model Context Protocol servers
+  </Card>
+</CardGroup>
+
+## Platform Availability
+
+<Callout type="info" title="Integration Availability">
+Source control and project management integrations are available in **OpenHands Cloud**. 
+MCP server configuration is available in both the **CLI** and **Cloud** versions.
+</Callout>
+
+## Getting Started
+
+1. **Choose your platform**: Decide whether to use [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud) or [self-hosted](/openhands/usage/run-openhands/local-setup) deployment
+2. **Connect source control**: Link your GitHub, GitLab, or Bitbucket account
+3. **Add communication**: Enable Slack integration for team collaboration
+4. **Configure project management**: Connect Jira or Linear for issue tracking
+
+## API Integration
+
+For programmatic access, see our [Cloud API](/openhands/usage/cloud/cloud-api) documentation or the [REST API Reference](/api-reference).
diff --git a/openhands/usage/playbooks.mdx b/openhands/usage/playbooks.mdx
new file mode 100644
index 00000000..81b916e3
--- /dev/null
+++ b/openhands/usage/playbooks.mdx
@@ -0,0 +1,398 @@
+---
+title: Playbooks & Reusable Prompts
+description: Create and use reusable prompt templates for common tasks
+---
+
+## Overview
+
+Playbooks are reusable prompt templates that help you consistently execute common tasks. By creating playbooks, you can ensure quality, save time, and share best practices with your team.
+
+## What is a Playbook?
+
+A playbook is a structured prompt template that:
+- Defines a repeatable task
+- Includes necessary context
+- Specifies expected outcomes
+- Can be customized for specific use cases
+
+### Playbook vs. One-Off Prompt
+
+| One-Off Prompt | Playbook |
+|----------------|----------|
+| Written for immediate use | Designed for reuse |
+| Includes all context inline | Parameterized for flexibility |
+| Variable quality | Consistent structure |
+| Individual knowledge | Team-shared knowledge |
+
+## Creating Effective Playbooks
+
+### Basic Structure
+
+A good playbook includes:
+
+```markdown
+## [Playbook Name]
+
+### Purpose
+What this playbook accomplishes
+
+### Prerequisites
+- Required setup
+- Necessary files or access
+
+### Parameters
+- `{param1}`: Description
+- `{param2}`: Description
+
+### Prompt Template
+The actual prompt with parameters
+
+### Expected Outcome
+What success looks like
+
+### Verification Steps
+How to verify completion
+```
+
+### Example: Add API Endpoint Playbook
+
+```markdown
+## Add REST API Endpoint
+
+### Purpose
+Add a new REST API endpoint following project conventions
+
+### Prerequisites
+- Express.js route structure in place
+- Database models defined
+- Test framework configured
+
+### Parameters
+- `{resource}`: The resource name (e.g., "users", "products")
+- `{method}`: HTTP method (GET, POST, PUT, DELETE)
+- `{path}`: The endpoint path
+- `{description}`: What the endpoint does
+
+### Prompt Template
+Add a {method} endpoint at {path} for {resource}.
+
+Requirements:
+- Follow the existing route patterns in src/routes/
+- Add input validation using our validation middleware
+- Include proper error handling following patterns in src/utils/errors.js
+- Add corresponding test in src/tests/routes/
+- Update the API documentation in docs/api.md
+
+The endpoint should {description}.
+
+### Expected Outcome
+- New route handler in appropriate file
+- Input validation implemented
+- Error handling in place
+- Passing test coverage
+- Documentation updated
+
+### Verification Steps
+1. Run `npm test` - all tests pass
+2. Run `npm run lint` - no errors
+3. Manual test with curl/Postman
+4. Review generated documentation
+```
+
+## Common Playbook Templates
+
+### 1. Bug Fix Playbook
+
+```markdown
+## Bug Fix
+
+### Parameters
+- `{issue}`: Bug description or issue number
+- `{file}`: Affected file(s) if known
+- `{reproduction}`: Steps to reproduce
+
+### Prompt Template
+Fix the bug: {issue}
+
+Context:
+- Affected files: {file}
+- Reproduction steps: {reproduction}
+
+Requirements:
+1. First, reproduce the bug to confirm understanding
+2. Identify the root cause
+3. Implement the fix with minimal changes
+4. Add a regression test
+5. Verify existing tests still pass
+6. Document what was changed and why
+
+### Verification Steps
+1. Run the reproduction steps - bug no longer occurs
+2. Run `npm test` - all tests pass including new regression test
+3. Run `npm run lint` - no new warnings
+```
+
+### 2. Add Test Coverage Playbook
+
+```markdown
+## Add Test Coverage
+
+### Parameters
+- `{module}`: The module/file to test
+- `{coverage_target}`: Desired coverage percentage
+
+### Prompt Template
+Write comprehensive tests for {module} to achieve {coverage_target}% coverage.
+
+Requirements:
+1. Analyze the existing code to understand all code paths
+2. Write tests for:
+   - Happy path scenarios
+   - Edge cases
+   - Error conditions
+   - Boundary values
+3. Follow existing test patterns in the codebase
+4. Use meaningful test descriptions
+5. Avoid testing implementation details
+
+### Verification Steps
+1. Run coverage report: `npm run test:coverage`
+2. Verify {coverage_target}% coverage achieved
+3. Review tests for quality, not just quantity
+```
+
+### 3. Code Refactoring Playbook
+
+```markdown
+## Refactor Module
+
+### Parameters
+- `{target}`: File or function to refactor
+- `{goal}`: What improvement to achieve
+- `{pattern}`: Desired pattern or approach
+
+### Prompt Template
+Refactor {target} to {goal}.
+
+Use the {pattern} pattern where appropriate.
+
+Requirements:
+1. First, write tests for existing behavior if not present
+2. Make changes incrementally
+3. Ensure all existing tests pass after each change
+4. Improve code readability and maintainability
+5. Do not change external interfaces without discussion
+6. Document any non-obvious decisions
+
+### Verification Steps
+1. All existing tests pass
+2. No new lint warnings
+3. Code review checklist:
+   - [ ] Logic is correct
+   - [ ] Code is readable
+   - [ ] No duplication introduced
+   - [ ] Follows project patterns
+```
+
+### 4. Documentation Playbook
+
+```markdown
+## Add Documentation
+
+### Parameters
+- `{target}`: File or module to document
+- `{type}`: Type of documentation (JSDoc, README, API docs)
+
+### Prompt Template
+Add {type} documentation to {target}.
+
+Requirements:
+1. Document all public functions/methods
+2. Include:
+   - Description of purpose
+   - Parameter descriptions with types
+   - Return value description
+   - Example usage where helpful
+3. Follow existing documentation style in the codebase
+4. Keep explanations clear and concise
+
+### Verification Steps
+1. Documentation lint passes (if applicable)
+2. Generated docs render correctly
+3. Examples are accurate and runnable
+```
+
+### 5. Database Migration Playbook
+
+```markdown
+## Create Database Migration
+
+### Parameters
+- `{change}`: Description of schema change
+- `{tables}`: Affected tables
+
+### Prompt Template
+Create a database migration to {change}.
+
+Affected tables: {tables}
+
+Requirements:
+1. Create both up and down migrations
+2. Handle existing data appropriately
+3. Consider performance on large tables
+4. Add comments explaining the migration
+5. Update relevant model files
+6. Add or update tests for affected models
+
+### Verification Steps
+1. Migration runs successfully: `npm run db:migrate`
+2. Rollback works: `npm run db:rollback`
+3. Data integrity maintained
+4. Model tests pass
+```
+
+## Using Playbooks
+
+### Direct Use
+
+Copy the prompt template, fill in parameters:
+
+```
+Add a GET endpoint at /api/v1/products/{id} for products.
+
+Requirements:
+- Follow the existing route patterns in src/routes/
+- Add input validation using our validation middleware
+- Include proper error handling following patterns in src/utils/errors.js
+- Add corresponding test in src/tests/routes/
+- Update the API documentation in docs/api.md
+
+The endpoint should return a single product by ID with all its details.
+```
+
+### With Skills
+
+Store playbooks in your repository Skills for automatic context:
+
+```markdown
+<!-- .openhands/microagents/repo.md -->
+
+# Standard Playbooks
+
+## When adding API endpoints:
+1. Follow route patterns in src/routes/
+2. Add validation middleware
+3. Include error handling from src/utils/errors.js
+4. Write tests in src/tests/routes/
+5. Update docs/api.md
+
+## When fixing bugs:
+1. Reproduce first
+2. Add failing test
+3. Implement fix
+4. Verify test passes
+```
+
+## Building a Playbook Library
+
+### Organize by Category
+
+```
+playbooks/
+├── api/
+│   ├── add-endpoint.md
+│   ├── add-authentication.md
+│   └── versioning.md
+├── testing/
+│   ├── unit-tests.md
+│   ├── integration-tests.md
+│   └── e2e-tests.md
+├── refactoring/
+│   ├── extract-function.md
+│   ├── rename-module.md
+│   └── split-component.md
+└── documentation/
+    ├── jsdoc.md
+    ├── readme.md
+    └── api-docs.md
+```
+
+### Version and Iterate
+
+Track playbook effectiveness:
+- Which playbooks work best?
+- What clarifications are commonly needed?
+- How can prompts be improved?
+
+### Share with Team
+
+Establish team playbooks:
+1. Start with individual playbooks
+2. Share successful ones
+3. Standardize common tasks
+4. Store in shared documentation
+
+## Best Practices
+
+### 1. Be Specific About Patterns
+
+Instead of:
+```
+❌ "Follow best practices"
+```
+
+Specify:
+```
+✅ "Follow the error handling pattern in src/utils/errors.js"
+✅ "Use the same test structure as UserService.test.js"
+```
+
+### 2. Include Verification
+
+Always include how to verify success:
+```
+### Verification Steps
+1. Run tests: `npm test`
+2. Check linting: `npm run lint`
+3. Manual verification: [specific steps]
+```
+
+### 3. Reference Existing Code
+
+Point to examples in your codebase:
+```
+"Follow the same patterns as the existing UserController"
+"Use the validation approach from src/middleware/validation.js"
+```
+
+### 4. Keep Playbooks Updated
+
+Review and update playbooks when:
+- Project patterns change
+- New conventions are adopted
+- Common issues are discovered
+- Better approaches are found
+
+## Example Playbooks Collection
+
+### Quick Reference
+
+| Task | Key Points |
+|------|------------|
+| **Add Feature** | Specify files, follow patterns, include tests |
+| **Fix Bug** | Reproduce first, add regression test |
+| **Add Tests** | Target coverage, test edge cases |
+| **Refactor** | Tests first, incremental changes |
+| **Document** | Follow style, include examples |
+| **Migrate DB** | Up/down migrations, handle data |
+
+### Starter Playbook Set
+
+Download our [starter playbook templates](https://github.com/OpenHands/playbook-templates) to begin building your library.
+
+## See Also
+
+- [Skills](/overview/skills) - Permanent repository context
+- [Writing Effective Instructions](/openhands/usage/tips/effective-instructions)
+- [Repository Customization](/openhands/usage/customization/repository)
+- [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices)
diff --git a/openhands/usage/repo-setup.mdx b/openhands/usage/repo-setup.mdx
new file mode 100644
index 00000000..027838c5
--- /dev/null
+++ b/openhands/usage/repo-setup.mdx
@@ -0,0 +1,373 @@
+---
+title: Repository Setup Guide
+description: Configure your repository for optimal OpenHands performance
+---
+
+## Overview
+
+Proper repository setup helps OpenHands work more effectively with your codebase. This guide covers configuration options that improve the agent's understanding of your project and enable smoother workflows.
+
+## Essential Configuration
+
+### Test Commands
+
+Tell OpenHands how to run your tests by creating a `.openhands/config.toml` file:
+
+```toml
+[repository]
+test_command = "npm test"
+```
+
+Common test command examples:
+
+| Project Type | Test Command |
+|--------------|--------------|
+| Node.js/npm | `npm test` |
+| Node.js/yarn | `yarn test` |
+| Python/pytest | `pytest` |
+| Python/unittest | `python -m unittest discover` |
+| Go | `go test ./...` |
+| Rust | `cargo test` |
+| Java/Maven | `mvn test` |
+| Java/Gradle | `./gradlew test` |
+
+<Tip>
+Include any necessary flags. For example: `npm test -- --coverage` or `pytest -v --tb=short`
+</Tip>
+
+### Lint Commands
+
+Configure linting to maintain code quality:
+
+```toml
+[repository]
+test_command = "npm test"
+lint_command = "npm run lint"
+```
+
+Common lint commands:
+
+| Project Type | Lint Command |
+|--------------|--------------|
+| JavaScript/ESLint | `npm run lint` or `eslint .` |
+| TypeScript | `npm run lint` or `tsc --noEmit` |
+| Python/Flake8 | `flake8` |
+| Python/Ruff | `ruff check .` |
+| Python/Black | `black --check .` |
+| Go | `golint ./...` |
+| Rust | `cargo clippy` |
+
+### Build Commands
+
+For projects that require building:
+
+```toml
+[repository]
+test_command = "npm test"
+lint_command = "npm run lint"
+build_command = "npm run build"
+```
+
+## Environment Variables
+
+### Setting Environment Variables
+
+Configure environment variables needed for your project:
+
+```toml
+[repository]
+test_command = "npm test"
+
+[environment]
+DATABASE_URL = "postgresql://localhost:5432/test"
+API_KEY = "${API_KEY}"  # Reference from system environment
+NODE_ENV = "test"
+```
+
+### Secret Management
+
+For sensitive values, use OpenHands' secrets management:
+
+<Tabs>
+  <Tab title="CLI">
+    Configure secrets in `~/.openhands/config.toml`:
+    ```toml
+    [secrets]
+    GITHUB_TOKEN = "your-token"
+    API_KEY = "your-api-key"
+    ```
+  </Tab>
+  <Tab title="Cloud">
+    Add secrets through the Settings UI in OpenHands Cloud.
+  </Tab>
+</Tabs>
+
+<Warning>
+Never commit actual secret values to your repository. Use environment variables or the secrets manager.
+</Warning>
+
+## Dependencies Management
+
+### Pre-Session Setup
+
+Configure commands to run before the agent starts working:
+
+```toml
+[repository]
+setup_commands = [
+    "npm install",
+    "npm run db:migrate"
+]
+```
+
+### Common Setup Patterns
+
+**Node.js Project:**
+```toml
+[repository]
+setup_commands = ["npm install"]
+test_command = "npm test"
+lint_command = "npm run lint"
+```
+
+**Python Project:**
+```toml
+[repository]
+setup_commands = [
+    "pip install -r requirements.txt",
+    "pip install -r requirements-dev.txt"
+]
+test_command = "pytest"
+lint_command = "ruff check . && black --check ."
+```
+
+**Monorepo:**
+```toml
+[repository]
+setup_commands = [
+    "npm install",
+    "npm run bootstrap"  # For Lerna or similar
+]
+```
+
+## Custom Setup Scripts
+
+For complex setups, create a script:
+
+```bash
+#!/bin/bash
+# .openhands/setup.sh
+
+# Install dependencies
+npm install
+
+# Set up database
+docker-compose up -d postgres
+sleep 5
+npm run db:migrate
+npm run db:seed
+
+# Generate types
+npm run generate:types
+```
+
+Then reference it in your config:
+
+```toml
+[repository]
+setup_commands = ["bash .openhands/setup.sh"]
+```
+
+## Per-Repository Configuration
+
+### Full Configuration Example
+
+```toml
+# .openhands/config.toml
+
+[repository]
+# Commands
+test_command = "npm test"
+lint_command = "npm run lint"
+build_command = "npm run build"
+setup_commands = ["npm install"]
+
+# Repository description (helps agent understand context)
+description = "E-commerce API built with Node.js and PostgreSQL"
+
+[environment]
+NODE_ENV = "development"
+DATABASE_URL = "postgresql://localhost:5432/myapp_dev"
+REDIS_URL = "redis://localhost:6379"
+
+[agent]
+# Preferred patterns
+coding_style = "functional"
+testing_framework = "jest"
+```
+
+### File Locations
+
+| File | Purpose |
+|------|---------|
+| `.openhands/config.toml` | Main configuration file |
+| `.openhands/setup.sh` | Custom setup script |
+| `.openhands/microagents/repo.md` | Repository-specific instructions ([Skills](/overview/skills/repo)) |
+
+## Skills (Repository Instructions)
+
+Create `.openhands/microagents/repo.md` to provide repository-specific guidance:
+
+```markdown
+# Repository Guidelines
+
+## Architecture
+- This is a Node.js REST API using Express
+- Database: PostgreSQL with Prisma ORM
+- Authentication: JWT tokens stored in HTTP-only cookies
+
+## Coding Standards
+- Use functional components and hooks
+- Write tests for all new features
+- Follow existing error handling patterns in src/utils/errors.ts
+
+## Important Files
+- `src/routes/index.ts` - API route definitions
+- `src/services/` - Business logic
+- `src/models/` - Prisma models
+
+## Commands
+- `npm run dev` - Start development server
+- `npm test` - Run all tests
+- `npm run db:migrate` - Run database migrations
+```
+
+See [Repository Skills](/overview/skills/repo) for more details.
+
+## Troubleshooting Common Setup Issues
+
+### Dependencies Not Installing
+
+**Problem:** Agent can't install dependencies.
+
+**Solutions:**
+1. Verify `setup_commands` in config
+2. Check for missing system dependencies
+3. Ensure package manager is available
+
+```toml
+[repository]
+setup_commands = [
+    "npm install --legacy-peer-deps"  # If peer dependency issues
+]
+```
+
+### Tests Not Running
+
+**Problem:** Tests fail to execute.
+
+**Solutions:**
+1. Verify the test command works locally
+2. Check for missing environment variables
+3. Ensure test database is available
+
+```toml
+[environment]
+CI = "true"  # Some test frameworks need this
+```
+
+### Build Failures
+
+**Problem:** Build command fails.
+
+**Solutions:**
+1. Run build locally to verify it works
+2. Check for missing build dependencies
+3. Ensure correct Node/Python version
+
+### Database Connection Issues
+
+**Problem:** Can't connect to database.
+
+**Solutions:**
+1. Use Docker for local databases:
+   ```toml
+   [repository]
+   setup_commands = [
+       "docker-compose up -d db",
+       "sleep 5",
+       "npm run db:migrate"
+   ]
+   ```
+2. Use SQLite for testing:
+   ```toml
+   [environment]
+   DATABASE_URL = "file:./test.db"
+   ```
+
+## Best Practices
+
+### 1. Keep Setup Fast
+
+Optimize setup commands for speed:
+- Use caching where possible
+- Avoid unnecessary installations
+- Consider using pre-built Docker images
+
+### 2. Use Consistent Environments
+
+Ensure the OpenHands environment matches your development environment:
+- Same Node/Python versions
+- Same package manager
+- Same database setup
+
+### 3. Document Requirements
+
+In your `repo.md` file, document:
+- Required services (databases, cache, etc.)
+- Environment variable requirements
+- Build prerequisites
+
+### 4. Test Your Config
+
+Before relying on OpenHands for important tasks:
+1. Clone a fresh copy of your repo
+2. Apply only the OpenHands config
+3. Verify setup and test commands work
+
+## Configuration Reference
+
+### Complete `config.toml` Options
+
+```toml
+[repository]
+# Required commands
+test_command = "npm test"
+
+# Optional commands
+lint_command = "npm run lint"
+build_command = "npm run build"
+format_command = "npm run format"
+setup_commands = ["npm install"]
+
+# Metadata
+description = "Project description for context"
+language = "typescript"
+
+[environment]
+# Environment variables
+KEY = "value"
+
+[agent]
+# Agent behavior settings
+max_iterations = 50
+auto_lint = true
+auto_test = true
+```
+
+## See Also
+
+- [Repository Skills](/overview/skills/repo)
+- [Configuration Options](/openhands/usage/advanced/configuration-options)
+- [Headless Mode](/openhands/usage/cli/headless) - For CI/CD integration
+- [Custom Sandbox Guide](/openhands/usage/advanced/custom-sandbox-guide)
diff --git a/openhands/usage/sdlc-integration.mdx b/openhands/usage/sdlc-integration.mdx
new file mode 100644
index 00000000..97cd6183
--- /dev/null
+++ b/openhands/usage/sdlc-integration.mdx
@@ -0,0 +1,301 @@
+---
+title: SDLC Integration
+description: How OpenHands fits into your software development lifecycle
+---
+
+## Overview
+
+OpenHands integrates throughout your software development lifecycle (SDLC), from planning to deployment. This guide explains where and how to use OpenHands effectively at each stage.
+
+## Development Phases
+
+### 1. Planning & Analysis
+
+Use OpenHands to accelerate the planning phase:
+
+**Codebase Exploration**
+```
+"Analyze the codebase and explain how the authentication system works"
+"List all API endpoints and their purposes"
+"Find all places where we connect to the database"
+```
+
+**Task Scoping**
+```
+"What files would need to change to add a new user role?"
+"Estimate the complexity of migrating from REST to GraphQL"
+"Identify dependencies that might be affected by upgrading Node.js"
+```
+
+**Architecture Review**
+```
+"Review the current architecture and suggest improvements"
+"Identify potential security vulnerabilities in the user module"
+"Find code that doesn't follow our coding standards"
+```
+
+<Tip>
+Use OpenHands for codebase exploration when onboarding new team members or investigating unfamiliar parts of your system.
+</Tip>
+
+### 2. Development
+
+The primary use case for OpenHands—implementing features and fixes:
+
+**Feature Implementation**
+```
+"Implement a password reset feature with email verification"
+"Add pagination to the /api/products endpoint"
+"Create a dashboard component that displays user statistics"
+```
+
+**Bug Fixes**
+```
+"Fix the race condition in the checkout process"
+"Resolve the memory leak in the image processing service"
+"Fix the failing test in UserService.test.js"
+```
+
+**Refactoring**
+```
+"Refactor the payment module to use the strategy pattern"
+"Convert the callback-based API to async/await"
+"Split the monolithic UserController into smaller services"
+```
+
+**Code Generation**
+```
+"Generate TypeScript interfaces from this JSON schema"
+"Create database migration for the new orders table"
+"Generate API client code from the OpenAPI spec"
+```
+
+### 3. Testing
+
+Improve test coverage and quality:
+
+**Unit Tests**
+```
+"Write unit tests for the OrderService class with 80% coverage"
+"Add tests for edge cases in the validation module"
+"Create mock implementations for external service dependencies"
+```
+
+**Integration Tests**
+```
+"Write integration tests for the authentication flow"
+"Create API tests for all CRUD operations"
+"Add end-to-end tests for the checkout process"
+```
+
+**Test Maintenance**
+```
+"Fix all failing tests after the refactoring"
+"Update tests to work with the new API response format"
+"Remove outdated test fixtures"
+```
+
+<Tip>
+OpenHands excels at writing tests because it can analyze your existing code and test patterns to maintain consistency.
+</Tip>
+
+### 4. Code Review
+
+Use OpenHands to assist with code reviews:
+
+**Automated PR Review**
+```
+"Review this PR for potential issues and suggest improvements"
+"Check if this code follows our coding standards"
+"Identify any security concerns in these changes"
+```
+
+**PR Creation**
+When OpenHands completes a task, it can create a pull request with:
+- Clear description of changes
+- Summary of files modified
+- Testing instructions
+
+**Documentation Updates**
+```
+"Update the README to reflect the new API changes"
+"Add inline comments explaining the complex algorithm"
+"Generate API documentation for the new endpoints"
+```
+
+### 5. Deployment & Operations
+
+Support operational tasks:
+
+**Configuration**
+```
+"Create Kubernetes deployment manifests for the new service"
+"Set up GitHub Actions workflow for CI/CD"
+"Configure environment variables for production"
+```
+
+**Troubleshooting**
+```
+"Analyze these error logs and suggest fixes"
+"Find the root cause of the performance degradation"
+"Identify what changed between these two deployments"
+```
+
+**Monitoring**
+```
+"Add health check endpoints to all services"
+"Implement structured logging throughout the application"
+"Create Prometheus metrics for key operations"
+```
+
+## Integration Patterns
+
+### Parallel Execution
+
+Run multiple OpenHands sessions for independent tasks:
+
+```
+Session 1: "Implement the user profile feature"
+Session 2: "Write tests for the existing auth module"
+Session 3: "Update documentation for the API"
+```
+
+<Warning>
+Avoid running parallel sessions that modify the same files to prevent merge conflicts.
+</Warning>
+
+### Sequential Workflows
+
+Chain tasks for dependent work:
+
+```
+1. "Create the database schema for the new orders feature"
+2. "Implement the Order model and repository"
+3. "Create API endpoints for order management"
+4. "Write tests for the order functionality"
+5. "Update the API documentation"
+```
+
+### Review-and-Refine
+
+Iterative development approach:
+
+```
+1. "Implement a basic version of the search feature"
+   → Review the output
+2. "Add fuzzy matching to the search"
+   → Review the output
+3. "Optimize the search performance for large datasets"
+   → Final review
+```
+
+## Team Integration
+
+### Workflow Recommendations
+
+| Team Size | Recommended Approach |
+|-----------|---------------------|
+| Solo Developer | Direct integration, use for all suitable tasks |
+| Small Team (2-5) | Shared best practices, consistent prompting patterns |
+| Larger Teams | Establish guidelines, use Skills for consistency |
+
+### Coordination Strategies
+
+**Ticket Assignment**
+- Use OpenHands for well-defined tickets
+- Include necessary context in ticket descriptions
+- Reference relevant files and patterns
+
+**Branch Management**
+- Create feature branches before starting tasks
+- Use consistent naming conventions
+- Review changes before merging
+
+**Code Standards**
+Use [Skills](/overview/skills) to encode your team's standards:
+- Coding conventions
+- Testing requirements
+- Documentation patterns
+- Security guidelines
+
+## Best Practices
+
+### 1. Task Sizing
+
+| Task Size | Suitability | Example |
+|-----------|-------------|---------|
+| Small (1-2 files) | ✅ Excellent | Add a new API endpoint |
+| Medium (3-10 files) | ✅ Good | Implement a feature module |
+| Large (10+ files) | ⚠️ Break down | System-wide refactoring |
+
+### 2. Context Provision
+
+Provide relevant context for better results:
+
+```
+"Add caching to the product service.
+- Use Redis (already configured in config/redis.js)
+- Cache for 5 minutes
+- Invalidate on product updates
+- Follow the pattern in services/userService.js"
+```
+
+### 3. Verification Steps
+
+Always verify OpenHands' work:
+
+1. **Run tests**: `npm test` or your test command
+2. **Check linting**: `npm run lint`
+3. **Review changes**: Use `git diff` to see all modifications
+4. **Manual testing**: Test the feature manually when appropriate
+
+### 4. Documentation
+
+Keep track of what OpenHands does:
+
+- Review generated commit messages
+- Update tickets with implementation details
+- Note any manual follow-up needed
+
+## Measuring Success
+
+Track these metrics to measure OpenHands' impact:
+
+- **Time to completion**: Compare task completion times
+- **Code quality**: Monitor test coverage and lint errors
+- **Iteration count**: Track how many clarifications are needed
+- **Adoption rate**: Measure team usage over time
+
+## Common Patterns
+
+### The Exploration-Then-Execute Pattern
+
+```
+1. "Explore the codebase and explain how payments are processed"
+2. [Review the explanation]
+3. "Now add support for PayPal using the same patterns"
+```
+
+### The Test-First Pattern
+
+```
+1. "Write failing tests for a user registration feature"
+2. [Review the tests]
+3. "Now implement the feature to make the tests pass"
+```
+
+### The Incremental Refactoring Pattern
+
+```
+1. "Identify all technical debt in the auth module"
+2. [Review and prioritize]
+3. "Refactor the highest priority item: the session management"
+4. [Verify and repeat]
+```
+
+## See Also
+
+- [When to Use OpenHands](/openhands/usage/tips/when-to-use-openhands)
+- [Writing Effective Instructions](/openhands/usage/tips/effective-instructions)
+- [Repository Customization](/openhands/usage/customization/repository)
+- [Skills](/overview/skills)
diff --git a/openhands/usage/tips/effective-instructions.mdx b/openhands/usage/tips/effective-instructions.mdx
new file mode 100644
index 00000000..4dbec5e6
--- /dev/null
+++ b/openhands/usage/tips/effective-instructions.mdx
@@ -0,0 +1,230 @@
+---
+title: "Writing Effective Instructions"
+sidebarTitle: "Effective Instructions"
+description: "How to write clear, effective instructions for OpenHands"
+---
+
+# Writing Effective Instructions
+
+The quality of OpenHands' output depends significantly on how you communicate your task. This guide covers techniques for writing clear, effective instructions.
+
+## The Anatomy of a Good Instruction
+
+A well-structured instruction includes:
+
+<Steps>
+  <Step title="Context">
+    Background information OpenHands needs to understand the task
+  </Step>
+  <Step title="Objective">
+    What you want to accomplish
+  </Step>
+  <Step title="Constraints">
+    Boundaries and limitations to work within
+  </Step>
+  <Step title="Verification">
+    How to confirm the task is complete
+  </Step>
+</Steps>
+
+## Writing Clear Instructions
+
+### Be Specific, Not Vague
+
+<Tabs>
+  <Tab title="❌ Vague">
+    ```
+    Fix the API
+    ```
+  </Tab>
+  <Tab title="✅ Specific">
+    ```
+    Fix the /api/users endpoint that returns a 500 error 
+    when the email field is missing from the request body.
+    
+    Expected behavior: Return a 400 error with message 
+    "Email is required" when email is not provided.
+    ```
+  </Tab>
+</Tabs>
+
+### Provide Necessary Context
+
+Include information that isn't obvious from the code:
+
+```markdown
+Context:
+- We use PostgreSQL for the database
+- The User model is in src/models/user.py
+- We follow the repository pattern for data access
+- Related tests are in tests/test_user.py
+
+Task:
+Add a "last_login" timestamp field to the User model that 
+updates automatically when a user authenticates.
+```
+
+### Define Acceptance Criteria
+
+Clearly state what "done" looks like:
+
+```markdown
+Acceptance Criteria:
+1. The login endpoint updates last_login on successful authentication
+2. last_login is included in the user profile response
+3. All existing tests continue to pass
+4. New tests cover the last_login functionality
+```
+
+## Instruction Templates
+
+### Bug Fix Template
+
+```markdown
+## Bug Description
+[Describe the bug and its symptoms]
+
+## Steps to Reproduce
+1. [First step]
+2. [Second step]
+3. [Expected vs actual result]
+
+## Root Cause (if known)
+[Any insights into what's causing the bug]
+
+## Acceptance Criteria
+- [ ] Bug no longer reproduces
+- [ ] Existing tests pass
+- [ ] New test added to prevent regression
+```
+
+### Feature Implementation Template
+
+```markdown
+## Feature Description
+[What the feature should do]
+
+## Requirements
+- [Requirement 1]
+- [Requirement 2]
+
+## Technical Constraints
+- [Technologies to use]
+- [Patterns to follow]
+- [Files/areas to modify]
+
+## Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] Tests added
+- [ ] Documentation updated
+```
+
+### Refactoring Template
+
+```markdown
+## Current State
+[Describe the current implementation]
+
+## Desired State
+[Describe the target implementation]
+
+## Scope
+- Files to modify: [list files]
+- Files NOT to modify: [list files]
+
+## Constraints
+- Maintain backward compatibility
+- No changes to public APIs
+- All tests must pass
+
+## Verification
+[How to verify the refactoring is successful]
+```
+
+## Advanced Techniques
+
+### Break Down Complex Tasks
+
+Instead of one large instruction, use multiple smaller ones:
+
+```markdown
+Phase 1: Set up the database schema
+- Add migration for new tables
+- Update models
+
+Phase 2: Implement the service layer
+- Create UserService class
+- Add CRUD methods
+
+Phase 3: Add API endpoints
+- Create routes
+- Add request validation
+- Write tests
+```
+
+### Provide Examples
+
+When patterns matter, show examples:
+
+```markdown
+Follow the existing pattern for API handlers. For example,
+see how we handle the /api/products endpoint:
+
+```python
+@app.route('/api/products', methods=['GET'])
+def get_products():
+    products = ProductService.get_all()
+    return jsonify([p.to_dict() for p in products])
+```
+
+Implement a similar endpoint for /api/orders.
+```
+
+### Reference Documentation
+
+Point to relevant resources:
+
+```markdown
+Implement OAuth2 authentication following the specification at:
+https://oauth.net/2/
+
+Use our existing HTTP client wrapper in src/utils/http.py
+for making external requests.
+```
+
+## Common Pitfalls to Avoid
+
+<AccordionGroup>
+  <Accordion title="Assuming Context">
+    Don't assume OpenHands knows about conventions, tools, or patterns specific to your project. Be explicit.
+  </Accordion>
+  <Accordion title="Overloading Instructions">
+    Don't combine too many unrelated tasks in one instruction. Keep tasks focused.
+  </Accordion>
+  <Accordion title="Ambiguous Requirements">
+    Avoid words like "improve," "better," or "clean up" without specific criteria.
+  </Accordion>
+  <Accordion title="Missing Verification">
+    Always include how to verify the work is correct.
+  </Accordion>
+</AccordionGroup>
+
+## Using Skills for Repeated Instructions
+
+If you find yourself writing similar instructions repeatedly, consider creating a [Skill](/overview/skills) to encode common patterns and context.
+
+<Card title="Learn About Skills" icon="brain" href="/overview/skills">
+  Create reusable context and instructions for your repositories
+</Card>
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Good vs Bad Instructions" icon="scale-balanced" href="/openhands/usage/tips/good-vs-bad-instructions">
+    See examples of effective and ineffective instructions
+  </Card>
+  <Card title="Prompting Best Practices" icon="lightbulb" href="/openhands/usage/tips/prompting-best-practices">
+    More tips for getting the best results
+  </Card>
+</CardGroup>
diff --git a/openhands/usage/tips/good-vs-bad-instructions.mdx b/openhands/usage/tips/good-vs-bad-instructions.mdx
new file mode 100644
index 00000000..cb96cda0
--- /dev/null
+++ b/openhands/usage/tips/good-vs-bad-instructions.mdx
@@ -0,0 +1,326 @@
+---
+title: "Good vs Bad Instructions"
+sidebarTitle: "Good vs Bad Instructions"
+description: "Examples of effective and ineffective instructions for OpenHands"
+---
+
+# Good vs Bad Instructions
+
+Learn from real examples what makes instructions effective—and what causes them to fail.
+
+## Bug Fixing Examples
+
+### Example 1: Login Error
+
+<Tabs>
+  <Tab title="❌ Bad">
+    ```
+    The login is broken, fix it
+    ```
+    
+    **Why it fails:**
+    - No description of the actual problem
+    - No reproduction steps
+    - No indication of where to look
+    - No way to verify the fix
+  </Tab>
+  <Tab title="✅ Good">
+    ```
+    Fix the login authentication error.
+
+    Problem: Users receive "Invalid credentials" even with correct 
+    username/password. The issue started after commit abc123.
+
+    To reproduce:
+    1. Go to /login
+    2. Enter: test@example.com / password123
+    3. Click "Sign In"
+    4. Error appears even though credentials are valid in the database
+
+    Suspected cause: The password hashing was changed but the 
+    comparison logic wasn't updated.
+
+    Files to check:
+    - src/auth/login.py
+    - src/utils/password.py
+
+    Verify fix by:
+    1. Running: pytest tests/test_auth.py
+    2. Manually testing login with test credentials
+    ```
+  </Tab>
+</Tabs>
+
+### Example 2: API Response Error
+
+<Tabs>
+  <Tab title="❌ Bad">
+    ```
+    The API returns wrong data sometimes
+    ```
+  </Tab>
+  <Tab title="✅ Good">
+    ```
+    Fix inconsistent API response format for /api/users/{id}
+
+    Current behavior:
+    - Sometimes returns: {"user": {"id": 1, "name": "John"}}
+    - Sometimes returns: {"id": 1, "name": "John"}
+
+    Expected behavior:
+    - Always return: {"user": {"id": 1, "name": "John"}}
+
+    The inconsistency happens because some code paths use 
+    user.to_dict() directly while others wrap it in {"user": ...}
+
+    Fix by ensuring all return paths in src/api/users.py use 
+    the UserResponse schema from src/schemas/user.py
+    ```
+  </Tab>
+</Tabs>
+
+## Feature Implementation Examples
+
+### Example 3: Adding a Feature
+
+<Tabs>
+  <Tab title="❌ Bad">
+    ```
+    Add email notifications
+    ```
+    
+    **Why it fails:**
+    - No specification of what triggers notifications
+    - No template requirements
+    - No indication of email service to use
+    - No scope boundaries
+  </Tab>
+  <Tab title="✅ Good">
+    ```
+    Add email notification when a user's order ships.
+
+    Requirements:
+    1. Send email when order status changes to "shipped"
+    2. Use the existing EmailService in src/services/email.py
+    3. Email should include:
+       - Order number
+       - Tracking number
+       - Estimated delivery date
+       - List of items
+
+    Template location: Create new template at 
+    templates/emails/order_shipped.html
+
+    Trigger: Add to the update_order_status() method in 
+    src/services/order.py
+
+    Configuration: Use existing SMTP settings from config.py
+
+    Tests: Add tests in tests/test_order_notifications.py
+    
+    Do NOT modify:
+    - The Order model
+    - Existing email templates
+    - The email service itself
+    ```
+  </Tab>
+</Tabs>
+
+### Example 4: UI Component
+
+<Tabs>
+  <Tab title="❌ Bad">
+    ```
+    Make a nice dashboard
+    ```
+  </Tab>
+  <Tab title="✅ Good">
+    ```
+    Create a sales dashboard component showing monthly metrics.
+
+    Component: src/components/SalesDashboard.tsx
+
+    Required sections:
+    1. Summary cards showing:
+       - Total revenue (from /api/metrics/revenue)
+       - Order count (from /api/metrics/orders)
+       - Average order value (calculated)
+    
+    2. Line chart showing daily sales for the current month
+       - Use the existing Chart component from src/components/Chart
+       - Data from /api/metrics/daily-sales
+
+    Styling:
+    - Follow existing Tailwind patterns in other dashboard components
+    - Use the Card component from src/components/ui/Card
+    - Responsive: stack on mobile, grid on desktop
+
+    Loading states:
+    - Show skeleton loaders while data fetches
+    - Show error state if API calls fail
+
+    Tests: Add component tests in __tests__/SalesDashboard.test.tsx
+    ```
+  </Tab>
+</Tabs>
+
+## Refactoring Examples
+
+### Example 5: Code Cleanup
+
+<Tabs>
+  <Tab title="❌ Bad">
+    ```
+    Clean up the utils folder
+    ```
+  </Tab>
+  <Tab title="✅ Good">
+    ```
+    Refactor src/utils/ to remove duplicate helper functions.
+
+    Analysis needed:
+    1. Find duplicate or near-duplicate functions across:
+       - src/utils/string.py
+       - src/utils/format.py
+       - src/utils/helpers.py
+
+    Actions:
+    1. Consolidate string formatting functions into src/utils/string.py
+    2. Remove duplicates, keeping the most complete implementation
+    3. Update all imports in the codebase
+    4. Add type hints to all consolidated functions
+    5. Add docstrings following Google style
+
+    Constraints:
+    - Maintain backward compatibility (keep function signatures)
+    - All existing tests must pass
+    - Do not rename any public functions
+
+    Verify:
+    - Run: pytest tests/
+    - Run: mypy src/utils/
+    ```
+  </Tab>
+</Tabs>
+
+### Example 6: Architecture Change
+
+<Tabs>
+  <Tab title="❌ Bad">
+    ```
+    We need to use TypeScript now
+    ```
+  </Tab>
+  <Tab title="✅ Good">
+    ```
+    Migrate src/components/Button.jsx to TypeScript.
+
+    Steps:
+    1. Rename Button.jsx to Button.tsx
+    2. Add TypeScript types for all props:
+       - variant: 'primary' | 'secondary' | 'danger'
+       - size: 'sm' | 'md' | 'lg'
+       - disabled: boolean
+       - onClick: (event: MouseEvent) => void
+       - children: ReactNode
+
+    3. Export the Props type as ButtonProps
+    4. Update imports in files that use Button
+    5. Run type checking: npx tsc --noEmit
+
+    Follow the pattern established in src/components/Input.tsx 
+    for type definitions.
+
+    Do NOT migrate other components in this task.
+    ```
+  </Tab>
+</Tabs>
+
+## Test Writing Examples
+
+### Example 7: Adding Tests
+
+<Tabs>
+  <Tab title="❌ Bad">
+    ```
+    Add tests for the user module
+    ```
+  </Tab>
+  <Tab title="✅ Good">
+    ```
+    Add unit tests for UserService.create_user() method.
+
+    Location: tests/services/test_user_service.py
+
+    Test cases to cover:
+    1. Successful user creation with valid data
+    2. Failure when email already exists (expect DuplicateEmailError)
+    3. Failure when password is too short (expect ValidationError)
+    4. Failure when required fields are missing
+    5. Verify password is hashed before storing
+
+    Test setup:
+    - Use pytest fixtures from conftest.py
+    - Mock the database with the existing mock_db fixture
+    - Use factory_boy for test data (see tests/factories.py)
+
+    Assertions should verify:
+    - Return value matches expected user object
+    - Database method was called with correct arguments
+    - Appropriate exceptions are raised with correct messages
+    ```
+  </Tab>
+</Tabs>
+
+## Common Patterns
+
+### The Context-Task-Verify Pattern
+
+Structure your instructions with these three sections:
+
+```markdown
+## Context
+[Background information, relevant files, existing patterns]
+
+## Task
+[Specific changes to make, with clear scope]
+
+## Verify
+[How to confirm the task is complete and correct]
+```
+
+### The Problem-Solution-Constraints Pattern
+
+For bug fixes:
+
+```markdown
+## Problem
+[What's wrong, how to reproduce]
+
+## Solution
+[Expected fix approach or outcome]
+
+## Constraints
+[What should NOT change, compatibility requirements]
+```
+
+## Quick Reference
+
+| Aspect | ❌ Avoid | ✅ Do |
+|--------|---------|-------|
+| Scope | "Fix everything" | "Fix X in file Y" |
+| Details | "Make it better" | "Change A to B because C" |
+| Verification | (none) | "Run tests, check output" |
+| Context | Assumptions | Explicit file paths, patterns |
+| Boundaries | Open-ended | "Only modify these files" |
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Prompting Best Practices" icon="lightbulb" href="/openhands/usage/tips/prompting-best-practices">
+    More tips for effective prompting
+  </Card>
+  <Card title="When to Use OpenHands" icon="clock" href="/openhands/usage/tips/when-to-use-openhands">
+    Learn which tasks work best with OpenHands
+  </Card>
+</CardGroup>
diff --git a/openhands/usage/tips/limitations.mdx b/openhands/usage/tips/limitations.mdx
new file mode 100644
index 00000000..87d2a0c7
--- /dev/null
+++ b/openhands/usage/tips/limitations.mdx
@@ -0,0 +1,281 @@
+---
+title: Limitations & Best Fit Tasks
+description: Understanding what OpenHands excels at and current limitations
+---
+
+## Overview
+
+Understanding OpenHands' strengths and limitations helps you choose the right tasks and set appropriate expectations. This guide provides an honest assessment of current capabilities.
+
+## What OpenHands Excels At
+
+### ✅ Well-Defined Code Changes
+
+OpenHands performs best with clear, specific tasks:
+
+| Task Type | Why It Works Well |
+|-----------|-------------------|
+| Adding new endpoints | Clear requirements, testable output |
+| Writing tests | Analyzable patterns, verifiable results |
+| Bug fixes with reproduction | Clear success criteria |
+| Refactoring specific code | Bounded scope, measurable improvement |
+| Documentation updates | Straightforward content creation |
+
+**Examples of Excellent Tasks:**
+```
+✅ "Add a GET /api/users/:id endpoint that returns user details"
+✅ "Write unit tests for the PaymentService class"
+✅ "Fix the null pointer exception in the login handler"
+✅ "Convert callback-based functions in utils.js to async/await"
+✅ "Add JSDoc comments to all exported functions"
+```
+
+### ✅ Code That Follows Patterns
+
+Tasks involving established patterns are handled effectively:
+- Following existing code style
+- Implementing similar features to existing ones
+- Creating files matching existing templates
+- Adding to established test suites
+
+### ✅ Single-Repository Tasks
+
+OpenHands works within one repository at a time:
+- All necessary files are accessible
+- Context is contained and manageable
+- Changes can be tested in isolation
+
+### ✅ Tasks with Clear Success Criteria
+
+The agent performs better when it can verify its work:
+- Tests pass/fail
+- Linting succeeds
+- Build completes
+- Expected output is produced
+
+## Current Limitations
+
+### ⚠️ Complex Multi-Step Reasoning
+
+Tasks requiring extensive planning across many files may need guidance:
+
+```
+⚠️ "Redesign the entire authentication system to use OAuth2"
+
+Better approach:
+1. "Analyze the current auth system and list all affected files"
+2. "Create the OAuth2 provider configuration"
+3. "Update the login endpoint to support OAuth2"
+4. "Migrate the session management"
+5. "Update all affected tests"
+```
+
+### ⚠️ Highly Ambiguous Requirements
+
+Vague tasks lead to uncertain results:
+
+```
+❌ "Make the code better"
+❌ "Improve performance"
+❌ "Clean up the codebase"
+
+✅ "Refactor the processOrders function to reduce complexity"
+✅ "Add database query caching to the product list endpoint"
+✅ "Remove unused imports and dead code from the utils folder"
+```
+
+### ⚠️ Cross-Repository Changes
+
+OpenHands operates in a single repository context:
+- Can't modify multiple repositories simultaneously
+- Can't coordinate changes across microservices
+- External API dependencies need to be mocked or available
+
+**Workaround:** Make changes in each repository separately, coordinating manually.
+
+### ⚠️ Real-Time External Services
+
+Tasks requiring live external services may face challenges:
+- Third-party APIs with authentication
+- Live database migrations on production
+- Services requiring network access not available in the sandbox
+
+**Workaround:** Use mocks, test environments, or configure the sandbox appropriately.
+
+### ⚠️ Long-Running Processes
+
+Tasks that require extended execution time:
+- Complete test suites that take hours
+- Large data migrations
+- Extended build processes
+
+**Workaround:** Break into smaller, verifiable chunks.
+
+### ⚠️ UI/Visual Design Tasks
+
+While OpenHands can write UI code, it has limitations in:
+- Judging visual aesthetics
+- Pixel-perfect implementations
+- Complex responsive design
+
+**Workaround:** Provide specific design specs, use the browser preview for verification.
+
+## Task Complexity Guidelines
+
+### Simple Tasks (High Success Rate)
+
+Single-file changes, clear requirements:
+- Add a function
+- Fix a specific bug
+- Update documentation
+- Add test cases
+
+Estimated time: 2-5 minutes
+
+### Medium Tasks (Good Success Rate)
+
+Multiple related files, clear patterns:
+- Add a new feature module
+- Implement an API endpoint with tests
+- Refactor a specific component
+- Set up a new configuration
+
+Estimated time: 5-15 minutes
+
+### Complex Tasks (Requires Guidance)
+
+System-wide changes, architectural decisions:
+- Major refactoring
+- New architectural patterns
+- Multi-component features
+- Migration projects
+
+Estimated time: 15+ minutes, often broken into steps
+
+## Best Fit Task Examples
+
+### Ideal for OpenHands
+
+| Task | Why It's Ideal |
+|------|----------------|
+| "Add input validation to the registration form" | Bounded scope, clear requirements |
+| "Write integration tests for the order API" | Pattern-following, verifiable |
+| "Migrate from Moment.js to Day.js" | Clear transformation rules |
+| "Add error handling to all API endpoints" | Repetitive, well-defined |
+| "Create TypeScript types for the API responses" | Generatable from existing code |
+
+### Use with Guidance
+
+| Task | How to Approach |
+|------|-----------------|
+| "Implement user authentication" | Break into: login, session, middleware |
+| "Optimize database queries" | First: "Identify slow queries", then fix each |
+| "Set up CI/CD pipeline" | Step-by-step: config, tests, deploy |
+
+### Better Done Manually
+
+| Task | Why |
+|------|-----|
+| Initial project architecture decisions | Requires human judgment and discussion |
+| Sensitive security configurations | Needs careful human review |
+| Production database migrations | Risk too high for automation |
+| Complex business logic decisions | Requires domain expertise |
+
+## Scoping Tasks Appropriately
+
+### The SMART Framework for Tasks
+
+**S - Specific:** Clear, unambiguous description
+```
+❌ "Fix the bug"
+✅ "Fix the TypeError on line 45 of userService.js"
+```
+
+**M - Measurable:** Verifiable success criteria
+```
+❌ "Improve test coverage"
+✅ "Add tests to achieve 80% coverage for authModule"
+```
+
+**A - Achievable:** Within OpenHands' capabilities
+```
+❌ "Rewrite the entire application"
+✅ "Rewrite the authentication module using the new patterns"
+```
+
+**R - Relevant:** Appropriate files are accessible
+```
+❌ "Update the mobile app too"
+✅ "Update the web API that the mobile app calls"
+```
+
+**T - Time-bounded:** Reasonable scope
+```
+❌ "Fix all the bugs"
+✅ "Fix the three bugs in the current sprint"
+```
+
+### Breaking Down Large Tasks
+
+**Original (Too Large):**
+```
+"Implement a complete e-commerce checkout system"
+```
+
+**Broken Down (Appropriate):**
+```
+1. "Create the Cart model and database schema"
+2. "Add API endpoints for cart operations (add, remove, update)"
+3. "Implement the checkout flow service"
+4. "Add payment gateway integration"
+5. "Create order confirmation and email notifications"
+6. "Write tests for the checkout flow"
+```
+
+## Setting Expectations
+
+### What to Expect
+
+| Expectation | Reality |
+|-------------|---------|
+| Perfect code on first try | Often needs 1-2 iterations |
+| Understanding all context | May need clarification |
+| Following all conventions | Works better with Skills/guidance |
+| Handling all edge cases | Benefits from specific instructions |
+
+### Iteration is Normal
+
+Most tasks follow this pattern:
+1. Initial implementation (80% correct)
+2. Review and feedback
+3. Refinement (95% correct)
+4. Final polish (done)
+
+This iterative process is normal and efficient.
+
+## Maximizing Success
+
+### Before Starting
+
+1. **Check task fit:** Is this appropriate for OpenHands?
+2. **Gather context:** What does the agent need to know?
+3. **Define success:** How will you verify completion?
+
+### During Execution
+
+1. **Monitor progress:** Watch for early issues
+2. **Provide feedback:** Redirect if needed
+3. **Break down:** Split complex tasks if stuck
+
+### After Completion
+
+1. **Review changes:** Check all modified files
+2. **Run tests:** Verify nothing is broken
+3. **Test manually:** Spot-check functionality
+
+## See Also
+
+- [When to Use OpenHands](/openhands/usage/tips/when-to-use-openhands)
+- [Writing Effective Instructions](/openhands/usage/tips/effective-instructions)
+- [Good vs Bad Instructions](/openhands/usage/tips/good-vs-bad-instructions)
+- [SDLC Integration](/openhands/usage/sdlc-integration)
diff --git a/openhands/usage/tips/when-to-use-openhands.mdx b/openhands/usage/tips/when-to-use-openhands.mdx
new file mode 100644
index 00000000..c0dbfbfd
--- /dev/null
+++ b/openhands/usage/tips/when-to-use-openhands.mdx
@@ -0,0 +1,149 @@
+---
+title: "When to Use OpenHands"
+sidebarTitle: "When to Use OpenHands"
+description: "Learn when OpenHands is most effective and how to get the best results"
+---
+
+# When to Use OpenHands
+
+OpenHands excels at certain types of tasks. Understanding when to use it—and when not to—will help you get the best results.
+
+## Ideal Use Cases
+
+### 1. Well-Defined, Scoped Tasks
+
+OpenHands performs best on tasks with clear boundaries and acceptance criteria:
+
+- **Bug fixes** with specific reproduction steps
+- **Feature additions** with clear requirements
+- **Refactoring** with well-defined scope
+- **Test writing** for existing functionality
+- **Documentation updates** with specific content needs
+
+### 2. Repetitive Engineering Tasks
+
+Tasks you've done many times before:
+
+- Adding unit tests to existing code
+- Implementing CRUD endpoints
+- Setting up boilerplate for new features
+- Migrating code patterns across files
+- Updating dependencies and fixing breaking changes
+
+### 3. Code Exploration and Understanding
+
+When you need to understand a codebase:
+
+- Answering questions about how code works
+- Finding where functionality is implemented
+- Explaining complex code patterns
+- Identifying dependencies between components
+
+### 4. Parallel Task Execution
+
+Running multiple independent tasks simultaneously:
+
+- Fixing multiple independent bugs
+- Adding tests across different modules
+- Updating documentation in parallel
+- Migrating multiple files with similar changes
+
+## Less Ideal Use Cases
+
+### Tasks Requiring External Context
+
+OpenHands works best when context is available in the codebase:
+
+<Warning>
+**Challenging scenarios:**
+- Tasks requiring proprietary business knowledge not in code
+- Decisions needing stakeholder input
+- Work depending on external systems without documentation
+</Warning>
+
+### Large-Scale Architectural Changes
+
+For major restructuring, consider breaking work into phases:
+
+- **Instead of**: "Rewrite the entire authentication system"
+- **Try**: "Add JWT support to the existing auth module" → "Migrate user sessions to JWT" → "Remove legacy auth code"
+
+### Highly Creative or Subjective Work
+
+Tasks with subjective quality criteria may need more guidance:
+
+- UI/UX design decisions
+- Naming conventions without established patterns
+- Architecture decisions without clear requirements
+
+## Best Practices Checklist
+
+Before starting a task, verify:
+
+<Steps>
+  <Step title="Clear Acceptance Criteria">
+    Can you describe what "done" looks like?
+  </Step>
+  <Step title="Testable Outcome">
+    Can you verify the result programmatically or visually?
+  </Step>
+  <Step title="Sufficient Context">
+    Is the necessary information in the codebase or can you provide it?
+  </Step>
+  <Step title="Appropriate Scope">
+    Is the task small enough to complete in one session?
+  </Step>
+</Steps>
+
+## Task Complexity Guidelines
+
+| Complexity | Example | Recommendation |
+|------------|---------|----------------|
+| **Simple** | Fix a typo, add a test | Single prompt, minimal guidance |
+| **Medium** | Implement a feature, fix a bug | Provide context and acceptance criteria |
+| **Complex** | Multi-file refactoring | Break into subtasks, provide detailed guidance |
+| **Very Complex** | Architectural changes | Consider human-led design with OpenHands implementation |
+
+## Maximizing Success
+
+### 1. Provide Clear Instructions
+
+Be specific about what you want:
+
+```
+❌ "Fix the login bug"
+✅ "Fix the login bug where users see a blank page after clicking submit. 
+    The error appears in the console as 'undefined is not a function'. 
+    The bug was introduced in PR #123."
+```
+
+### 2. Include Verification Steps
+
+Tell OpenHands how to verify its work:
+
+```
+✅ "After implementing, run `npm test` to ensure all tests pass, 
+    and manually test by logging in with test credentials."
+```
+
+### 3. Set Boundaries
+
+Define what should and shouldn't change:
+
+```
+✅ "Modify only files in the `src/auth/` directory. 
+    Do not change the public API signatures."
+```
+
+## Getting Help
+
+If you're unsure whether a task is suitable for OpenHands:
+
+1. Start with a smaller version of the task
+2. Provide more context than you think necessary
+3. Use [iterative refinement](/sdk/guides/iterative-refinement) to improve results
+4. Check the [prompting best practices](/openhands/usage/tips/prompting-best-practices) guide
+
+<Card title="Need More Help?" icon="life-ring" href="/openhands/usage/troubleshooting/feedback">
+  Share your use case with the community for guidance
+</Card>
diff --git a/openhands/usage/workspace-tools.mdx b/openhands/usage/workspace-tools.mdx
new file mode 100644
index 00000000..bca9f407
--- /dev/null
+++ b/openhands/usage/workspace-tools.mdx
@@ -0,0 +1,328 @@
+---
+title: Workspace & Session Tools
+description: Understanding the OpenHands workspace and available session tools
+---
+
+## Overview
+
+When you start an OpenHands session, you're working within a managed workspace that provides various tools for development. This guide explains how to use these tools effectively.
+
+## The Workspace
+
+### What is the Workspace?
+
+The workspace is the environment where OpenHands operates. Depending on your setup:
+
+| Setup | Workspace Location |
+|-------|-------------------|
+| CLI with `--mount-cwd` | Your current directory mounted at `/workspace` |
+| Local GUI | Mounted project directory |
+| OpenHands Cloud | Cloned repository in isolated environment |
+
+### Workspace Persistence
+
+<Tabs>
+  <Tab title="CLI">
+    Changes are made directly to your mounted directory and persist after the session ends.
+  </Tab>
+  <Tab title="Cloud">
+    Changes persist within the session and can be committed to a branch or PR.
+  </Tab>
+</Tabs>
+
+### Working with Files
+
+The agent can:
+- **Read** any file in the workspace
+- **Create** new files and directories
+- **Modify** existing files
+- **Delete** files when necessary
+- **Search** across the codebase
+
+<Tip>
+The agent sees your project as you do. If a file is in your `.gitignore`, the agent can still access it but may not include it in commits.
+</Tip>
+
+## Terminal / Shell
+
+### Real-Time Command Execution
+
+Watch commands execute in real-time:
+
+```
+Agent: Running `npm test`
+───────────────────────────────────────
+> project@1.0.0 test
+> jest
+
+PASS  src/tests/user.test.js
+PASS  src/tests/auth.test.js
+
+Test Suites: 2 passed, 2 total
+Tests:       12 passed, 12 total
+───────────────────────────────────────
+```
+
+### Common Operations
+
+The agent typically uses the terminal for:
+
+| Operation | Example Commands |
+|-----------|-----------------|
+| Installing dependencies | `npm install`, `pip install` |
+| Running tests | `npm test`, `pytest` |
+| Building projects | `npm run build`, `make` |
+| Linting | `npm run lint`, `flake8` |
+| Git operations | `git status`, `git diff` |
+| File operations | `ls`, `cat`, `find` |
+
+### Monitoring Output
+
+Pay attention to terminal output for:
+- **Errors**: The agent will attempt to fix them
+- **Warnings**: May indicate potential issues
+- **Test results**: Verify expected behavior
+- **Build output**: Check for successful compilation
+
+<Warning>
+If you see the agent running commands that seem incorrect, you can interrupt and provide guidance.
+</Warning>
+
+## Code Editor
+
+### Viewing Changes
+
+In the web interface, the code editor shows:
+- Currently open files
+- Syntax highlighting
+- Line numbers
+- Diff view for changes
+
+### Change Tracking
+
+The agent tracks all modifications:
+
+```diff
+// Original
+function processData(data) {
+-  return data;
++  return data.map(item => ({
++    ...item,
++    processed: true
++  }));
+}
+```
+
+### Manual Editing
+
+You can make manual edits alongside the agent:
+1. Pause the agent if running
+2. Make your changes
+3. Resume or provide new instructions
+
+<Tip>
+If you make manual changes, mention them to the agent so it can incorporate them into its context.
+</Tip>
+
+## Browser Tool
+
+### Web Testing
+
+For web development tasks, the browser tool enables:
+- **Preview**: View your application
+- **Interaction**: Click, type, navigate
+- **Screenshots**: Capture current state
+- **Console**: Monitor browser logs
+
+### Use Cases
+
+| Task | How the Agent Uses Browser |
+|------|---------------------------|
+| UI Development | Preview components, verify layout |
+| Testing | Interact with forms, verify functionality |
+| Debugging | Check console errors, network requests |
+| Screenshot | Capture states for verification |
+
+### Example Workflow
+
+```
+1. Agent makes UI changes
+2. Agent opens browser to http://localhost:3000
+3. Agent navigates to the modified page
+4. Agent verifies the changes look correct
+5. Agent reports success or makes adjustments
+```
+
+## Progress Tracking
+
+### Session Timeline
+
+The session maintains a history of:
+- Commands executed
+- Files modified
+- Decisions made
+- Errors encountered
+
+### Status Indicators
+
+| Indicator | Meaning |
+|-----------|---------|
+| 🔄 Running | Agent is executing a step |
+| ⏸️ Paused | Agent is waiting for input |
+| ✅ Complete | Task finished successfully |
+| ❌ Error | An error occurred |
+| ⏳ Thinking | Agent is planning next steps |
+
+### Understanding Agent Behavior
+
+The agent typically follows this pattern:
+
+```
+1. Read and understand the task
+2. Explore relevant code
+3. Plan the approach
+4. Make changes
+5. Test the changes
+6. Iterate if needed
+7. Report completion
+```
+
+## Taking Control
+
+### Pausing the Agent
+
+<Tabs>
+  <Tab title="CLI">
+    Press `Esc` to pause. The agent will stop after completing its current step.
+  </Tab>
+  <Tab title="Web/Cloud">
+    Type a message to interrupt. The agent will acknowledge and await new instructions.
+  </Tab>
+</Tabs>
+
+### Running Your Own Commands
+
+You can guide the agent to run specific commands:
+
+```
+"Please run `npm run test:integration` to verify the changes"
+"Execute `docker-compose up -d` to start the services"
+"Run `git diff` to show me what changed"
+```
+
+### Providing Corrections
+
+If the agent is heading in the wrong direction:
+
+```
+❌ Don't: "That's wrong"
+✅ Do: "Stop. Instead of modifying user.js, please update the auth.js file"
+```
+
+## Session Management
+
+### Saving Progress
+
+Your session state is automatically saved, including:
+- Conversation history
+- Modified files
+- Pending changes
+
+### Resuming Sessions
+
+In the CLI, resume previous work:
+
+```bash
+# List recent sessions
+openhands --resume
+
+# Resume the most recent
+openhands --resume --last
+
+# Resume a specific session
+openhands --resume <session-id>
+```
+
+### Ending Sessions
+
+When you're done:
+
+| Action | CLI | Web/Cloud |
+|--------|-----|-----------|
+| Exit cleanly | `Ctrl+Q` or `/exit` | Close tab or click end |
+| Create PR | Agent can do this | Use the PR button |
+| Save state | Automatic | Automatic |
+
+## Best Practices
+
+### 1. Monitor Actively
+
+Don't just start a task and walk away:
+- Watch for errors or unexpected behavior
+- Provide timely feedback
+- Catch issues early
+
+### 2. Use the Right Tool
+
+Guide the agent to use appropriate tools:
+
+```
+"Use the terminal to run the tests"
+"Preview the changes in the browser"
+"Show me the diff of what you changed"
+```
+
+### 3. Verify Results
+
+Always verify the agent's work:
+
+```bash
+# Check what changed
+git diff
+
+# Run tests
+npm test
+
+# Check for lint errors
+npm run lint
+```
+
+### 4. Provide Context
+
+Help the agent understand your workspace:
+
+```
+"The test database is at localhost:5432"
+"Run tests with `npm run test:unit`"
+"The main entry point is src/index.ts"
+```
+
+## Troubleshooting
+
+### Agent Seems Stuck
+
+If the agent isn't making progress:
+1. Check if it's waiting for input
+2. Provide more specific guidance
+3. Break down the task into smaller steps
+
+### Commands Failing
+
+If commands fail:
+- Check if dependencies are installed
+- Verify the working directory
+- Ensure required services are running
+
+### Unexpected Changes
+
+If you see unwanted changes:
+1. Pause the agent
+2. Use `git checkout -- <file>` to revert
+3. Provide clearer instructions
+
+## See Also
+
+- [Terminal (TUI)](/openhands/usage/cli/terminal)
+- [Resume Conversations](/openhands/usage/cli/resume)
+- [Your First Session](/overview/your-first-session)
+- [Headless Mode](/openhands/usage/cli/headless)
diff --git a/overview/your-first-session.mdx b/overview/your-first-session.mdx
new file mode 100644
index 00000000..f64571d2
--- /dev/null
+++ b/overview/your-first-session.mdx
@@ -0,0 +1,202 @@
+---
+title: Your First Session
+description: A step-by-step guide to your first interaction with OpenHands
+---
+
+## Overview
+
+This guide walks you through your first session with OpenHands, from starting the interface to successfully completing your first task. Whether you're using the CLI, web interface, or OpenHands Cloud, these fundamentals will help you get the most out of your experience.
+
+## Understanding the Interface
+
+OpenHands provides several ways to interact with the AI agent:
+
+### Chat Panel
+The main interaction area where you communicate with the agent. Here you can:
+- Type natural language instructions
+- Ask questions about your codebase
+- Provide feedback and clarifications
+- See the agent's responses and explanations
+
+### Terminal Output
+Watch the agent execute commands in real-time:
+- See exactly what commands are being run
+- Monitor output and error messages
+- Track progress on multi-step tasks
+
+### Code Editor (Web/Cloud)
+View and monitor code changes:
+- See files being created or modified
+- Review changes before they're committed
+- Make manual edits when needed
+
+### Browser Tool (Web/Cloud)
+For web development tasks:
+- Preview applications
+- Test functionality
+- Verify UI changes
+
+## Starting Your First Task
+
+### Step 1: Prepare Your Task Description
+
+Before starting, clearly define what you want to accomplish. Good first tasks include:
+- **Adding a simple feature**: "Add a /health endpoint to my Flask API"
+- **Writing tests**: "Write unit tests for the UserService class"
+- **Documentation**: "Add docstrings to all functions in utils.py"
+- **Bug fixes**: "Fix the TypeError in the login function"
+
+### Step 2: Start the Session
+
+<Tabs>
+  <Tab title="CLI">
+    ```bash
+    # Navigate to your project
+    cd /path/to/your/project
+
+    # Start OpenHands with your task
+    openhands -t "Add a /health endpoint that returns JSON with status: ok"
+    ```
+  </Tab>
+  <Tab title="Web Interface">
+    ```bash
+    # Start the web interface
+    openhands web
+
+    # Open http://localhost:12000 in your browser
+    ```
+    Then type your task in the chat input.
+  </Tab>
+  <Tab title="Cloud">
+    1. Go to [app.all-hands.dev](https://app.all-hands.dev)
+    2. Select your repository
+    3. Type your task in the chat input
+  </Tab>
+</Tabs>
+
+### Step 3: Monitor Progress
+
+Once you've submitted your task, the agent will:
+
+1. **Analyze the request**: Understand what you're asking for
+2. **Explore the codebase**: Look at relevant files and understand the structure
+3. **Plan the approach**: Decide how to implement the solution
+4. **Execute steps**: Make changes, run commands, and test the results
+5. **Report completion**: Summarize what was done
+
+<Tip>
+Watch the terminal output to understand what the agent is doing. This helps you provide better guidance if needed.
+</Tip>
+
+### Step 4: Provide Feedback
+
+During the session, you can:
+
+- **Clarify**: If the agent asks questions, provide clear answers
+- **Redirect**: If it's going in the wrong direction, explain what you want instead
+- **Pause**: Press `Esc` (CLI) to pause and provide new instructions
+- **Approve**: Confirm actions when prompted
+
+## Common First-Task Examples
+
+### Example 1: Add a REST Endpoint
+
+```
+Task: "Add a GET /users endpoint to my Express.js API that returns a list of users from the database"
+```
+
+What to expect:
+- Agent reads your existing route files
+- Creates the new endpoint following your patterns
+- Adds necessary database queries
+- Tests the endpoint if possible
+
+### Example 2: Write Tests
+
+```
+Task: "Write comprehensive unit tests for the authentication module"
+```
+
+What to expect:
+- Agent examines the authentication code
+- Identifies functions to test
+- Creates test file following your testing patterns
+- Runs tests to verify they pass
+
+### Example 3: Fix a Bug
+
+```
+Task: "Fix the bug where users can't upload files larger than 1MB"
+```
+
+What to expect:
+- Agent searches for file upload code
+- Identifies the size limit configuration
+- Makes the necessary changes
+- Tests the fix
+
+### Example 4: Documentation
+
+```
+Task: "Add JSDoc comments to all exported functions in the utils folder"
+```
+
+What to expect:
+- Agent lists files in the utils folder
+- Reads each file and understands the functions
+- Adds appropriate documentation
+- Preserves existing comments
+
+## Taking Over the Session
+
+Sometimes you may want to take control:
+
+### When to Take Over
+
+- The agent is stuck in a loop
+- You see a simpler solution
+- You need to make a quick manual fix
+- You want to run a specific command
+
+### How to Take Over
+
+<Tabs>
+  <Tab title="CLI">
+    Press `Esc` to pause the agent, then provide new instructions or corrections.
+  </Tab>
+  <Tab title="Web/Cloud">
+    Type a new message to interrupt the agent. Be specific about what you want changed.
+  </Tab>
+</Tabs>
+
+## Tips for Successful First Sessions
+
+### 1. Start Small
+Your first task should be achievable in a few steps. Save complex refactoring for when you're familiar with the workflow.
+
+### 2. Be Specific
+Instead of "make the code better," try "refactor the handleSubmit function to use async/await instead of callbacks."
+
+### 3. Provide Context
+If there are conventions or requirements the agent should follow, mention them:
+- "Use our existing error handling pattern from utils/errors.js"
+- "Follow the same testing style as UserService.test.js"
+
+### 4. Watch and Learn
+Observe how the agent approaches problems. This helps you write better prompts in the future.
+
+### 5. Don't Hesitate to Redirect
+If the agent is heading in the wrong direction, interrupt early with corrections.
+
+## What's Next?
+
+After your first successful session:
+
+- [Explore different running modes](/openhands/usage/cli/terminal)
+- [Learn about Skills](/overview/skills) to customize agent behavior
+- [Read prompting best practices](/openhands/usage/tips/prompting-best-practices)
+- [Try more complex tasks](/overview/first-projects)
+
+<Tip>
+Each session teaches you something new about working with AI agents. Don't worry if your first few sessions require some back-and-forth—this is normal and helps you learn how to communicate effectively with the agent.
+</Tip>
diff --git a/use-cases/best-practices.mdx b/use-cases/best-practices.mdx
new file mode 100644
index 00000000..aca1c543
--- /dev/null
+++ b/use-cases/best-practices.mdx
@@ -0,0 +1,296 @@
+---
+title: "Use Case Best Practices"
+sidebarTitle: "Best Practices"
+description: "Maximize success with OpenHands across different use cases"
+---
+
+# Use Case Best Practices
+
+Learn how to get the best results from OpenHands for different types of tasks.
+
+## General Principles
+
+<AccordionGroup>
+  <Accordion title="Break Down Large Tasks">
+    Complex projects should be divided into smaller, independent tasks that can be completed and verified individually.
+    
+    **Instead of:** "Rewrite the authentication system"
+    
+    **Try:** 
+    1. "Add password strength validation"
+    2. "Implement JWT token refresh"
+    3. "Add rate limiting to login endpoint"
+  </Accordion>
+  
+  <Accordion title="Provide Clear Verification">
+    Always include how to verify the task is complete:
+    
+    - Which tests to run
+    - What behavior to check
+    - What the output should look like
+  </Accordion>
+  
+  <Accordion title="Include Relevant Context">
+    Don't assume OpenHands knows project conventions. Explicitly mention:
+    
+    - File locations and naming conventions
+    - Coding patterns to follow
+    - Related files to reference
+  </Accordion>
+  
+  <Accordion title="Set Appropriate Boundaries">
+    Define what should and shouldn't change:
+    
+    - Which files are in scope
+    - Which APIs must remain stable
+    - What dependencies can be added
+  </Accordion>
+</AccordionGroup>
+
+## By Use Case Type
+
+### Code Migrations
+
+**Goal:** Transform code from one pattern, language, or framework to another.
+
+<Tabs>
+  <Tab title="Do's">
+    - Migrate one file or module at a time
+    - Provide before/after examples
+    - Include the migration checklist
+    - Test after each migration step
+    - Preserve existing functionality
+  </Tab>
+  <Tab title="Don'ts">
+    - Migrate entire codebase at once
+    - Skip verification steps
+    - Change behavior during migration
+    - Ignore edge cases
+  </Tab>
+</Tabs>
+
+**Example instruction:**
+
+```markdown
+Migrate src/utils/helpers.js from JavaScript to TypeScript.
+
+Pattern to follow (see src/utils/format.ts for reference):
+- Add explicit type annotations
+- Use interfaces for object shapes
+- Export types alongside functions
+
+Checklist:
+- [ ] File renamed to .ts
+- [ ] All functions have parameter types
+- [ ] Return types are explicit
+- [ ] No 'any' types used
+- [ ] Imports updated in dependent files
+- [ ] npx tsc --noEmit passes
+```
+
+### Test Coverage
+
+**Goal:** Add tests to existing code to improve reliability.
+
+<Tabs>
+  <Tab title="Do's">
+    - Focus on one module at a time
+    - Include happy path and error cases
+    - Specify the testing framework and patterns
+    - Point to existing test examples
+    - Cover edge cases
+  </Tab>
+  <Tab title="Don'ts">
+    - Write tests for everything at once
+    - Skip edge cases
+    - Use different patterns than existing tests
+    - Forget to mock external dependencies
+  </Tab>
+</Tabs>
+
+**Example instruction:**
+
+```markdown
+Add unit tests for the OrderService class.
+
+File: tests/services/test_order_service.py
+Follow pattern in: tests/services/test_user_service.py
+
+Test cases needed:
+1. create_order() - valid order creation
+2. create_order() - missing required fields
+3. create_order() - invalid product ID
+4. get_order() - existing order
+5. get_order() - non-existent order
+6. cancel_order() - successful cancellation
+7. cancel_order() - already shipped order (should fail)
+
+Use fixtures from conftest.py for database mocking.
+Target: 90%+ coverage for OrderService
+```
+
+### Bug Fixing
+
+**Goal:** Identify and fix issues in the codebase.
+
+<Tabs>
+  <Tab title="Do's">
+    - Include reproduction steps
+    - Describe expected vs actual behavior
+    - Point to relevant log entries or error messages
+    - Mention when the bug was introduced if known
+    - Request a regression test
+  </Tab>
+  <Tab title="Don'ts">
+    - Describe symptoms without context
+    - Fix without understanding root cause
+    - Skip adding tests
+    - Make unrelated changes
+  </Tab>
+</Tabs>
+
+**Example instruction:**
+
+```markdown
+Fix: Users can't checkout with more than 10 items
+
+Reproduction:
+1. Add 11+ items to cart
+2. Click "Checkout"
+3. Error: "Cart validation failed"
+
+Expected: Checkout succeeds for any valid cart
+Actual: Fails for carts with >10 items
+
+Suspected cause: Hardcoded limit in src/services/cart.py line 45
+
+After fix:
+- Add test for checkout with 100 items
+- Verify existing tests still pass
+```
+
+### Documentation
+
+**Goal:** Generate or update project documentation.
+
+<Tabs>
+  <Tab title="Do's">
+    - Specify the documentation style
+    - Point to existing docs as examples
+    - Include all required sections
+    - Request examples and code snippets
+    - Define the audience
+  </Tab>
+  <Tab title="Don'ts">
+    - Generate docs without structure
+    - Skip code examples
+    - Ignore existing documentation patterns
+    - Over-document simple functions
+  </Tab>
+</Tabs>
+
+**Example instruction:**
+
+```markdown
+Add docstrings to all public functions in src/api/users.py
+
+Style: Google docstrings (see src/api/products.py for examples)
+
+Include:
+- Brief description
+- Args with types
+- Returns with type
+- Raises for exceptions
+- Example usage for complex functions
+
+Skip: Private methods (prefixed with _)
+```
+
+### Refactoring
+
+**Goal:** Improve code structure without changing behavior.
+
+<Tabs>
+  <Tab title="Do's">
+    - Define the specific improvement
+    - Ensure tests exist before refactoring
+    - Make incremental changes
+    - Verify behavior is unchanged
+    - Keep commits focused
+  </Tab>
+  <Tab title="Don'ts">
+    - Change functionality during refactor
+    - Refactor without test coverage
+    - Make too many changes at once
+    - Rename public APIs without migration plan
+  </Tab>
+</Tabs>
+
+**Example instruction:**
+
+```markdown
+Refactor: Extract email sending logic into a service
+
+Current: Email sending is scattered across multiple controllers
+Target: Centralized EmailService class
+
+Steps:
+1. Create src/services/email_service.py
+2. Move email logic from:
+   - src/controllers/user.py (send_welcome_email)
+   - src/controllers/order.py (send_confirmation)
+   - src/controllers/auth.py (send_reset_link)
+3. Update controllers to use EmailService
+4. Add interface for testing (mock injection)
+
+Constraints:
+- No changes to email content
+- No changes to when emails are sent
+- All existing tests must pass
+```
+
+## Workflow Tips
+
+### Parallel Execution
+
+For large tasks, run multiple OpenHands sessions in parallel:
+
+```
+Session 1: Migrate src/components/Button.jsx
+Session 2: Migrate src/components/Input.jsx
+Session 3: Migrate src/components/Modal.jsx
+```
+
+### Iterative Refinement
+
+For complex tasks, iterate:
+
+1. Start with a basic implementation
+2. Review and provide feedback
+3. Request specific improvements
+4. Verify and finalize
+
+### Using Skills
+
+Create [Skills](/overview/skills) to encode:
+
+- Project-specific conventions
+- Common patterns
+- Frequently used context
+
+This reduces repetition in your instructions.
+
+## Measuring Success
+
+Track these metrics to improve over time:
+
+| Metric | Target |
+|--------|--------|
+| Task completion rate | >90% |
+| Tests passing after changes | 100% |
+| Code review acceptance | >80% |
+| Time saved vs manual | >50% |
+
+<Card title="See Use Case Examples" icon="folder-open" href="/use-cases/examples/code-migrations">
+  Browse specific use case examples and templates
+</Card>
diff --git a/use-cases/examples/api-integration.mdx b/use-cases/examples/api-integration.mdx
new file mode 100644
index 00000000..3c8162bd
--- /dev/null
+++ b/use-cases/examples/api-integration.mdx
@@ -0,0 +1,108 @@
+---
+title: "API Integration"
+sidebarTitle: "API Integration"
+description: "Using OpenHands to integrate with external APIs"
+---
+
+# API Integration
+
+OpenHands can help implement integrations with external APIs and services.
+
+## Common Integration Tasks
+
+- Implementing SDK wrappers
+- Building API clients
+- Adding webhook handlers
+- Data synchronization
+
+## Instruction Template
+
+```markdown
+Integrate with [Service Name] API.
+
+## API Documentation
+[Link to API docs or describe endpoints]
+
+## Requirements
+1. [Endpoint/feature 1]
+2. [Endpoint/feature 2]
+
+## Implementation Details
+- Location: src/integrations/[service].py
+- Authentication: [API key/OAuth/etc]
+- Error handling: [requirements]
+
+## Configuration
+- Store credentials in [location]
+- Use existing HTTP client from [location]
+
+## Testing
+- Mock external calls in tests
+- Test error handling
+```
+
+## Example: Payment API
+
+### Request
+
+```markdown
+Integrate Stripe payment processing.
+
+API Docs: https://stripe.com/docs/api
+
+Requirements:
+1. Create payment intent
+2. Confirm payment
+3. Handle webhooks for payment events
+
+Implementation:
+- Location: src/services/payment/stripe_service.py
+- Use stripe-python SDK
+- Follow existing service patterns in src/services/
+
+Configuration:
+- STRIPE_SECRET_KEY in environment
+- STRIPE_WEBHOOK_SECRET for webhook verification
+
+Error Handling:
+- Wrap Stripe exceptions in custom PaymentError
+- Log all API calls for debugging
+- Implement retry for transient failures
+
+Testing:
+- Use Stripe test keys
+- Mock webhook payloads
+- Test all error scenarios
+```
+
+## Best Practices
+
+<CardGroup cols={2}>
+  <Card title="Wrap External APIs" icon="box">
+    Create abstraction layers around external services
+  </Card>
+  <Card title="Handle Errors" icon="triangle-exclamation">
+    Implement comprehensive error handling
+  </Card>
+  <Card title="Test with Mocks" icon="vial">
+    Mock external calls in unit tests
+  </Card>
+  <Card title="Secure Credentials" icon="lock">
+    Never hardcode API keys or secrets
+  </Card>
+</CardGroup>
+
+## Integration Checklist
+
+- [ ] API client/wrapper created
+- [ ] Error handling implemented
+- [ ] Retry logic for transient failures
+- [ ] Credentials stored securely
+- [ ] Logging for debugging
+- [ ] Unit tests with mocks
+- [ ] Integration tests (optional)
+- [ ] Documentation updated
+
+<Card title="See Tutorials" icon="graduation-cap" href="/use-cases/tutorials/getting-started">
+  Follow step-by-step integration tutorials
+</Card>
diff --git a/use-cases/examples/bug-fixing.mdx b/use-cases/examples/bug-fixing.mdx
new file mode 100644
index 00000000..8391fb79
--- /dev/null
+++ b/use-cases/examples/bug-fixing.mdx
@@ -0,0 +1,135 @@
+---
+title: "Bug Fixing & Debugging"
+sidebarTitle: "Bug Fixing"
+description: "Using OpenHands to fix bugs and debug issues"
+---
+
+# Bug Fixing & Debugging
+
+OpenHands can help identify, diagnose, and fix bugs in your codebase.
+
+## Effective Bug Reports
+
+The key to successful bug fixing with OpenHands is providing clear context.
+
+### Essential Information
+
+<Steps>
+  <Step title="Describe the Bug">
+    What's happening vs what should happen
+  </Step>
+  <Step title="Reproduction Steps">
+    Exact steps to trigger the bug
+  </Step>
+  <Step title="Environment">
+    Relevant configuration, versions, data
+  </Step>
+  <Step title="Evidence">
+    Error messages, logs, screenshots
+  </Step>
+</Steps>
+
+## Instruction Template
+
+```markdown
+## Bug Description
+[What is happening incorrectly]
+
+## Expected Behavior
+[What should happen instead]
+
+## Steps to Reproduce
+1. [Step 1]
+2. [Step 2]
+3. [Observe the bug]
+
+## Error Message/Logs
+```
+[Paste error messages here]
+```
+
+## Relevant Files
+- [file path 1]
+- [file path 2]
+
+## Additional Context
+- When did this start happening?
+- Was there a recent change that might have caused this?
+- Does it happen consistently or intermittently?
+
+## Acceptance Criteria
+- [ ] Bug no longer reproduces
+- [ ] Regression test added
+- [ ] All existing tests pass
+```
+
+## Example: API Error Bug
+
+### Bug Report
+
+```markdown
+## Bug Description
+The /api/users/search endpoint returns 500 error when search 
+query contains special characters like "&" or "?".
+
+## Expected Behavior
+Should return filtered results or empty array, never 500 error.
+
+## Steps to Reproduce
+1. Call GET /api/users/search?q=test&value
+2. Observe 500 Internal Server Error
+
+## Error Log
+```
+TypeError: Cannot read property 'toLowerCase' of undefined
+    at searchUsers (src/api/users.js:45)
+```
+
+## Relevant Files
+- src/api/users.js (search endpoint)
+- src/services/userSearch.js (search logic)
+
+## Acceptance Criteria
+- [ ] Special characters in search work correctly
+- [ ] Add input sanitization
+- [ ] Add test for special character handling
+```
+
+### Fix Approach
+
+OpenHands will:
+1. Identify the root cause (URL parsing issue)
+2. Add proper input validation
+3. Fix the search function
+4. Add regression tests
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Isolate the Problem">
+    Narrow down where the bug occurs before asking for a fix.
+  </Accordion>
+  <Accordion title="Always Add Tests">
+    Request a regression test to prevent the bug from returning.
+  </Accordion>
+  <Accordion title="Minimal Changes">
+    Fix only the bug; avoid unrelated improvements.
+  </Accordion>
+  <Accordion title="Verify the Fix">
+    Include verification steps in your request.
+  </Accordion>
+</AccordionGroup>
+
+## Types of Bugs
+
+| Bug Type | Information to Include |
+|----------|----------------------|
+| Crash/Error | Full stack trace, trigger conditions |
+| Logic Error | Expected vs actual output |
+| Performance | Metrics, profiling data |
+| UI/UX | Screenshots, browser info |
+| Data Issue | Sample data, database state |
+
+<Card title="See Good vs Bad Instructions" icon="scale-balanced" href="/openhands/usage/tips/good-vs-bad-instructions">
+  Learn how to write effective bug reports
+</Card>
diff --git a/use-cases/examples/code-migrations.mdx b/use-cases/examples/code-migrations.mdx
new file mode 100644
index 00000000..bbc9ea36
--- /dev/null
+++ b/use-cases/examples/code-migrations.mdx
@@ -0,0 +1,158 @@
+---
+title: "Code Migrations"
+sidebarTitle: "Code Migrations"
+description: "Using OpenHands for language and framework migrations"
+---
+
+# Code Migrations
+
+OpenHands excels at systematic code transformations, making it ideal for migration projects.
+
+## Common Migration Types
+
+### Language Migrations
+
+- JavaScript → TypeScript
+- Python 2 → Python 3
+- Java 8 → Java 17+
+- CoffeeScript → JavaScript
+
+### Framework Migrations
+
+- React Class Components → Hooks
+- Angular.js → Angular
+- Express → Fastify
+- jQuery → Vanilla JS
+
+### Pattern Migrations
+
+- Callbacks → Promises/Async-Await
+- REST → GraphQL
+- Monolith → Microservices patterns
+
+## Migration Workflow
+
+<Steps>
+  <Step title="Analyze">
+    Identify all files that need migration and any dependencies
+  </Step>
+  <Step title="Plan">
+    Order files by dependency graph (migrate dependencies first)
+  </Step>
+  <Step title="Execute">
+    Migrate files one at a time with verification
+  </Step>
+  <Step title="Verify">
+    Run tests and manual verification after each migration
+  </Step>
+</Steps>
+
+## Example: JavaScript to TypeScript
+
+### Instruction Template
+
+```markdown
+Migrate [filename].js to TypeScript.
+
+## Requirements
+1. Rename file to .ts/.tsx
+2. Add type annotations to all:
+   - Function parameters
+   - Return types
+   - Variables where inference isn't clear
+3. Create interfaces for object shapes
+4. Fix any type errors
+
+## Reference
+See [example-file].ts for the pattern to follow
+
+## Verification
+- [ ] npx tsc --noEmit passes
+- [ ] All tests pass
+- [ ] No 'any' types except where explicitly needed
+```
+
+### Before
+
+```javascript
+// src/utils/format.js
+export function formatCurrency(amount, currency) {
+  const formatter = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: currency,
+  });
+  return formatter.format(amount);
+}
+
+export function formatDate(date, options) {
+  return new Date(date).toLocaleDateString('en-US', options);
+}
+```
+
+### After
+
+```typescript
+// src/utils/format.ts
+interface CurrencyFormatOptions {
+  currency: string;
+  locale?: string;
+}
+
+interface DateFormatOptions {
+  year?: 'numeric' | '2-digit';
+  month?: 'numeric' | '2-digit' | 'long' | 'short' | 'narrow';
+  day?: 'numeric' | '2-digit';
+}
+
+export function formatCurrency(
+  amount: number,
+  currency: string,
+  locale: string = 'en-US'
+): string {
+  const formatter = new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+  });
+  return formatter.format(amount);
+}
+
+export function formatDate(
+  date: Date | string,
+  options?: DateFormatOptions,
+  locale: string = 'en-US'
+): string {
+  return new Date(date).toLocaleDateString(locale, options);
+}
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Migrate in Dependency Order">
+    Start with files that have no internal dependencies, then work up the dependency tree.
+  </Accordion>
+  <Accordion title="Keep Changes Minimal">
+    Focus only on the migration. Don't refactor or add features simultaneously.
+  </Accordion>
+  <Accordion title="Verify After Each File">
+    Run type checking and tests after each file to catch issues early.
+  </Accordion>
+  <Accordion title="Preserve Behavior">
+    The goal is equivalent functionality, not improvement.
+  </Accordion>
+</AccordionGroup>
+
+## Parallel Migration
+
+For large codebases, migrate independent files in parallel:
+
+```markdown
+# Run these in parallel sessions:
+Session 1: Migrate src/utils/string.js
+Session 2: Migrate src/utils/number.js
+Session 3: Migrate src/utils/date.js
+```
+
+<Card title="See More Examples" icon="code" href="/use-cases/tutorials/getting-started">
+  Follow step-by-step migration tutorials
+</Card>
diff --git a/use-cases/examples/documentation.mdx b/use-cases/examples/documentation.mdx
new file mode 100644
index 00000000..b281677a
--- /dev/null
+++ b/use-cases/examples/documentation.mdx
@@ -0,0 +1,157 @@
+---
+title: "Documentation Generation"
+sidebarTitle: "Documentation"
+description: "Using OpenHands to generate and maintain documentation"
+---
+
+# Documentation Generation
+
+OpenHands can help create and maintain various types of documentation.
+
+## Documentation Types
+
+### Code Documentation
+
+- Docstrings and inline comments
+- API documentation
+- Type annotations
+
+### Project Documentation
+
+- README files
+- Contributing guides
+- Architecture docs
+
+### User Documentation
+
+- User guides
+- Tutorials
+- API references
+
+## Instruction Templates
+
+### Adding Docstrings
+
+```markdown
+Add docstrings to all public functions in [file].
+
+Style: [Google/NumPy/Sphinx]
+Reference: [example file with desired style]
+
+Include:
+- Brief description
+- Parameters with types
+- Return value with type
+- Exceptions raised
+- Example usage (for complex functions)
+```
+
+### README Generation
+
+```markdown
+Generate a README.md for this project.
+
+Include:
+- Project description
+- Installation instructions
+- Quick start guide
+- Configuration options
+- Contributing guidelines
+- License information
+
+Reference existing docs in /docs for accuracy.
+Follow the template in [example repo].
+```
+
+## Example: API Documentation
+
+### Request
+
+```markdown
+Generate API documentation for src/api/orders.py
+
+Format: Markdown file at docs/api/orders.md
+
+For each endpoint, include:
+- HTTP method and path
+- Description
+- Request parameters/body
+- Response format
+- Error responses
+- Example request/response
+
+Follow the format in docs/api/users.md
+```
+
+### Output
+
+```markdown
+# Orders API
+
+## Create Order
+
+`POST /api/orders`
+
+Creates a new order for the authenticated user.
+
+### Request Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| items | array | Yes | List of order items |
+| shipping_address | object | Yes | Delivery address |
+
+### Response
+
+```json
+{
+  "id": "ord_123",
+  "status": "pending",
+  "total": 99.99,
+  "created_at": "2024-01-15T10:30:00Z"
+}
+```
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 400 | Invalid request body |
+| 401 | Not authenticated |
+| 422 | Validation error |
+```
+
+## Best Practices
+
+<CardGroup cols={2}>
+  <Card title="Consistency" icon="equals">
+    Match existing documentation style
+  </Card>
+  <Card title="Accuracy" icon="check-double">
+    Documentation should match current code
+  </Card>
+  <Card title="Examples" icon="code">
+    Include working code examples
+  </Card>
+  <Card title="Keep Updated" icon="rotate">
+    Update docs when code changes
+  </Card>
+</CardGroup>
+
+## Maintaining Documentation
+
+Use OpenHands to keep documentation in sync:
+
+```markdown
+Update the API documentation for [endpoint] to reflect 
+the changes in PR #123.
+
+Changes to document:
+- New optional parameter: `include_metadata`
+- Updated response format (added `metadata` field)
+- New error code 429 for rate limiting
+```
+
+<Card title="Prompting Best Practices" icon="lightbulb" href="/openhands/usage/tips/prompting-best-practices">
+  Learn how to get better documentation output
+</Card>
diff --git a/use-cases/examples/refactoring.mdx b/use-cases/examples/refactoring.mdx
new file mode 100644
index 00000000..0c22fe44
--- /dev/null
+++ b/use-cases/examples/refactoring.mdx
@@ -0,0 +1,124 @@
+---
+title: "Code Refactoring"
+sidebarTitle: "Refactoring"
+description: "Using OpenHands for safe code refactoring"
+---
+
+# Code Refactoring
+
+OpenHands can help refactor code to improve quality while preserving functionality.
+
+## Refactoring Types
+
+### Structural Refactoring
+
+- Extract methods/functions
+- Extract classes
+- Move code to appropriate modules
+- Reduce duplication
+
+### Pattern Refactoring
+
+- Apply design patterns
+- Remove anti-patterns
+- Improve code organization
+
+### Performance Refactoring
+
+- Optimize algorithms
+- Reduce complexity
+- Improve efficiency
+
+## Prerequisites
+
+<Callout type="warning" title="Test Coverage First">
+Before refactoring, ensure adequate test coverage exists to verify behavior is preserved.
+</Callout>
+
+## Instruction Template
+
+```markdown
+## Current State
+[Describe the current code structure/issue]
+
+## Desired State  
+[Describe the target structure]
+
+## Scope
+Files to modify: [list]
+Files NOT to modify: [list]
+
+## Constraints
+- Maintain backward compatibility
+- No changes to public APIs
+- All tests must pass
+
+## Verification
+[How to verify the refactoring succeeded]
+```
+
+## Example: Extract Service
+
+### Request
+
+```markdown
+Extract email sending logic into a dedicated service.
+
+Current state:
+- Email sending scattered across UserController, OrderController, AuthController
+- Duplicate SMTP configuration in each location
+- No consistent error handling
+
+Desired state:
+- Single EmailService class
+- Consistent error handling and logging
+- Easy to mock for testing
+
+Files to modify:
+- Create: src/services/email_service.py
+- Update: src/controllers/user.py
+- Update: src/controllers/order.py
+- Update: src/controllers/auth.py
+
+Constraints:
+- Don't change email content
+- Don't change when emails are sent
+- Maintain existing function signatures
+
+Verification:
+- All existing tests pass
+- New unit tests for EmailService
+- Manual test: trigger each email type
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Small Steps">
+    Make incremental changes, verifying after each step.
+  </Accordion>
+  <Accordion title="Test First">
+    Ensure tests exist before refactoring.
+  </Accordion>
+  <Accordion title="Behavior Preservation">
+    Refactoring changes structure, not behavior.
+  </Accordion>
+  <Accordion title="Clear Boundaries">
+    Define exactly what should and shouldn't change.
+  </Accordion>
+</AccordionGroup>
+
+## Common Refactoring Tasks
+
+| Task | Good For |
+|------|----------|
+| Extract Method | Long functions with distinct sections |
+| Extract Class | Classes with multiple responsibilities |
+| Move Method | Method in wrong class |
+| Rename | Unclear naming |
+| Replace Conditional with Polymorphism | Complex if/else chains |
+| Introduce Parameter Object | Functions with many parameters |
+
+<Card title="Best Practices Guide" icon="lightbulb" href="/use-cases/best-practices">
+  More tips for successful refactoring
+</Card>
diff --git a/use-cases/examples/test-coverage.mdx b/use-cases/examples/test-coverage.mdx
new file mode 100644
index 00000000..e62433e5
--- /dev/null
+++ b/use-cases/examples/test-coverage.mdx
@@ -0,0 +1,211 @@
+---
+title: "Test Coverage"
+sidebarTitle: "Test Coverage"
+description: "Using OpenHands to improve test coverage"
+---
+
+# Improving Test Coverage
+
+OpenHands can systematically add tests to your codebase, improving reliability and enabling safe refactoring.
+
+## When to Use This
+
+- **Legacy code** without tests
+- **New features** needing test coverage
+- **Critical paths** requiring additional verification
+- **Pre-refactoring** to ensure behavior is captured
+
+## Test Types
+
+### Unit Tests
+
+Test individual functions or methods in isolation.
+
+```markdown
+Add unit tests for the validateEmail() function in src/utils/validation.js
+
+Test cases:
+1. Valid email formats (user@domain.com)
+2. Invalid formats (missing @, invalid TLD)
+3. Edge cases (empty string, null, undefined)
+4. International characters
+```
+
+### Integration Tests
+
+Test component interactions.
+
+```markdown
+Add integration tests for the user registration flow.
+
+Test the complete path:
+1. POST /api/register with valid data
+2. Verify user created in database
+3. Verify welcome email sent
+4. Verify response structure
+```
+
+### Component Tests (Frontend)
+
+Test UI components.
+
+```markdown
+Add tests for the LoginForm component.
+
+Test:
+1. Renders all required fields
+2. Shows validation errors on submit with empty fields
+3. Calls onSubmit with form data when valid
+4. Disables submit button while loading
+```
+
+## Instruction Templates
+
+### Unit Test Template
+
+```markdown
+Add unit tests for [function/class] in [file].
+
+Location: [test file path]
+Framework: [jest/pytest/etc]
+Follow pattern in: [example test file]
+
+Test cases:
+1. [Happy path description]
+2. [Error case 1]
+3. [Error case 2]
+4. [Edge case]
+
+Coverage target: [X]%
+```
+
+### Integration Test Template
+
+```markdown
+Add integration tests for [feature/endpoint].
+
+Location: [test file path]
+Setup: [database/mocks needed]
+
+Test scenarios:
+1. [Scenario 1 - expected flow]
+2. [Scenario 2 - error handling]
+3. [Scenario 3 - edge case]
+
+Assertions:
+- [What to verify]
+```
+
+## Example: Adding Unit Tests
+
+### Task
+
+```markdown
+Add unit tests for the OrderCalculator class.
+
+File: tests/unit/test_order_calculator.py
+Class: src/services/order_calculator.py
+
+Test cases for calculate_total():
+1. Single item order
+2. Multiple items
+3. Empty order (should return 0)
+4. Order with discount code
+5. Order with quantity > 1 of same item
+
+Test cases for apply_discount():
+1. Valid percentage discount
+2. Valid fixed amount discount
+3. Invalid discount code (should raise)
+4. Expired discount (should raise)
+
+Use pytest fixtures from conftest.py for test data.
+Mock the DiscountService for discount tests.
+```
+
+### Output
+
+```python
+import pytest
+from unittest.mock import Mock, patch
+from src.services.order_calculator import OrderCalculator
+from src.models import Order, OrderItem
+
+
+class TestOrderCalculator:
+    @pytest.fixture
+    def calculator(self):
+        return OrderCalculator()
+
+    @pytest.fixture
+    def sample_items(self):
+        return [
+            OrderItem(product_id=1, price=10.00, quantity=1),
+            OrderItem(product_id=2, price=25.00, quantity=2),
+        ]
+
+    def test_calculate_total_single_item(self, calculator):
+        items = [OrderItem(product_id=1, price=10.00, quantity=1)]
+        assert calculator.calculate_total(items) == 10.00
+
+    def test_calculate_total_multiple_items(self, calculator, sample_items):
+        # 10 + (25 * 2) = 60
+        assert calculator.calculate_total(sample_items) == 60.00
+
+    def test_calculate_total_empty_order(self, calculator):
+        assert calculator.calculate_total([]) == 0.00
+
+    @patch('src.services.order_calculator.DiscountService')
+    def test_apply_discount_percentage(self, mock_discount, calculator):
+        mock_discount.get_discount.return_value = {
+            'type': 'percentage',
+            'value': 10
+        }
+        result = calculator.apply_discount(100.00, 'SAVE10')
+        assert result == 90.00
+
+    @patch('src.services.order_calculator.DiscountService')
+    def test_apply_discount_invalid_code(self, mock_discount, calculator):
+        mock_discount.get_discount.side_effect = ValueError('Invalid code')
+        with pytest.raises(ValueError, match='Invalid code'):
+            calculator.apply_discount(100.00, 'INVALID')
+```
+
+## Best Practices
+
+<CardGroup cols={2}>
+  <Card title="Match Existing Patterns" icon="copy">
+    Follow the testing patterns already in the codebase
+  </Card>
+  <Card title="Test Behavior, Not Implementation" icon="check">
+    Focus on what the code does, not how it does it
+  </Card>
+  <Card title="Include Edge Cases" icon="border-all">
+    Test boundaries, empty inputs, and error conditions
+  </Card>
+  <Card title="Use Meaningful Names" icon="tag">
+    Test names should describe the scenario being tested
+  </Card>
+</CardGroup>
+
+## Coverage Strategies
+
+### By Module
+
+```markdown
+Week 1: src/services/ (critical business logic)
+Week 2: src/api/ (endpoint handlers)
+Week 3: src/utils/ (helper functions)
+```
+
+### By Criticality
+
+1. Payment processing
+2. Authentication
+3. Data validation
+4. Business rules
+5. UI components
+
+<Card title="Tutorial: Adding Test Coverage" icon="graduation-cap" href="/use-cases/tutorials/test-coverage">
+  Follow a step-by-step tutorial
+</Card>
diff --git a/use-cases/overview.mdx b/use-cases/overview.mdx
new file mode 100644
index 00000000..6cd01158
--- /dev/null
+++ b/use-cases/overview.mdx
@@ -0,0 +1,109 @@
+---
+title: "Use Cases Overview"
+sidebarTitle: "Overview"
+description: "Explore proven use cases and examples for OpenHands"
+---
+
+# Use Cases Overview
+
+Discover how teams use OpenHands to accelerate development, improve code quality, and automate engineering workflows.
+
+## What Makes a Good Use Case
+
+The best tasks for OpenHands are:
+
+<CardGroup cols={2}>
+  <Card title="Clearly Scoped" icon="crosshairs">
+    Tasks with well-defined boundaries and acceptance criteria
+  </Card>
+  <Card title="Verifiable" icon="check-circle">
+    Results that can be validated through tests or inspection
+  </Card>
+  <Card title="Repeatable" icon="repeat">
+    Patterns that can be applied across multiple files or projects
+  </Card>
+  <Card title="Well-Documented" icon="book">
+    Sufficient context available in the codebase or instructions
+  </Card>
+</CardGroup>
+
+## Popular Use Cases
+
+### Code Migrations & Modernization
+
+OpenHands excels at systematic code transformations:
+
+<CardGroup cols={2}>
+  <Card title="Code Migrations" icon="arrow-right" href="/use-cases/examples/code-migrations">
+    Language and framework migrations
+  </Card>
+  <Card title="Refactoring" icon="wand-magic-sparkles" href="/use-cases/examples/refactoring">
+    Code cleanup and restructuring
+  </Card>
+</CardGroup>
+
+### Quality & Testing
+
+Improve code quality and test coverage:
+
+<CardGroup cols={2}>
+  <Card title="Test Coverage" icon="vial" href="/use-cases/examples/test-coverage">
+    Adding tests to existing code
+  </Card>
+  <Card title="Bug Fixing" icon="bug" href="/use-cases/examples/bug-fixing">
+    Debugging and fixing issues
+  </Card>
+</CardGroup>
+
+### Development Workflows
+
+Streamline common development tasks:
+
+<CardGroup cols={2}>
+  <Card title="Documentation" icon="file-lines" href="/use-cases/examples/documentation">
+    Generate and maintain docs
+  </Card>
+  <Card title="API Integration" icon="plug" href="/use-cases/examples/api-integration">
+    Working with external APIs
+  </Card>
+</CardGroup>
+
+## Success Stories
+
+Teams using OpenHands effectively report:
+
+- **50-70% reduction** in time spent on repetitive tasks
+- **Faster onboarding** with automated code understanding
+- **Improved test coverage** through systematic test generation
+- **Reduced technical debt** via automated refactoring
+
+## Getting Started
+
+<Steps>
+  <Step title="Choose Your Use Case">
+    Browse the [use cases](/use-cases/examples/code-migrations) to find one that matches your needs
+  </Step>
+  <Step title="Follow a Tutorial">
+    Work through a [tutorial](/use-cases/tutorials/getting-started) to learn the patterns
+  </Step>
+  <Step title="Use the Prompt Library">
+    Find ready-to-use [prompts](/use-cases/prompts/testing-refactoring) for common tasks
+  </Step>
+  <Step title="Customize for Your Project">
+    Create [Skills](/overview/skills) to encode project-specific context
+  </Step>
+</Steps>
+
+## Best Practices
+
+For the best results:
+
+1. **Start small**: Begin with simple, well-defined tasks
+2. **Provide context**: Include relevant background information
+3. **Set clear criteria**: Define what "done" looks like
+4. **Verify results**: Always review and test the output
+5. **Iterate**: Refine your approach based on results
+
+<Card title="Best Practices Guide" icon="lightbulb" href="/use-cases/best-practices">
+  Learn detailed best practices for each use case type
+</Card>
diff --git a/use-cases/prompts/data-analysis.mdx b/use-cases/prompts/data-analysis.mdx
new file mode 100644
index 00000000..4145cd72
--- /dev/null
+++ b/use-cases/prompts/data-analysis.mdx
@@ -0,0 +1,256 @@
+---
+title: "Data & Analysis Prompts"
+sidebarTitle: "Data & Analysis"
+description: "Ready-to-use prompts for data processing and analysis tasks"
+---
+
+# Data & Analysis Prompts
+
+Copy and customize these prompts for data processing and analysis tasks.
+
+## Data Processing Prompts
+
+### Create Data Pipeline
+
+```markdown
+Create a data pipeline to process [data_source].
+
+Input: [file format, API endpoint, database table]
+Output: [destination and format]
+
+Processing steps:
+1. Extract from [source]
+2. Validate [validation rules]
+3. Transform [transformations needed]
+4. Load to [destination]
+
+Error handling:
+- Log invalid records
+- Continue on non-critical errors
+- Fail fast on critical issues
+
+Add tests with sample data.
+```
+
+### Data Validation
+
+```markdown
+Add data validation for [model/schema].
+
+Validate:
+- Required fields: [list]
+- Format validations: [email, phone, etc]
+- Range validations: [min/max values]
+- Custom rules: [business logic]
+
+On validation failure:
+- Return specific error messages
+- Include field name and invalid value
+- Support multiple errors per record
+```
+
+### CSV/JSON Processing
+
+```markdown
+Create a utility to process [file_type] files.
+
+Features:
+- Read large files efficiently (streaming)
+- Handle encoding issues
+- Skip header row (configurable)
+- Map columns to model
+
+Input: [file path or file object]
+Output: [list of objects, generator, etc]
+
+Include:
+- Progress callback for large files
+- Error handling for malformed rows
+- Type conversion (strings to dates, numbers)
+```
+
+## Analysis Prompts
+
+### Generate Report
+
+```markdown
+Create a report generator for [report_name].
+
+Data sources:
+- [source 1]
+- [source 2]
+
+Metrics to calculate:
+- [metric 1]: [formula/logic]
+- [metric 2]: [formula/logic]
+- [metric 3]: [formula/logic]
+
+Output format: [PDF/HTML/JSON]
+
+Include:
+- Summary statistics
+- Trends over time
+- Comparison with previous period
+```
+
+### Data Aggregation
+
+```markdown
+Create aggregation functions for [data_type].
+
+Aggregations needed:
+1. Group by [field] and calculate:
+   - Count
+   - Sum of [amount_field]
+   - Average of [value_field]
+   
+2. Time-based aggregation:
+   - Daily/Weekly/Monthly totals
+   - Running averages
+   - Period-over-period comparison
+
+Output as [DataFrame/dict/JSON].
+```
+
+### Statistical Analysis
+
+```markdown
+Add statistical analysis to [data_module].
+
+Calculate:
+- Descriptive stats (mean, median, std, min, max)
+- Distribution analysis
+- Correlation between [field1] and [field2]
+- Outlier detection
+
+Visualization:
+- Histogram for distribution
+- Scatter plot for correlation
+- Box plot for outliers
+
+Use [pandas/numpy/scipy] following project conventions.
+```
+
+## Database Prompts
+
+### Write SQL Query
+
+```markdown
+Write a SQL query to [objective].
+
+Tables involved:
+- [table1]: [columns]
+- [table2]: [columns]
+
+Requirements:
+- [filter conditions]
+- [join logic]
+- [grouping/aggregation]
+- [sorting]
+
+Performance considerations:
+- Use indexes on [fields]
+- Limit results to [N]
+- Avoid full table scans
+```
+
+### Database Migration
+
+```markdown
+Create a database migration for [change].
+
+Changes:
+- Add column: [column_name] [type] to [table]
+- Modify column: [changes]
+- Add index on: [columns]
+- Create table: [schema]
+
+Include:
+- Up migration
+- Down migration (rollback)
+- Data migration script if needed
+
+Test with sample data before and after.
+```
+
+### Query Optimization
+
+```markdown
+Optimize this slow query:
+
+```sql
+[paste query]
+```
+
+Current performance: [time/rows scanned]
+Target: [desired performance]
+
+Analyze:
+- Missing indexes
+- Inefficient joins
+- Subquery vs join opportunities
+- Query plan analysis
+
+Provide optimized query and explanation.
+```
+
+## Data Integration Prompts
+
+### API Data Sync
+
+```markdown
+Create a sync job for [external_api] data.
+
+API details:
+- Endpoint: [url]
+- Auth: [method]
+- Rate limit: [requests/minute]
+
+Sync logic:
+- Full sync: [when/how]
+- Incremental sync: [based on timestamp/id]
+- Conflict resolution: [strategy]
+
+Error handling:
+- Retry on transient errors
+- Log permanent failures
+- Alert on threshold exceeded
+```
+
+### ETL Script
+
+```markdown
+Create an ETL script for [data_source] to [destination].
+
+Extract:
+- Source: [database/API/file]
+- Query/Filter: [conditions]
+- Frequency: [schedule]
+
+Transform:
+- [transformation 1]
+- [transformation 2]
+- Data cleaning rules
+
+Load:
+- Destination: [target]
+- Mode: [insert/upsert/replace]
+- Batch size: [number]
+
+Add logging for monitoring and debugging.
+```
+
+## Quick Reference
+
+| Task | Key Elements |
+|------|--------------|
+| Pipeline | Source, destination, steps, error handling |
+| Validation | Rules, error messages, failure handling |
+| Report | Data sources, metrics, output format |
+| SQL | Tables, joins, filters, performance |
+| Migration | Changes, up/down scripts, data migration |
+| ETL | Extract source, transforms, load destination |
+
+<Card title="Best Practices" icon="lightbulb" href="/use-cases/best-practices">
+  Learn how to structure data tasks effectively
+</Card>
diff --git a/use-cases/prompts/testing-refactoring.mdx b/use-cases/prompts/testing-refactoring.mdx
new file mode 100644
index 00000000..2000c892
--- /dev/null
+++ b/use-cases/prompts/testing-refactoring.mdx
@@ -0,0 +1,213 @@
+---
+title: "Testing & Refactoring Prompts"
+sidebarTitle: "Testing & Refactoring"
+description: "Ready-to-use prompts for testing and refactoring tasks"
+---
+
+# Testing & Refactoring Prompts
+
+Copy and customize these prompts for common testing and refactoring tasks.
+
+## Unit Testing Prompts
+
+### Add Unit Tests to a Function
+
+```markdown
+Add unit tests for the [function_name] function in [file_path].
+
+Test cases to cover:
+1. Happy path with valid input
+2. Edge case: empty input
+3. Edge case: null/undefined input  
+4. Error case: invalid input type
+5. Boundary conditions
+
+Framework: [pytest/jest/etc]
+Location: [test_file_path]
+Follow patterns in: [example_test_file]
+```
+
+### Increase Test Coverage
+
+```markdown
+Increase test coverage for [module_name] from [current]% to [target]%.
+
+Priority order:
+1. Untested public methods
+2. Error handling paths
+3. Edge cases in existing tests
+4. Integration points
+
+Generate a coverage report first, then add tests for uncovered lines.
+```
+
+### Add Integration Tests
+
+```markdown
+Add integration tests for the [feature] workflow.
+
+Test the complete flow:
+1. [Step 1]
+2. [Step 2]  
+3. [Step 3]
+
+Setup requirements:
+- Test database with seed data
+- Mock external services: [list]
+
+Assertions:
+- Database state after each step
+- API response formats
+- Side effects (emails, events, etc.)
+```
+
+## Refactoring Prompts
+
+### Extract Method
+
+```markdown
+Extract the code block at lines [X-Y] in [file] into a new method.
+
+New method:
+- Name: [method_name]
+- Parameters: [infer from extracted code]
+- Return type: [infer or specify]
+
+Requirements:
+- Update original code to call new method
+- Add docstring to new method
+- All tests must pass
+```
+
+### Extract Class
+
+```markdown
+Extract [responsibility] from [class_name] into a new class.
+
+New class: [NewClassName]
+Location: [file_path]
+
+Move these methods:
+- [method1]
+- [method2]
+
+Move these properties:
+- [property1]
+- [property2]
+
+Update [OriginalClass] to use [NewClassName] via composition.
+Maintain backward compatibility.
+```
+
+### Reduce Duplication
+
+```markdown
+Identify and eliminate code duplication in [module/directory].
+
+Analysis:
+1. Find duplicate or near-duplicate code blocks
+2. Identify common patterns that should be abstracted
+
+Actions:
+1. Create shared utility functions
+2. Extract common base classes if appropriate
+3. Update all usages to use shared code
+4. Ensure all tests pass
+```
+
+### Improve Error Handling
+
+```markdown
+Improve error handling in [file/module].
+
+Current issues:
+- Generic exceptions caught everywhere
+- Errors not logged properly
+- Missing error recovery
+
+Requirements:
+1. Create specific exception classes
+2. Add proper try/catch blocks
+3. Log errors with context
+4. Implement graceful degradation where possible
+5. Update tests to verify error handling
+```
+
+### Apply Design Pattern
+
+```markdown
+Refactor [code_area] to use the [Pattern] pattern.
+
+Current implementation:
+[Describe current approach]
+
+Target:
+Apply [Strategy/Factory/Observer/etc] pattern to:
+- [Benefit 1]
+- [Benefit 2]
+
+Constraints:
+- Maintain existing public API
+- All tests must pass
+- Add tests for new pattern usage
+```
+
+## Code Quality Prompts
+
+### Add Type Annotations
+
+```markdown
+Add type annotations to all functions in [file].
+
+Requirements:
+- Parameter types
+- Return types
+- Generic types where appropriate
+- No 'any' types unless necessary
+
+Verify with: [mypy/tsc --noEmit]
+```
+
+### Add Docstrings
+
+```markdown
+Add docstrings to all public functions/classes in [file].
+
+Style: [Google/NumPy/JSDoc]
+
+Include:
+- Brief description
+- Parameters with types
+- Return value
+- Exceptions raised
+- Example usage (for complex functions)
+```
+
+### Improve Naming
+
+```markdown
+Review and improve naming in [file/module].
+
+Check:
+- Variables: descriptive, not abbreviated
+- Functions: verb-based, clear purpose
+- Classes: noun-based, single responsibility
+- Constants: UPPER_CASE with clear meaning
+
+Rename anything unclear, updating all references.
+```
+
+## Quick Reference
+
+| Task | Key Elements to Include |
+|------|------------------------|
+| Unit test | Function, test cases, framework, location |
+| Integration test | Workflow steps, setup, assertions |
+| Extract method | Code location, new name, requirements |
+| Extract class | Methods to move, new class details |
+| Error handling | Current issues, desired behavior |
+| Type annotations | File, verification command |
+
+<Card title="Good vs Bad Instructions" icon="scale-balanced" href="/openhands/usage/tips/good-vs-bad-instructions">
+  Learn how to customize these prompts effectively
+</Card>
diff --git a/use-cases/prompts/web-development.mdx b/use-cases/prompts/web-development.mdx
new file mode 100644
index 00000000..85312afd
--- /dev/null
+++ b/use-cases/prompts/web-development.mdx
@@ -0,0 +1,278 @@
+---
+title: "Web Development Prompts"
+sidebarTitle: "Web Development"
+description: "Ready-to-use prompts for web development tasks"
+---
+
+# Web Development Prompts
+
+Copy and customize these prompts for frontend and full-stack web development tasks.
+
+## Component Prompts
+
+### Create UI Component
+
+```markdown
+Create a [ComponentName] component.
+
+Location: src/components/[ComponentName]/[ComponentName].tsx
+
+Props:
+- [prop1]: [type] - [description]
+- [prop2]: [type] - [description]
+- [prop3]?: [type] - [optional, default: value]
+
+Features:
+- [Feature 1]
+- [Feature 2]
+
+Styling: [Tailwind/CSS Modules/styled-components]
+Follow patterns in: src/components/[ExampleComponent]
+
+Include:
+- TypeScript interfaces
+- Default props
+- Unit tests
+- Storybook story (if applicable)
+```
+
+### Create Form Component
+
+```markdown
+Create a form for [purpose].
+
+Location: src/components/forms/[FormName].tsx
+
+Fields:
+- [field1]: [type] - [validation rules]
+- [field2]: [type] - [validation rules]
+- [field3]: [type] - [validation rules]
+
+Behavior:
+- Validation on blur and submit
+- Error messages under fields
+- Loading state on submit
+- Success/error callbacks
+
+Use: [react-hook-form/formik/etc]
+Validation: [zod/yup/etc]
+```
+
+### Create Modal/Dialog
+
+```markdown
+Create a modal component for [purpose].
+
+Props:
+- isOpen: boolean
+- onClose: () => void
+- title: string
+- [additional props]
+
+Features:
+- Close on backdrop click
+- Close on Escape key
+- Focus trap inside modal
+- Animated open/close
+- Accessible (ARIA)
+
+Content: [describe content/children]
+Actions: [button labels and behaviors]
+```
+
+## Page Prompts
+
+### Create Page/Route
+
+```markdown
+Create the [PageName] page.
+
+Route: /[path]
+Location: src/pages/[PageName]/[PageName].tsx
+
+Sections:
+1. [Section 1 description]
+2. [Section 2 description]
+3. [Section 3 description]
+
+Data requirements:
+- Fetch from: [API endpoint]
+- State management: [local/context/store]
+
+Features:
+- Loading skeleton
+- Error state
+- Empty state
+- Responsive layout
+```
+
+### Create Dashboard Page
+
+```markdown
+Create a dashboard page showing [overview].
+
+Sections:
+1. Summary cards: [metrics to show]
+2. Charts: [chart types and data]
+3. Recent activity: [list of items]
+4. Quick actions: [buttons/links]
+
+Data sources:
+- [endpoint 1] for [data]
+- [endpoint 2] for [data]
+
+Refresh: [auto-refresh interval or manual]
+```
+
+## API Prompts
+
+### Create API Endpoint
+
+```markdown
+Create a REST endpoint for [resource].
+
+Method: [GET/POST/PUT/DELETE]
+Path: /api/[path]
+Location: src/api/[handler].ts
+
+Request:
+- Headers: [auth requirements]
+- Body: [schema if applicable]
+- Query params: [parameters]
+
+Response:
+- Success: [status code, body schema]
+- Errors: [error codes and messages]
+
+Include:
+- Input validation
+- Error handling
+- Rate limiting (if applicable)
+- Tests
+```
+
+### Create API Client
+
+```markdown
+Create an API client for [service].
+
+Location: src/services/[ServiceName]Client.ts
+
+Methods:
+- [method1]: [description, params, return]
+- [method2]: [description, params, return]
+- [method3]: [description, params, return]
+
+Features:
+- TypeScript types for all requests/responses
+- Error handling with custom exceptions
+- Request/response interceptors
+- Retry logic for transient failures
+- Request cancellation support
+
+Base URL: [from environment config]
+Auth: [token/API key handling]
+```
+
+## State Management Prompts
+
+### Create Store/Context
+
+```markdown
+Create state management for [feature].
+
+Location: src/store/[feature].ts
+
+State:
+- [property1]: [type]
+- [property2]: [type]
+
+Actions:
+- [action1]: [description]
+- [action2]: [description]
+
+Use: [zustand/redux/context]
+Follow patterns in: src/store/[existing_store]
+
+Include persistence to localStorage for: [which state]
+```
+
+### Add Data Fetching
+
+```markdown
+Add data fetching for [resource] with caching.
+
+Hook: src/hooks/use[Resource].ts
+
+Features:
+- Fetch data from [endpoint]
+- Cache with [react-query/SWR/etc]
+- Automatic refetch on window focus
+- Optimistic updates for mutations
+- Loading and error states
+
+Types: Define TypeScript interfaces for response data.
+```
+
+## Styling Prompts
+
+### Add Responsive Styles
+
+```markdown
+Make [component/page] responsive.
+
+Breakpoints:
+- Mobile: < 640px
+- Tablet: 640-1024px
+- Desktop: > 1024px
+
+Mobile changes:
+- [change 1]
+- [change 2]
+
+Tablet changes:
+- [change 1]
+- [change 2]
+
+Test on: [specific devices/dimensions]
+```
+
+### Create Theme/Design Tokens
+
+```markdown
+Create design tokens for the application.
+
+Location: src/styles/tokens.ts
+
+Colors:
+- Primary: [hex values for shades]
+- Secondary: [hex values]
+- Neutral: [gray scale]
+- Semantic: success, warning, error, info
+
+Typography:
+- Font families
+- Font sizes
+- Line heights
+- Font weights
+
+Spacing:
+- Scale (4, 8, 12, 16, 24, 32, 48, 64)
+
+Export for use with [Tailwind/CSS-in-JS/etc]
+```
+
+## Quick Reference
+
+| Task | Key Elements |
+|------|--------------|
+| Component | Props, features, styling, tests |
+| Form | Fields, validation, submit handling |
+| Page | Sections, data, states |
+| API | Method, path, request/response, errors |
+| State | Properties, actions, persistence |
+| Styling | Breakpoints, changes per size |
+
+<Card title="Frontend Tutorial" icon="browser" href="/use-cases/tutorials/frontend-development">
+  See full frontend development tutorials
+</Card>
diff --git a/use-cases/tutorials/containerization.mdx b/use-cases/tutorials/containerization.mdx
new file mode 100644
index 00000000..0d7432f2
--- /dev/null
+++ b/use-cases/tutorials/containerization.mdx
@@ -0,0 +1,224 @@
+---
+title: "Containerize an Application"
+sidebarTitle: "Containerization"
+description: "Tutorial: Dockerize an application with OpenHands"
+---
+
+# Tutorial: Containerize an Application
+
+Learn how to use OpenHands to containerize an existing application with Docker.
+
+## Prerequisites
+
+- Existing application to containerize
+- Docker installed locally
+- OpenHands CLI or Cloud access
+
+## What We'll Create
+
+- Optimized Dockerfile
+- Docker Compose configuration
+- Development and production setups
+- CI/CD integration
+
+## Step 1: Analyze the Application
+
+First, have OpenHands analyze your app:
+
+```markdown
+Analyze this application and determine containerization requirements.
+
+Check:
+1. Language/runtime requirements
+2. Dependencies and build steps
+3. Environment variables needed
+4. Ports to expose
+5. External service dependencies (database, cache, etc.)
+6. Static files or assets
+
+Output a containerization plan.
+```
+
+## Step 2: Create the Dockerfile
+
+```markdown
+Create an optimized Dockerfile for this application.
+
+Requirements:
+- Multi-stage build for smaller image
+- Non-root user for security
+- Proper layer caching
+- Health check endpoint
+
+Application details:
+- Python 3.11 / Node 18 / etc.
+- Dependencies in requirements.txt / package.json
+- Entry point: [command]
+- Port: [port]
+
+Follow best practices:
+- Pin base image versions
+- Minimize layers
+- Copy requirements before source code
+- Use .dockerignore
+```
+
+### Example Output (Python)
+
+```dockerfile
+# Build stage
+FROM python:3.11-slim as builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip wheel --no-cache-dir --no-deps --wheel-dir /app/wheels -r requirements.txt
+
+# Production stage
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Create non-root user
+RUN useradd --create-home --shell /bin/bash app
+USER app
+
+# Install dependencies from wheels
+COPY --from=builder /app/wheels /wheels
+RUN pip install --no-cache-dir /wheels/*
+
+# Copy application code
+COPY --chown=app:app . .
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=3s \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+## Step 3: Create Docker Compose
+
+```markdown
+Create docker-compose.yml for local development.
+
+Include:
+- Application service
+- Database (PostgreSQL)
+- Redis (if used)
+- Volume mounts for hot reload
+- Environment file support
+
+Development features:
+- Source code mounted as volume
+- Debug mode enabled
+- Exposed ports for debugging
+```
+
+### Example Output
+
+```yaml
+version: '3.8'
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8000"
+    volumes:
+      - .:/app
+    environment:
+      - DATABASE_URL=postgresql://user:pass@db:5432/app
+      - REDIS_URL=redis://redis:6379
+    depends_on:
+      - db
+      - redis
+    
+  db:
+    image: postgres:15
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: pass
+      POSTGRES_DB: app
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    
+  redis:
+    image: redis:7-alpine
+
+volumes:
+  postgres_data:
+```
+
+## Step 4: Add Production Configuration
+
+```markdown
+Create production docker-compose configuration.
+
+Differences from development:
+- No volume mounts (use built image)
+- Production environment variables
+- Resource limits
+- Restart policies
+- Logging configuration
+```
+
+## Step 5: Test the Container
+
+Verify the containerized application:
+
+```bash
+# Build
+docker-compose build
+
+# Run
+docker-compose up -d
+
+# Check logs
+docker-compose logs -f app
+
+# Test health
+curl http://localhost:8000/health
+
+# Run tests in container
+docker-compose exec app pytest
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Use Multi-Stage Builds">
+    Keep production images small by separating build and runtime stages.
+  </Accordion>
+  <Accordion title="Don't Run as Root">
+    Create and use a non-root user for security.
+  </Accordion>
+  <Accordion title="Optimize Layer Caching">
+    Copy dependency files before source code for better caching.
+  </Accordion>
+  <Accordion title="Include Health Checks">
+    Enable orchestrators to monitor container health.
+  </Accordion>
+</AccordionGroup>
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Large image size | Use multi-stage builds, slim base images |
+| Slow builds | Optimize layer ordering for caching |
+| Permission errors | Check user permissions, file ownership |
+| Connection refused | Verify port mappings, network configuration |
+
+<Card title="More Tutorials" icon="graduation-cap" href="/use-cases/tutorials/getting-started">
+  Explore other tutorials
+</Card>
diff --git a/use-cases/tutorials/frontend-development.mdx b/use-cases/tutorials/frontend-development.mdx
new file mode 100644
index 00000000..b2ad3cfb
--- /dev/null
+++ b/use-cases/tutorials/frontend-development.mdx
@@ -0,0 +1,198 @@
+---
+title: "Frontend Development"
+sidebarTitle: "Frontend Development"
+description: "Tutorial: Build frontend features with OpenHands"
+---
+
+# Tutorial: Frontend Development
+
+Learn how to use OpenHands for frontend development tasks including components, features, and UI improvements.
+
+## Prerequisites
+
+- Frontend project (React, Vue, Angular, etc.)
+- OpenHands CLI or Cloud access
+- Basic frontend knowledge
+
+## Common Frontend Tasks
+
+<CardGroup cols={2}>
+  <Card title="Components" icon="cube">
+    Build reusable UI components
+  </Card>
+  <Card title="Features" icon="puzzle-piece">
+    Implement complete features
+  </Card>
+  <Card title="Styling" icon="palette">
+    Add styling and responsive design
+  </Card>
+  <Card title="State" icon="database">
+    Manage application state
+  </Card>
+</CardGroup>
+
+## Example 1: Build a Component
+
+### Task: Create a Data Table Component
+
+```markdown
+Create a reusable DataTable component.
+
+Location: src/components/DataTable/DataTable.tsx
+
+Features:
+- Accept data array and column configuration
+- Sortable columns (click header to sort)
+- Pagination with configurable page size
+- Loading and empty states
+- Responsive design
+
+Props interface:
+```typescript
+interface DataTableProps<T> {
+  data: T[];
+  columns: Column<T>[];
+  pageSize?: number;
+  loading?: boolean;
+  onRowClick?: (row: T) => void;
+}
+```
+
+Styling:
+- Use existing Tailwind classes
+- Follow patterns in src/components/Card
+
+Tests:
+- Renders with data
+- Sorting works
+- Pagination works
+- Shows loading state
+- Shows empty state
+```
+
+## Example 2: Implement a Feature
+
+### Task: Add Search Functionality
+
+```markdown
+Add search/filter functionality to the products page.
+
+Location: src/pages/Products/Products.tsx
+
+Requirements:
+1. Search input in the header area
+2. Debounced search (300ms delay)
+3. Filter by: name, category, price range
+4. Clear filters button
+5. Persist filters in URL params
+6. Loading state while filtering
+
+UI/UX:
+- Search icon in input
+- Show active filter count
+- Animate filter panel open/close
+
+Use existing hooks:
+- useDebounce from src/hooks
+- useQueryParams for URL sync
+```
+
+## Example 3: Responsive Design
+
+### Task: Make Dashboard Mobile-Friendly
+
+```markdown
+Make the dashboard responsive for mobile devices.
+
+File: src/pages/Dashboard/Dashboard.tsx
+
+Current issues:
+- Cards overflow on small screens
+- Navigation not usable on mobile
+- Charts too small to read
+
+Requirements:
+1. Stack cards vertically on mobile
+2. Collapsible sidebar navigation
+3. Touch-friendly chart interactions
+4. Readable font sizes
+
+Breakpoints:
+- Mobile: < 640px
+- Tablet: 640px - 1024px
+- Desktop: > 1024px
+
+Test on:
+- iPhone SE (375px)
+- iPad (768px)
+- Desktop (1440px)
+```
+
+## Example 4: State Management
+
+### Task: Add Shopping Cart State
+
+```markdown
+Implement shopping cart state management.
+
+State requirements:
+- Items in cart (product, quantity)
+- Cart total (with discounts)
+- Persist to localStorage
+- Sync across tabs
+
+Actions:
+- addItem(product, quantity)
+- removeItem(productId)
+- updateQuantity(productId, quantity)
+- clearCart()
+- applyDiscount(code)
+
+Location: 
+- Store: src/store/cart.ts
+- Hook: src/hooks/useCart.ts
+
+Use Zustand following patterns in src/store/user.ts
+```
+
+## Frontend Best Practices
+
+<AccordionGroup>
+  <Accordion title="Component Design">
+    - Single responsibility
+    - Props for customization
+    - Sensible defaults
+    - TypeScript interfaces
+  </Accordion>
+  <Accordion title="Performance">
+    - Memoize expensive computations
+    - Lazy load routes/components
+    - Optimize re-renders
+    - Use proper keys in lists
+  </Accordion>
+  <Accordion title="Accessibility">
+    - Semantic HTML
+    - ARIA labels
+    - Keyboard navigation
+    - Color contrast
+  </Accordion>
+  <Accordion title="Testing">
+    - Unit tests for logic
+    - Component tests for rendering
+    - E2E for critical flows
+  </Accordion>
+</AccordionGroup>
+
+## Tips for Frontend Tasks
+
+| Do | Don't |
+|----|-------|
+| Specify design system/patterns | Assume styling approach |
+| Include responsive requirements | Ignore mobile |
+| Reference existing components | Create from scratch unnecessarily |
+| Specify state management approach | Leave state undefined |
+| Include accessibility requirements | Skip a11y |
+
+<Card title="More Tutorials" icon="graduation-cap" href="/use-cases/tutorials/getting-started">
+  Explore other tutorials
+</Card>
diff --git a/use-cases/tutorials/getting-started.mdx b/use-cases/tutorials/getting-started.mdx
new file mode 100644
index 00000000..4dbbfea7
--- /dev/null
+++ b/use-cases/tutorials/getting-started.mdx
@@ -0,0 +1,133 @@
+---
+title: "Getting Started with Tutorials"
+sidebarTitle: "Getting Started"
+description: "Learn OpenHands through hands-on tutorials"
+---
+
+# Getting Started with Tutorials
+
+These tutorials will help you learn OpenHands by working through practical examples.
+
+## Tutorial Structure
+
+Each tutorial follows this pattern:
+
+<Steps>
+  <Step title="Setup">
+    Prerequisites and environment setup
+  </Step>
+  <Step title="Task Definition">
+    Clear description of what we'll build
+  </Step>
+  <Step title="Implementation">
+    Step-by-step instructions for OpenHands
+  </Step>
+  <Step title="Verification">
+    How to test the results
+  </Step>
+</Steps>
+
+## Available Tutorials
+
+<CardGroup cols={2}>
+  <Card title="Build a REST API" icon="server" href="/use-cases/tutorials/rest-api">
+    Create a complete REST API from scratch
+  </Card>
+  <Card title="Add Test Coverage" icon="vial" href="/use-cases/tutorials/test-coverage">
+    Add comprehensive tests to existing code
+  </Card>
+  <Card title="Containerize an App" icon="docker" href="/use-cases/tutorials/containerization">
+    Package an application with Docker
+  </Card>
+  <Card title="Frontend Development" icon="browser" href="/use-cases/tutorials/frontend-development">
+    Build UI components and features
+  </Card>
+</CardGroup>
+
+## Your First Tutorial
+
+Start with this simple task to get familiar with OpenHands:
+
+### Task: Add a Utility Function
+
+```markdown
+Create a utility function that validates email addresses.
+
+Location: src/utils/validation.py
+
+Requirements:
+1. Function name: validate_email
+2. Accept a string parameter
+3. Return True if valid email format, False otherwise
+4. Handle edge cases (empty string, None)
+
+Add tests in: tests/utils/test_validation.py
+
+Test cases:
+- Valid emails (user@domain.com, user+tag@domain.co.uk)
+- Invalid emails (missing @, no domain, etc.)
+- Edge cases (empty, None, whitespace)
+```
+
+### Expected Outcome
+
+OpenHands will create:
+
+1. **The validation function:**
+```python
+# src/utils/validation.py
+import re
+
+def validate_email(email: str | None) -> bool:
+    """Validate email address format."""
+    if not email or not isinstance(email, str):
+        return False
+    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+    return bool(re.match(pattern, email.strip()))
+```
+
+2. **Tests:**
+```python
+# tests/utils/test_validation.py
+import pytest
+from src.utils.validation import validate_email
+
+class TestValidateEmail:
+    def test_valid_email(self):
+        assert validate_email("user@example.com") is True
+    
+    def test_invalid_email_no_at(self):
+        assert validate_email("userexample.com") is False
+    
+    def test_empty_string(self):
+        assert validate_email("") is False
+    
+    def test_none(self):
+        assert validate_email(None) is False
+```
+
+## Tips for Success
+
+<AccordionGroup>
+  <Accordion title="Read the Full Task">
+    Make sure you understand all requirements before starting.
+  </Accordion>
+  <Accordion title="Run Incrementally">
+    Test each step before moving to the next.
+  </Accordion>
+  <Accordion title="Ask for Help">
+    If something isn't working, provide feedback to OpenHands.
+  </Accordion>
+</AccordionGroup>
+
+## Next Steps
+
+Choose a tutorial based on your goals:
+
+- **Learning OpenHands**: Start with [Build a REST API](/use-cases/tutorials/rest-api)
+- **Improving existing code**: Try [Add Test Coverage](/use-cases/tutorials/test-coverage)
+- **DevOps tasks**: Go to [Containerization](/use-cases/tutorials/containerization)
+
+<Card title="First Projects" icon="rocket" href="/overview/first-projects">
+  More project ideas to try with OpenHands
+</Card>
diff --git a/use-cases/tutorials/rest-api.mdx b/use-cases/tutorials/rest-api.mdx
new file mode 100644
index 00000000..8de6fbf4
--- /dev/null
+++ b/use-cases/tutorials/rest-api.mdx
@@ -0,0 +1,173 @@
+---
+title: "Build a REST API"
+sidebarTitle: "REST API"
+description: "Tutorial: Create a REST API with OpenHands"
+---
+
+# Tutorial: Build a REST API
+
+In this tutorial, you'll use OpenHands to build a complete REST API for a task management application.
+
+## Prerequisites
+
+- OpenHands CLI or Cloud access
+- Python 3.10+ environment
+- Basic understanding of REST APIs
+
+## What We'll Build
+
+A task management API with:
+- CRUD operations for tasks
+- User authentication
+- Input validation
+- Error handling
+
+## Step 1: Project Setup
+
+First, have OpenHands set up the project structure:
+
+```markdown
+Create a new Python REST API project for task management.
+
+Structure:
+```
+task-api/
+├── src/
+│   ├── __init__.py
+│   ├── main.py          # FastAPI application
+│   ├── models/          # Pydantic models
+│   ├── routes/          # API endpoints
+│   └── services/        # Business logic
+├── tests/
+├── requirements.txt
+└── README.md
+```
+
+Use FastAPI with Pydantic for validation.
+Include: uvicorn, pytest, httpx for testing.
+```
+
+## Step 2: Create the Task Model
+
+```markdown
+Create the Task model and schemas.
+
+Location: src/models/task.py
+
+Fields:
+- id: UUID (generated)
+- title: string (required, max 100 chars)
+- description: string (optional)
+- status: enum (pending, in_progress, completed)
+- created_at: datetime
+- updated_at: datetime
+
+Create Pydantic schemas:
+- TaskCreate (for POST)
+- TaskUpdate (for PATCH)
+- TaskResponse (for responses)
+```
+
+## Step 3: Implement CRUD Routes
+
+```markdown
+Create CRUD endpoints for tasks.
+
+Location: src/routes/tasks.py
+
+Endpoints:
+- GET /tasks - List all tasks (with pagination)
+- GET /tasks/{id} - Get single task
+- POST /tasks - Create task
+- PATCH /tasks/{id} - Update task
+- DELETE /tasks/{id} - Delete task
+
+Include:
+- Input validation
+- Proper HTTP status codes
+- Error responses for not found, validation errors
+```
+
+## Step 4: Add Tests
+
+```markdown
+Add comprehensive tests for the task API.
+
+Location: tests/test_tasks.py
+
+Test cases:
+1. Create task - success
+2. Create task - validation error (missing title)
+3. Get task - success
+4. Get task - not found
+5. Update task - success
+6. Delete task - success
+7. List tasks - pagination
+
+Use pytest with httpx TestClient.
+```
+
+## Step 5: Documentation
+
+```markdown
+Add API documentation.
+
+OpenAPI docs should include:
+- Descriptions for all endpoints
+- Request/response examples
+- Error response schemas
+
+Create README with:
+- Setup instructions
+- API endpoint reference
+- Example requests
+```
+
+## Running the API
+
+After OpenHands completes the implementation:
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the server
+uvicorn src.main:app --reload
+
+# Run tests
+pytest tests/ -v
+```
+
+## Expected Outcome
+
+You should have a working API:
+
+```bash
+# Create a task
+curl -X POST http://localhost:8000/tasks \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Learn OpenHands", "status": "in_progress"}'
+
+# Response
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "title": "Learn OpenHands",
+  "description": null,
+  "status": "in_progress",
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-15T10:30:00Z"
+}
+```
+
+## Next Steps
+
+Extend this API by asking OpenHands to:
+
+- Add user authentication
+- Add database persistence (SQLite/PostgreSQL)
+- Add rate limiting
+- Deploy to cloud platform
+
+<Card title="More Tutorials" icon="graduation-cap" href="/use-cases/tutorials/getting-started">
+  Explore other tutorials
+</Card>
diff --git a/use-cases/tutorials/test-coverage.mdx b/use-cases/tutorials/test-coverage.mdx
new file mode 100644
index 00000000..ae89e304
--- /dev/null
+++ b/use-cases/tutorials/test-coverage.mdx
@@ -0,0 +1,205 @@
+---
+title: "Add Test Coverage"
+sidebarTitle: "Test Coverage"
+description: "Tutorial: Improve test coverage with OpenHands"
+---
+
+# Tutorial: Add Test Coverage
+
+Learn how to systematically add tests to an existing codebase using OpenHands.
+
+## Prerequisites
+
+- Existing codebase with limited test coverage
+- Testing framework installed (pytest, jest, etc.)
+- OpenHands CLI or Cloud access
+
+## Overview
+
+We'll follow this process:
+
+<Steps>
+  <Step title="Analyze Coverage">
+    Identify untested code
+  </Step>
+  <Step title="Prioritize">
+    Rank by criticality
+  </Step>
+  <Step title="Generate Tests">
+    Use OpenHands to write tests
+  </Step>
+  <Step title="Verify">
+    Run and review tests
+  </Step>
+</Steps>
+
+## Step 1: Check Current Coverage
+
+First, measure existing coverage:
+
+```bash
+# Python
+pytest --cov=src --cov-report=html
+
+# JavaScript
+npm test -- --coverage
+```
+
+## Step 2: Identify Critical Untested Code
+
+Ask OpenHands to analyze:
+
+```markdown
+Analyze the codebase and identify critical untested functions.
+
+Focus on:
+1. Business logic in src/services/
+2. Data validation in src/utils/
+3. API handlers in src/api/
+
+List functions with:
+- Function name and location
+- Why it's critical
+- Suggested test cases
+```
+
+## Step 3: Generate Tests Systematically
+
+### Module by Module
+
+For each module, provide a clear instruction:
+
+```markdown
+Add tests for src/services/order_service.py
+
+Current coverage: 45%
+Target coverage: 90%
+
+Functions to test:
+1. create_order()
+2. calculate_total()
+3. apply_discount()
+4. validate_order()
+
+Testing patterns:
+- Follow existing tests in tests/services/test_user_service.py
+- Use fixtures from conftest.py
+- Mock external dependencies (PaymentGateway, InventoryService)
+
+For each function, test:
+- Happy path
+- Edge cases
+- Error conditions
+```
+
+### Example Output
+
+```python
+# tests/services/test_order_service.py
+import pytest
+from unittest.mock import Mock, patch
+from src.services.order_service import OrderService
+
+
+class TestCreateOrder:
+    @pytest.fixture
+    def order_service(self):
+        return OrderService()
+
+    @pytest.fixture
+    def valid_order_data(self):
+        return {
+            "user_id": 1,
+            "items": [{"product_id": 1, "quantity": 2}],
+            "shipping_address": {"city": "NYC", "zip": "10001"}
+        }
+
+    def test_create_order_success(self, order_service, valid_order_data):
+        order = order_service.create_order(valid_order_data)
+        assert order.status == "pending"
+        assert order.user_id == 1
+        assert len(order.items) == 1
+
+    def test_create_order_empty_items(self, order_service):
+        with pytest.raises(ValueError, match="Order must have items"):
+            order_service.create_order({"user_id": 1, "items": []})
+
+    @patch('src.services.order_service.InventoryService')
+    def test_create_order_out_of_stock(self, mock_inventory, order_service):
+        mock_inventory.check_stock.return_value = False
+        with pytest.raises(OutOfStockError):
+            order_service.create_order({"user_id": 1, "items": [...]})
+```
+
+## Step 4: Iterate and Refine
+
+After initial tests:
+
+```markdown
+Review the test results and improve coverage.
+
+Current status:
+- 15 tests added
+- 3 tests failing
+- Coverage at 78% (target: 90%)
+
+Fix the failing tests and add tests for:
+- Edge case: order with more than 100 items
+- Edge case: discount code expiration
+- Integration: full order workflow
+```
+
+## Coverage Strategies
+
+### By Layer
+
+```
+Week 1: Service layer (business logic)
+Week 2: API layer (endpoints)  
+Week 3: Utils (helpers, validators)
+Week 4: Integration tests
+```
+
+### By Criticality
+
+1. Payment processing
+2. Authentication
+3. Order management
+4. User management
+5. Reporting
+
+## Best Practices
+
+<CardGroup cols={2}>
+  <Card title="Test Behavior" icon="check">
+    Test what code does, not how
+  </Card>
+  <Card title="Meaningful Names" icon="tag">
+    Test names should describe scenarios
+  </Card>
+  <Card title="Independent Tests" icon="cubes">
+    Each test should run in isolation
+  </Card>
+  <Card title="Fast Tests" icon="bolt">
+    Unit tests should be quick
+  </Card>
+</CardGroup>
+
+## Tracking Progress
+
+Monitor coverage improvement:
+
+```bash
+# Generate coverage report
+pytest --cov=src --cov-report=term-missing
+
+# Track over time
+# Day 1: 45%
+# Day 3: 65%
+# Day 5: 85%
+# Day 7: 92%
+```
+
+<Card title="Test Coverage Use Case" icon="vial" href="/use-cases/examples/test-coverage">
+  More patterns for test generation
+</Card>