diff --git a/sdk/guides/agent-file-based.mdx b/sdk/guides/agent-file-based.mdx
index 627e44a4..e96439f0 100644
--- a/sdk/guides/agent-file-based.mdx
+++ b/sdk/guides/agent-file-based.mdx
@@ -101,15 +101,42 @@ Put agents shared across all your projects in `~/.agents/agents/`. Put project-s
 
 ## Built-in Agents
 
-The SDK ships with built-in agents that are automatically loaded at the beginning of each conversation and are available to the user.
+The `openhands-tools` package ships with built-in sub-agents as Markdown files in `openhands/tools/preset/subagents/`.
+They can be registered via `register_builtins_agents()` and become available for delegation tasks.
 
-By default, agents include `FinishTool` and `ThinkTool`; they are appended after tool filtering.
+By default, all agents include `finish` tool and the `think` tool.
 
-The table below summarizes all available built-in agents:
+### Available Built-in Sub-Agents
 
 | Agent | Tools | Description |
 |--------|-------|-------|
-| **default** | `terminal`, `file_editor`, `task_tracker`, `browser_tool_set` | general purpose agent |
+| **default** | `terminal`, `file_editor`, `task_tracker`, `browser_tool_set` | General-purpose agent. Used as the fallback when no agent name is specified. |
+| **default cli mode** | `terminal`, `file_editor`, `task_tracker` | Same as `default` but without browser tools (used in CLI mode). |
+| **explore** | `terminal` | Read-only codebase exploration agent. Finds files, searches code, reads source — never creates or modifies anything. |
+| **bash** | `terminal` | Command execution specialist. Runs shell commands, builds, tests, and git operations. |
+
+In CLI mode, the `default` agent (with browser tools) is replaced by the `default cli mode` agent. In non-CLI mode, `default cli mode` is filtered out.
+
+### Registering Built-in Sub-Agents
+
+Call `register_builtins_agents()` to register all built-in sub-agents. This is typically done once before creating a conversation:
+
+```python icon="python" focus={3-4, 6-7}
+from openhands.tools.preset.default import register_builtins_agents
+
+# Register built-in sub-agents (default, explore, bash)
+register_builtins_agents()
+
+# Or in CLI mode (swaps default for default cli mode — no browser)
+register_builtins_agents(cli_mode=True)
+```
+
+<Warning>
+Registration order is critical when programmatically registering agents that share a name with a built-in agent. The system is designed to skip registration if a name is already taken. Therefore, if you register your custom agents before the built-in agents are loaded, your custom versions will take precedence.
+
+Conversely, if the built-in agents are loaded first, they will take precedence, and any subsequent registration of a custom agent with the same name will be ignored.
+</Warning>
+
 
 ## Overall Priority
 
@@ -120,8 +147,7 @@ When the same agent name is defined in multiple places, the highest-priority sou
 | 1 (highest) | **Programmatic** `register_agent()` | Registered first, never overwritten |
 | 2 | **Plugin agents** (`Plugin.agents`) | Loaded from plugin `agents/` directories |
 | 3 | **Project-level** file-based agents | `.agents/agents/*.md` or `.openhands/agents/*.md` |
-| 4 | **User-level** file-based agents | `~/.agents/agents/*.md` or `~/.openhands/agents/*.md` |
-| 5 (lowest) | **Built-in agents** | SDK built-in agents |
+| 4 (lowest) | **User-level** file-based agents | `~/.agents/agents/*.md` or `~/.openhands/agents/*.md` |
 
 ## Auto-Registration