diff --git a/deer-flow.code-workspace b/deer-flow.code-workspace
index ef2863302..a4f4cb240 100644
--- a/deer-flow.code-workspace
+++ b/deer-flow.code-workspace
@@ -5,7 +5,7 @@
     }
   ],
   "settings": {
-    "typescript.tsdk": "frontend/node_modules/typescript/lib",
+    "js/ts.tsdk.path": "frontend/node_modules/typescript/lib",
     "python-envs.pythonProjects": [
       {
         "path": "backend",
@@ -44,4 +44,4 @@
       }
     ]
   }
-}
+}
\ No newline at end of file
diff --git a/frontend/src/app/[lang]/docs/layout.tsx b/frontend/src/app/[lang]/docs/layout.tsx
index f63d6ae7b..895da1da8 100644
--- a/frontend/src/app/[lang]/docs/layout.tsx
+++ b/frontend/src/app/[lang]/docs/layout.tsx
@@ -34,14 +34,14 @@ export default async function DocLayout({ children, params }) {
     <Layout
       navbar={
         <Header
-          className="relative max-w-full px-10"
+          className="sticky max-w-full px-10"
           homeURL="/"
           locale={locale}
         />
       }
       pageMap={pageMap}
       docsRepositoryBase="https://github.com/bytedance/deerflow/tree/main/frontend/src/content"
-      footer={<Footer />}
+      footer={<Footer className="mt-0" />}
       i18n={i18n}
       // ... Your additional layout options
     >
diff --git a/frontend/src/components/landing/footer.tsx b/frontend/src/components/landing/footer.tsx
index 4176fb353..0c86be205 100644
--- a/frontend/src/components/landing/footer.tsx
+++ b/frontend/src/components/landing/footer.tsx
@@ -1,9 +1,20 @@
 import { useMemo } from "react";
 
-export function Footer() {
+import { cn } from "@/lib/utils";
+
+export type FooterProps = {
+  className?: string;
+};
+
+export function Footer({ className }: FooterProps) {
   const year = useMemo(() => new Date().getFullYear(), []);
   return (
-    <footer className="container-md mx-auto mt-32 flex flex-col items-center justify-center">
+    <footer
+      className={cn(
+        "container-md mx-auto mt-32 flex flex-col items-center justify-center",
+        className,
+      )}
+    >
       <hr className="from-border/0 to-border/0 m-0 h-px w-full border-none bg-linear-to-r via-white/20" />
       <div className="text-muted-foreground container flex h-20 flex-col items-center justify-center text-sm">
         <p className="text-center font-serif text-lg md:text-xl">
diff --git a/frontend/src/content/en/_meta.ts b/frontend/src/content/en/_meta.ts
index 49b33a784..2451ce3be 100644
--- a/frontend/src/content/en/_meta.ts
+++ b/frontend/src/content/en/_meta.ts
@@ -25,6 +25,15 @@ const meta: MetaRecord = {
   blog: {
     type: "page",
   },
+  posts: {
+    type: "page",
+  },
+  login: {
+    type: "page",
+  },
+  setup: {
+    type: "page",
+  },
 };
 
 export default meta;
diff --git a/frontend/src/content/en/application/agents-and-threads.mdx b/frontend/src/content/en/application/agents-and-threads.mdx
index da6e7ca06..bbf3cfc7e 100644
--- a/frontend/src/content/en/application/agents-and-threads.mdx
+++ b/frontend/src/content/en/application/agents-and-threads.mdx
@@ -1,3 +1,8 @@
+---
+title: Agents and Threads
+description: DeerFlow App supports multiple named agents and maintains conversation state across sessions through threads and checkpointing.
+---
+
 import { Callout, Cards, Steps } from "nextra/components";
 
 # Agents and Threads
diff --git a/frontend/src/content/en/application/configuration.mdx b/frontend/src/content/en/application/configuration.mdx
index 00f387ef6..fb0fedc89 100644
--- a/frontend/src/content/en/application/configuration.mdx
+++ b/frontend/src/content/en/application/configuration.mdx
@@ -1,3 +1,8 @@
+---
+title: Configuration
+description: DeerFlow App is configured through two files and a set of environment variables. This page covers the application-level configuration that most operators need to set up before deploying.
+---
+
 import { Callout, Cards, Tabs } from "nextra/components";
 
 # Configuration
diff --git a/frontend/src/content/en/application/deployment-guide.mdx b/frontend/src/content/en/application/deployment-guide.mdx
index 59a60d72c..8d5542dbb 100644
--- a/frontend/src/content/en/application/deployment-guide.mdx
+++ b/frontend/src/content/en/application/deployment-guide.mdx
@@ -1,3 +1,8 @@
+---
+title: Deployment Guide 
+description: "This guide covers all supported deployment methods for DeerFlow App: local development, Docker Compose, and production with Kubernetes-managed sandboxes."
+---
+
 import { Callout, Cards, Steps, Tabs } from "nextra/components";
 
 # Deployment Guide
@@ -16,14 +21,15 @@ make dev
 
 Services started:
 
-| Service | Port | Description |
-|---|---|---|
-| LangGraph | 2024 | DeerFlow Harness runtime |
-| Gateway API | 8001 | FastAPI backend |
-| Frontend | 3000 | Next.js UI |
-| nginx | 2026 | Unified reverse proxy |
+| Service     | Port | Description              |
+| ----------- | ---- | ------------------------ |
+| LangGraph   | 2024 | DeerFlow Harness runtime |
+| Gateway API | 8001 | FastAPI backend          |
+| Frontend    | 3000 | Next.js UI               |
+| nginx       | 2026 | Unified reverse proxy    |
 
 Access the app at **http://localhost:2026**.
+
   </Tabs.Tab>
   <Tabs.Tab>
 ```bash
@@ -31,6 +37,7 @@ make stop
 ```
 
 Stops all four services. Safe to run even if a service is not running.
+
   </Tabs.Tab>
   <Tabs.Tab>
 ```
@@ -41,9 +48,11 @@ logs/nginx.log       # nginx access/error logs
 ```
 
 Tail a log in real time:
+
 ```bash
 tail -f logs/langgraph.log
 ```
+
   </Tabs.Tab>
 </Tabs>
 
@@ -103,11 +112,11 @@ For production, use a named volume or a Persistent Volume Claim (PVC) instead of
 
 ### Sandbox mode selection
 
-| Sandbox | Use case |
-|---|---|
-| `LocalSandboxProvider` | Single-user, trusted local workflows |
-| `AioSandboxProvider` (Docker) | Multi-user, moderate isolation requirement |
-| `AioSandboxProvider` + K8s Provisioner | Production, strong isolation, multi-user |
+| Sandbox                                | Use case                                   |
+| -------------------------------------- | ------------------------------------------ |
+| `LocalSandboxProvider`                 | Single-user, trusted local workflows       |
+| `AioSandboxProvider` (Docker)          | Multi-user, moderate isolation requirement |
+| `AioSandboxProvider` + K8s Provisioner | Production, strong isolation, multi-user   |
 
 For any deployment with more than one concurrent user, use a container-based sandbox to prevent users from interfering with each other's execution environments.
 
@@ -154,10 +163,10 @@ When `USERDATA_PVC_NAME` is set, the provisioner automatically uses subPath (`th
 
 nginx routes all traffic. Key environment variables that control routing:
 
-| Variable | Default | Description |
-|---|---|---|
-| `LANGGRAPH_UPSTREAM` | `langgraph:2024` | LangGraph service address |
-| `LANGGRAPH_REWRITE` | `/` | URL rewrite prefix for LangGraph routes |
+| Variable             | Default          | Description                             |
+| -------------------- | ---------------- | --------------------------------------- |
+| `LANGGRAPH_UPSTREAM` | `langgraph:2024` | LangGraph service address               |
+| `LANGGRAPH_REWRITE`  | `/`              | URL rewrite prefix for LangGraph routes |
 
 These are set in the Docker Compose environment and processed by `envsubst` at container startup.
 
@@ -175,12 +184,12 @@ openssl rand -base64 32
 
 ### Resource recommendations
 
-| Service | Minimum | Recommended |
-|---|---|---|
-| LangGraph (agent runtime) | 2 vCPU, 4 GB RAM | 4 vCPU, 8 GB RAM |
-| Gateway | 0.5 vCPU, 512 MB | 1 vCPU, 1 GB |
-| Frontend | 0.5 vCPU, 512 MB | 1 vCPU, 1 GB |
-| Sandbox container (per session) | 1 vCPU, 1 GB | 2 vCPU, 2 GB |
+| Service                         | Minimum          | Recommended      |
+| ------------------------------- | ---------------- | ---------------- |
+| LangGraph (agent runtime)       | 2 vCPU, 4 GB RAM | 4 vCPU, 8 GB RAM |
+| Gateway                         | 0.5 vCPU, 512 MB | 1 vCPU, 1 GB     |
+| Frontend                        | 0.5 vCPU, 512 MB | 1 vCPU, 1 GB     |
+| Sandbox container (per session) | 1 vCPU, 1 GB     | 2 vCPU, 2 GB     |
 
 ## Deployment verification
 
@@ -201,5 +210,8 @@ A working deployment returns a `200` response from each endpoint. The `/api/mode
 
 <Cards num={2}>
   <Cards.Card title="Configuration" href="/docs/application/configuration" />
-  <Cards.Card title="Operations & Troubleshooting" href="/docs/application/operations-and-troubleshooting" />
+  <Cards.Card
+    title="Operations & Troubleshooting"
+    href="/docs/application/operations-and-troubleshooting"
+  />
 </Cards>
diff --git a/frontend/src/content/en/application/index.mdx b/frontend/src/content/en/application/index.mdx
index 8e2bf133b..f61f18775 100644
--- a/frontend/src/content/en/application/index.mdx
+++ b/frontend/src/content/en/application/index.mdx
@@ -1,3 +1,8 @@
+---
+title: DeerFlow App
+description: DeerFlow App is the reference implementation of what a production DeerFlow experience looks like. It assembles the Harness runtime, a web-based conversation workspace, an API gateway, and a reverse proxy into a single deployable system.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # DeerFlow App
diff --git a/frontend/src/content/en/application/operations-and-troubleshooting.mdx b/frontend/src/content/en/application/operations-and-troubleshooting.mdx
index 7592e5fbf..e12f4d4f1 100644
--- a/frontend/src/content/en/application/operations-and-troubleshooting.mdx
+++ b/frontend/src/content/en/application/operations-and-troubleshooting.mdx
@@ -1,3 +1,8 @@
+---
+title: Operations and Troubleshooting
+description: This page covers day-to-day operational tasks and solutions to common problems when running DeerFlow App.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Operations and Troubleshooting
diff --git a/frontend/src/content/en/application/quick-start.mdx b/frontend/src/content/en/application/quick-start.mdx
index 2363f8191..d9b4a3e7d 100644
--- a/frontend/src/content/en/application/quick-start.mdx
+++ b/frontend/src/content/en/application/quick-start.mdx
@@ -1,3 +1,8 @@
+---
+title: Quick Start
+description: This guide walks you through starting DeerFlow App on your local machine using the `make dev` workflow. All four services (LangGraph, Gateway, Frontend, nginx) start together and are accessible through a single URL.
+---
+
 import { Callout, Cards, Steps } from "nextra/components";
 
 # Quick Start
diff --git a/frontend/src/content/en/application/workspace-usage.mdx b/frontend/src/content/en/application/workspace-usage.mdx
index e879f6df4..8589c624c 100644
--- a/frontend/src/content/en/application/workspace-usage.mdx
+++ b/frontend/src/content/en/application/workspace-usage.mdx
@@ -1,3 +1,8 @@
+---
+title: Workspace Usage
+description: The DeerFlow App workspace is a browser-based interface for having multi-turn conversations with the agent, tracking task progress, viewing artifacts, and managing files.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Workspace Usage
diff --git a/frontend/src/content/en/harness/configuration.mdx b/frontend/src/content/en/harness/configuration.mdx
index fd2d9f16a..8043e2beb 100644
--- a/frontend/src/content/en/harness/configuration.mdx
+++ b/frontend/src/content/en/harness/configuration.mdx
@@ -1,3 +1,8 @@
+---
+title: Configuration
+description: "DeerFlow's configuration system is designed around one goal: every meaningful behavior should be expressible in a config file, not hardcoded in the application. This makes deployments reproducible, auditable, and easy to customize per environment."
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Configuration
diff --git a/frontend/src/content/en/harness/customization.mdx b/frontend/src/content/en/harness/customization.mdx
index c348eeabc..9d8c6b934 100644
--- a/frontend/src/content/en/harness/customization.mdx
+++ b/frontend/src/content/en/harness/customization.mdx
@@ -1,3 +1,8 @@
+---
+title: Customization
+description: DeerFlow's pluggable architecture means most parts of the system can be replaced or extended without forking the core. This page maps the extension points and explains how to use each one.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Customization
diff --git a/frontend/src/content/en/harness/design-principles.mdx b/frontend/src/content/en/harness/design-principles.mdx
index 49ca9d8ae..bda534217 100644
--- a/frontend/src/content/en/harness/design-principles.mdx
+++ b/frontend/src/content/en/harness/design-principles.mdx
@@ -1,3 +1,8 @@
+---
+title: Design Principles
+description: Understanding the design principles behind DeerFlow Harness helps you use it effectively, extend it confidently, and reason about how your agents will behave in production.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Design Principles
diff --git a/frontend/src/content/en/harness/index.mdx b/frontend/src/content/en/harness/index.mdx
index 02c9e46f3..ea0c098ec 100644
--- a/frontend/src/content/en/harness/index.mdx
+++ b/frontend/src/content/en/harness/index.mdx
@@ -1,3 +1,8 @@
+---
+title: Install DeerFlow Harness
+description: The DeerFlow Harness is the Python SDK and runtime foundation for building your own Super Agent systems.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Install DeerFlow Harness
diff --git a/frontend/src/content/en/harness/integration-guide.mdx b/frontend/src/content/en/harness/integration-guide.mdx
index 9d6846e50..61fffc9af 100644
--- a/frontend/src/content/en/harness/integration-guide.mdx
+++ b/frontend/src/content/en/harness/integration-guide.mdx
@@ -1,3 +1,8 @@
+---
+title: Integration Guide
+description: DeerFlow Harness is not only a standalone application. It is a Python library you can import and use inside your own backend, API server, automation system, or multi-agent orchestrator.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Integration Guide
diff --git a/frontend/src/content/en/harness/lead-agent.mdx b/frontend/src/content/en/harness/lead-agent.mdx
index 59d3337a0..4aafa80a1 100644
--- a/frontend/src/content/en/harness/lead-agent.mdx
+++ b/frontend/src/content/en/harness/lead-agent.mdx
@@ -1,3 +1,8 @@
+---
+title: Lead Agent
+description: The Lead Agent is the central executor in a DeerFlow thread. Every conversation, task, and workflow flows through it. Understanding how it works helps you configure it effectively and extend it when needed.
+---
+
 import { Callout, Cards, Steps } from "nextra/components";
 
 # Lead Agent
diff --git a/frontend/src/content/en/harness/mcp.mdx b/frontend/src/content/en/harness/mcp.mdx
index 32b95672b..0ea0f186d 100644
--- a/frontend/src/content/en/harness/mcp.mdx
+++ b/frontend/src/content/en/harness/mcp.mdx
@@ -1,3 +1,8 @@
+---
+title: MCP Integration
+description: The **Model Context Protocol (MCP)** is an open standard for connecting language models to external tools and data sources. DeerFlow's MCP integration allows you to extend the agent with any tool server that implements the MCP protocol — without modifying the harness itself.
+---
+
 import { Callout, Cards, Steps } from "nextra/components";
 
 # MCP Integration
diff --git a/frontend/src/content/en/harness/memory.mdx b/frontend/src/content/en/harness/memory.mdx
index 97094bbd7..4904c54bb 100644
--- a/frontend/src/content/en/harness/memory.mdx
+++ b/frontend/src/content/en/harness/memory.mdx
@@ -1,3 +1,8 @@
+---
+title: Memory
+description: Memory is a runtime feature of the DeerFlow Harness. It is not a simple conversation log — it is a structured store of facts and context summaries that persist across separate sessions and inform the agent's behavior in future conversations.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Memory
diff --git a/frontend/src/content/en/harness/middlewares.mdx b/frontend/src/content/en/harness/middlewares.mdx
index fab5b732f..fca391cf3 100644
--- a/frontend/src/content/en/harness/middlewares.mdx
+++ b/frontend/src/content/en/harness/middlewares.mdx
@@ -1,3 +1,8 @@
+---
+title: Middlewares
+description: Every time the Lead Agent calls the LLM, it runs through a **middleware chain** before and after the model call. Middlewares can read and modify the agent's state, inject content into the system prompt, intercept tool calls, and react to model outputs.
+---
+
 import { Callout } from "nextra/components";
 
 # Middlewares
diff --git a/frontend/src/content/en/harness/quick-start.mdx b/frontend/src/content/en/harness/quick-start.mdx
index 240cce8d2..5327e6773 100644
--- a/frontend/src/content/en/harness/quick-start.mdx
+++ b/frontend/src/content/en/harness/quick-start.mdx
@@ -1,14 +1,18 @@
+---
+title: Quick Start
+description: Learn how to create and run a DeerFlow agent with create_deerflow_agent, from model setup to streaming responses.
+---
+
 import { Callout, Cards, Steps } from "nextra/components";
 
 # Quick Start
 
 <Callout type="info" emoji="🚀">
-  This guide shows you how to use the DeerFlow Harness programmatically — not
-  through the App UI, but by importing and calling the harness directly in
-  Python.
+  This guide shows you how to build and run a DeerFlow agent in Python with
+  <code>create_deerflow_agent</code>.
 </Callout>
 
-The DeerFlow Harness is the Python SDK and runtime foundation. This quick start walks you through the key APIs for running an agent, streaming its output, and working with threads.
+The fastest way to understand DeerFlow Harness is to create an agent directly in code. This quick start walks through model setup, agent creation, and streaming a response.
 
 ## Prerequisites
 
@@ -21,130 +25,86 @@ cd backend
 uv sync
 ```
 
-## Configuration
+You will also need a chat model instance from the LangChain provider package you want to use.
 
-All harness behaviors are driven by `config.yaml`. At minimum, you need at least one model configured:
-
-```yaml
-# config.yaml
-config_version: 6
-
-models:
-  - name: gpt-4o
-    use: langchain_openai:ChatOpenAI
-    model: gpt-4o
-    api_key: $OPENAI_API_KEY
-    request_timeout: 600.0
-    max_retries: 2
-
-sandbox:
-  use: deerflow.sandbox.local:LocalSandboxProvider
-
-tools:
-  - use: deerflow.community.ddg_search.tools:web_search_tool
-  - use: deerflow.community.jina_ai.tools:web_fetch_tool
-  - use: deerflow.sandbox.tools:ls_tool
-  - use: deerflow.sandbox.tools:read_file_tool
-  - use: deerflow.sandbox.tools:write_file_tool
-  - use: deerflow.sandbox.tools:bash_tool
-```
-
-Copy `config.example.yaml` to `config.yaml` and fill in your API key.
-
-## Running the harness
-
-The primary entry point for the DeerFlow Harness is `DeerFlowClient`. It manages thread state, invokes the Lead Agent, and streams the response.
+## Create your first agent
 
 <Steps>
 
-### Import and configure
+### Import the factory and model
 
 ```python
-import asyncio
-from deerflow.client import DeerFlowClient
-from deerflow.config import load_config
-
-# Load config.yaml from the current directory or DEER_FLOW_CONFIG_PATH
-load_config()
-
-client = DeerFlowClient()
+from deerflow.agents import create_deerflow_agent
+from langchain_openai import ChatOpenAI
 ```
 
-### Create a thread
+### Create a model
 
 ```python
-thread_id = "my-thread-001"
+model = ChatOpenAI(
+    model="gpt-4o",
+    api_key="YOUR_OPENAI_API_KEY",
+)
 ```
 
-Thread IDs are arbitrary strings. Reusing the same ID continues the existing conversation (if a checkpointer is configured).
-
-### Send a message and stream the response
+### Create an agent
 
 ```python
-async def run():
-    async for event in client.astream(
-        thread_id=thread_id,
-        message="Research the top 3 open-source LLM frameworks and summarize them.",
-        config={
-            "configurable": {
-                "model_name": "gpt-4o",
-                "thinking_enabled": False,
-                "is_plan_mode": True,
-                "subagent_enabled": True,
-            }
-        },
-    ):
-        print(event)
+agent = create_deerflow_agent(model)
+```
 
-asyncio.run(run())
+This returns a compiled LangGraph agent with DeerFlow's default middleware chain.
+
+### Stream a response
+
+```python
+for event in agent.stream(
+    {"messages": [{"role": "user", "content": "Explain what DeerFlow Harness is."}]},
+    stream_mode=["messages", "values"],
+):
+    print(event)
 ```
 
 </Steps>
 
-## Configurable options
+## Add tools or behavior
 
-The `config.configurable` dict controls per-request behavior:
-
-| Key | Type | Default | Description |
-|---|---|---|---|
-| `model_name` | `str \| None` | first model in config | Model to use for this request |
-| `thinking_enabled` | `bool` | `True` | Enable extended thinking mode (if supported) |
-| `reasoning_effort` | `str \| None` | `None` | Reasoning effort level (model-specific) |
-| `is_plan_mode` | `bool` | `False` | Enable TodoList middleware for task tracking |
-| `subagent_enabled` | `bool` | `False` | Allow the agent to delegate subtasks |
-| `max_concurrent_subagents` | `int` | `3` | Maximum parallel subagent calls per turn |
-| `agent_name` | `str \| None` | `None` | Name of a custom agent to load |
-
-## Streaming event types
-
-`client.astream()` yields events from the LangGraph runtime. The key event types are:
-
-| Event type | Description |
-|---|---|
-| `messages` | Individual message chunks (text, thinking, tool calls) |
-| `thread_state` | Thread state updates (title, artifacts, todo list) |
-
-Message chunks contain the token stream as the agent generates its response.
-
-## Working with a custom agent
-
-If you have defined a custom agent, pass its `name` in the configurable:
+You can customize the agent by passing tools, a system prompt, runtime features, middleware, or a checkpointer.
 
 ```python
-async for event in client.astream(
-    thread_id="thread-002",
-    message="Analyze the attached CSV and generate a summary chart.",
-    config={
-        "configurable": {
-            "agent_name": "data-analyst",
-            "subagent_enabled": True,
-        }
-    },
-):
-    ...
+from deerflow.agents import RuntimeFeatures, create_deerflow_agent
+
+agent = create_deerflow_agent(
+    model,
+    system_prompt="You are a concise research assistant.",
+    features=RuntimeFeatures(subagent=True, memory=False),
+    plan_mode=True,
+    name="research-agent",
+)
 ```
 
-The custom agent's configuration (model, skills, tool groups) is loaded automatically from `agents/data-analyst/config.yaml`.
+Common parameters:
+
+| Parameter | Description |
+|---|---|
+| `tools` | Additional tools available to the agent |
+| `system_prompt` | Custom system prompt |
+| `features` | Enable or replace built-in runtime features |
+| `extra_middleware` | Insert custom middleware into the default chain |
+| `plan_mode` | Enable Todo-style task tracking |
+| `checkpointer` | Persist agent state across runs |
+| `name` | Logical agent name |
+
+## When to use DeerFlowClient instead
+
+`create_deerflow_agent()` is the low-level SDK factory when you want to work directly with the compiled agent graph.
+
+Use `DeerFlowClient` when you want the higher-level embedded app interface, such as:
+
+- thread-oriented chat helpers,
+- model / skills / memory management APIs,
+- file uploads and artifacts,
+- Gateway-like response formats.
 
 ## Next steps
 
diff --git a/frontend/src/content/en/harness/sandbox.mdx b/frontend/src/content/en/harness/sandbox.mdx
index b5762210c..203e5c44d 100644
--- a/frontend/src/content/en/harness/sandbox.mdx
+++ b/frontend/src/content/en/harness/sandbox.mdx
@@ -1,3 +1,8 @@
+---
+title: Sandbox
+description: The sandbox gives the Lead Agent a controlled environment where it can read files, write outputs, run shell commands, and produce artifacts. Without a sandbox, the agent can only generate text. With a sandbox, it can write and execute code, process data files, generate charts, and build deliverables.
+---
+
 import { Callout, Cards, Tabs } from "nextra/components";
 
 # Sandbox
diff --git a/frontend/src/content/en/harness/skills.mdx b/frontend/src/content/en/harness/skills.mdx
index 71efab6fc..45f232b37 100644
--- a/frontend/src/content/en/harness/skills.mdx
+++ b/frontend/src/content/en/harness/skills.mdx
@@ -1,3 +1,8 @@
+---
+title: Skills
+description: A skill is more than a prompt. It is a self-contained capability package that can include structured instructions, step-by-step workflows, domain-specific best practices, supporting resources, and tool configurations. Skills are loaded on demand — they inject their content when a task calls for them and stay out of the context otherwise.
+---
+
 import { Callout, Cards, FileTree, Steps } from "nextra/components";
 
 # Skills
diff --git a/frontend/src/content/en/harness/subagents.mdx b/frontend/src/content/en/harness/subagents.mdx
index 062ca9698..193f1aa0c 100644
--- a/frontend/src/content/en/harness/subagents.mdx
+++ b/frontend/src/content/en/harness/subagents.mdx
@@ -1,3 +1,8 @@
+---
+title: Subagents
+description: When a task is too broad for a single reasoning thread, or when parts of it can be done in parallel, the Lead Agent delegates work to **subagents**. A subagent is a self-contained agent invocation that receives a specific task, executes it, and returns the result.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Subagents
diff --git a/frontend/src/content/en/harness/tools.mdx b/frontend/src/content/en/harness/tools.mdx
index eefc72631..005fa3ed3 100644
--- a/frontend/src/content/en/harness/tools.mdx
+++ b/frontend/src/content/en/harness/tools.mdx
@@ -1,3 +1,8 @@
+---
+title: Tools
+description: "The Lead Agent is a tool-calling agent. Tools are how it interacts with the world: searching the web, reading and writing files, running commands, delegating tasks, and presenting outputs to the user."
+---
+
 import { Callout, Cards, Tabs } from "nextra/components";
 
 # Tools
diff --git a/frontend/src/content/en/introduction/core-concepts.mdx b/frontend/src/content/en/introduction/core-concepts.mdx
index dfed365cb..f7203ae1e 100644
--- a/frontend/src/content/en/introduction/core-concepts.mdx
+++ b/frontend/src/content/en/introduction/core-concepts.mdx
@@ -1,3 +1,8 @@
+---
+title: Core Concepts
+description: Before you go deeper into DeerFlow, it helps to anchor on a few concepts that appear throughout the system. These concepts explain what DeerFlow is optimizing for and why its architecture looks the way it does.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Core Concepts
diff --git a/frontend/src/content/en/introduction/harness-vs-app.mdx b/frontend/src/content/en/introduction/harness-vs-app.mdx
index e0bbb6d55..9e6b8ece2 100644
--- a/frontend/src/content/en/introduction/harness-vs-app.mdx
+++ b/frontend/src/content/en/introduction/harness-vs-app.mdx
@@ -1,3 +1,8 @@
+---
+title: Harness vs App
+description: "DeerFlow has two layers that are closely related but serve different purposes."
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Harness vs App
diff --git a/frontend/src/content/en/introduction/why-deerflow.mdx b/frontend/src/content/en/introduction/why-deerflow.mdx
index f7fad9628..66ca91f31 100644
--- a/frontend/src/content/en/introduction/why-deerflow.mdx
+++ b/frontend/src/content/en/introduction/why-deerflow.mdx
@@ -1,3 +1,8 @@
+---
+title: Why DeerFlow
+description: DeerFlow exists because modern agent systems need more than a chat loop. A useful agent must plan over long horizons, break work into sub-tasks, use tools, manipulate files, run code safely, and preserve enough context to stay coherent across a complex task. DeerFlow was built to provide that runtime foundation.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Why DeerFlow
diff --git a/frontend/src/content/en/reference/_meta.ts b/frontend/src/content/en/reference/_meta.ts
index cf53ad9a8..835fd6ce0 100644
--- a/frontend/src/content/en/reference/_meta.ts
+++ b/frontend/src/content/en/reference/_meta.ts
@@ -1,20 +1,8 @@
 import type { MetaRecord } from "nextra";
 
 const meta: MetaRecord = {
-  "concepts-glossary": {
-    title: "Concepts Glossary",
-  },
-  "configuration-reference": {
-    title: "Configuration Reference",
-  },
-  "api-gateway-reference": {
-    title: "API / Gateway Reference",
-  },
-  "runtime-flags-and-modes": {
-    title: "Runtime Flags and Modes",
-  },
-  "source-map": {
-    title: "Source Map",
+  "model-providers": {
+    title: "Model providers",
   },
 };
 
diff --git a/frontend/src/content/en/reference/api-gateway-reference.mdx b/frontend/src/content/en/reference/api-gateway-reference.mdx
deleted file mode 100644
index b3497db83..000000000
--- a/frontend/src/content/en/reference/api-gateway-reference.mdx
+++ /dev/null
@@ -1,69 +0,0 @@
-import { Callout } from "nextra/components";
-
-# API / Gateway Reference
-
-<Callout type="info">
-  DeerFlow Gateway is built on FastAPI and provides interactive API
-  documentation at <code>http://localhost:8001/docs</code>.
-</Callout>
-
-## Base URL
-
-```
-http://localhost:8001
-```
-
-Via nginx proxy:
-
-```
-http://localhost:2026/api
-```
-
-## Core endpoints
-
-### System
-
-| Method | Path          | Description                       |
-| ------ | ------------- | --------------------------------- |
-| `GET`  | `/health`     | Service health check              |
-| `GET`  | `/api/models` | Get the list of configured models |
-
-### Agent management
-
-| Method   | Path                 | Description                     |
-| -------- | -------------------- | ------------------------------- |
-| `GET`    | `/api/agents`        | List all agents                 |
-| `POST`   | `/api/agents`        | Create a custom agent           |
-| `GET`    | `/api/agents/{name}` | Get agent configuration         |
-| `PUT`    | `/api/agents/{name}` | Update agent configuration      |
-| `DELETE` | `/api/agents/{name}` | Delete an agent                 |
-| `POST`   | `/api/agents/check`  | Check/suggest unique agent slug |
-
-### Threads and memory
-
-| Method   | Path                       | Description               |
-| -------- | -------------------------- | ------------------------- |
-| `GET`    | `/api/threads`             | List threads              |
-| `DELETE` | `/api/threads/{thread_id}` | Delete a thread           |
-| `GET`    | `/api/memory`              | Get global memory         |
-| `GET`    | `/api/memory/{agent_name}` | Get agent-specific memory |
-| `DELETE` | `/api/memory`              | Clear global memory       |
-
-### Extensions
-
-| Method | Path                                    | Description                                  |
-| ------ | --------------------------------------- | -------------------------------------------- |
-| `GET`  | `/api/extensions`                       | List all extensions (MCP servers and skills) |
-| `POST` | `/api/extensions/mcp/{name}/enable`     | Enable an MCP server                         |
-| `POST` | `/api/extensions/mcp/{name}/disable`    | Disable an MCP server                        |
-| `POST` | `/api/extensions/skills/{name}/enable`  | Enable a skill                               |
-| `POST` | `/api/extensions/skills/{name}/disable` | Disable a skill                              |
-
-### File uploads
-
-| Method | Path                                  | Description                           |
-| ------ | ------------------------------------- | ------------------------------------- |
-| `POST` | `/api/uploads/{thread_id}`            | Upload a file to the thread workspace |
-| `GET`  | `/api/uploads/{thread_id}/{filename}` | Retrieve an uploaded file             |
-
-For the full interactive API documentation visit `http://localhost:8001/docs` (Swagger UI).
diff --git a/frontend/src/content/en/reference/concepts-glossary.mdx b/frontend/src/content/en/reference/concepts-glossary.mdx
deleted file mode 100644
index 4302fd9c3..000000000
--- a/frontend/src/content/en/reference/concepts-glossary.mdx
+++ /dev/null
@@ -1,67 +0,0 @@
-import { Callout } from "nextra/components";
-
-# Concepts Glossary
-
-This glossary defines the core terms used throughout the DeerFlow documentation.
-
----
-
-## Agent
-
-In DeerFlow, an agent is the primary processing unit that receives user messages, decides what actions to take (tool calls or direct responses), and generates output. DeerFlow uses a two-tier architecture with a **Lead Agent** and **Subagents**.
-
-## Artifact
-
-A file produced by the agent — a report, chart, code file, or other deliverable. Artifacts are exposed via the `present_files` tool and persisted in the thread's user-data directory.
-
-## Checkpoint
-
-A persisted snapshot of thread state, saved after each agent turn. Checkpoints allow conversations to resume after server restarts and support state management for long-horizon tasks.
-
-## Context Engineering
-
-The practice of controlling what the agent sees, remembers, and ignores at each step — through summarization, scoped subagent contexts, and external file memory — to keep the agent effective over long-horizon tasks.
-
-## Harness
-
-An opinionated agent runtime that packages tool access, skill loading, sandbox execution, memory, subagent coordination, and context management — rather than just exposing abstractions.
-
-## Lead Agent
-
-The primary executor in each DeerFlow thread, responsible for planning, tool calls, and response generation. Built on LangGraph + LangChain Agent, augmented by the middleware chain.
-
-## Long-horizon Agent
-
-An agent that remains useful across a chain of actions — making plans, calling tools many times, managing intermediate files, and producing a final artifact — rather than producing only a single answer.
-
-## Memory
-
-Structured facts and user context that persists across independent conversation sessions, injected into the agent's system prompt in subsequent sessions.
-
-## Middleware
-
-A plugin that wraps every LLM call, able to read and modify agent state before and after the model invocation. DeerFlow uses middleware for memory, summarization, title generation, and other cross-cutting behaviors.
-
-## MCP (Model Context Protocol)
-
-An open standard for connecting language models to external tools and data sources. DeerFlow's MCP integration allows connection to any compatible tool server.
-
-## Sandbox
-
-The isolated execution environment where the agent performs file and command-based work. DeerFlow supports local (`LocalSandboxProvider`) and container-based (`AioSandboxProvider`) sandbox modes.
-
-## Skill
-
-A task-oriented capability pack containing structured instructions, workflows, and best practices, loaded into the agent's context on demand. Skills provide specialization without polluting the general agent context.
-
-## Subagent
-
-A focused worker that handles a delegated subtask, running with an isolated context that contains only the information needed to complete its assigned work.
-
-## Thread
-
-The complete encapsulation of a conversation and all its associated state — message history, artifacts, todo list, and checkpoint data.
-
-## ThreadState
-
-The LangGraph-managed state object in DeerFlow, containing `messages`, `artifacts`, `todo_list`, and runtime metadata.
diff --git a/frontend/src/content/en/reference/configuration-reference.mdx b/frontend/src/content/en/reference/configuration-reference.mdx
deleted file mode 100644
index 88cdb3f15..000000000
--- a/frontend/src/content/en/reference/configuration-reference.mdx
+++ /dev/null
@@ -1,123 +0,0 @@
-import { Callout } from "nextra/components";
-
-# Configuration Reference
-
-This page is the complete reference for all top-level fields in `config.yaml`.
-
-<Callout type="info">
-  See <code>config.example.yaml</code> in the repository root for a fully
-  commented example with all available options.
-</Callout>
-
-## Top-level fields
-
-| Field                  | Type          | Description                                     |
-| ---------------------- | ------------- | ----------------------------------------------- |
-| `config_version`       | `int`         | Config schema version (current: 6)              |
-| `log_level`            | `str`         | Log verbosity: `debug`/`info`/`warning`/`error` |
-| `models`               | `list`        | Available LLM model configurations              |
-| `image_generate_model` | `str \| list` | Model name to use for image generation          |
-| `token_usage`          | `object`      | Token usage tracking config                     |
-| `tools`                | `list`        | Available tool configurations                   |
-| `tool_groups`          | `list`        | Named groupings of tools                        |
-| `tool_search`          | `object`      | Deferred tool loading config                    |
-| `sandbox`              | `object`      | Sandbox provider and options                    |
-| `skills`               | `object`      | Skills directory and container path             |
-| `skill_evolution`      | `object`      | Agent-managed skill creation                    |
-| `subagents`            | `object`      | Subagent timeouts and max turns                 |
-| `acp_agents`           | `dict`        | External ACP agent configurations               |
-| `memory`               | `object`      | Cross-session memory storage                    |
-| `summarization`        | `object`      | Conversation summarization                      |
-| `title`                | `object`      | Automatic thread title generation               |
-| `checkpointer`         | `object`      | Thread state persistence                        |
-| `guardrails`           | `object`      | Tool call authorization                         |
-| `uploads`              | `object`      | File upload settings                            |
-| `channels`             | `list`        | IM channel integrations                         |
-
-## models
-
-```yaml
-models:
-  - name: gpt-4o # Model identifier (referenced in requests)
-    use: langchain_openai:ChatOpenAI # Python class path
-    model: gpt-4o # Model name passed to the LLM
-    api_key: $OPENAI_API_KEY # API key (env var interpolation supported)
-    base_url: null # Optional: custom endpoint URL
-    request_timeout: 600.0 # Request timeout in seconds
-    max_retries: 2 # Number of retries on failure
-    supports_vision: true # Whether to enable vision capabilities
-    thinking_enabled: false # Whether to enable extended thinking
-    # Any additional fields are passed through to the model constructor
-```
-
-## sandbox
-
-```yaml
-sandbox:
-  # Local (default, no container isolation)
-  use: deerflow.sandbox.local:LocalSandboxProvider
-  allow_host_bash: false
-  bash_output_max_chars: 20000
-  read_file_output_max_chars: 50000
-  ls_output_max_chars: 20000
-
-  # Container-based
-  # use: deerflow.community.aio_sandbox:AioSandboxProvider
-  # image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
-  # replicas: 3
-  # idle_timeout: 600
-```
-
-## memory
-
-```yaml
-memory:
-  enabled: true
-  storage_path: memory.json
-  debounce_seconds: 30
-  max_facts: 100
-  fact_confidence_threshold: 0.7
-  injection_enabled: true
-  max_injection_tokens: 2000
-  model_name: null
-```
-
-## summarization
-
-```yaml
-summarization:
-  enabled: true
-  model_name: null
-  trigger:
-    - type: tokens
-      value: 15564
-  keep:
-    type: messages
-    value: 10
-  trim_tokens_to_summarize: 15564
-  summary_prompt: null
-```
-
-## checkpointer
-
-```yaml
-checkpointer:
-  type: sqlite # sqlite | redis | postgres
-  connection_string: .deer-flow/checkpoints.db
-```
-
-## subagents
-
-```yaml
-subagents:
-  timeout_seconds: 900
-  agents:
-    general-purpose:
-      timeout_seconds: 1800
-      max_turns: 160
-    bash:
-      timeout_seconds: 300
-      max_turns: 80
-```
-
-See the dedicated documentation page for each feature for full field descriptions.
diff --git a/frontend/src/content/en/reference/model-providers/_meta.ts b/frontend/src/content/en/reference/model-providers/_meta.ts
new file mode 100644
index 000000000..81fd1b56f
--- /dev/null
+++ b/frontend/src/content/en/reference/model-providers/_meta.ts
@@ -0,0 +1,9 @@
+import type { MetaRecord } from "nextra";
+
+const meta: MetaRecord = {
+  ark: {
+    title: "火山方舟",
+  },
+};
+
+export default meta;
diff --git a/frontend/src/content/en/reference/model-providers/ark.mdx b/frontend/src/content/en/reference/model-providers/ark.mdx
new file mode 100644
index 000000000..5956d691b
--- /dev/null
+++ b/frontend/src/content/en/reference/model-providers/ark.mdx
@@ -0,0 +1,8 @@
+---
+title: Volcano Ark
+description: Integration guide for the Volcano Ark model provider.
+---
+
+# Volcano Ark
+
+## Coding Plan
diff --git a/frontend/src/content/en/reference/model-providers/index.mdx b/frontend/src/content/en/reference/model-providers/index.mdx
new file mode 100644
index 000000000..f9b506a6d
--- /dev/null
+++ b/frontend/src/content/en/reference/model-providers/index.mdx
@@ -0,0 +1,7 @@
+---
+title: Model providers
+description: Integration references for supported model provider services.
+asIndexPage: true
+---
+
+# Model providers
diff --git a/frontend/src/content/en/reference/runtime-flags-and-modes.mdx b/frontend/src/content/en/reference/runtime-flags-and-modes.mdx
deleted file mode 100644
index db1d3a517..000000000
--- a/frontend/src/content/en/reference/runtime-flags-and-modes.mdx
+++ /dev/null
@@ -1,36 +0,0 @@
-# Runtime Flags and Modes
-
-This page documents the runtime flags and modes that affect DeerFlow Harness and agent runtime behavior.
-
-## Per-request configurable options
-
-These options are passed via `config.configurable` (for programmatic use) or selected in the web UI (for application use):
-
-| Flag                       | Type          | Default                | Description                                      |
-| -------------------------- | ------------- | ---------------------- | ------------------------------------------------ |
-| `model_name`               | `str \| None` | First configured model | Model to use for the request                     |
-| `agent_name`               | `str \| None` | `None`                 | Load a custom agent configuration                |
-| `thinking_enabled`         | `bool`        | `True`                 | Enable extended thinking (model must support it) |
-| `reasoning_effort`         | `str \| None` | `None`                 | Reasoning effort level (model-specific)          |
-| `is_plan_mode`             | `bool`        | `False`                | Enable TodoList middleware                       |
-| `subagent_enabled`         | `bool`        | `False`                | Allow subagent delegation                        |
-| `max_concurrent_subagents` | `int`         | `3`                    | Maximum parallel subagent calls per turn         |
-
-## Environment variables
-
-| Variable                | Default         | Description                                      |
-| ----------------------- | --------------- | ------------------------------------------------ |
-| `DEER_FLOW_CONFIG_PATH` | Auto-discovered | Absolute path to `config.yaml`                   |
-| `LOG_LEVEL`             | `info`          | Log level override                               |
-| `DEER_FLOW_ROOT`        | Repo root       | Base path for Docker bind mounts                 |
-| `BETTER_AUTH_SECRET`    | —               | Frontend session secret (required in production) |
-| `BETTER_AUTH_URL`       | —               | Public URL (for callbacks and CORS)              |
-
-## Model capability flags
-
-Set in the model configuration in `config.yaml`:
-
-| Flag               | Type   | Description                           |
-| ------------------ | ------ | ------------------------------------- |
-| `supports_vision`  | `bool` | Model accepts image inputs            |
-| `thinking_enabled` | `bool` | Model supports extended thinking mode |
diff --git a/frontend/src/content/en/reference/source-map.mdx b/frontend/src/content/en/reference/source-map.mdx
deleted file mode 100644
index c5f526232..000000000
--- a/frontend/src/content/en/reference/source-map.mdx
+++ /dev/null
@@ -1,88 +0,0 @@
-# Source Map
-
-This page maps DeerFlow's core concepts to where they are implemented in the codebase, helping you quickly locate specific features.
-
-## Backend core paths
-
-```
-backend/
-├── app/
-│   └── gateway/              # FastAPI Gateway API
-│       ├── routers/
-│       │   ├── agents.py     # Custom agent CRUD
-│       │   ├── extensions.py # MCP/skill enable/disable
-│       │   ├── memory.py     # Memory read/clear
-│       │   ├── threads.py    # Thread management
-│       │   └── uploads.py    # File uploads
-│       └── main.py           # FastAPI app entry point
-│
-└── packages/harness/deerflow/
-    ├── agents/
-    │   ├── lead_agent/
-    │   │   ├── agent.py      # make_lead_agent() factory
-    │   │   └── prompt.py     # System prompt templates
-    │   ├── middlewares/      # All middleware implementations
-    │   ├── memory/
-    │   │   ├── middleware.py # MemoryMiddleware
-    │   │   └── storage.py   # Memory file storage
-    │   └── thread_state.py  # ThreadState dataclass
-    │
-    ├── config/
-    │   ├── app_config.py    # AppConfig (top-level config)
-    │   ├── model_config.py  # ModelConfig
-    │   ├── paths.py         # Path resolution utilities
-    │   └── *.py             # Per-module config classes
-    │
-    ├── mcp/
-    │   ├── cache.py         # mtime-based tool cache
-    │   └── oauth.py         # MCP OAuth support
-    │
-    ├── models/
-    │   └── factory.py       # create_chat_model() LLM factory
-    │
-    ├── sandbox/
-    │   ├── local/           # LocalSandboxProvider
-    │   └── sandbox.py       # Sandbox base class
-    │
-    ├── skills/
-    │   ├── loader.py        # load_skills() (hot reload)
-    │   ├── parser.py        # SKILL.md parsing
-    │   ├── installer.py     # Dependency installation
-    │   └── manager.py       # Skill lifecycle management
-    │
-    ├── subagents/
-    │   └── registry.py      # Subagent lookup and config override
-    │
-    └── tools/
-        └── builtins/        # Built-in tool implementations
-```
-
-## Frontend core paths
-
-```
-frontend/src/
-├── app/                     # Next.js routes and pages
-├── components/
-│   └── workspace/           # Workspace UI components
-├── core/
-│   ├── agents/              # Agent types and API client
-│   ├── messages/            # Message types and tool call handling
-│   └── threads/             # Thread state management
-└── content/                 # Documentation content (MDX)
-    ├── en/                  # English documentation
-    └── zh/                  # Chinese documentation
-```
-
-## Quick index
-
-| Goal                       | File                          |
-| -------------------------- | ----------------------------- |
-| Lead agent creation        | `agents/lead_agent/agent.py`  |
-| System prompt template     | `agents/lead_agent/prompt.py` |
-| All middleware             | `agents/middlewares/`         |
-| Config loading             | `config/app_config.py`        |
-| Model factory              | `models/factory.py`           |
-| Skill loading (hot reload) | `skills/loader.py`            |
-| MCP tool cache             | `mcp/cache.py`                |
-| File upload handling       | `uploads/manager.py`          |
-| Gateway main router        | `app/gateway/main.py`         |
diff --git a/frontend/src/content/en/tutorials/create-your-first-harness.mdx b/frontend/src/content/en/tutorials/create-your-first-harness.mdx
index 0b74ff549..3e94f984c 100644
--- a/frontend/src/content/en/tutorials/create-your-first-harness.mdx
+++ b/frontend/src/content/en/tutorials/create-your-first-harness.mdx
@@ -1,3 +1,8 @@
+---
+title: Create Your First Harness
+description: This tutorial shows you how to use the DeerFlow Harness programmatically — importing and using DeerFlow directly in your Python code rather than through the web interface.
+---
+
 import { Callout, Steps } from "nextra/components";
 
 # Create Your First Harness
diff --git a/frontend/src/content/en/tutorials/deploy-your-own-deerflow.mdx b/frontend/src/content/en/tutorials/deploy-your-own-deerflow.mdx
index 0833072e7..bd62bbb51 100644
--- a/frontend/src/content/en/tutorials/deploy-your-own-deerflow.mdx
+++ b/frontend/src/content/en/tutorials/deploy-your-own-deerflow.mdx
@@ -1,3 +1,8 @@
+---
+title: Deploy Your Own DeerFlow
+description: This tutorial guides you through deploying DeerFlow to a production environment using Docker Compose for multi-user access.
+---
+
 import { Callout, Steps } from "nextra/components";
 
 # Deploy Your Own DeerFlow
diff --git a/frontend/src/content/en/tutorials/first-conversation.mdx b/frontend/src/content/en/tutorials/first-conversation.mdx
index ed2d63b20..271e806d2 100644
--- a/frontend/src/content/en/tutorials/first-conversation.mdx
+++ b/frontend/src/content/en/tutorials/first-conversation.mdx
@@ -1,3 +1,8 @@
+---
+title: First Conversation
+description: This tutorial walks you through your first complete agent conversation in DeerFlow — from launching the app to getting meaningful work done with the agent.
+---
+
 import { Callout, Steps } from "nextra/components";
 
 # First Conversation
diff --git a/frontend/src/content/en/tutorials/use-tools-and-skills.mdx b/frontend/src/content/en/tutorials/use-tools-and-skills.mdx
index c36385ee7..dc84a6317 100644
--- a/frontend/src/content/en/tutorials/use-tools-and-skills.mdx
+++ b/frontend/src/content/en/tutorials/use-tools-and-skills.mdx
@@ -1,3 +1,8 @@
+---
+title: Use Tools and Skills
+description: This tutorial shows you how to configure and use tools and skills in DeerFlow to give the agent access to web search, file operations, and domain-specific capabilities.
+---
+
 import { Callout } from "nextra/components";
 
 # Use Tools and Skills
diff --git a/frontend/src/content/en/tutorials/work-with-memory.mdx b/frontend/src/content/en/tutorials/work-with-memory.mdx
index 622ad312c..8b101aaf4 100644
--- a/frontend/src/content/en/tutorials/work-with-memory.mdx
+++ b/frontend/src/content/en/tutorials/work-with-memory.mdx
@@ -1,3 +1,8 @@
+---
+title: Work with Memory
+description: This tutorial shows you how to enable and use DeerFlow's memory system so the agent remembers important information about you across multiple sessions.
+---
+
 import { Callout } from "nextra/components";
 
 # Work with Memory
diff --git a/frontend/src/content/zh/_meta.ts b/frontend/src/content/zh/_meta.ts
index 37f816e1a..9540c441e 100644
--- a/frontend/src/content/zh/_meta.ts
+++ b/frontend/src/content/zh/_meta.ts
@@ -25,6 +25,15 @@ const meta: MetaRecord = {
   blog: {
     type: "page",
   },
+  posts: {
+    type: "page",
+  },
+  login: {
+    type: "page",
+  },
+  setup: {
+    type: "page",
+  },
 };
 
 export default meta;
diff --git a/frontend/src/content/zh/application/agents-and-threads.mdx b/frontend/src/content/zh/application/agents-and-threads.mdx
index c7743438f..0900c733a 100644
--- a/frontend/src/content/zh/application/agents-and-threads.mdx
+++ b/frontend/src/content/zh/application/agents-and-threads.mdx
@@ -1,3 +1,8 @@
+---
+title: Agent 与线程
+description: 了解 DeerFlow 中 Agent 与线程的关系，以及如何管理自定义 Agent 和对话线程。
+---
+
 import { Callout, Cards, Steps } from "nextra/components";
 
 # Agent 与线程
diff --git a/frontend/src/content/zh/application/configuration.mdx b/frontend/src/content/zh/application/configuration.mdx
index 011171f3a..a0cb9c7cc 100644
--- a/frontend/src/content/zh/application/configuration.mdx
+++ b/frontend/src/content/zh/application/configuration.mdx
@@ -1,3 +1,8 @@
+---
+title: 配置
+description: 本页面涵盖 DeerFlow 应用的所有配置层——`config.yaml`、前端环境变量、`extensions_config.json` 和运行时环境变量。
+---
+
 import { Callout, Cards, Tabs } from "nextra/components";
 
 # 配置
diff --git a/frontend/src/content/zh/application/deployment-guide.mdx b/frontend/src/content/zh/application/deployment-guide.mdx
index 6695ca10c..ff75c21b0 100644
--- a/frontend/src/content/zh/application/deployment-guide.mdx
+++ b/frontend/src/content/zh/application/deployment-guide.mdx
@@ -1,3 +1,8 @@
+---
+title: 部署指南
+description: 本指南涵盖 DeerFlow 应用所有支持的部署方式：本地开发、Docker Compose 以及使用 Kubernetes 管理沙箱的生产环境。
+---
+
 import { Callout, Cards, Steps, Tabs } from "nextra/components";
 
 # 部署指南
diff --git a/frontend/src/content/zh/application/index.mdx b/frontend/src/content/zh/application/index.mdx
index 479edf1d2..d8c06d0c4 100644
--- a/frontend/src/content/zh/application/index.mdx
+++ b/frontend/src/content/zh/application/index.mdx
@@ -1,3 +1,8 @@
+---
+title: DeerFlow 应用
+description: DeerFlow 应用是 DeerFlow 生产体验的参考实现。它将 Harness 运行时、基于 Web 的对话工作区、API Gateway 和反向代理组合成一个可部署的完整系统。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # DeerFlow 应用
diff --git a/frontend/src/content/zh/application/operations-and-troubleshooting.mdx b/frontend/src/content/zh/application/operations-and-troubleshooting.mdx
index c07e48b6e..3b4157d4f 100644
--- a/frontend/src/content/zh/application/operations-and-troubleshooting.mdx
+++ b/frontend/src/content/zh/application/operations-and-troubleshooting.mdx
@@ -1,3 +1,8 @@
+---
+title: 运维与排障
+description: 本页面涵盖运行 DeerFlow 应用的操作信息：日志记录、常见问题和维护任务。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # 运维与排障
diff --git a/frontend/src/content/zh/application/quick-start.mdx b/frontend/src/content/zh/application/quick-start.mdx
index f10b583b2..a531a6430 100644
--- a/frontend/src/content/zh/application/quick-start.mdx
+++ b/frontend/src/content/zh/application/quick-start.mdx
@@ -1,3 +1,8 @@
+---
+title: 快速上手
+description: 本指南引导你使用 `make dev` 工作流在本地机器上启动 DeerFlow 应用。所有四个服务（LangGraph、Gateway、前端、nginx）一起启动，通过单个 URL 访问。
+---
+
 import { Callout, Cards, Steps } from "nextra/components";
 
 # 快速上手
diff --git a/frontend/src/content/zh/application/workspace-usage.mdx b/frontend/src/content/zh/application/workspace-usage.mdx
index aa4c95300..5ade5cc13 100644
--- a/frontend/src/content/zh/application/workspace-usage.mdx
+++ b/frontend/src/content/zh/application/workspace-usage.mdx
@@ -1,3 +1,8 @@
+---
+title: 工作区使用
+description: DeerFlow 工作区是一个基于浏览器的对话界面，你可以在其中向 Agent 发送消息、上传文件、查看中间步骤，以及下载生成的产出物。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # 工作区使用
diff --git a/frontend/src/content/zh/harness/configuration.mdx b/frontend/src/content/zh/harness/configuration.mdx
index 41ec8fd83..eda2370dc 100644
--- a/frontend/src/content/zh/harness/configuration.mdx
+++ b/frontend/src/content/zh/harness/configuration.mdx
@@ -1,3 +1,8 @@
+---
+title: 配置
+description: DeerFlow 的配置系统围绕一个目标设计：每一个有意义的行为都应该可以在配置文件中表达，而不是硬编码在应用程序中。这使部署可重现、可审计，并且易于按环境定制。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # 配置
diff --git a/frontend/src/content/zh/harness/customization.mdx b/frontend/src/content/zh/harness/customization.mdx
index 841e33c20..25f902acd 100644
--- a/frontend/src/content/zh/harness/customization.mdx
+++ b/frontend/src/content/zh/harness/customization.mdx
@@ -1,3 +1,8 @@
+---
+title: 自定义与扩展
+description: DeerFlow 的可插拔架构意味着系统的大多数部分都可以在不 fork 核心的情况下被替换或扩展。本页面列举了扩展点，并解释如何使用每一个。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # 自定义与扩展
diff --git a/frontend/src/content/zh/harness/design-principles.mdx b/frontend/src/content/zh/harness/design-principles.mdx
index 9aadcb824..c25931d14 100644
--- a/frontend/src/content/zh/harness/design-principles.mdx
+++ b/frontend/src/content/zh/harness/design-principles.mdx
@@ -1,3 +1,8 @@
+---
+title: 设计理念
+description: 了解 DeerFlow Harness 背后的设计理念，有助于你有效地使用它、自信地扩展它，并推断 Agent 在生产环境中的行为方式。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # 设计理念
diff --git a/frontend/src/content/zh/harness/index.mdx b/frontend/src/content/zh/harness/index.mdx
index 196bc649f..ea8712487 100644
--- a/frontend/src/content/zh/harness/index.mdx
+++ b/frontend/src/content/zh/harness/index.mdx
@@ -1,3 +1,8 @@
+---
+title: 安装 DeerFlow Harness
+description: DeerFlow Harness 是构建自己 Super Agent 系统的 Python SDK 和运行时基础。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # 安装 DeerFlow Harness
diff --git a/frontend/src/content/zh/harness/integration-guide.mdx b/frontend/src/content/zh/harness/integration-guide.mdx
index 5b0e7b497..2d2e389a8 100644
--- a/frontend/src/content/zh/harness/integration-guide.mdx
+++ b/frontend/src/content/zh/harness/integration-guide.mdx
@@ -1,3 +1,8 @@
+---
+title: 集成指南
+description: DeerFlow Harness 不仅仅是一个独立应用程序——它是一个可以导入并在你自己的后端、API 服务器、自动化系统或多 Agent 协调器中使用的 Python 库。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # 集成指南
diff --git a/frontend/src/content/zh/harness/lead-agent.mdx b/frontend/src/content/zh/harness/lead-agent.mdx
index 98a7b3ba9..c6f16a413 100644
--- a/frontend/src/content/zh/harness/lead-agent.mdx
+++ b/frontend/src/content/zh/harness/lead-agent.mdx
@@ -1,3 +1,8 @@
+---
+title: Lead Agent
+description: Lead Agent 是 DeerFlow 线程中的核心执行者。每个对话、任务和工作流都通过它进行。理解它的工作方式有助于你有效地配置它，并在需要时扩展它。
+---
+
 import { Callout, Cards, Steps } from "nextra/components";
 
 # Lead Agent
diff --git a/frontend/src/content/zh/harness/mcp.mdx b/frontend/src/content/zh/harness/mcp.mdx
index daba39ac1..4bf72c1a6 100644
--- a/frontend/src/content/zh/harness/mcp.mdx
+++ b/frontend/src/content/zh/harness/mcp.mdx
@@ -1,9 +1,15 @@
+---
+title: MCP 集成
+description: Model Context Protocol（MCP） 是连接语言模型与外部工具和数据源的开放标准。DeerFlow 的 MCP 集成允许你用任何实现了 MCP 协议的工具服务器扩展 Agent——无需修改 Harness 本身。
+---
+
 import { Callout, Cards, Steps } from "nextra/components";
 
 # MCP 集成
 
 <Callout type="info" emoji="🔌">
-  Model Context Protocol（MCP）让 DeerFlow 能够连接任何外部工具服务器。连接后，MCP 工具与内置工具一样对 Lead Agent 可用。
+  Model Context Protocol（MCP）让 DeerFlow
+  能够连接任何外部工具服务器。连接后，MCP 工具与内置工具一样对 Lead Agent 可用。
 </Callout>
 
 **Model Context Protocol（MCP）** 是连接语言模型与外部工具和数据源的开放标准。DeerFlow 的 MCP 集成允许你用任何实现了 MCP 协议的工具服务器扩展 Agent——无需修改 Harness 本身。
@@ -37,6 +43,7 @@ MCP 服务器在 `extensions_config.json` 中配置，这个文件独立于 `con
 ```
 
 每个服务器条目支持：
+
 - `command`：要运行的可执行文件（如 `npx`、`uvx`、`python`）
 - `args`：命令参数数组
 - `enabled`：服务器是否激活（可切换而无需删除条目）
@@ -81,6 +88,7 @@ tool_search:
 某些 MCP 服务器需要 OAuth 认证。DeerFlow 的 `mcp/oauth.py` 处理声明了 OAuth 需求的服务器的 OAuth 流程。
 
 当连接到受 OAuth 保护的 MCP 服务器时，DeerFlow 会：
+
 1. 从服务器能力头中检测 OAuth 需求
 2. 使用 `get_initial_oauth_headers()` 构建适当的授权头
 3. 通过 `build_oauth_tool_interceptor()` 用 OAuth 拦截器包装工具调用
diff --git a/frontend/src/content/zh/harness/memory.mdx b/frontend/src/content/zh/harness/memory.mdx
index c9d4fc6a9..71de258ad 100644
--- a/frontend/src/content/zh/harness/memory.mdx
+++ b/frontend/src/content/zh/harness/memory.mdx
@@ -1,3 +1,8 @@
+---
+title: 记忆系统
+description: 记忆是 DeerFlow Harness 的一个运行时功能。它不是简单的对话日志，而是跨多个独立会话持久化、在未来对话中影响 Agent 行为的结构化事实和上下文摘要存储。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # 记忆系统
diff --git a/frontend/src/content/zh/harness/middlewares.mdx b/frontend/src/content/zh/harness/middlewares.mdx
index ed069e65b..94b3571c7 100644
--- a/frontend/src/content/zh/harness/middlewares.mdx
+++ b/frontend/src/content/zh/harness/middlewares.mdx
@@ -1,3 +1,8 @@
+---
+title: 中间件
+description: 每次 Lead Agent 调用 LLM 时，都会先后执行一条**中间件链**。中间件可以读取和修改 Agent 的状态、向系统提示注入内容、拦截工具调用，并对模型输出做出反应。
+---
+
 import { Callout } from "nextra/components";
 
 # 中间件
diff --git a/frontend/src/content/zh/harness/quick-start.mdx b/frontend/src/content/zh/harness/quick-start.mdx
index 346052bc6..bf335e392 100644
--- a/frontend/src/content/zh/harness/quick-start.mdx
+++ b/frontend/src/content/zh/harness/quick-start.mdx
@@ -1,12 +1,18 @@
+---
+title: 快速上手
+description: 学习如何使用 create_deerflow_agent 创建并运行 DeerFlow Agent，从模型初始化到流式响应。
+---
+
 import { Callout, Cards, Steps } from "nextra/components";
 
 # 快速上手
 
 <Callout type="info" emoji="🚀">
-  本指南介绍如何以编程方式使用 DeerFlow Harness——不是通过应用界面，而是直接在 Python 中导入和调用 Harness。
+  本指南介绍如何在 Python 中通过 <code>create_deerflow_agent</code>
+  创建并运行一个 DeerFlow Agent。
 </Callout>
 
-DeerFlow Harness 是 Python SDK 和运行时基础。本快速上手指南将带你了解运行 Agent、流式传输输出和使用线程的核心 API。
+理解 DeerFlow Harness 的最快方式，是直接在代码里创建一个 Agent。本快速上手指南将带你完成模型初始化、Agent 创建，以及响应流式输出。
 
 ## 前置条件
 
@@ -19,130 +25,86 @@ cd backend
 uv sync
 ```
 
-## 配置
+你还需要准备一个来自对应 LangChain Provider 包的聊天模型实例。
 
-所有 Harness 行为由 `config.yaml` 驱动。至少需要配置一个模型：
-
-```yaml
-# config.yaml
-config_version: 6
-
-models:
-  - name: gpt-4o
-    use: langchain_openai:ChatOpenAI
-    model: gpt-4o
-    api_key: $OPENAI_API_KEY
-    request_timeout: 600.0
-    max_retries: 2
-
-sandbox:
-  use: deerflow.sandbox.local:LocalSandboxProvider
-
-tools:
-  - use: deerflow.community.ddg_search.tools:web_search_tool
-  - use: deerflow.community.jina_ai.tools:web_fetch_tool
-  - use: deerflow.sandbox.tools:ls_tool
-  - use: deerflow.sandbox.tools:read_file_tool
-  - use: deerflow.sandbox.tools:write_file_tool
-  - use: deerflow.sandbox.tools:bash_tool
-```
-
-将 `config.example.yaml` 复制到 `config.yaml` 并填写你的 API Key。
-
-## 运行 Harness
-
-DeerFlow Harness 的主要入口是 `DeerFlowClient`。它管理线程状态、调用 Lead Agent，并流式传输响应。
+## 创建第一个 Agent
 
 <Steps>
 
-### 导入并配置
+### 导入工厂函数与模型类
 
 ```python
-import asyncio
-from deerflow.client import DeerFlowClient
-from deerflow.config import load_config
-
-# 从当前目录或 DEER_FLOW_CONFIG_PATH 加载 config.yaml
-load_config()
-
-client = DeerFlowClient()
+from deerflow.agents import create_deerflow_agent
+from langchain_openai import ChatOpenAI
 ```
 
-### 创建线程
+### 创建模型
 
 ```python
-thread_id = "my-thread-001"
+model = ChatOpenAI(
+    model="gpt-4o",
+    api_key="YOUR_OPENAI_API_KEY",
+)
 ```
 
-线程 ID 是任意字符串。使用相同 ID 可以继续已有对话（需要配置检查点）。
-
-### 发送消息并流式传输响应
+### 创建 Agent
 
 ```python
-async def run():
-    async for event in client.astream(
-        thread_id=thread_id,
-        message="研究前三大开源 LLM 框架并进行总结。",
-        config={
-            "configurable": {
-                "model_name": "gpt-4o",
-                "thinking_enabled": False,
-                "is_plan_mode": True,
-                "subagent_enabled": True,
-            }
-        },
-    ):
-        print(event)
+agent = create_deerflow_agent(model)
+```
 
-asyncio.run(run())
+这会返回一个已经编译好的 LangGraph Agent，并带有 DeerFlow 默认的中间件链。
+
+### 流式获取响应
+
+```python
+for event in agent.stream(
+    {"messages": [{"role": "user", "content": "解释一下 DeerFlow Harness 是什么。"}]},
+    stream_mode=["messages", "values"],
+):
+    print(event)
 ```
 
 </Steps>
 
-## 可配置选项
+## 添加工具或行为
 
-`config.configurable` 字典控制每次请求的行为：
-
-| 键 | 类型 | 默认值 | 说明 |
-|---|---|---|---|
-| `model_name` | `str \| None` | 配置中第一个模型 | 本次请求使用的模型 |
-| `thinking_enabled` | `bool` | `True` | 启用扩展思考模式（如果支持） |
-| `reasoning_effort` | `str \| None` | `None` | 推理努力程度（特定模型参数） |
-| `is_plan_mode` | `bool` | `False` | 启用 TodoList 中间件进行任务跟踪 |
-| `subagent_enabled` | `bool` | `False` | 允许 Agent 委派子任务 |
-| `max_concurrent_subagents` | `int` | `3` | 每轮最大并行子 Agent 调用数 |
-| `agent_name` | `str \| None` | `None` | 要加载的自定义 Agent 名称 |
-
-## 流式事件类型
-
-`client.astream()` 从 LangGraph 运行时产生事件，主要事件类型如下：
-
-| 事件类型 | 说明 |
-|---|---|
-| `messages` | 消息块（文本、思考过程、工具调用） |
-| `thread_state` | 线程状态更新（标题、产出物、待办列表） |
-
-消息块包含 Agent 生成响应时的 token 流。
-
-## 使用自定义 Agent
-
-如果已定义自定义 Agent，在 configurable 中传入其 `name`：
+你可以通过传入工具、系统提示词、运行时特性、中间件或 checkpointer 来自定义 Agent。
 
 ```python
-async for event in client.astream(
-    thread_id="thread-002",
-    message="分析上传的 CSV 并生成摘要图表。",
-    config={
-        "configurable": {
-            "agent_name": "data-analyst",
-            "subagent_enabled": True,
-        }
-    },
-):
-    ...
+from deerflow.agents import RuntimeFeatures, create_deerflow_agent
+
+agent = create_deerflow_agent(
+    model,
+    system_prompt="你是一个简洁的研究助手。",
+    features=RuntimeFeatures(subagent=True, memory=False),
+    plan_mode=True,
+    name="research-agent",
+)
 ```
 
-自定义 Agent 的配置（模型、技能、工具组）将从 `agents/data-analyst/config.yaml` 自动加载。
+常用参数：
+
+| 参数 | 说明 |
+|---|---|
+| `tools` | 提供给 Agent 的额外工具 |
+| `system_prompt` | 自定义系统提示词 |
+| `features` | 启用或替换内置运行时能力 |
+| `extra_middleware` | 将自定义中间件插入默认链路 |
+| `plan_mode` | 启用 Todo 风格的任务跟踪 |
+| `checkpointer` | 为多轮运行持久化状态 |
+| `name` | Agent 的逻辑名称 |
+
+## 什么时候使用 DeerFlowClient
+
+如果你想直接操作底层的编译后 Agent 图，使用 `create_deerflow_agent()`。
+
+如果你想使用更高层的嵌入式应用接口，则应使用 `DeerFlowClient`，例如：
+
+- 面向线程的对话封装，
+- 模型 / 技能 / 记忆管理 API，
+- 文件上传与 artifacts，
+- 与 Gateway 一致的返回格式。
 
 <Cards num={3}>
   <Cards.Card title="设计理念" href="/docs/harness/design-principles" />
diff --git a/frontend/src/content/zh/harness/sandbox.mdx b/frontend/src/content/zh/harness/sandbox.mdx
index bfe578d86..16a05f9e7 100644
--- a/frontend/src/content/zh/harness/sandbox.mdx
+++ b/frontend/src/content/zh/harness/sandbox.mdx
@@ -1,3 +1,8 @@
+---
+title: 沙箱
+description: 沙箱为 Lead Agent 提供一个受控环境，在其中可以读取文件、写入输出、运行 Shell 命令并生成产出物。没有沙箱，Agent 只能生成文本；有了沙箱，它可以编写和执行代码、处理数据文件、生成图表并构建交付物。
+---
+
 import { Callout, Cards, Tabs } from "nextra/components";
 
 # 沙箱
diff --git a/frontend/src/content/zh/harness/skills.mdx b/frontend/src/content/zh/harness/skills.mdx
index 0b4aa93dd..f0f0aa659 100644
--- a/frontend/src/content/zh/harness/skills.mdx
+++ b/frontend/src/content/zh/harness/skills.mdx
@@ -1,3 +1,8 @@
+---
+title: 技能
+description: 技能不仅仅是提示词。它是一个自包含的能力包，可以包含结构化指令、分步工作流、领域最佳实践、支撑资源和工具配置。技能按需加载——在任务需要时注入内容，否则不影响上下文。
+---
+
 import { Callout, Cards, FileTree, Steps } from "nextra/components";
 
 # 技能
diff --git a/frontend/src/content/zh/harness/subagents.mdx b/frontend/src/content/zh/harness/subagents.mdx
index a199c9268..929dfccd4 100644
--- a/frontend/src/content/zh/harness/subagents.mdx
+++ b/frontend/src/content/zh/harness/subagents.mdx
@@ -1,3 +1,8 @@
+---
+title: 子 Agent
+description: 当一个任务对单个推理线程来说太宽泛，或者部分任务可以并行完成时，Lead Agent 将工作委派给**子 Agent**。子 Agent 是一个独立的 Agent 调用，接收特定任务、执行并返回结果。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # 子 Agent
diff --git a/frontend/src/content/zh/harness/tools.mdx b/frontend/src/content/zh/harness/tools.mdx
index 5be461c5a..b23d25f87 100644
--- a/frontend/src/content/zh/harness/tools.mdx
+++ b/frontend/src/content/zh/harness/tools.mdx
@@ -1,3 +1,8 @@
+---
+title: 工具
+description: Lead Agent 是一个工具调用 Agent。工具是它与世界交互的方式：搜索网络、读写文件、运行命令、委派任务以及向用户呈现输出。
+---
+
 import { Callout, Cards, Tabs } from "nextra/components";
 
 # 工具
diff --git a/frontend/src/content/zh/introduction/core-concepts.mdx b/frontend/src/content/zh/introduction/core-concepts.mdx
index b4ac63ac8..fd85ab875 100644
--- a/frontend/src/content/zh/introduction/core-concepts.mdx
+++ b/frontend/src/content/zh/introduction/core-concepts.mdx
@@ -1,3 +1,8 @@
+---
+title: 核心概念
+description: 在深入了解 DeerFlow 之前，先建立一些贯穿整个系统的核心概念。这些概念解释了 DeerFlow 的优化目标以及其架构设计的原因。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # 核心概念
diff --git a/frontend/src/content/zh/introduction/harness-vs-app.mdx b/frontend/src/content/zh/introduction/harness-vs-app.mdx
index 5ecd92f00..7333b6ef7 100644
--- a/frontend/src/content/zh/introduction/harness-vs-app.mdx
+++ b/frontend/src/content/zh/introduction/harness-vs-app.mdx
@@ -1,3 +1,8 @@
+---
+title: Harness 与应用
+description: DeerFlow 有两个紧密相关但服务于不同目的的层次：.
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # Harness 与应用
diff --git a/frontend/src/content/zh/introduction/why-deerflow.mdx b/frontend/src/content/zh/introduction/why-deerflow.mdx
index 775c0ff19..dd59fc2d5 100644
--- a/frontend/src/content/zh/introduction/why-deerflow.mdx
+++ b/frontend/src/content/zh/introduction/why-deerflow.mdx
@@ -1,3 +1,8 @@
+---
+title: 为什么选择 DeerFlow
+description: DeerFlow 的诞生是因为现代 Agent 系统需要的不仅仅是一个聊天循环。一个真正有用的 Agent 必须能够进行长时序规划、将任务拆解为子任务、使用工具、操作文件、安全地运行代码，并在复杂任务中保持足够的上下文连贯性。DeerFlow 正是为提供这样的运行时基础而构建的。
+---
+
 import { Callout, Cards } from "nextra/components";
 
 # 为什么选择 DeerFlow
diff --git a/frontend/src/content/zh/reference/_meta.ts b/frontend/src/content/zh/reference/_meta.ts
index 984f12015..5001ebfd8 100644
--- a/frontend/src/content/zh/reference/_meta.ts
+++ b/frontend/src/content/zh/reference/_meta.ts
@@ -1,20 +1,8 @@
 import type { MetaRecord } from "nextra";
 
 const meta: MetaRecord = {
-  "concepts-glossary": {
-    title: "概念词汇表",
-  },
-  "configuration-reference": {
-    title: "配置参考",
-  },
-  "api-gateway-reference": {
-    title: "API / Gateway 参考",
-  },
-  "runtime-flags-and-modes": {
-    title: "运行时标志与模式",
-  },
-  "source-map": {
-    title: "代码映射",
+  "model-providers": {
+    title: "模型接入",
   },
 };
 
diff --git a/frontend/src/content/zh/reference/api-gateway-reference.mdx b/frontend/src/content/zh/reference/api-gateway-reference.mdx
deleted file mode 100644
index 8d819b1d8..000000000
--- a/frontend/src/content/zh/reference/api-gateway-reference.mdx
+++ /dev/null
@@ -1,68 +0,0 @@
-import { Callout } from "nextra/components";
-
-# API / Gateway 参考
-
-<Callout type="info">
-  DeerFlow Gateway 是基于 FastAPI 构建的，提供交互式 API 文档，可通过 <code>http://localhost:8001/docs</code> 访问。
-</Callout>
-
-## 基础 URL
-
-```
-http://localhost:8001
-```
-
-通过 nginx 代理：
-
-```
-http://localhost:2026/api
-```
-
-## 核心端点
-
-### 系统
-
-| 方法 | 路径 | 描述 |
-|---|---|---|
-| `GET` | `/health` | 服务健康检查 |
-| `GET` | `/api/models` | 获取已配置的模型列表 |
-
-### Agent 管理
-
-| 方法 | 路径 | 描述 |
-|---|---|---|
-| `GET` | `/api/agents` | 列出所有 Agent |
-| `POST` | `/api/agents` | 创建自定义 Agent |
-| `GET` | `/api/agents/{name}` | 获取 Agent 配置 |
-| `PUT` | `/api/agents/{name}` | 更新 Agent 配置 |
-| `DELETE` | `/api/agents/{name}` | 删除 Agent |
-| `POST` | `/api/agents/check` | 检查/建议 Agent slug 唯一性 |
-
-### 线程和记忆
-
-| 方法 | 路径 | 描述 |
-|---|---|---|
-| `GET` | `/api/threads` | 列出线程 |
-| `DELETE` | `/api/threads/{thread_id}` | 删除线程 |
-| `GET` | `/api/memory` | 获取全局记忆 |
-| `GET` | `/api/memory/{agent_name}` | 获取 Agent 特定记忆 |
-| `DELETE` | `/api/memory` | 清除全局记忆 |
-
-### 扩展
-
-| 方法 | 路径 | 描述 |
-|---|---|---|
-| `GET` | `/api/extensions` | 列出所有扩展（MCP 服务器和技能） |
-| `POST` | `/api/extensions/mcp/{name}/enable` | 启用 MCP 服务器 |
-| `POST` | `/api/extensions/mcp/{name}/disable` | 禁用 MCP 服务器 |
-| `POST` | `/api/extensions/skills/{name}/enable` | 启用技能 |
-| `POST` | `/api/extensions/skills/{name}/disable` | 禁用技能 |
-
-### 文件上传
-
-| 方法 | 路径 | 描述 |
-|---|---|---|
-| `POST` | `/api/uploads/{thread_id}` | 上传文件到线程工作区 |
-| `GET` | `/api/uploads/{thread_id}/{filename}` | 获取上传的文件 |
-
-完整的交互式 API 文档请访问 `http://localhost:8001/docs`（Swagger UI）。
diff --git a/frontend/src/content/zh/reference/concepts-glossary.mdx b/frontend/src/content/zh/reference/concepts-glossary.mdx
deleted file mode 100644
index e39c0c3b1..000000000
--- a/frontend/src/content/zh/reference/concepts-glossary.mdx
+++ /dev/null
@@ -1,67 +0,0 @@
-import { Callout } from "nextra/components";
-
-# 概念词汇表
-
-本词汇表定义了 DeerFlow 文档中使用的核心术语。
-
----
-
-## Agent
-
-在 DeerFlow 中，Agent 是接收用户消息、决定采取什么行动（工具调用或直接响应），并生成输出的主要处理单元。DeerFlow 使用 **Lead Agent** 和**子 Agent** 两级架构。
-
-## Artifact（产出物）
-
-Agent 生成的文件——报告、图表、代码或其他交付物。产出物通过 `present_files` 工具暴露，并持久化存储在线程的用户数据目录中。
-
-## Checkpoint（检查点）
-
-线程状态的持久化快照，在每次 Agent 轮次后保存。检查点允许服务器重启后恢复对话，并支持长时序任务的状态管理。
-
-## Context Engineering（上下文工程）
-
-通过控制 Agent 在每个步骤可见的内容（通过摘要压缩、子 Agent 上下文隔离和外部文件记忆）来保持 Agent 在长时序任务中有效的实践。
-
-## Harness
-
-带有主张的 Agent 运行时，打包了工具访问、技能加载、沙箱执行、记忆、子 Agent 协调和上下文管理——而不仅仅是暴露抽象接口。
-
-## Lead Agent
-
-每个 DeerFlow 线程中的主要执行者，负责规划、工具调用和响应生成。基于 LangGraph + LangChain Agent 构建，由中间件链增强。
-
-## Long-horizon Agent（长时序 Agent）
-
-在一系列动作中保持有效的 Agent——进行规划、多次调用工具、管理中间文件，并生成最终产出物——而不是只产生单一答案。
-
-## Memory（记忆）
-
-跨多个独立对话会话持久化的结构化事实和用户上下文存储，在后续会话中注入到 Agent 的系统提示中。
-
-## Middleware（中间件）
-
-包裹每次 LLM 调用的插件，可以在模型调用前后读取和修改 Agent 状态。DeerFlow 使用中间件实现记忆、摘要压缩、标题生成等跨领域行为。
-
-## MCP（Model Context Protocol）
-
-连接语言模型与外部工具和数据源的开放标准。DeerFlow 的 MCP 集成允许连接任何兼容的工具服务器。
-
-## Sandbox（沙箱）
-
-Agent 进行文件和命令操作的隔离执行环境。DeerFlow 支持本地（`LocalSandboxProvider`）和基于容器（`AioSandboxProvider`）两种沙箱模式。
-
-## Skill（技能）
-
-面向任务的能力包，包含结构化指令、工作流程和最佳实践，按需加载到 Agent 上下文中。技能提供专业化而不污染通用 Agent 上下文。
-
-## Subagent（子 Agent）
-
-接受委派子任务的专注执行者，以隔离上下文运行，仅接收完成其分配任务所需的信息。
-
-## Thread（线程）
-
-对话及其所有相关状态——消息历史、产出物、待办列表和检查点数据——的完整封装。
-
-## ThreadState
-
-DeerFlow 中 LangGraph 管理的状态对象，包含 `messages`、`artifacts`、`todo_list` 和运行时元数据。
diff --git a/frontend/src/content/zh/reference/configuration-reference.mdx b/frontend/src/content/zh/reference/configuration-reference.mdx
deleted file mode 100644
index 0fb2acb23..000000000
--- a/frontend/src/content/zh/reference/configuration-reference.mdx
+++ /dev/null
@@ -1,122 +0,0 @@
-import { Callout } from "nextra/components";
-
-# 配置参考
-
-本页面提供 `config.yaml` 中所有顶层字段的完整参考。
-
-<Callout type="info">
-  查看仓库根目录中的 <code>config.example.yaml</code> 获取带注释的完整配置示例。
-</Callout>
-
-## 顶层字段
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `config_version` | `int` | 配置 schema 版本（当前：6） |
-| `log_level` | `str` | 日志级别：`debug`/`info`/`warning`/`error` |
-| `models` | `list` | 可用的 LLM 模型配置 |
-| `image_generate_model` | `str \| list` | 图像生成使用的模型名称 |
-| `token_usage` | `object` | Token 使用追踪配置 |
-| `tools` | `list` | 可用工具配置 |
-| `tool_groups` | `list` | 工具的命名分组 |
-| `tool_search` | `object` | 延迟工具加载配置 |
-| `sandbox` | `object` | 沙箱提供者配置 |
-| `skills` | `object` | 技能目录和容器路径 |
-| `skill_evolution` | `object` | Agent 管理的技能创建 |
-| `subagents` | `object` | 子 Agent 超时和最大轮次 |
-| `acp_agents` | `dict` | 外部 ACP Agent 配置 |
-| `memory` | `object` | 跨会话记忆存储 |
-| `summarization` | `object` | 对话摘要压缩 |
-| `title` | `object` | 自动线程标题生成 |
-| `checkpointer` | `object` | 线程状态持久化 |
-| `guardrails` | `object` | 工具调用授权 |
-| `uploads` | `object` | 文件上传配置 |
-| `channels` | `list` | IM 频道集成 |
-
-## models
-
-```yaml
-models:
-  - name: gpt-4o                    # 模型标识符（在请求中引用）
-    use: langchain_openai:ChatOpenAI # Python 类路径
-    model: gpt-4o                   # 传给 LLM 的模型名称
-    api_key: $OPENAI_API_KEY        # API 密钥（支持环境变量）
-    base_url: null                  # 可选：自定义端点
-    request_timeout: 600.0         # 请求超时（秒）
-    max_retries: 2                  # 重试次数
-    supports_vision: true           # 是否启用视觉功能
-    thinking_enabled: false         # 是否启用扩展思考
-    # 任何其他字段都会传递给模型构造函数
-```
-
-## sandbox
-
-```yaml
-sandbox:
-  # 本地（默认，无容器隔离）
-  use: deerflow.sandbox.local:LocalSandboxProvider
-  allow_host_bash: false
-  bash_output_max_chars: 20000
-  read_file_output_max_chars: 50000
-  ls_output_max_chars: 20000
-
-  # 基于容器
-  # use: deerflow.community.aio_sandbox:AioSandboxProvider
-  # image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
-  # replicas: 3
-  # idle_timeout: 600
-```
-
-## memory
-
-```yaml
-memory:
-  enabled: true
-  storage_path: memory.json
-  debounce_seconds: 30
-  max_facts: 100
-  fact_confidence_threshold: 0.7
-  injection_enabled: true
-  max_injection_tokens: 2000
-  model_name: null
-```
-
-## summarization
-
-```yaml
-summarization:
-  enabled: true
-  model_name: null
-  trigger:
-    - type: tokens
-      value: 15564
-  keep:
-    type: messages
-    value: 10
-  trim_tokens_to_summarize: 15564
-  summary_prompt: null
-```
-
-## checkpointer
-
-```yaml
-checkpointer:
-  type: sqlite                    # sqlite | redis | postgres
-  connection_string: .deer-flow/checkpoints.db
-```
-
-## subagents
-
-```yaml
-subagents:
-  timeout_seconds: 900
-  agents:
-    general-purpose:
-      timeout_seconds: 1800
-      max_turns: 160
-    bash:
-      timeout_seconds: 300
-      max_turns: 80
-```
-
-参见各功能的文档页面了解所有字段的详细说明。
diff --git a/frontend/src/content/zh/reference/model-providers/_meta.ts b/frontend/src/content/zh/reference/model-providers/_meta.ts
new file mode 100644
index 000000000..81fd1b56f
--- /dev/null
+++ b/frontend/src/content/zh/reference/model-providers/_meta.ts
@@ -0,0 +1,9 @@
+import type { MetaRecord } from "nextra";
+
+const meta: MetaRecord = {
+  ark: {
+    title: "火山方舟",
+  },
+};
+
+export default meta;
diff --git a/frontend/src/content/zh/reference/model-providers/ark.mdx b/frontend/src/content/zh/reference/model-providers/ark.mdx
new file mode 100644
index 000000000..6f6e4ed12
--- /dev/null
+++ b/frontend/src/content/zh/reference/model-providers/ark.mdx
@@ -0,0 +1,8 @@
+---
+title: 火山方舟
+description: 火山方舟模型接入指南。
+---
+
+# 火山方舟
+
+## Coding Plan
diff --git a/frontend/src/content/zh/reference/model-providers/index.mdx b/frontend/src/content/zh/reference/model-providers/index.mdx
new file mode 100644
index 000000000..be8f9a450
--- /dev/null
+++ b/frontend/src/content/zh/reference/model-providers/index.mdx
@@ -0,0 +1,7 @@
+---
+title: 模型厂商服务接入
+description: 已支持模型厂商服务的接入参考文档。
+asIndexPage: true
+---
+
+# 更多模型厂商服务接入
diff --git a/frontend/src/content/zh/reference/runtime-flags-and-modes.mdx b/frontend/src/content/zh/reference/runtime-flags-and-modes.mdx
deleted file mode 100644
index e6eae11fe..000000000
--- a/frontend/src/content/zh/reference/runtime-flags-and-modes.mdx
+++ /dev/null
@@ -1,36 +0,0 @@
-# 运行时标志与模式
-
-本页面记录影响 DeerFlow Harness 和 Agent 运行时行为的运行时标志和模式。
-
-## 每次请求的可配置选项
-
-这些选项通过 `config.configurable` 字典传递（用于程序化使用）或在 Web UI 中选择（用于应用使用）：
-
-| 标志 | 类型 | 默认值 | 描述 |
-|---|---|---|---|
-| `model_name` | `str \| None` | 配置的第一个模型 | 请求使用的模型 |
-| `agent_name` | `str \| None` | `None` | 加载自定义 Agent 配置 |
-| `thinking_enabled` | `bool` | `True` | 启用扩展思考（模型必须支持） |
-| `reasoning_effort` | `str \| None` | `None` | 推理努力程度（模型特定） |
-| `is_plan_mode` | `bool` | `False` | 启用 TodoList 中间件 |
-| `subagent_enabled` | `bool` | `False` | 允许子 Agent 委派 |
-| `max_concurrent_subagents` | `int` | `3` | 最大并行子 Agent 调用数 |
-
-## 环境变量
-
-| 变量 | 默认值 | 描述 |
-|---|---|---|
-| `DEER_FLOW_CONFIG_PATH` | 自动发现 | `config.yaml` 的绝对路径 |
-| `LOG_LEVEL` | `info` | 日志级别覆盖 |
-| `DEER_FLOW_ROOT` | 仓库根目录 | Docker 挂载的基础路径 |
-| `BETTER_AUTH_SECRET` | — | 前端会话密钥（生产必须设置） |
-| `BETTER_AUTH_URL` | — | 公开 URL（用于回调和 CORS） |
-
-## 模型能力标志
-
-在 `config.yaml` 中的模型配置里设置：
-
-| 标志 | 类型 | 描述 |
-|---|---|---|
-| `supports_vision` | `bool` | 模型接受图像输入 |
-| `thinking_enabled` | `bool` | 模型支持扩展思考模式 |
diff --git a/frontend/src/content/zh/reference/source-map.mdx b/frontend/src/content/zh/reference/source-map.mdx
deleted file mode 100644
index 0d5711def..000000000
--- a/frontend/src/content/zh/reference/source-map.mdx
+++ /dev/null
@@ -1,88 +0,0 @@
-# 代码映射
-
-本页面将 DeerFlow 的核心概念映射到其在代码库中的实现位置，帮助你快速定位特定功能的代码。
-
-## 后端核心路径
-
-```
-backend/
-├── app/
-│   └── gateway/              # FastAPI Gateway API
-│       ├── routers/
-│       │   ├── agents.py     # 自定义 Agent CRUD
-│       │   ├── extensions.py # MCP/技能启用禁用
-│       │   ├── memory.py     # 记忆读取/清除
-│       │   ├── threads.py    # 线程管理
-│       │   └── uploads.py    # 文件上传
-│       └── main.py           # FastAPI 应用入口
-│
-└── packages/harness/deerflow/
-    ├── agents/
-    │   ├── lead_agent/
-    │   │   ├── agent.py      # make_lead_agent() 工厂
-    │   │   └── prompt.py     # 系统提示模板
-    │   ├── middlewares/      # 所有中间件实现
-    │   ├── memory/
-    │   │   ├── middleware.py # MemoryMiddleware
-    │   │   └── storage.py    # 记忆文件存储
-    │   └── thread_state.py   # ThreadState 数据类
-    │
-    ├── config/
-    │   ├── app_config.py     # AppConfig（顶层配置）
-    │   ├── model_config.py   # ModelConfig
-    │   ├── paths.py          # 路径解析工具
-    │   └── *.py              # 各模块配置类
-    │
-    ├── mcp/
-    │   ├── cache.py          # 基于 mtime 的工具缓存
-    │   └── oauth.py          # MCP OAuth 支持
-    │
-    ├── models/
-    │   └── factory.py        # create_chat_model() LLM 工厂
-    │
-    ├── sandbox/
-    │   ├── local/            # LocalSandboxProvider
-    │   └── sandbox.py        # Sandbox 基类
-    │
-    ├── skills/
-    │   ├── loader.py         # load_skills()（热重载）
-    │   ├── parser.py         # SKILL.md 解析
-    │   ├── installer.py      # 依赖安装
-    │   └── manager.py        # 技能生命周期
-    │
-    ├── subagents/
-    │   └── registry.py       # 子 Agent 查找与配置覆盖
-    │
-    └── tools/
-        └── builtins/         # 内置工具实现
-```
-
-## 前端核心路径
-
-```
-frontend/src/
-├── app/                      # Next.js 路由
-├── components/
-│   └── workspace/            # 工作区 UI 组件
-├── core/
-│   ├── agents/               # Agent 类型和 API 客户端
-│   ├── messages/             # 消息类型和工具调用处理
-│   └── threads/              # 线程状态管理
-└── content/                  # 文档内容（MDX）
-    ├── en/                   # 英文文档
-    └── zh/                   # 中文文档
-```
-
-## 关键文件快速索引
-
-| 目标 | 文件 |
-|---|---|
-| Lead Agent 创建 | `agents/lead_agent/agent.py` |
-| 系统提示模板 | `agents/lead_agent/prompt.py` |
-| 所有中间件 | `agents/middlewares/` |
-| 配置加载 | `config/app_config.py` |
-| 模型工厂 | `models/factory.py` |
-| 技能加载（热重载） | `skills/loader.py` |
-| MCP 工具缓存 | `mcp/cache.py` |
-| 文件上传处理 | `uploads/manager.py` |
-| Gateway 主路由器 | `app/gateway/main.py` |
diff --git a/frontend/src/content/zh/tutorials/create-your-first-harness.mdx b/frontend/src/content/zh/tutorials/create-your-first-harness.mdx
index 2ce6f6b27..622fd6553 100644
--- a/frontend/src/content/zh/tutorials/create-your-first-harness.mdx
+++ b/frontend/src/content/zh/tutorials/create-your-first-harness.mdx
@@ -1,3 +1,8 @@
+---
+title: 创建你的第一个 Harness
+description: 本教程介绍如何以编程方式使用 DeerFlow Harness Python SDK——直接在你的 Python 代码中导入和使用 DeerFlow，而不是通过 Web 界面。
+---
+
 # 创建你的第一个 Harness
 
 本教程介绍如何以编程方式使用 DeerFlow Harness Python SDK——直接在你的 Python 代码中导入和使用 DeerFlow，而不是通过 Web 界面。
diff --git a/frontend/src/content/zh/tutorials/deploy-your-own-deerflow.mdx b/frontend/src/content/zh/tutorials/deploy-your-own-deerflow.mdx
index b8b26741e..897be67ca 100644
--- a/frontend/src/content/zh/tutorials/deploy-your-own-deerflow.mdx
+++ b/frontend/src/content/zh/tutorials/deploy-your-own-deerflow.mdx
@@ -1,3 +1,8 @@
+---
+title: 部署你的 DeerFlow
+description: 本教程引导你将 DeerFlow 部署到生产环境，使用 Docker Compose 进行多用户访问。
+---
+
 # 部署你的 DeerFlow
 
 本教程引导你将 DeerFlow 部署到生产环境，使用 Docker Compose 进行多用户访问。
diff --git a/frontend/src/content/zh/tutorials/first-conversation.mdx b/frontend/src/content/zh/tutorials/first-conversation.mdx
index 95524ef11..1e1a9d387 100644
--- a/frontend/src/content/zh/tutorials/first-conversation.mdx
+++ b/frontend/src/content/zh/tutorials/first-conversation.mdx
@@ -1,3 +1,8 @@
+---
+title: 第一次对话
+description: 本教程引导你在 DeerFlow 中完成第一次完整的 Agent 对话，从启动应用到与 Agent 进行实质性任务交互。
+---
+
 # 第一次对话
 
 本教程引导你在 DeerFlow 中完成第一次完整的 Agent 对话，从启动应用到与 Agent 进行实质性任务交互。
diff --git a/frontend/src/content/zh/tutorials/use-tools-and-skills.mdx b/frontend/src/content/zh/tutorials/use-tools-and-skills.mdx
index 1f89dad0d..eedc95308 100644
--- a/frontend/src/content/zh/tutorials/use-tools-and-skills.mdx
+++ b/frontend/src/content/zh/tutorials/use-tools-and-skills.mdx
@@ -1,3 +1,8 @@
+---
+title: 使用工具和技能
+description: 本教程介绍如何在 DeerFlow 中配置和使用工具（Tools）与技能（Skills），让 Agent 能够访问搜索、文件操作和特定领域能力。
+---
+
 # 使用工具和技能
 
 本教程介绍如何在 DeerFlow 中配置和使用工具（Tools）与技能（Skills），让 Agent 能够访问搜索、文件操作和特定领域能力。
diff --git a/frontend/src/content/zh/tutorials/work-with-memory.mdx b/frontend/src/content/zh/tutorials/work-with-memory.mdx
index 8e2e80a32..64ae09640 100644
--- a/frontend/src/content/zh/tutorials/work-with-memory.mdx
+++ b/frontend/src/content/zh/tutorials/work-with-memory.mdx
@@ -1,3 +1,8 @@
+---
+title: 使用记忆系统
+description: 本教程介绍如何在 DeerFlow 中启用和使用记忆系统，让 Agent 在多次会话中记住关于你的重要信息。
+---
+
 # 使用记忆系统
 
 本教程介绍如何在 DeerFlow 中启用和使用记忆系统，让 Agent 在多次会话中记住关于你的重要信息。