docs: consolidate obsolete pages and label retained legacy references

docs.json

@@ -737,11 +737,11 @@
     },
     {
       "source": "/openhands/usage/how-to/debugging",
-      "destination": "/openhands/usage/developers/debugging"
+      "destination": "/openhands/usage/agent-canvas/development"
     },
     {
       "source": "/openhands/usage/how-to/development-overview",
-      "destination": "/openhands/usage/developers/development-overview"
+      "destination": "/openhands/usage/agent-canvas/development"
     },
     {
       "source": "/openhands/usage/how-to/evaluation-harness",
@@ -805,7 +805,7 @@
     },
     {
       "source": "/openhands/usage/start-building",
-      "destination": "/overview/first-projects"
+      "destination": "/openhands/usage/get-started/tutorials"
     },
     {
       "source": "/overview/key-features",
@@ -926,6 +926,26 @@
     {
       "source": "/enterprise/custom-sandbox-image#run-multiple-custom-images-with-warm-runtime-pools",
       "destination": "/enterprise/custom-sandbox-images/multiple-images-warm-pools"
+    },
+    {
+      "source": "/openhands/usage/about",
+      "destination": "/overview/introduction"
+    },
+    {
+      "source": "/openhands/usage/developers/debugging",
+      "destination": "/openhands/usage/agent-canvas/development"
+    },
+    {
+      "source": "/openhands/usage/developers/development-overview",
+      "destination": "/openhands/usage/agent-canvas/development"
+    },
+    {
+      "source": "/overview/first-projects",
+      "destination": "/openhands/usage/get-started/tutorials"
+    },
+    {
+      "source": "/sdk/arch/sdk",
+      "destination": "/sdk/arch/overview"
     }
   ]
 }

openhands/usage/agents.mdx

@@ -1,7 +1,14 @@
 ---
-title: Main Agent and Capabilities
+title: Legacy CodeAct Agent
+description: Archived documentation for the former OpenHands Python monorepo
+noindex: true
 ---
 
+<Warning>
+This page describes the historical CodeAct agent. For the current Software Agent SDK, see [Agent Architecture](/sdk/arch/agent).
+</Warning>
+
+
 ## CodeActAgent
 
 ### Description

openhands/usage/developers/evaluation-harness.mdx

@@ -1,7 +1,14 @@
 ---
-title: Evaluation Harness
+title: Legacy Evaluation Harness
+description: Archived documentation for the former OpenHands Python monorepo
+noindex: true
 ---
 
+<Warning>
+This page describes the former Python monorepo evaluation harness. For current SDK-based evaluations, use the [OpenHands benchmarks repository](https://github.com/OpenHands/benchmarks). Its setup and benchmark-specific runners replace the workflow below; there is no equivalent generic harness-authoring guide in this documentation yet.
+</Warning>
+
+
 This guide provides an overview of how to integrate your own evaluation benchmark into the OpenHands framework.
 
 ## Setup Environment and LLM Configuration
@@ -9,7 +16,7 @@
 Please follow instructions [here](https://github.com/OpenHands/OpenHands/blob/main/Development.md) to setup your local development environment.
 OpenHands in development mode uses `config.toml` to keep track of most configurations.
 
 Here's an example configuration file you can use to define and use multiple LLMs:
 
 ```toml
 [llm]
@@ -181,7 +188,7 @@
    )
    ```
 
 This workflow sets up the configuration, initializes the runtime environment, processes each instance by running the agent and evaluating its actions, and then collects the results into an `EvalOutput` object. The `run_evaluation` function handles parallelization and progress tracking.
 
 Remember to customize the `get_instruction`, `your_user_response_function`, and `evaluate_agent_actions` functions according to your specific benchmark requirements.
 

openhands/usage/developers/websocket-connection.mdx

@@ -1,7 +1,14 @@
 ---
-title: WebSocket Connection
+title: Legacy WebSocket Connection
+description: Archived documentation for the former OpenHands Python monorepo
+noindex: true
 ---
 
+<Warning>
+This page describes the former Socket.IO protocol. Agent Canvas uses a native WebSocket connection instead. See [Canvas Architecture](/openhands/usage/agent-canvas/architecture) and [SDK Events](/sdk/arch/events) for current architecture and event concepts. Those pages are not a replacement wire-protocol reference; do not use the Socket.IO examples below with Canvas.
+</Warning>
+
+
 This guide explains how to connect to the OpenHands WebSocket API to receive real-time events and send actions to the agent.
 
 ## Overview
@@ -91,7 +98,7 @@
 });
 ```
 
 ## Using Websocat for Testing
 
 [Websocat](https://github.com/vi/websocat) is a command-line tool for interacting with WebSockets. It's useful for testing your WebSocket connection without writing a full client application.
 
@@ -123,7 +130,7 @@
 websocat "ws://localhost:3000/socket.io/?EIO=4&transport=websocket&conversation_id=your-conversation-id&latest_event_id=-1"
 ```
 
 ### Complete Example with Websocat
 
 Here's a complete example of connecting to the WebSocket, sending a message, and receiving events:
 

