@modern-js/main-doc 3.6.0 → 3.8.0

package/docs/en/apis/app/hooks/config/mock.mdx

@@ -4,4 +4,7 @@ sidebar_position: 5
 ---
 # mock/
 
-When there is a `config/mock/index.js` file in the project directory, Modern.js will automatically enable the Mock service during development.
+When there is a `config/mock/index.ts` or `config/mock/index.js` file in the
+project directory, Modern.js will automatically enable the Mock service during
+development. Use [`dev.mockDir`](/configure/app/dev/mock-dir) to customize
+this directory.

package/docs/en/configure/app/dev/mock-dir.mdx

@@ -0,0 +1,35 @@
+---
+title: mockDir
+---
+
+# dev.mockDir
+
+- **Type:** `string`
+- **Default:** `'./config/mock'`
+
+Sets the directory containing the Mock API entry file. Relative paths are
+resolved from the application directory, and absolute paths are also supported.
+Modern.js loads `index.ts` or `index.js` from this directory during development.
+
+For example, move the Mock API entry to `mocks/index.ts`:
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  dev: {
+    mockDir: './mocks',
+  },
+});
+```
+
+This is also useful in a monorepo when multiple applications share one Mock
+directory:
+
+```js title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    mockDir: '../../shared/mocks',
+  },
+});
+```

package/docs/en/configure/app/source/react-compiler.mdx

@@ -0,0 +1,72 @@
+---
+title: reactCompiler
+---
+
+# source.reactCompiler
+
+- **Type:** `boolean | ReactCompilerOptions`
+- **Default:** `undefined` (disabled)
+
+Whether to enable [React Compiler](https://react.dev/learn/react-compiler). React Compiler is a build-time tool that optimizes re-rendering performance of React applications through automatic memoization.
+
+Modern.js implements this capability based on the Rust-based React Compiler built into Rspack's `builtin:swc-loader` (equivalent to setting SWC's `jsc.transform.reactCompiler`), reusing Rspack's built-in SWC transform chain without introducing Babel.
+
+:::tip
+This option is disabled by default. It must be enabled explicitly for any React version, including React 19.
+:::
+
+## Example
+
+### Enable React Compiler (React 19)
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: true,
+  },
+});
+```
+
+### Using with React 18
+
+The compiled output targets React 19 by default. To use it in React 18 projects, you need to:
+
+1. Install [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) as a **runtime dependency** (the compiled output references it at runtime):
+
+```bash
+npm add react-compiler-runtime
+```
+
+2. Specify the React version via `target`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      target: '18',
+    },
+  },
+});
+```
+
+### Customize compilation behavior
+
+When passing an object, the options are the same as Rspack's `jsc.transform.reactCompiler`. For example, use `compilationMode: 'annotation'` to only compile functions annotated with the `"use memo"` directive:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      compilationMode: 'annotation',
+    },
+  },
+});
+```
+
+For the complete list of options, see [Rsbuild - reactCompiler](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) and the [React Compiler configuration docs](https://react.dev/reference/react-compiler/configuration).

package/docs/en/configure/app/tools/ts-checker.mdx

@@ -81,32 +81,16 @@ export default {
 
 > Please refer to [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) for more details.
 
-## TypeScript Go Support
+## TypeScript 7+ Support
 
-`tools.tsChecker` supports enabling [TypeScript Go](https://github.com/microsoft/typescript-go) for type checking. This experimental capability is provided by [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin), which is integrated by [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check), and can reduce type-checking time by about 5-10x.
+`tools.tsChecker` supports the native checker included in TypeScript 7+. This capability is provided by [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin), which is integrated by [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check), and can reduce type-checking time on large projects.
 
-Install TypeScript 7.0 RC to enable TypeScript Go automatically:
+Install TypeScript >= 7.0.0 to enable `tsgo` automatically:
 
-<PackageManagerTabs command="install typescript@rc -D" />
+<PackageManagerTabs command="install typescript@latest -D" />
 
-You can also install `@typescript/native-preview` and set `typescript.tsgo` to `true`:
+When `tsgo` is enabled and `typescript.typescriptPath` is set manually, it must point to an absolute TypeScript 7+ `typescript/package.json` path or the legacy `@typescript/native-preview/package.json` path.
 
-<PackageManagerTabs command="install @typescript/native-preview -D" />
+> The `@typescript/native-preview` path is kept only for compatibility. New setups should use TypeScript 7+ from the standard `typescript` package.
 
-```ts
-export default {
-  tools: {
-    tsChecker: {
-      typescript: {
-        tsgo: true,
-      },
-    },
-  },
-};
-```
-
-When `tsgo` is enabled and `typescript.typescriptPath` is set manually, it must point to an absolute `typescript/package.json` path from TypeScript 7+ or `@typescript/native-preview/package.json`.
-
-> The `@typescript/native-preview` usage is deprecated and kept only for compatibility. We recommend installing `typescript@rc` to use `tsgo`.
-
-For supported options and limitations, please refer to [ts-checker-rspack-plugin - TypeScript Go support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-go-support).
+For supported options and limitations, please refer to [ts-checker-rspack-plugin - TypeScript 7+ support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-7-support).

package/docs/en/guides/advanced-features/page-performance/react-compiler.mdx

@@ -1,54 +1,69 @@
 # React Compiler
 
-The React Compiler is an experimental compiler introduced in React 19 that can automatically optimize your React code.
+React Compiler is a build-time compiler from the React team that reduces unnecessary re-renders through automatic memoization, without manually writing `useMemo`, `useCallback`, or `React.memo`.
 
-Before starting to use the React Compiler, it is recommended to read the [React Compiler documentation](https://zh-hans.react.dev/learn/react-compiler) to understand its features, current status, and usage.
+Before starting to use React Compiler, it is recommended to read the [React Compiler documentation](https://react.dev/learn/react-compiler) to understand its features, current status, and usage.
 
 ## How to Use
 
-### React 19
+Modern.js provides built-in support for React Compiler via the [source.reactCompiler](/configure/app/source/react-compiler) option, powered by the Rust-based React Compiler implementation in Rspack's `builtin:swc-loader`. It reuses Rspack's built-in SWC transform chain without introducing Babel (`babel-plugin-react-compiler`).
 
-If you are using React 19, Modern.js has built-in support for React Compiler, and no additional configuration is required.
+This capability is **disabled by default** and must be enabled explicitly for any React version.
 
-### React 18
+### React 19
 
-If you are using React 18, you need to configure it as follows:
+If you are using React 19, simply enable `source.reactCompiler` — no additional dependencies are required:
 
-1. Install `react-compiler-runtime` to allow the compiled code to run on versions before 19:
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
 
-```bash
-npm install react-compiler-runtime
+export default defineConfig({
+  source: {
+    reactCompiler: true,
+  },
+  plugins: [appTools()],
+});
 ```
 
-2. Install `babel-plugin-react-compiler`:
+### React 18
+
+If you are using React 18, configure it as follows:
+
+1. Install `react-compiler-runtime` as a **runtime dependency** to allow the compiled code to run on versions before React 19:
 
 ```bash
-npm install babel-plugin-react-compiler
+npm add react-compiler-runtime
 ```
 
-3. Register the Babel plugin in your Modern.js configuration file:
+2. Specify the React version via `target` in the configuration:
 
 ```ts title="modern.config.ts"
 import { appTools, defineConfig } from '@modern-js/app-tools';
-import { pluginBabel } from '@rsbuild/plugin-babel';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginBabel({
-      babelLoaderOptions: (config, { addPlugins }) => {
-        addPlugins([
-          [
-            'babel-plugin-react-compiler',
-          {
-            target: '18', // 或 '17'，根据你使用的 React 版本
-          },
-          ],
-        ]);
-      },
-    });
-  ];
+  source: {
+    reactCompiler: {
+      target: '18',
+    },
+  },
   plugins: [appTools()],
 });
 ```
 
+## Customize Compilation Behavior
+
+`source.reactCompiler` accepts an object to configure the compilation behavior, with the same options as Rspack's `jsc.transform.reactCompiler`. For example, use `compilationMode: 'annotation'` to only compile functions annotated with the `"use memo"` directive, enabling React Compiler incrementally:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      compilationMode: 'annotation',
+    },
+  },
+});
+```
+
+For the complete list of options, see [Rsbuild - reactCompiler](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) and the [React Compiler configuration docs](https://react.dev/reference/react-compiler/configuration).
+
 > For detailed code, you can refer to the [Modern.js & React Compiler example project](https://github.com/web-infra-dev/modern.js/tree/main/examples/react-compiler)

package/docs/en/guides/basic-features/debug/mock.mdx

@@ -20,6 +20,17 @@ By convention, when there is an `index.ts` in the `config/mock/` directory, mock
 └── modern.config.ts
 ```
 
+You can use [`dev.mockDir`](/configure/app/dev/mock-dir) to place the
+Mock entry in another directory:
+
+```js title="modern.config.ts"
+export default {
+  dev: {
+    mockDir: './mocks',
+  },
+};
+```
+
 ## Writing Mock Files
 
 The `config/mock/index.ts` file only needs to export an object containing all Mock APIs. The properties of the object are composed of the request configuration `method` and `url`, and the corresponding property values can be `Object`, `Array`, or `Function`:

package/docs/en/guides/get-started/ai-coding-agents.mdx

@@ -5,16 +5,31 @@ sidebar_position: 6
 
 # Modern.js For AI
 
-Modern.js provides a toolkit for AI agents that helps developers use AI to efficiently complete feature development, dependency upgrades, and version migration for Modern.js applications.
+Modern.js provides a toolkit for AI agents that makes your project agent-ready out of the box, helping you use AI to develop, upgrade, and migrate Modern.js applications more accurately and efficiently.
+
+## Bundled docs
+
+Modern.js ships the English docs that match your installed version together with `@modern-js/app-tools`. After you install or upgrade, they live at `node_modules/@modern-js/app-tools/docs/`, available offline with no extra setup.
+
+AI agents use them to get APIs, config, and conventions that exactly match your framework version, rather than relying on potentially outdated training data.
+
+## AGENTS.md
+
+`AGENTS.md` gives AI coding agents project-level guidance — telling them to read the bundled docs before making changes and to follow Modern.js conventions. A `CLAUDE.md` is generated alongside it, reusing the same guidance for Claude Code via the `@AGENTS.md` import.
+
+- **New projects**: `npx @modern-js/create` generates both files by default; pass `--no-agents-md` to skip them.
+- **Existing projects**: run `npx @modern-js/create --agents-md-only` at the project root to create or update them. Re-run it any time; your own additions are preserved.
+
+Modern.js only maintains the content inside the `<!-- BEGIN:modernjs-agent-rules -->` markers in `AGENTS.md`; anything you write outside them is left untouched.
 
 ## llms.txt
 
-Modern.js docs follow the [llms.txt specification](https://llmstxt.org/), auto-generated by [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms), accessible via `/llms.txt` or `/llms-full.txt`:
+llms.txt is an online documentation index following the [llms.txt specification](https://llmstxt.org/), auto-generated by [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms) for AI tools to retrieve the full docs online:
 
 - Index: [`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
-- Full text: `https://modernjs.dev/llms-full.txt` (large — fetch on demand)
+- Full text: [`https://modernjs.dev/llms-full.txt`](https://modernjs.dev/llms-full.txt) (large — fetch on demand)
 
-Most "what is this API / config" questions can be answered from llms.txt. Just let your agent retrieve it on demand; no need to copy docs into your project.
+Use it when you need content beyond the bundled docs — just let your agent retrieve it on demand, no need to copy docs into your project. Typical cases: looking up another framework version, a section not included in the bundle, or getting Modern.js information outside of a project (for example before a project exists, or when researching on its own).
 
 ## Skills
 

package/docs/en/guides/get-started/upgrade.mdx

@@ -24,7 +24,7 @@ All Modern.js official packages are released with a **uniform version number**,
    - Visit [npm](https://www.npmjs.com/package/@modern-js/app-tools) to check the latest version of `@modern-js/app-tools`
    - Check [GitHub Releases](https://github.com/web-infra-dev/modern.js/releases)
 
-   <ReleaseNote />
+<ReleaseNote />
 
 2. **Update package.json**
 
@@ -46,7 +46,7 @@ All Modern.js official packages are released with a **uniform version number**,
 
    After updating `package.json`, reinstall dependencies:
 
-   <PackageManagerTabs command="install" />
+<PackageManagerTabs command="install" />
 
 :::tip
 When upgrading, you need to upgrade all packages provided by Modern.js uniformly, rather than upgrading individual dependencies. Ensure that all `@modern-js/**` packages have the same version number.

package/docs/zh/apis/app/hooks/config/mock.mdx

@@ -4,4 +4,6 @@ sidebar_position: 5
 ---
 # mock/
 
-当项目目录下存在 `config/mock/index.js` 时，Modern.js 在开发环节将自动开启 Mock 服务。
+当项目目录下存在 `config/mock/index.ts` 或 `config/mock/index.js` 时，Modern.js
+会在开发环节自动开启 Mock 服务。可以通过
+[`dev.mockDir`](/configure/app/dev/mock-dir) 自定义该目录。

package/docs/zh/configure/app/dev/mock-dir.mdx

@@ -0,0 +1,33 @@
+---
+title: mockDir
+---
+
+# dev.mockDir
+
+- **类型：** `string`
+- **默认值：** `'./config/mock'`
+
+设置 Mock API 入口文件所在的目录。相对路径基于应用目录解析，同时也支持绝对路径。
+开发环境下，Modern.js 会加载该目录中的 `index.ts` 或 `index.js`。
+
+例如，将 Mock API 入口移动到 `mocks/index.ts`：
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  dev: {
+    mockDir: './mocks',
+  },
+});
+```
+
+在 Monorepo 中，也可以让多个应用指向一个共享的 Mock 目录：
+
+```js title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    mockDir: '../../shared/mocks',
+  },
+});
+```

package/docs/zh/configure/app/source/react-compiler.mdx

@@ -0,0 +1,72 @@
+---
+title: reactCompiler
+---
+
+# source.reactCompiler
+
+- **类型：** `boolean | ReactCompilerOptions`
+- **默认值：** `undefined`（不开启）
+
+是否启用 [React Compiler](https://zh-hans.react.dev/learn/react-compiler)。React Compiler 是一个构建期工具，通过自动记忆化（memoization）优化 React 应用的重渲染性能。
+
+Modern.js 基于 Rspack `builtin:swc-loader` 内置的 Rust 版 React Compiler 实现该能力（等价于设置 SWC 的 `jsc.transform.reactCompiler`），复用 Rspack 内置的 SWC 转换链，无需额外引入 Babel。
+
+:::tip
+该配置默认关闭，任何 React 版本下都需要显式开启，包括 React 19。
+:::
+
+## 示例
+
+### 开启 React Compiler（React 19）
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: true,
+  },
+});
+```
+
+### 在 React 18 中使用
+
+React Compiler 编译产物默认面向 React 19。在 React 18 项目中使用时，需要：
+
+1. 将 [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) 安装为**运行时依赖**（编译产物会在运行时引用它）：
+
+```bash
+npm add react-compiler-runtime
+```
+
+2. 通过 `target` 指定 React 版本：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      target: '18',
+    },
+  },
+});
+```
+
+### 自定义编译行为
+
+传入对象时，选项与 Rspack `jsc.transform.reactCompiler` 一致，例如通过 `compilationMode: 'annotation'` 仅编译带有 `"use memo"` 指令的函数：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      compilationMode: 'annotation',
+    },
+  },
+});
+```
+
+完整选项请参考 [Rsbuild - reactCompiler](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) 与 [React Compiler 配置文档](https://zh-hans.react.dev/reference/react-compiler/configuration)。

package/docs/zh/configure/app/tools/ts-checker.mdx

@@ -81,32 +81,16 @@ export default {
 
 > 请参考 [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) 了解更多用法。
 
-## TypeScript Go 支持
+## TypeScript 7+ 支持
 
-`tools.tsChecker` 支持开启 [TypeScript Go](https://github.com/microsoft/typescript-go) 进行类型检查。该能力由 [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check) 底层集成的 [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin) 提供，目前仍处于实验阶段，可以将类型检查耗时减少约 5-10 倍。
+`tools.tsChecker` 支持使用 TypeScript 7+ 的原生检查器进行类型检查。该能力由 [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check) 底层集成的 [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin) 提供，可以减少大型项目的类型检查耗时。
 
-安装 TypeScript 7.0 RC 后，TypeScript Go 会自动开启：
+安装 TypeScript >= 7.0.0 后会自动启用 `tsgo`：
 
-<PackageManagerTabs command="install typescript@rc -D" />
+<PackageManagerTabs command="install typescript@latest -D" />
 
-你也可以安装 `@typescript/native-preview`，并将 `typescript.tsgo` 设置为 `true`：
+开启 `tsgo` 后，如果手动设置 `typescript.typescriptPath`，它必须指向 TypeScript 7+ 的 `typescript/package.json` 或旧版 `@typescript/native-preview/package.json` 的绝对路径。
 
-<PackageManagerTabs command="install @typescript/native-preview -D" />
+> `@typescript/native-preview` 路径仅作为兼容保留。新项目应使用标准 `typescript` 包提供的 TypeScript 7+。
 
-```ts
-export default {
-  tools: {
-    tsChecker: {
-      typescript: {
-        tsgo: true,
-      },
-    },
-  },
-};
-```
-
-开启 `tsgo` 后，如果手动设置 `typescript.typescriptPath`，它必须指向 TypeScript 7+ 的 `typescript/package.json` 或 `@typescript/native-preview/package.json` 的绝对路径。
-
-> `@typescript/native-preview` 的用法已废弃，仅作为兼容保留。推荐安装 `typescript@rc` 使用 `tsgo`。
-
-关于 `tsgo` 模式下生效的配置项和相关限制，请参考 [ts-checker-rspack-plugin - TypeScript Go support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-go-support)。
+关于 `tsgo` 模式下生效的配置项和相关限制，请参考 [ts-checker-rspack-plugin - TypeScript 7+ support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-7-support)。

package/docs/zh/guides/advanced-features/page-performance/react-compiler.mdx

@@ -1,54 +1,69 @@
 # React Compiler
 
-React Compiler 是 React 19 引入的一个实验性编译器，它可以自动优化你的 React 代码。
+React Compiler 是 React 官方提供的构建期编译器，通过自动记忆化（memoization）减少不必要的重渲染，无需手动编写 `useMemo`、`useCallback` 和 `React.memo`。
 
-在开始使用 React Compiler 之前，建议阅读 [React Compiler 文档](https://zh-hans.react.dev/learn/react-compiler)，以了解 React Compiler 的功能、当前状态和使用方法。
+在开始使用 React Compiler 之前，建议阅读 [React Compiler 文档](https://zh-hans.react.dev/learn/react-compiler)，以了解它的功能、当前状态和使用方法。
 
 ## 如何使用
 
-### React 19
+Modern.js 通过 [source.reactCompiler](/configure/app/source/react-compiler) 配置内置支持 React Compiler，底层使用 Rspack `builtin:swc-loader` 中 Rust 实现的 React Compiler，复用 Rspack 内置的 SWC 转换链，无需额外引入 Babel（`babel-plugin-react-compiler`）。
 
-如果你使用的是 React 19，Modern.js 已内置支持 React Compiler，无需额外配置即可使用。
+该能力**默认关闭**，任何 React 版本下都需要显式开启。
 
-### React 18
+### React 19
 
-如果你使用的是 React 18，需要按照以下步骤配置：
+如果你使用的是 React 19，开启 `source.reactCompiler` 即可，无需安装任何额外依赖：
 
-1. 安装 `react-compiler-runtime`，以允许编译后的代码在 19 之前的版本上运行：
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
 
-```bash
-npm install react-compiler-runtime
+export default defineConfig({
+  source: {
+    reactCompiler: true,
+  },
+  plugins: [appTools()],
+});
 ```
 
-2. 安装 `babel-plugin-react-compiler`：
+### React 18
+
+如果你使用的是 React 18，需要按照以下步骤配置：
+
+1. 将 `react-compiler-runtime` 安装为**运行时依赖**，以允许编译后的代码在 React 19 之前的版本上运行：
 
 ```bash
-npm install babel-plugin-react-compiler
+npm add react-compiler-runtime
 ```
 
-3. 在你的 Modern.js 配置文件中注册 Babel 插件：
+2. 在配置中通过 `target` 指定 React 版本：
 
 ```ts title="modern.config.ts"
 import { appTools, defineConfig } from '@modern-js/app-tools';
-import { pluginBabel } from '@rsbuild/plugin-babel';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginBabel({
-      babelLoaderOptions: (config, { addPlugins }) => {
-        addPlugins([
-          [
-            'babel-plugin-react-compiler',
-          {
-            target: '18', // 或 '17'，根据你使用的 React 版本
-          },
-          ],
-        ]);
-      },
-    });
-  ];
+  source: {
+    reactCompiler: {
+      target: '18',
+    },
+  },
   plugins: [appTools()],
 });
 ```
 
+## 自定义编译行为
+
+`source.reactCompiler` 支持传入对象来配置编译行为，选项与 Rspack 的 `jsc.transform.reactCompiler` 一致。例如，通过 `compilationMode: 'annotation'` 可以只编译带有 `"use memo"` 指令的函数，渐进式地启用 React Compiler：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      compilationMode: 'annotation',
+    },
+  },
+});
+```
+
+完整选项请参考 [Rsbuild - reactCompiler](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) 与 [React Compiler 配置文档](https://zh-hans.react.dev/reference/react-compiler/configuration)。
+
 > 详细代码可以参考：[Modern.js & React Compiler 示例项目](https://github.com/web-infra-dev/modern.js/tree/main/examples/react-compiler)

package/docs/zh/guides/basic-features/debug/mock.mdx

@@ -20,6 +20,16 @@ Modern.js 提供了快速生成 Mock 数据的功能，能够让前端独立自
 └── modern.config.ts
 ```
 
+你可以通过 [`dev.mockDir`](/configure/app/dev/mock-dir) 将 Mock 入口放到其他目录：
+
+```js title="modern.config.ts"
+export default {
+  dev: {
+    mockDir: './mocks',
+  },
+};
+```
+
 ## 编写 Mock 文件
 
 `config/mock/index.ts` 文件只需要导出一个包含所有 Mock API 的对象，对象的属性由请求配置 `method` 和 `url` 组成，对应的属性值可以为 `Object`、`Array`、`Function`：

package/docs/zh/guides/get-started/ai-coding-agents.mdx

@@ -5,16 +5,31 @@ sidebar_position: 6
 
 # Modern.js For AI
 
-Modern.js 为 AI Agent 提供了一套工具套件，帮助开发者利用 AI 高效完成 Modern.js 应用的功能开发、依赖升级与版本迁移工作。
+Modern.js 为 AI Agent 提供了一套工具套件，让项目开箱即为 agent-ready，帮助你更准确、高效地用 AI 完成 Modern.js 应用的开发、升级与迁移。
+
+## 随包文档
+
+Modern.js 把与你安装版本一致的英文文档随 `@modern-js/app-tools` 一起分发。安装或升级后，文档即位于 `node_modules/@modern-js/app-tools/docs/`，离线可用、无需额外配置。
+
+AI Agent 由此获取与当前框架版本严格匹配的 API、配置与约定，而不是依赖可能过时的训练数据。
+
+## AGENTS.md
+
+`AGENTS.md` 是给 AI 编码助手的项目指引，告诉它在动手前先阅读随包文档、并遵循 Modern.js 的约定；同时会生成 `CLAUDE.md`，通过 `@AGENTS.md` 让 Claude Code 复用同一份指引。
+
+- **新建项目**：`npx @modern-js/create` 默认生成这两个文件，加 `--no-agents-md` 可跳过。
+- **已有项目**：在项目根运行 `npx @modern-js/create --agents-md-only` 生成或更新，可随时重复运行，你添加的自定义内容会被保留。
+
+Modern.js 只维护 `AGENTS.md` 中 `<!-- BEGIN:modernjs-agent-rules -->` 标记内的内容，标记之外你写的内容不会被改动。
 
 ## llms.txt
 
-Modern.js 文档遵循 [llms.txt 规范](https://llmstxt.org/)，由 [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms) 自动生成，可通过 `/llms.txt` 或 `/llms-full.txt` 供 AI 工具检索：
+llms.txt 是遵循 [llms.txt 规范](https://llmstxt.org/) 的在线文档索引，由 [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms) 自动生成，供 AI 工具在线检索完整文档：
 
 - 索引：[`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
-- 全文：`https://modernjs.dev/llms-full.txt`（体积较大，按需取片段）
+- 全文：[`https://modernjs.dev/llms-full.txt`](https://modernjs.dev/llms-full.txt)（体积较大，按需取片段）
 
-大部分「这个 API / 配置是什么」类问题，靠 llms.txt 即可解决。让你的 Agent 按需检索它即可，不必把文档复制进项目。
+当需要查阅随包文档之外的内容时，让 Agent 在线检索它即可，不必把文档复制进项目。典型场景包括：查阅其他框架版本、随包未包含的章节，或在 Modern.js 项目之外获取信息（例如尚未创建项目、或独立查阅资料时）。
 
 ## Skills
 

package/docs/zh/guides/get-started/upgrade.mdx

@@ -24,7 +24,7 @@ Modern.js 所有的官方包使用**统一版本号**进行发布，因此升级
    - 访问 [npm](https://www.npmjs.com/package/@modern-js/app-tools) 查看 `@modern-js/app-tools` 的最新版本
    - 查看 [GitHub Releases](https://github.com/web-infra-dev/modern.js/releases)
 
-   <ReleaseNote />
+<ReleaseNote />
 
 2. **更新 package.json**
 
@@ -46,7 +46,7 @@ Modern.js 所有的官方包使用**统一版本号**进行发布，因此升级
 
    更新完 `package.json` 后，重新安装依赖：
 
-   <PackageManagerTabs command="install" />
+<PackageManagerTabs command="install" />
 
 :::tip
 当升级时，需要对 Modern.js 官方提供的所有包做统一升级，而不是升级单个依赖。确保所有 `@modern-js/**` 包的版本号保持一致。

package/package.json

@@ -16,14 +16,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.6.0",
+  "version": "3.8.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.15.0",
-    "@modern-js/sandpack-react": "3.6.0"
+    "@modern-js/sandpack-react": "3.8.0"
   },
   "devDependencies": {
     "rsbuild-plugin-open-graph": "1.1.3",
@@ -42,6 +42,21 @@
     "ts-node": "^10.9.2",
     "typescript": "^5"
   },
+  "nx": {
+    "targets": {
+      "build": {
+        "inputs": [
+          "build",
+          "^build",
+          "{projectRoot}/docs/**/*",
+          "{projectRoot}/rspress.config.ts"
+        ],
+        "outputs": [
+          "{projectRoot}/doc_build"
+        ]
+      }
+    }
+  },
   "scripts": {
     "dev": "rspress dev",
     "dev:no_lazy": "LAZY=false rspress dev",