docs: consolidate obsolete pages and label retained legacy references

docs.json

@@ -687,11 +687,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",
@@ -755,7 +755,7 @@
     },
     {
       "source": "/openhands/usage/start-building",
-      "destination": "/overview/first-projects"
+      "destination": "/openhands/usage/get-started/tutorials"
     },
     {
       "source": "/overview/key-features",
@@ -868,6 +868,26 @@
     {
       "source": "/openhands/usage/automations/examples",
       "destination": "/openhands/usage/automations/overview"
+    },
+    {
+      "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

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

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
@@ -152,20 +158,8 @@ These variables correspond to the `[security]` section in `config.toml`:
 
 ### 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 |

openhands/usage/get-started/tutorials.mdx

@@ -5,6 +5,46 @@ description: Centralized hub for OpenHands tutorials and examples
 
 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 |

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:

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?