openhands/usage/environment-variables.mdx

@@ -1,8 +1,14 @@
 ---
-title: Environment Variables Reference
-description: Complete reference of all environment variables supported by OpenHands
+title: Archived Environment Variables Reference
+description: Archived documentation for the former OpenHands Python monorepo
+noindex: true
 ---
 
+<Warning>
+This reference was assembled for the former Python monorepo and is retained for older deployments. It is not a complete or verified reference for current Canvas or SDK releases. For current settings, see [Canvas Development](/openhands/usage/agent-canvas/development#docker-conversation-runtime-settings) and [Agent Server Architecture](/sdk/arch/agent-server).
+</Warning>
+
+
 This page provides a reference of environment variables that can be used to configure OpenHands. Environment variables provide an alternative to TOML configuration files and are particularly useful for containerized deployments, CI/CD pipelines, and cloud environments.
 
 ## Environment Variable Naming Convention
@@ -36,7 +42,7 @@
 | `RUNTIME` | string | `"docker"` | Runtime environment (`docker`, `local`, `cli`, etc.) |
 | `DEFAULT_AGENT` | string | `"CodeActAgent"` | Default agent class to use |
 | `JWT_SECRET` | string | auto-generated | JWT secret for authentication |
 | `RUN_AS_OPENHANDS` | boolean | `true` | Whether to run as the openhands user |
 | `VOLUMES` | string | `""` | Volume mounts in format `host:container[:mode]` |
 
 ## LLM Configuration Variables
@@ -58,12 +64,12 @@
 | `LLM_NUM_RETRIES` | integer | `8` | Number of retry attempts |
 | `LLM_RETRY_MIN_WAIT` | integer | `15` | Minimum wait time between retries (seconds) |
 | `LLM_RETRY_MAX_WAIT` | integer | `120` | Maximum wait time between retries (seconds) |
 | `LLM_RETRY_MULTIPLIER` | float | `2.0` | Exponential backoff multiplier |
 | `LLM_DROP_PARAMS` | boolean | `false` | Drop unsupported parameters without error |
 | `LLM_CACHING_PROMPT` | boolean | `true` | Enable prompt caching if supported |
 | `LLM_DISABLE_VISION` | boolean | `false` | Disable vision capabilities for cost reduction |
 | `LLM_CUSTOM_LLM_PROVIDER` | string | `""` | Custom LLM provider name |
 | `LLM_OLLAMA_BASE_URL` | string | `""` | Base URL for Ollama API |
 | `LLM_INPUT_COST_PER_TOKEN` | float | `0.0` | Cost per input token |
 | `LLM_OUTPUT_COST_PER_TOKEN` | float | `0.0` | Cost per output token |
 | `LLM_REASONING_EFFORT` | string | `""` | Reasoning effort for o-series models (`low`, `medium`, `high`) |
@@ -87,7 +93,7 @@
 | `AGENT_ENABLE_LLM_EDITOR` | boolean | `false` | Enable LLM-based editor |
 | `AGENT_ENABLE_JUPYTER` | boolean | `false` | Enable Jupyter integration |
 | `AGENT_ENABLE_HISTORY_TRUNCATION` | boolean | `true` | Enable history truncation |
 | `AGENT_ENABLE_PROMPT_EXTENSIONS` | boolean | `true` | Enable skills (formerly known as microagents) (prompt extensions) |
 | `AGENT_DISABLED_MICROAGENTS` | list | `[]` | List of skills to disable |
 
 ## Sandbox Configuration Variables
@@ -110,8 +116,8 @@
 | `AGENT_SERVER_IMAGE_REPOSITORY` | string | `""` | Runtime container image repository (e.g., `ghcr.io/openhands/agent-server`) |
 | `AGENT_SERVER_IMAGE_TAG` | string | `""` | Runtime container image tag (e.g., `1.26.0-python`) |
 | `SANDBOX_KEEP_RUNTIME_ALIVE` | boolean | `false` | Keep runtime alive after session ends |
 | `SANDBOX_PAUSE_CLOSED_RUNTIMES` | boolean | `false` | Pause instead of stopping closed runtimes |
 | `SANDBOX_CLOSE_DELAY` | integer | `300` | Delay before closing idle runtimes (seconds) |
 | `SANDBOX_RM_ALL_CONTAINERS` | boolean | `false` | Remove all containers when stopping |
 | `SANDBOX_ENABLE_GPU` | boolean | `false` | Enable GPU support |
 | `SANDBOX_CUDA_VISIBLE_DEVICES` | string | `""` | Specify GPU devices by ID |
@@ -152,20 +158,8 @@
 
 ### Docker Conversation Runtime (Canvas)
 
-When running Agent Canvas locally via the `dev-safe.mjs` launcher, Canvas can forward conversation-runtime settings to its bundled Agent Server. This enables `OH_CONVERSATION_RUNTIME=docker`, which runs each conversation in an isolated Docker container instead of the default local process runtime.
-
-Canvas forwards these settings only when the operator explicitly sets them. Unset values remain absent so Agent Server defaults stay authoritative.
-
-| Environment Variable | Type | Default | Description |
-|---------------------|------|---------|-------------|
-| `OH_CONVERSATION_RUNTIME` | string | unset | Conversation runtime type. Set to `docker` to run conversations in Docker containers. |
-| `OH_CONVERSATION_IMAGE` | string | unset | Docker image to use for conversation containers. |
-| `OH_CONVERSATION_CONTAINER_MEMORY` | string | unset | Memory limit for conversation containers (e.g., `2g`). |
-| `OH_CONVERSATION_CONTAINER_CPUS` | string | unset | CPU limit for conversation containers. |
-| `OH_CONVERSATION_CONTAINER_PIDS_LIMIT` | string | unset | PID limit for conversation containers. |
-| `OH_CONVERSATION_CONTAINER_STARTUP_TIMEOUT` | string | unset | Startup timeout for conversation containers (seconds). |
-
-These variables are specific to Canvas's `dev-safe.mjs` launcher and are forwarded to the bundled Agent Server process. Docker provisioning and setting interpretation are handled by Agent Server.
+The current `OH_CONVERSATION_*` settings are documented in
+[Canvas Development](/openhands/usage/agent-canvas/development#docker-conversation-runtime-settings).
 
 ### Remote Runtime
 | Environment Variable | Type | Default | Description |
@@ -189,7 +183,7 @@
 | `ALLOW_INSECURE_GIT_ACCESS` | boolean | `false` | Allow OpenHands to connect to git providers over plain HTTP. Set this only for trusted local or internal git providers (such as Gitea/Forgejo) where HTTPS is not available. |
 
 <Warning>
   `ALLOW_INSECURE_GIT_ACCESS=true` permits insecure HTTP connections to git providers. Only enable it for trusted local or internal networks that you control. Do not use it for public or untrusted git providers.
 </Warning>
 
 When running OpenHands with Docker, set this on the OpenHands server container:
@@ -210,7 +204,7 @@
 | `ANTHROPIC_API_KEY` | string | `""` | Anthropic API key |
 | `GOOGLE_API_KEY` | string | `""` | Google API key |
 | `AZURE_API_KEY` | string | `""` | Azure API key |
 | `TAVILY_API_KEY` | string | `""` | Tavily search API key |
 
 ## Server Configuration Variables
 

openhands/usage/get-started/tutorials.mdx

@@ -5,6 +5,46 @@
 
 Welcome to the OpenHands tutorial library. These tutorials show you how to use OpenHands for common development tasks, from testing to feature development. Each tutorial includes example prompts, expected workflows, and tips for success.
 
+## First Projects
+
+After [setting up OpenHands](/overview/quickstart), start with a small task and
+iterate. These prompts work as starting points without relying on a particular
+interface or repository integration.
+
+### Hello World
+
+> Write a bash script hello.sh that prints "hello world!" and run it.
+
+Then refine it:
+
+> Modify hello.sh so it accepts a name as the first argument and defaults to "world". Test both cases.
+
+### Build a Small App
+
+> Build a frontend-only TODO app in React. Store its state in localStorage.
+
+Once the basics work:
+
+> Allow adding an optional due date to each task. Add tests for creating and updating due dates.
+
+### Work in an Existing Repository
+
+Give the agent the repository context and a focused goal:
+
+> Add a GitHub Actions workflow that runs this repository's existing lint command.
+
+For a small refactor:
+
+> Split build_and_deploy_widgets in widget.php into build_widgets and deploy_widgets. Preserve the behavior and run the relevant tests.
+
+For a bug fix:
+
+> The hello function crashes on an empty string. Write a test that reproduces the bug, then fix the code so it passes.
+
+Review each change before expanding the task. Include file names, expected
+behavior, and examples in your prompts. See [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices)
+for more guidance.
+
 ## Categories Overview
 
 | Category | Best For | Complexity |
@@ -277,7 +317,7 @@
 ### Bug Fixing
 
 <Note>
 For production incident investigation and automated error analysis, see the [Incident Triage Use Case](/openhands/usage/use-cases/incident-triage) which covers integration with monitoring tools like Datadog.
 </Note>
 
 #### Tutorial: Fix a Crash Bug

openhands/usage/llms/custom-llm-configs.mdx

@@ -1,8 +1,14 @@
 ---
-title: Custom LLM Configurations
-description: OpenHands supports defining multiple named LLM configurations in your `config.toml` file. This feature allows you to use different LLM configurations for different purposes, such as using a cheaper model for tasks that don't require high-quality responses, or using different models with different parameters for specific agents.
+title: Legacy Custom LLM Configurations
+description: Archived documentation for the former OpenHands Python monorepo
+noindex: true
 ---
 
+<Warning>
+This page describes named TOML configurations in the former Python monorepo. For current configuration, see [Canvas LLM Profiles](/openhands/usage/agent-canvas/llm-profiles) or the [SDK LLM Profile Store](/sdk/guides/llm-profile-store).
+</Warning>
+
+
 ## How It Works
 
 Named LLM configurations are defined in the `config.toml` file using sections that start with `llm.`. For example:
@@ -64,7 +70,7 @@
 Custom LLM configurations are particularly useful in several scenarios:
 
 - **Cost Optimization**: Use cheaper models for tasks that don't require high-quality responses, like repository exploration or simple file operations.
 - **Task-Specific Tuning**: Configure different temperature and top_p values for tasks that require different levels of creativity or determinism.
 - **Different Providers**: Use different LLM providers or API endpoints for different tasks.
 - **Testing and Development**: Easily switch between different model configurations during development and testing.
 
@@ -124,7 +130,7 @@
 This configuration:
 - Uses GPT-4 for high-quality edits and suggestions
 - Sets a low temperature (0.2) to maintain consistency while allowing some flexibility
 - Uses a high top_p value (0.95) to consider a wide range of token options
 - Disables presence and frequency penalties to maintain focus on the specific edits needed
 
 Use this configuration when you want to let an LLM draft edits before making them. In general, it may be useful to:

openhands/usage/tips/prompting-best-practices.mdx

@@ -35,4 +35,4 @@ Good prompts are:
 
 The more precise and informative your prompt, the better OpenHands can assist you.
 
-See [First Projects](/overview/first-projects) for more examples of helpful prompts.
+See [First Projects](/openhands/usage/get-started/tutorials) for more examples of helpful prompts.

overview/faqs.mdx

@@ -12,7 +12,7 @@ description: Frequently asked questions about OpenHands.
   [Bitbucket](/openhands/usage/cloud/bitbucket-installation),
   and [Slack](/openhands/usage/cloud/slack-installation) integrations.
 2. **Run on your own**: If you prefer to run it on your own hardware, follow our [Getting Started guide](/openhands/usage/run-openhands/local-setup).
-3. **First steps**: Read over the [first projects guidelines](/overview/first-projects) and
+3. **First steps**: Read over the [first projects guidelines](/openhands/usage/get-started/tutorials) and
   [prompting best practices](/openhands/usage/tips/prompting-best-practices) to learn the basics.
 
 ### Can I use OpenHands for production workloads?