Add documents site (#1767)

* feat: add docs site

- Implemented dynamic routing for MDX documentation pages with language support.
- Created layout components for documentation with a header and footer.
- Added metadata for various documentation sections in English and Chinese.
- Developed initial content for the DeerFlow App and Harness documentation.
- Introduced i18n hooks and translations for English and Chinese languages.
- Enhanced header component to include navigation links for documentation and blog.
- Established a structure for tutorials and reference materials.
- Created a new translations file to manage locale-specific strings.

* feat: enhance documentation structure and content for application and harness sections

* feat: update .gitignore to include .playwright-mcp and remove obsolete Playwright YAML file

* fix(docs): correct punctuation and formatting in documentation files

* feat(docs): remove outdated index.mdx file from documentation

* fix(docs): update documentation links and improve Chinese description in index.mdx

* fix(docs): update title in Chinese for meta information in _meta.ts

.gitignore

@@ -54,3 +54,4 @@ web/
 # Deployment artifacts
 backend/Dockerfile.langgraph
 config.yaml.bak
+.playwright-mcp

docker/nginx/nginx.local.conf

@@ -179,8 +179,8 @@ http {
         }
 
         # API Documentation: Swagger UI
-        location /docs {
-            proxy_pass http://gateway;
+        location /api/docs {
+            proxy_pass http://gateway/docs  ;
             proxy_http_version 1.1;
             proxy_set_header Host $host;
             proxy_set_header X-Real-IP $remote_addr;
@@ -189,8 +189,8 @@ http {
         }
 
         # API Documentation: ReDoc
-        location /redoc {
-            proxy_pass http://gateway;
+        location /api/redoc {
+            proxy_pass http://gateway/redoc;
             proxy_http_version 1.1;
             proxy_set_header Host $host;
             proxy_set_header X-Real-IP $remote_addr;

frontend/next.config.js

@@ -10,9 +10,16 @@ function getInternalServiceURL(envKey, fallbackURL) {
     ? configured.replace(/\/+$/, "")
     : fallbackURL;
 }
+import nextra from "nextra";
+
+const withNextra = nextra({});
 
 /** @type {import("next").NextConfig} */
 const config = {
+  i18n: {
+    locales: ["en", "zh"],
+    defaultLocale: "en",
+  },
   devIndicators: false,
   async rewrites() {
     const rewrites = [];
@@ -51,4 +58,4 @@ const config = {
   },
 };
 
-export default config;
+export default withNextra(config);

frontend/package.json

@@ -69,6 +69,8 @@
     "nanoid": "^5.1.6",
     "next": "^16.1.7",
     "next-themes": "^0.4.6",
+    "nextra": "^4.6.1",
+    "nextra-theme-docs": "^4.6.1",
     "nuxt-og-image": "^5.1.13",
     "ogl": "^1.0.11",
     "react": "^19.0.0",

frontend/src/app/[lang]/docs/[[...mdxPath]]/page.tsx

@@ -0,0 +1,29 @@
+import { generateStaticParamsFor, importPage } from "nextra/pages";
+
+import { useMDXComponents as getMDXComponents } from "../../../../mdx-components";
+
+export const generateStaticParams = generateStaticParamsFor("mdxPath");
+
+export async function generateMetadata(props) {
+  const params = await props.params;
+  const { metadata } = await importPage(params.mdxPath, params.lang);
+  return metadata;
+}
+
+// eslint-disable-next-line @typescript-eslint/unbound-method
+const Wrapper = getMDXComponents().wrapper;
+
+export default async function Page(props) {
+  const params = await props.params;
+  const {
+    default: MDXContent,
+    toc,
+    metadata,
+    sourceCode,
+  } = await importPage(params.mdxPath, params.lang);
+  return (
+    <Wrapper toc={toc} metadata={metadata} sourceCode={sourceCode}>
+      <MDXContent {...props} params={params} />
+    </Wrapper>
+  );
+}

frontend/src/app/[lang]/docs/layout.tsx

@@ -0,0 +1,51 @@
+import type { PageMapItem } from "nextra";
+import { getPageMap } from "nextra/page-map";
+import { Footer, Layout } from "nextra-theme-docs";
+
+import { Header } from "@/components/landing/header";
+import { getLocaleByLang } from "@/core/i18n/locale";
+import "nextra-theme-docs/style.css";
+
+const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>;
+
+const i18n = [
+  { locale: "en", name: "English" },
+  { locale: "zh", name: "中文" },
+];
+
+function formatPageRoute(base: string, items: PageMapItem[]): PageMapItem[] {
+  return items.map((item) => {
+    if ("route" in item) {
+      item.route = `${base}${item.route}`;
+    }
+    if ("children" in item && item.children) {
+      item.children = formatPageRoute(base, item.children);
+    }
+    return item;
+  });
+}
+
+export default async function DocLayout({ children, params }) {
+  const { lang } = await params;
+  const locale = getLocaleByLang(lang);
+  const pages = await getPageMap(`/${lang}`);
+
+  return (
+    <Layout
+      navbar={
+        <Header
+          className="relative max-w-full px-10"
+          homeURL="/"
+          locale={locale}
+        />
+      }
+      pageMap={formatPageRoute(`/${lang}/docs`, pages)}
+      docsRepositoryBase="https://github.com/bytedance/deerflow/tree/main/frontend/src/app/content"
+      footer={footer}
+      i18n={i18n}
+      // ... Your additional layout options
+    >
+      {children}
+    </Layout>
+  );
+}

frontend/src/components/landing/header.tsx

@@ -1,21 +1,54 @@
 import { StarFilledIcon, GitHubLogoIcon } from "@radix-ui/react-icons";
+import Link from "next/link";
 
 import { Button } from "@/components/ui/button";
 import { NumberTicker } from "@/components/ui/number-ticker";
+import type { Locale } from "@/core/i18n/locale";
+import { getI18n } from "@/core/i18n/server";
 import { env } from "@/env";
+import { cn } from "@/lib/utils";
 
-export function Header() {
+export type HeaderProps = {
+  className?: string;
+  homeURL?: string;
+  locale?: Locale;
+};
+
+export async function Header({ className, homeURL, locale }: HeaderProps) {
+  const isExternalHome = !homeURL;
+  const { locale: resolvedLocale, t } = await getI18n(locale);
+  const lang = resolvedLocale.substring(0, 2);
   return (
-    <header className="container-md fixed top-0 right-0 left-0 z-20 mx-auto flex h-16 items-center justify-between backdrop-blur-xs">
-      <div className="flex items-center gap-2">
+    <header
+      className={cn(
+        "container-md fixed top-0 right-0 left-0 z-20 mx-auto flex h-16 items-center justify-between backdrop-blur-xs",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-6">
         <a
-          href="https://github.com/bytedance/deer-flow"
-          target="_blank"
-          rel="noopener noreferrer"
+          href={homeURL ?? "https://github.com/bytedance/deer-flow"}
+          target={isExternalHome ? "_blank" : "_self"}
+          rel={isExternalHome ? "noopener noreferrer" : undefined}
         >
           <h1 className="font-serif text-xl">DeerFlow</h1>
         </a>
       </div>
+      <nav className="mr-8 ml-auto flex items-center gap-8 text-sm font-medium">
+        <Link
+          href={`/${lang}/docs`}
+          className="text-secondary-foreground hover:text-foreground transition-colors"
+        >
+          {t.home.docs}
+        </Link>
+        <a
+          href={`/${lang}/blog`}
+          target="_self"
+          className="text-secondary-foreground hover:text-foreground transition-colors"
+        >
+          {t.home.blog}
+        </a>
+      </nav>
       <div className="relative">
         <div
           className="pointer-events-none absolute inset-0 z-0 h-full w-full rounded-full opacity-30 blur-2xl"

frontend/src/content/en/_meta.ts

@@ -0,0 +1,27 @@
+import type { MetaRecord } from "nextra";
+
+const meta: MetaRecord = {
+  index: {
+    title: "Overview",
+  },
+  introduction: {
+    title: "Introduction",
+  },
+  harness: {
+    title: "DeerFlow Harness",
+  },
+  application: {
+    title: "DeerFlow App",
+  },
+  tutorials: {
+    title: "Tutorials",
+  },
+  reference: {
+    title: "Reference",
+  },
+  workspace: {
+    type: "page",
+  },
+};
+
+export default meta;

frontend/src/content/en/application/_meta.ts

@@ -0,0 +1,27 @@
+import type { MetaRecord } from "nextra";
+
+const meta: MetaRecord = {
+  index: {
+    title: "Overview",
+  },
+  "quick-start": {
+    title: "Quick Start",
+  },
+  "deployment-guide": {
+    title: "Deployment Guide",
+  },
+  configuration: {
+    title: "Configuration",
+  },
+  "workspace-usage": {
+    title: "Workspace Usage",
+  },
+  "agents-and-threads": {
+    title: "Agents and Threads",
+  },
+  "operations-and-troubleshooting": {
+    title: "Operations and Troubleshooting",
+  },
+};
+
+export default meta;

frontend/src/content/en/application/agents-and-threads.mdx

@@ -0,0 +1,3 @@
+# Agents and Threads
+
+TBD

frontend/src/content/en/application/configuration.mdx

@@ -0,0 +1,3 @@
+# Configuration
+
+TBD

frontend/src/content/en/application/deployment-guide.mdx

@@ -0,0 +1,3 @@
+# Deployment Guide
+
+TBD

frontend/src/content/en/application/index.mdx

@@ -0,0 +1,3 @@
+# DeerFlow App
+
+TBD

frontend/src/content/en/application/operations-and-troubleshooting.mdx

@@ -0,0 +1,3 @@
+# Operations and Troubleshooting
+
+TBD

frontend/src/content/en/application/quick-start.mdx

@@ -0,0 +1,3 @@
+# Quick Start
+
+TBD

frontend/src/content/en/application/workspace-usage.mdx

@@ -0,0 +1,3 @@
+# Workspace Usage
+
+TBD

frontend/src/content/en/harness/_meta.ts

@@ -0,0 +1,36 @@
+import type { MetaRecord } from "nextra";
+
+const meta: MetaRecord = {
+  index: {
+    title: "Install",
+  },
+  "quick-start": {
+    title: "Quick Start",
+  },
+  "design-principles": {
+    title: "Design Principles",
+  },
+  configuration: {
+    title: "Configuration",
+  },
+  memory: {
+    title: "Memory",
+  },
+  tools: {
+    title: "Tools",
+  },
+  skills: {
+    title: "Skills",
+  },
+  sandbox: {
+    title: "Sandbox",
+  },
+  customization: {
+    title: "Customization",
+  },
+  "integration-guide": {
+    title: "Integration Guide",
+  },
+};
+
+export default meta;

frontend/src/content/en/harness/configuration.mdx

@@ -0,0 +1,3 @@
+# Configuration
+
+TBD

frontend/src/content/en/harness/customization.mdx

@@ -0,0 +1,3 @@
+# Customization
+
+TBD

frontend/src/content/en/harness/design-principles.mdx

@@ -0,0 +1,3 @@
+# Design Principles
+
+TBD

frontend/src/content/en/harness/index.mdx

@@ -0,0 +1,50 @@
+import { Callout, Cards } from "nextra/components";
+
+# Install DeerFlow Harness
+
+<Callout type="info" emoji="📦">
+  The DeerFlow Harness Python package will be published as <code>deerflow</code>
+  . It is not released yet, so installation is currently{" "}
+  <strong>Coming Soon</strong>.
+</Callout>
+
+The DeerFlow Harness is the Python SDK and runtime foundation for building your own Super Agent systems.
+
+If you want to compose agents with skills, memory, tools, sandboxes, and subagents inside your own product or workflow, this is the part of DeerFlow you will build on.
+
+## Package name
+
+The package name will be:
+
+```bash
+pip install deerflow
+```
+
+That package is not publicly available yet, but this is the installation path the documentation will use once it is released.
+
+## Current status
+
+The DeerFlow Harness package is **coming soon**.
+
+At the moment, this section exists to establish the SDK entry point and package identity, while the public distribution flow is being finalized.
+
+## What the Harness will give you
+
+The Harness is designed for developers who want to build their own agent system on top of DeerFlow's runtime model.
+
+It will provide the foundation for:
+
+- building long-horizon agents,
+- composing runtime capabilities such as memory, tools, skills, and subagents,
+- running agents with sandboxed execution,
+- customizing agent behavior through configuration and code, and
+- integrating DeerFlow into your own application architecture.
+
+## What to do next
+
+Until the package is released, the best way to understand the DeerFlow Harness is to read the conceptual and implementation docs in this section.
+
+<Cards num={2}>
+  <Cards.Card title="Quick Start" href="/docs/harness/quick-start" />
+  <Cards.Card title="Configuration" href="/docs/harness/configuration" />
+</Cards>

frontend/src/content/en/harness/integration-guide.mdx

@@ -0,0 +1,3 @@
+# Integration Guide
+
+TBD

frontend/src/content/en/harness/memory.mdx

@@ -0,0 +1,3 @@
+# Memory
+
+TBD

frontend/src/content/en/harness/quick-start.mdx

@@ -0,0 +1,3 @@
+# Quick Start
+
+TBD

frontend/src/content/en/harness/sandbox.mdx

@@ -0,0 +1,3 @@
+# Sandbox
+
+TBD

frontend/src/content/en/harness/skills.mdx

@@ -0,0 +1,3 @@
+# Skills
+
+TBD

frontend/src/content/en/harness/tools.mdx

@@ -0,0 +1,3 @@
+# Tools
+
+TBD

frontend/src/content/en/index.mdx

@@ -0,0 +1,95 @@
+---
+title: DeerFlow Documentation
+description: Understand DeerFlow, build with the Harness, and deploy the App.
+---
+
+# DeerFlow Documentation
+
+DeerFlow is a framework for building and operating agent systems. It gives you a runtime harness for composing agents with memory, tools, skills, sandboxes, and subagents, and it also provides an application layer that turns those capabilities into a usable product experience.
+
+This documentation is organized around those two parts:
+
+- **DeerFlow Harness**: the core SDK and runtime layer for building your own agent system.
+- **DeerFlow App**: a reference application built on top of the Harness for deployment, operations, and end-user workflows.
+
+If you want to understand how DeerFlow works, start with the Introduction. If you want to build on the core runtime, go to the Harness docs. If you want to deploy and use DeerFlow as an application, go to the App docs.
+
+## Start here
+
+### If you are new to DeerFlow
+
+Start with the conceptual overview first.
+
+- [Introduction](/docs/introduction)
+- [Why DeerFlow](/docs/introduction/why-deerflow)
+- [Harness vs App](/docs/introduction/harness-vs-app)
+
+### If you want to build with DeerFlow
+
+Start with the Harness section. This path is for teams who want to integrate DeerFlow capabilities into their own system or build a custom agent product on top of the DeerFlow runtime.
+
+- [DeerFlow Harness](/docs/harness)
+- [Quick Start](/docs/harness/quick-start)
+- [Configuration](/docs/harness/configuration)
+- [Customization](/docs/harness/customization)
+
+### If you want to deploy and use DeerFlow
+
+Start with the App section. This path is for teams who want to run DeerFlow as a complete application and understand how to configure, operate, and use it in practice.
+
+- [DeerFlow App](/docs/app)
+- [Quick Start](/docs/app/quick-start)
+- [Deployment Guide](/docs/app/deployment-guide)
+- [Workspace Usage](/docs/app/workspace-usage)
+
+## Documentation structure
+
+### Introduction
+
+The Introduction section helps you build the right mental model before you look at implementation details.
+
+- **What is DeerFlow** explains what DeerFlow is and what problems it is designed to solve.
+- **Why DeerFlow** explains the motivation behind the project.
+- **Core Concepts** introduces the concepts that appear across the documentation.
+- **Harness vs App** explains the relationship between the runtime layer and the application layer.
+
+### DeerFlow Harness
+
+The Harness section is the core of the technical documentation. It is written for developers who want to build their own DeerFlow-based system.
+
+- **Quick Start** shows how to create your first harness with the core DeerFlow API.
+- **Design Principles** explains the architectural ideas behind the Harness.
+- **Configuration** covers the main configuration surface of the SDK/runtime.
+- **Memory**, **Tools**, **Skills**, and **Sandbox** explain the major system capabilities separately.
+- **Customization** shows how to adapt DeerFlow to your own product requirements.
+- **Integration Guide** explains how to integrate the Harness into a larger system.
+
+### DeerFlow App
+
+The App section is written for teams who want to deploy DeerFlow as a usable product.
+
+- **Quick Start** helps you run the application locally.
+- **Deployment Guide** explains how to deploy DeerFlow in your own environment.
+- **Configuration** covers the application-level configuration model.
+- **Workspace Usage** explains the main user workflows.
+- **Agents and Threads** explains how users interact with DeerFlow in practice.
+- **Operations and Troubleshooting** covers maintenance and production usage.
+
+### Tutorials
+
+The Tutorials section is for hands-on, task-oriented learning.
+
+- [Tutorials](/docs/tutorials)
+
+### Reference
+
+The Reference section is for detailed lookup material, including configuration, runtime modes, APIs, and source-oriented mapping.
+
+- [Reference](/docs/reference)
+
+## Choose the right path
+
+- If you are **evaluating the project**, start with [Introduction](/docs/introduction).
+- If you are **building your own agent system**, start with [DeerFlow Harness](/docs/harness).
+- If you are **deploying DeerFlow for users**, start with [DeerFlow App](/docs/app).
+- If you want to **learn by doing**, go to [Tutorials](/docs/tutorials).

frontend/src/content/en/introduction/_meta.ts

@@ -0,0 +1,15 @@
+import type { MetaRecord } from "nextra";
+
+const meta: MetaRecord = {
+  "why-deerflow": {
+    title: "Why DeerFlow",
+  },
+  "core-concepts": {
+    title: "Core Concepts",
+  },
+  "harness-vs-app": {
+    title: "Harness vs App",
+  },
+};
+
+export default meta;

frontend/src/content/en/introduction/core-concepts.mdx

@@ -0,0 +1,113 @@
+import { Callout, Cards } from "nextra/components";
+
+# Core Concepts
+
+<Callout type="important" emoji="🧠">
+  DeerFlow makes the most sense if you think of it as a runtime for long-horizon
+  agents, not just a chat interface or a workflow graph.
+</Callout>
+
+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.
+
+## Harness
+
+In DeerFlow, a **harness** is the runtime layer that gives an agent the environment it needs to do real work.
+
+A framework usually gives you abstractions and building blocks. A harness goes further: it packages an opinionated set of runtime capabilities so the agent can plan, act, use tools, manage files, and operate across longer tasks without you rebuilding the same infrastructure each time.
+
+In practice, DeerFlow's harness includes things like:
+
+- tool access,
+- skill loading,
+- sandboxed execution,
+- memory,
+- subagent orchestration, and
+- context management.
+
+That is why DeerFlow is not only a model wrapper and not only a workflow graph. It is a runtime environment for agents.
+
+## Long-horizon agent
+
+A **long-horizon agent** is an agent that stays useful across a chain of actions instead of producing only a single answer.
+
+This kind of agent may need to:
+
+1. make a plan,
+2. decide the next step repeatedly,
+3. call tools many times,
+4. inspect and modify files,
+5. store intermediate results, and
+6. return a usable artifact at the end.
+
+The important point is not just duration. It is sustained coordination across multiple steps.
+
+DeerFlow is designed for this kind of work. Its architecture assumes that useful tasks often take more than one tool call and more than one reasoning pass.
+
+## Skill
+
+A **skill** is a task-oriented capability package that teaches the agent how to do a certain class of work.
+
+A skill is not just a label. It usually includes structured instructions, workflows, best practices, and supporting resources that can be loaded when relevant. This keeps the base agent general while allowing specialized behavior to be added only when needed.
+
+In DeerFlow, deep research is one skill. Data analysis, content generation, design-oriented workflows, and other task families can also be represented as skills.
+
+This is a major part of the DeerFlow mental model: the runtime stays general, while skills provide specialization.
+
+## Sandbox
+
+A **sandbox** is the isolated execution environment where the agent does file and command-based work.
+
+Instead of treating the agent as a pure text generator, DeerFlow gives it a workspace where it can read files, write outputs, run commands, and produce artifacts. This makes the system much more useful for coding, analysis, and multi-step workflows.
+
+Isolation matters because execution should be controlled and reproducible. The sandbox is what lets DeerFlow support action, not just conversation.
+
+## Subagent
+
+A **subagent** is a focused worker that handles a delegated subtask.
+
+When a task is too broad for one reasoning thread, DeerFlow can split the work into smaller units and run them separately. Subagents help with parallel exploration, scoped execution, and reducing overload on the main agent.
+
+The key idea is isolation. A subagent does not need the full conversation history or every detail from the parent context. It only needs the information required to solve its assigned piece of work well.
+
+## Context engineering
+
+**Context engineering** is the practice of controlling what the agent sees, remembers, and ignores so it can stay effective over time.
+
+Long tasks put pressure on the context window. If everything is kept inline forever, the agent becomes slower, noisier, and less reliable. DeerFlow addresses this with techniques such as summarization, scoped context for subagents, and using the file system as external working memory.
+
+This is one of the most important ideas in DeerFlow. Good agent behavior is not only about a stronger model. It is also about giving the model the right working set at the right time.
+
+## Memory
+
+**Memory** is DeerFlow's mechanism for carrying useful information across sessions.
+
+Instead of starting from zero every time, the system can retain information such as user preferences, recurring project context, and durable facts that improve future interactions. Memory makes the agent more adaptive and less repetitive.
+
+In DeerFlow, memory is part of the runtime, not an afterthought layered on top.
+
+## Artifact
+
+An **artifact** is the concrete output of the agent's work.
+
+That output might be a report, a generated file, a code change, a chart, a design asset, or another deliverable that can be reviewed and used outside the chat itself.
+
+This matters because DeerFlow is designed around task completion, not just answer generation. The system is trying to produce something you can inspect, refine, or hand off.
+
+## Putting the concepts together
+
+These concepts fit together as one model:
+
+- The **harness** provides the runtime.
+- **Skills** provide specialization.
+- The **sandbox** provides an execution environment.
+- **Subagents** provide decomposition and parallelism.
+- **Context engineering** keeps long tasks manageable.
+- **Memory** preserves useful continuity.
+- **Artifacts** are the outputs that make the work tangible.
+
+If you keep that model in mind, the rest of the DeerFlow docs will be much easier to navigate.
+
+<Cards num={2}>
+  <Cards.Card title="Why DeerFlow" href="/docs/introduction/why-deerflow" />
+  <Cards.Card title="Harness vs App" href="/docs/introduction/harness-vs-app" />
+</Cards>

frontend/src/content/en/introduction/harness-vs-app.mdx

@@ -0,0 +1,103 @@
+import { Callout, Cards } from "nextra/components";
+
+# Harness vs App
+
+<Callout type="info" emoji="⚙️">
+  DeerFlow App is the best-practice Super Agent application built on top of
+  DeerFlow Harness, while DeerFlow Harness is the Python SDK and runtime
+  foundation for building your own agent system.
+</Callout>
+
+DeerFlow has two layers that are closely related but serve different purposes:
+
+- **DeerFlow Harness** is the runtime foundation.
+- **DeerFlow App** is the best-practice application built on top of that foundation.
+
+Understanding this distinction makes the rest of the documentation much easier to navigate.
+
+## The Harness is the runtime layer
+
+The **DeerFlow Harness** is the reusable system for building and operating long-horizon agents.
+
+It is also delivered as a **Python library SDK**, so developers can use DeerFlow as a programmable foundation for building their own Super Agent systems instead of starting from scratch.
+
+It provides the core runtime capabilities that make an agent useful in real work:
+
+- skills,
+- tool use,
+- sandboxed execution,
+- memory,
+- subagent orchestration,
+- context management, and
+- configurable runtime behavior.
+
+If you want to build your own agent product, integrate DeerFlow into an existing system, or customize the runtime deeply, the Harness is the part you should focus on.
+
+The Harness is the foundation. It is the part that makes DeerFlow programmable, extensible, and reusable.
+
+## The App is the reference implementation
+
+The **DeerFlow App** is a complete Super Agent application built with the Harness.
+
+Instead of only exposing runtime primitives, it shows what a production-oriented DeerFlow experience looks like when those primitives are assembled into a usable product. In other words, the App is not separate from the Harness. It is the best-practice implementation of what the Harness enables.
+
+That is why the App is the easiest way to understand DeerFlow as a working system: it demonstrates how the runtime, UI, workflows, and operational pieces come together in one place.
+
+## Why the App matters
+
+Many teams do not just want agent infrastructure. They want a usable application that already solves the common product and operations problems around running agents.
+
+The DeerFlow App addresses that need.
+
+It presents DeerFlow as a **Super Agent application** rather than only a set of low-level building blocks. That means users interact with a complete system that can manage conversations, run tasks, produce artifacts, and expose the core DeerFlow capabilities through an opinionated product surface.
+
+The App is therefore useful in two different ways:
+
+1. as a ready-to-run product for teams that want to deploy DeerFlow directly, and
+2. as a reference architecture for teams that want to build their own application on top of the Harness.
+
+## Best practices encoded in the App
+
+The App is where DeerFlow's recommended patterns become concrete.
+
+It reflects best practices for:
+
+- how users interact with a lead agent,
+- how threads and artifacts are organized,
+- how runtime capabilities are exposed in a product workflow,
+- how the system is configured and operated, and
+- how a self-hosted DeerFlow deployment should be structured.
+
+So when we say the App is built on the Harness, we do not only mean it imports the runtime. We mean it packages DeerFlow's preferred way to deliver a Super Agent experience end to end.
+
+## Self-hosting and deployment
+
+A key property of DeerFlow App is that it can be **self-hosted**.
+
+That matters for teams that want control over infrastructure, data handling, runtime configuration, and integration with their own environment. The App is designed so you can run DeerFlow in your own setup instead of treating it as a closed hosted service.
+
+This makes DeerFlow practical for internal tools, team workflows, and organization-specific deployments where control and extensibility matter as much as raw model capability.
+
+## How to choose between them
+
+The simplest rule is:
+
+- Choose the **Harness** if you want to build your own agent system.
+- Choose the **App** if you want DeerFlow as a complete Super Agent product.
+- Use both if you want to start from the App while still keeping access to the underlying runtime.
+
+The two layers are complementary. The Harness gives you the agent runtime. The App turns that runtime into a concrete product with deployment, operations, and user workflows already thought through.
+
+<Cards num={2}>
+  <Cards.Card title="DeerFlow Harness" href="/docs/harness" />
+  <Cards.Card title="DeerFlow App" href="/docs/app" />
+</Cards>
+
+## One foundation, two entry points
+
+DeerFlow is not split into two unrelated products. It is one system with two entry points.
+
+The **Harness** is the core runtime for developers.
+The **App** is the best-practice Super Agent application built on top of that runtime.
+
+If you want to go deeper into the runtime itself, continue with the [DeerFlow Harness](/docs/harness). If you want to run DeerFlow as a product, continue with the [DeerFlow App](/docs/app).

frontend/src/content/en/introduction/why-deerflow.mdx

@@ -0,0 +1,73 @@
+import { Callout, Cards } from "nextra/components";
+
+# Why DeerFlow
+
+<Callout type="info" emoji="🦌">
+  DeerFlow started with deep research, but it grew into a general runtime for
+  long-horizon agents that need skills, memory, tools, and coordination.
+</Callout>
+
+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.
+
+## It started as deep research
+
+The first version of DeerFlow was designed around a specific goal: produce real research outputs instead of lightweight chatbot summaries. The idea was to let an AI system work more like a research team: make a plan, gather sources, cross-check findings, and deliver a structured result with useful depth.
+
+That framing worked, but the project quickly revealed something more important. Teams were not only using DeerFlow for research. They were adapting it for data analysis, report generation, internal automation, operations workflows, and other tasks that also require multi-step execution.
+
+The common thread was clear: the valuable part was not only the research workflow itself, but the runtime capabilities underneath it.
+
+## Research was the first skill, not the whole system
+
+That shift in usage led to a key conclusion: deep research should be treated as one capability inside a broader agent runtime, not as the definition of the entire product.
+
+DeerFlow therefore evolved from a project centered on a single research pattern into a general-purpose harness for long-running agents. In this model, research is still important, but it becomes one skill among many rather than the fixed shape of the system.
+
+This is why DeerFlow is described as a **harness** instead of only a framework or only an application.
+
+## Why a harness matters
+
+A harness is an opinionated runtime for agents. It does not just expose abstractions. It packages the infrastructure an agent needs to do useful work in realistic environments.
+
+For DeerFlow, that means combining the core pieces required for long-horizon execution:
+
+- **Skills** for task-specific capabilities that can be loaded only when needed.
+- **Sandboxed execution** so agents can work with files, run commands, and produce artifacts safely.
+- **Subagents** so complex work can be decomposed and executed in parallel.
+- **Memory** so the system can retain user preferences and recurring context across sessions.
+- **Context management** so long tasks remain tractable even when conversations and outputs grow.
+
+These are the building blocks that make an agent useful beyond a single prompt-response exchange.
+
+## Why DeerFlow moved beyond fixed multi-agent graphs
+
+Earlier agent systems often modeled work as a fixed graph of specialized roles. That approach can work for a narrow workflow, but it becomes rigid once users want the system to handle a broader range of tasks.
+
+DeerFlow moved toward a different architecture: a lead agent with middleware, tools, and dynamically invoked subagents. This makes the system easier to extend because new capabilities can be introduced as skills, tools, or runtime policies instead of requiring the whole orchestration graph to be redesigned.
+
+That architectural shift reflects the main motivation behind DeerFlow: build the reusable runtime layer first, then let many workflows sit on top of it.
+
+## DeerFlow is built for long-horizon work
+
+DeerFlow is motivated by a specific view of agents: the most valuable systems are not the ones that generate a single answer fastest, but the ones that can stay productive across a longer chain of actions.
+
+A long-horizon agent needs to do more than respond. It needs to:
+
+1. decide what to do next,
+2. keep track of intermediate state,
+3. store work outside the model context when necessary,
+4. recover from complexity without losing direction, and
+5. return an artifact that a human can review, refine, or continue from.
+
+That is the category of problem DeerFlow is designed for.
+
+## The goal
+
+The goal of DeerFlow is to provide a solid foundation for building and operating agent systems that can actually do work.
+
+If you are evaluating DeerFlow, the important idea is this: DeerFlow is not just a research demo and not just a UI wrapper around an LLM. It is a runtime harness for agents that need skills, memory, tools, isolation, and coordination to complete real tasks.
+
+<Cards num={2}>
+  <Cards.Card title="Core Concepts" href="/docs/introduction/core-concepts" />
+  <Cards.Card title="Harness vs App" href="/docs/introduction/harness-vs-app" />
+</Cards>

frontend/src/content/en/reference/_meta.ts

@@ -0,0 +1,21 @@
+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",
+  },
+};
+
+export default meta;

frontend/src/content/en/reference/api-gateway-reference.mdx

@@ -0,0 +1,3 @@
+# API / Gateway Reference
+
+TBD

frontend/src/content/en/reference/concepts-glossary.mdx

@@ -0,0 +1,3 @@
+# Concepts Glossary
+
+TBD

frontend/src/content/en/reference/configuration-reference.mdx

@@ -0,0 +1,3 @@
+# Configuration Reference
+
+TBD

frontend/src/content/en/reference/runtime-flags-and-modes.mdx

@@ -0,0 +1,3 @@
+# Runtime Flags and Modes
+
+TBD

frontend/src/content/en/reference/source-map.mdx

@@ -0,0 +1,3 @@
+# Source Map
+
+TBD

frontend/src/content/en/tutorials/_meta.ts

@@ -0,0 +1,21 @@
+import type { MetaRecord } from "nextra";
+
+const meta: MetaRecord = {
+  "first-conversation": {
+    title: "First Conversation",
+  },
+  "create-your-first-harness": {
+    title: "Create Your First Harness",
+  },
+  "use-tools-and-skills": {
+    title: "Use Tools and Skills",
+  },
+  "work-with-memory": {
+    title: "Work with Memory",
+  },
+  "deploy-your-own-deerflow": {
+    title: "Deploy Your Own DeerFlow",
+  },
+};
+
+export default meta;

frontend/src/content/en/tutorials/create-your-first-harness.mdx

@@ -0,0 +1,3 @@
+# Create Your First Harness
+
+TBD

frontend/src/content/en/tutorials/deploy-your-own-deerflow.mdx

@@ -0,0 +1,3 @@
+# Deploy Your Own DeerFlow
+
+TBD

frontend/src/content/en/tutorials/first-conversation.mdx

@@ -0,0 +1,3 @@
+# First Conversation
+
+TBD

frontend/src/content/en/tutorials/use-tools-and-skills.mdx

@@ -0,0 +1,3 @@
+# Use Tools and Skills
+
+TBD

frontend/src/content/en/tutorials/work-with-memory.mdx

@@ -0,0 +1,3 @@
+# Work with Memory
+
+TBD

frontend/src/content/zh/_meta.ts

@@ -0,0 +1,12 @@
+import type { MetaRecord } from "nextra";
+
+const meta: MetaRecord = {
+  index: {
+    title: "概览",
+  },
+  workspace: {
+    type: "page",
+  },
+};
+
+export default meta;

frontend/src/content/zh/index.mdx

@@ -0,0 +1,6 @@
+---
+title: 概览
+description: 了解 DeerFlow，使用 Harness 构建，并部署应用。
+---
+
+# 概览

frontend/src/core/i18n/hooks.ts

@@ -4,22 +4,15 @@ import { useEffect } from "react";
 
 import { useI18nContext } from "./context";
 import { getLocaleFromCookie, setLocaleInCookie } from "./cookies";
-import { enUS } from "./locales/en-US";
-import { zhCN } from "./locales/zh-CN";
+import { translations } from "./translations";
 
 import {
   DEFAULT_LOCALE,
   detectLocale,
   normalizeLocale,
   type Locale,
-  type Translations,
 } from "./index";
 
-const translations: Record<Locale, Translations> = {
-  "en-US": enUS,
-  "zh-CN": zhCN,
-};
-
 export function useI18n() {
   const { locale, setLocale } = useI18nContext();
 

frontend/src/core/i18n/locale.ts

@@ -6,6 +6,16 @@ export function isLocale(value: string): value is Locale {
   return (SUPPORTED_LOCALES as readonly string[]).includes(value);
 }
 
+export function getLocaleByLang(lang: string): Locale {
+  const normalizedLang = lang.toLowerCase();
+  for (const locale of SUPPORTED_LOCALES) {
+    if (locale.startsWith(normalizedLang)) {
+      return locale;
+    }
+  }
+  return DEFAULT_LOCALE;
+}
+
 export function normalizeLocale(locale: string | null | undefined): Locale {
   if (!locale) {
     return DEFAULT_LOCALE;

frontend/src/core/i18n/locales/en-US.ts

@@ -51,6 +51,12 @@ export const enUS: Translations = {
     exportSuccess: "Conversation exported",
   },
 
+  // Home
+  home: {
+    docs: "Docs",
+    blog: "Blog",
+  },
+
   // Welcome
   welcome: {
     greeting: "Hello, again!",

frontend/src/core/i18n/locales/types.ts

@@ -40,6 +40,11 @@ export interface Translations {
     exportSuccess: string;
   };
 
+  home: {
+    docs: string;
+    blog: string;
+  };
+
   // Welcome
   welcome: {
     greeting: string;

frontend/src/core/i18n/locales/zh-CN.ts

@@ -51,6 +51,12 @@ export const zhCN: Translations = {
     exportSuccess: "对话已导出",
   },
 
+  // Home
+  home: {
+    docs: "文档",
+    blog: "博客",
+  },
+
   // Welcome
   welcome: {
     greeting: "你好，欢迎回来！",

frontend/src/core/i18n/server.ts

@@ -1,6 +1,7 @@
 import { cookies } from "next/headers";
 
-import { normalizeLocale, type Locale } from "./locale";
+import { DEFAULT_LOCALE, normalizeLocale, type Locale } from "./locale";
+import { translations } from "./translations";
 
 export async function detectLocaleServer(): Promise<Locale> {
   const cookieStore = await cookies();
@@ -15,3 +16,26 @@ export async function detectLocaleServer(): Promise<Locale> {
 
   return normalizeLocale(locale);
 }
+
+export async function setLocale(locale: string | Locale): Promise<Locale> {
+  const normalizedLocale = normalizeLocale(locale);
+  const cookieStore = await cookies();
+  cookieStore.set("locale", encodeURIComponent(normalizedLocale), {
+    maxAge: 365 * 24 * 60 * 60,
+    path: "/",
+    sameSite: "lax",
+  });
+
+  return normalizedLocale;
+}
+
+export async function getI18n(localeOverride?: string | Locale) {
+  const locale = localeOverride
+    ? normalizeLocale(localeOverride)
+    : await detectLocaleServer();
+  const t = translations[locale] ?? translations[DEFAULT_LOCALE];
+  return {
+    locale,
+    t,
+  };
+}

frontend/src/core/i18n/translations.ts

@@ -0,0 +1,7 @@
+import type { Locale } from "./locale";
+import { enUS, zhCN, type Translations } from "./locales";
+
+export const translations: Record<Locale, Translations> = {
+  "en-US": enUS,
+  "zh-CN": zhCN,
+};

frontend/src/mdx-components.ts

@@ -0,0 +1,11 @@
+import { useMDXComponents as getThemeComponents } from "nextra-theme-docs"; // nextra-theme-blog or your custom theme
+
+// Get the default MDX components
+const themeComponents = getThemeComponents();
+
+// Merge components
+export function useMDXComponents() {
+  return {
+    ...themeComponents,
+  };
+}