@bleedingdev/modern-js-main-doc 3.5.0-ultramodern.97 → 3.5.0-ultramodern.99

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/bff/effect.mdx

@@ -45,6 +45,23 @@ import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
 
 `bff.effect` is only effective when `bff.runtimeFramework` is set to `'effect'`.
 
+:::caution Install the Effect peers yourself
+`effect` and `@effect/opentelemetry` are **optional exact peer dependencies** of
+`@modern-js/plugin-bff`, not dependencies. The plugin no longer bundles a copy —
+Effect 4 derives `Context` / `Service` keys per module instance, so a bundled copy
+would give your app a second Effect identity. Before setting
+`runtimeFramework: 'effect'` or importing `@modern-js/plugin-bff/effect`,
+`/effect-server`, `/effect-edge` or `/effect-client`, install the exact cohort:
+
+```bash
+pnpm add effect@4.0.0-beta.102 @effect/opentelemetry@4.0.0-beta.102
+```
+
+The pin is exact because UltraModern ships Effect as one lockstep cohort. Apps
+using only `runtimeFramework: 'hono'` or the `./data-platform` lane need neither
+package.
+:::
+
 Generated UltraModern workspaces use this runtime as the only generated HTTP API
 path. The API contract lives at `shared/api.ts`, the server runtime lives at
 `api/index.ts`, clients live under `src/api/*-client.ts`, and generated checks
@@ -202,17 +219,17 @@ generated apps use:
 
 ```yaml
 minimumReleaseAgeExclude:
-  - 'effect@4.0.0-beta.97'
-  - '@effect/opentelemetry@4.0.0-beta.97'
+  - 'effect@4.0.0-beta.102'
+  - '@effect/opentelemetry@4.0.0-beta.102'
 
 trustPolicyExclude:
-  - 'effect@4.0.0-beta.97'
-  - '@effect/opentelemetry@4.0.0-beta.97'
+  - 'effect@4.0.0-beta.102'
+  - '@effect/opentelemetry@4.0.0-beta.102'
 
 overrides:
-  '@effect/opentelemetry': 4.0.0-beta.97
-  '@effect/vitest': 4.0.0-beta.97
-  effect: 4.0.0-beta.97
+  '@effect/opentelemetry': 4.0.0-beta.102
+  '@effect/vitest': 4.0.0-beta.102
+  effect: 4.0.0-beta.102
 ```
 
 Do not add a different direct `effect` version in an app package. A mismatched

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/server/rsc.mdx

@@ -22,7 +22,7 @@ export default defineConfig({
 :::tip Prerequisites
 Before enabling RSC, ensure:
 1. React and React DOM are upgraded to version 19 (recommended 19.2.4 or above)
-2. Install the `react-server-dom-rspack@0.0.1-beta.1` dependency
+2. Install the `react-server-dom-rspack@0.0.2` dependency
 
 :::
 

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/guides/advanced-features/international/api.mdx

@@ -145,19 +145,52 @@ const myPlugin = (): RuntimePlugin => ({
 
 The i18next instance type used by the plugin. It is a subset of the i18next `i18n` type and only lists fields actually used by the plugin:
 
+:::warning BREAKING (UltraModern)
+`I18nInstance` no longer declares a top-level `[key: string]: unknown` index
+signature: TypeScript never grants an interface an implicit index signature, so
+that member made the documented `runtime: { i18n: { i18nInstance: i18next } }`
+usage fail to typecheck. Reading a property that is not declared below is now a
+type error (TS2339) — cast to the concrete instance type instead. `t` is now a
+REQUIRED member, so object literals that produce an `I18nInstance` must supply
+one.
+:::
+
 ```ts
+type TranslateFn = (
+  key: string | string[],
+  options?: Record<string, unknown>,
+) => string;
+
 interface I18nInstance {
   language: string;
-  isInitialized: boolean;
-  init: (options?: I18nInitOptions) => void | Promise<void>;
-  changeLanguage: (lang: string) => void | Promise<void>;
-  use: (plugin: any) => void;
-  createInstance: (options?: I18nInitOptions) => I18nInstance;
+  isInitialized?: boolean;
+  init(options?: any, callback?: any): Promise<any>;
+  changeLanguage?(lng?: string, callback?: any): Promise<any>;
+  setLang?: (lang: string) => void | Promise<void>;
+  use(plugin: any): unknown;
+  t: TranslateFn;
+  exists?: (key: string | string[], options?: Record<string, unknown>) => boolean;
+  getFixedT?: (
+    lng: string | readonly string[] | null,
+    ns?: string | readonly string[] | null,
+    keyPrefix?: string,
+  ) => TranslateFn;
+  hasLoadedNamespace?: (
+    ns: string | readonly string[],
+    options?: Record<string, unknown>,
+  ) => boolean;
+  dir?: (lng?: string) => string;
+  languages?: readonly string[];
+  resolvedLanguage?: string;
+  createInstance?(options?: any, callback?: any): I18nInstance;
+  cloneInstance?(options?: any, callback?: any): I18nInstance;
   options?: {
-    backend?: BackendOptions;
-    supportedLngs?: string[];
-    [key: string]: any;
+    detection?: any;
+    backend?: any;
+    ns?: any;
+    defaultNS?: any;
   };
+  // ...see src/runtime/i18n/instance.ts for the full member list.
 }
 ```
 

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/basic-features/deploy.mdx

@@ -112,7 +112,7 @@ Add the following content to `netlify.toml`:
 ```
 
 :::info
-You can refer to the [deployment project example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+You can refer to the [deployment project example](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-csr).
 
 :::
 
@@ -137,7 +137,7 @@ Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. Th
 :::info
 
 1. Currently, Modern.js does not support deployment on Netlify Edge Functions. We will support it in future versions.
-2. You can refer to the [deployment project example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr).
+2. You can refer to the [deployment project example](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-ssr).
 
 :::
 
@@ -223,7 +223,7 @@ Commit your project to git, select Framework Preset as `Other` on the Vercel pla
 <img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/vercel-framework-preset.png" />
 
 :::info
-You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-csr).
 
 :::
 
@@ -237,7 +237,7 @@ In addition to configuring `vercel.json` in the same way as a [pure front-end pr
 2. The Node.js version for function execution is determined by the project configuration on the Vercel platform.
 
 :::info
-You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr).
+You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-ssr).
 
 :::
 
@@ -335,10 +335,10 @@ For branch deployment, follow these steps:
 :::info
 
 1. Running `MODERNJS_DEPLOY=ghPages modern deploy` will build the production output for GitHub in the .output directory.
-2. You can refer to the [project](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)
+2. You can refer to the [project](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-csr)
    :::
 
-For GitHub Actions deployment, select Settings > Pages > Source > GitHub Actions, and add a workflow file to the project. You can refer to the [example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+For GitHub Actions deployment, select Settings > Pages > Source > GitHub Actions, and add a workflow file to the project. You can refer to the [example](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-csr).
 
 ## Using Self-Built Node.js Server
 

package/docs/en/guides/basic-features/render/rsc.mdx

@@ -23,10 +23,10 @@ Before starting, we recommend reading React's official [Server Components docume
 
 1. **Ensure React and React DOM are upgraded to version 19** (recommended version 19.2.4 or above)
 
-2. **Install the `react-server-dom-rspack@0.0.1-beta.1` dependency**
+2. **Install the `react-server-dom-rspack@0.0.2` dependency**
 
 ```bash
-npm install react-server-dom-rspack@0.0.1-beta.1
+npm install react-server-dom-rspack@0.0.2
 ```
 
 :::warning Notes

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` 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/tech-stack.mdx

@@ -10,7 +10,7 @@ In this document, you can learn about the main technology stack involved in the
 
 ## UI Library
 
-Modern.js uses [React 18](https://react.dev/) to build user interfaces and is also compatible with React 17.
+Modern.js uses [React 19](https://react.dev/) to build user interfaces and is also compatible with React 18.
 
 Rsbuild supports building Vue applications. If you need to use Vue, you can refer to ["Rsbuild - Vue"](https://v2.rsbuild.rs/guide/framework/vue).
 

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

@@ -143,11 +143,11 @@ migration work: move code to `shared/api.ts`, `api/index.ts`, and
 and `src/effect`.
 
 Generated strict Effect workspaces pin the compatible Effect cohort with pnpm
-overrides: `effect@4.0.0-beta.97`, `@effect/opentelemetry@4.0.0-beta.97`,
-and `@effect/vitest@4.0.0-beta.97`. Do not add app-local direct Effect
+overrides: `effect@4.0.0-beta.102`, `@effect/opentelemetry@4.0.0-beta.102`,
+and `@effect/vitest@4.0.0-beta.102`. Do not add app-local direct Effect
 versions that disagree with those overrides. They also carry generated pnpm
-policy exclusions for `effect@4.0.0-beta.97` and
-`@effect/opentelemetry@4.0.0-beta.97` so the framework-selected Effect beta
+policy exclusions for `effect@4.0.0-beta.102` and
+`@effect/opentelemetry@4.0.0-beta.102` so the framework-selected Effect beta
 cohort is not blocked by the 24-hour age gate or trusted-publisher to
 provenance metadata transition.
 

package/docs/en/guides/topic-detail/module-federation/application.mdx

@@ -62,7 +62,7 @@ export default createModuleFederationConfig({
 ```
 
 :::info
-[`createBridgeComponent`](https://module-federation.io/practice/bridge/react-bridge/export-app.html#createbridgecomponent-api-reference) is used to export application-level modules. Modern.js related APIs can be found at [createRoot](/apis/app/runtime/core/create-root) and [render](/apis/app/runtime/core/render).
+[`createBridgeComponent`](https://module-federation.io/guide/bridge/overview#core-apis) is used to export application-level modules. Modern.js related APIs can be found at [createRoot](/apis/app/runtime/core/create-root) and [render](/apis/app/runtime/core/render).
 :::
 
 ## Using Modules in Consumer
@@ -98,7 +98,7 @@ export default RemoteApp;
 ```
 
 :::info
-[`createRemoteAppComponent`](https://module-federation.io/zh/practice/bridge/react-bridge/load-app.html#%E4%BB%80%E4%B9%88%E6%98%AF-createremoteappcomponent) is used to load application-level modules.
+[`createRemoteAppComponent`](https://module-federation.io/guide/bridge/overview#core-apis) is used to load application-level modules.
 :::
 
 ## Start the Application
@@ -109,8 +109,8 @@ After startup, when the consumer application accesses the `/remote` route, it wi
 
 You can create new route files in the producer application and add route navigation in the code. These functionalities will also work as expected.
 
-You can refer to the example here: [Modern.js & Module Federation Application-Level Modules](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/app-export).
+You can refer to the example here: [Modern.js & Module Federation Application-Level Modules](https://github.com/web-infra-dev/modern.js/tree/main/examples/module-federation/app-export).
 
 ## Related Documentation
 
-- [Module Federation Bridge](https://module-federation.io/zh/practice/bridge/index.html)
+- [Module Federation Bridge](https://module-federation.io/guide/bridge/overview)

package/docs/en/guides/topic-detail/module-federation/usage.mdx

@@ -195,7 +195,7 @@ Now, in the producer, run `modern build && MODERN_MF_AUTO_CORS=true  modern serv
 When using the `modern serve` command, you need to set the `MODERN_MF_AUTO_CORS=true` environment variable when starting the producer project to automatically handle CORS issues and ensure that consumers can properly access the producer's remote module resources.
 :::
 
-You can refer to this example: [Modern.js & Module Federation Basic Example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/base).
+You can refer to this example: [Modern.js & Module Federation Basic Example](https://github.com/web-infra-dev/modern.js/tree/main/examples/module-federation/base).
 
 ## Related Documentation
 

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/bff/effect.mdx

@@ -45,6 +45,21 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 
 仅当 `bff.runtimeFramework` 设置为 `'effect'` 时，`bff.effect` 才会生效。
 
+:::caution 需要自行安装 Effect peer 依赖
+`effect` 与 `@effect/opentelemetry` 是 `@modern-js/plugin-bff` 的**可选精确 peer
+依赖**，而不是直接依赖。插件不再自带副本——Effect 4 的 `Context` / `Service` 键按模块
+实例生成，自带副本会让应用出现第二份 Effect 身份。在设置 `runtimeFramework: 'effect'`
+或引入 `@modern-js/plugin-bff/effect`、`/effect-server`、`/effect-edge`、
+`/effect-client` 之前，请安装精确版本的依赖组：
+
+```bash
+pnpm add effect@4.0.0-beta.102 @effect/opentelemetry@4.0.0-beta.102
+```
+
+采用精确版本是因为 UltraModern 以锁步依赖组的方式发布 Effect。只使用
+`runtimeFramework: 'hono'` 或 `./data-platform` 通道的应用无需安装这两个包。
+:::
+
 生成的 UltraModern workspace 只把这个运行时作为生成 HTTP API 路径。API 契约固定在
 `shared/api.ts`，服务端运行时固定在 `api/index.ts`，客户端固定在
 `src/api/*-client.ts`。生成检查会拒绝 `api/effect`、`api/lambda`、
@@ -199,17 +214,17 @@ Effect 版本组。当前 UltraModern 版本组使用：
 
 ```yaml
 minimumReleaseAgeExclude:
-  - 'effect@4.0.0-beta.97'
-  - '@effect/opentelemetry@4.0.0-beta.97'
+  - 'effect@4.0.0-beta.102'
+  - '@effect/opentelemetry@4.0.0-beta.102'
 
 trustPolicyExclude:
-  - 'effect@4.0.0-beta.97'
-  - '@effect/opentelemetry@4.0.0-beta.97'
+  - 'effect@4.0.0-beta.102'
+  - '@effect/opentelemetry@4.0.0-beta.102'
 
 overrides:
-  '@effect/opentelemetry': 4.0.0-beta.97
-  '@effect/vitest': 4.0.0-beta.97
-  effect: 4.0.0-beta.97
+  '@effect/opentelemetry': 4.0.0-beta.102
+  '@effect/vitest': 4.0.0-beta.102
+  effect: 4.0.0-beta.102
 ```
 
 不要在应用包里添加不同版本的直接 `effect` 依赖。Effect beta 不一致时，Layer 或 HTTP

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/server/rsc.mdx

@@ -22,7 +22,7 @@ export default defineConfig({
 :::tip 前置条件
 在启用 RSC 之前，请确保：
 1. React 和 React DOM 已升级到 19 版本（建议 19.2.4 以上版本）
-2. 已安装 `react-server-dom-rspack@0.0.1-beta.1` 依赖
+2. 已安装 `react-server-dom-rspack@0.0.2` 依赖
 
 :::
 

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/guides/advanced-features/international/api.mdx

@@ -144,19 +144,50 @@ const myPlugin = (): RuntimePlugin => ({
 
 插件使用的 i18next 实例类型（i18next `i18n` 类型的子集，仅列出插件实际使用的字段）：
 
+:::warning 破坏性变更（UltraModern）
+`I18nInstance` 不再声明顶层的 `[key: string]: unknown` 索引签名：TypeScript 永远不会
+为 interface 自动添加隐式索引签名，该成员会让文档中的
+`runtime: { i18n: { i18nInstance: i18next } }` 用法无法通过类型检查。读取下方未声明的
+属性现在会报类型错误（TS2339），请改为断言到具体的实例类型。`t` 现在是**必需**成员，
+因此以对象字面量构造 `I18nInstance` 时必须提供 `t`。
+:::
+
 ```ts
+type TranslateFn = (
+  key: string | string[],
+  options?: Record<string, unknown>,
+) => string;
+
 interface I18nInstance {
   language: string;
-  isInitialized: boolean;
-  init: (options?: I18nInitOptions) => void | Promise<void>;
-  changeLanguage: (lang: string) => void | Promise<void>;
-  use: (plugin: any) => void;
-  createInstance: (options?: I18nInitOptions) => I18nInstance;
+  isInitialized?: boolean;
+  init(options?: any, callback?: any): Promise<any>;
+  changeLanguage?(lng?: string, callback?: any): Promise<any>;
+  setLang?: (lang: string) => void | Promise<void>;
+  use(plugin: any): unknown;
+  t: TranslateFn;
+  exists?: (key: string | string[], options?: Record<string, unknown>) => boolean;
+  getFixedT?: (
+    lng: string | readonly string[] | null,
+    ns?: string | readonly string[] | null,
+    keyPrefix?: string,
+  ) => TranslateFn;
+  hasLoadedNamespace?: (
+    ns: string | readonly string[],
+    options?: Record<string, unknown>,
+  ) => boolean;
+  dir?: (lng?: string) => string;
+  languages?: readonly string[];
+  resolvedLanguage?: string;
+  createInstance?(options?: any, callback?: any): I18nInstance;
+  cloneInstance?(options?: any, callback?: any): I18nInstance;
   options?: {
-    backend?: BackendOptions;
-    supportedLngs?: string[];
-    [key: string]: any;
+    detection?: any;
+    backend?: any;
+    ns?: any;
+    defaultNS?: any;
   };
+  // ...完整成员列表见 src/runtime/i18n/instance.ts。
 }
 ```
 

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/basic-features/deploy.mdx

@@ -317,7 +317,7 @@ Github Pages 支持两种部署方式，通过分支部署或通过 Github Actio
 :::info
 
 1. 执行 `MODERNJS_DEPLOY=ghPages modern deploy`，UltraModern.js 会把可用于 github 部署的产物构建到 `.output` 目录。
-2. 可以参考项目[示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
+2. 可以参考仓库内的[示例](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-csr)。
 
 :::
 

package/docs/zh/guides/basic-features/render/rsc.mdx

@@ -23,10 +23,10 @@ React Server Components (RSC) 是一种新的组件类型，允许在服务端
 
 1. **确保 React 和 React DOM 升级到 19 版本**（建议 19.2.4 以上版本）
 
-2. **安装 `react-server-dom-rspack@0.0.1-beta.1` 依赖**
+2. **安装 `react-server-dom-rspack@0.0.2` 依赖**
 
 ```bash
-npm install react-server-dom-rspack@0.0.1-beta.1
+npm install react-server-dom-rspack@0.0.2
 ```
 
 :::warning 注意事项

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` 生成或更新，可随时重复运行，你添加的自定义内容会被保留。
+
+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/ultramodern.mdx

@@ -128,10 +128,10 @@ pnpm overrides/trust policy 和 pnpm lockfile。剩余失败就是源码迁移
 `api/lambda`、`shared/effect` 和 `src/effect`。
 
 严格 Effect 生成 workspace 会通过 pnpm overrides 固定兼容版本组：
-`effect@4.0.0-beta.97`、`@effect/opentelemetry@4.0.0-beta.97` 和
-`@effect/vitest@4.0.0-beta.97`。不要添加与这些 overrides 冲突的 app 本地直接
-Effect 版本。生成的 pnpm policy 还会为 `effect@4.0.0-beta.97` 和
-`@effect/opentelemetry@4.0.0-beta.97` 添加例外，避免框架选定的 Effect beta
+`effect@4.0.0-beta.102`、`@effect/opentelemetry@4.0.0-beta.102` 和
+`@effect/vitest@4.0.0-beta.102`。不要添加与这些 overrides 冲突的 app 本地直接
+Effect 版本。生成的 pnpm policy 还会为 `effect@4.0.0-beta.102` 和
+`@effect/opentelemetry@4.0.0-beta.102` 添加例外，避免框架选定的 Effect beta
 版本组被 24 小时成熟期检查，或从 trusted-publisher metadata 迁移到 provenance
 attestation 时被 no-downgrade 检查误拦截。
 

package/docs/zh/guides/topic-detail/module-federation/application.mdx

@@ -63,7 +63,7 @@ export default createModuleFederationConfig({
 ```
 
 :::info
-[`createBridgeComponent`](https://module-federation.io/zh/practice/bridge/react-bridge/export-app.html#createbridgecomponent-api-%E5%8F%82%E8%80%83) 用于导出应用级别模块，Modern.js 相关 API 可以查看 [createRoot](/apis/app/runtime/core/create-root)、[render](/apis/app/runtime/core/render)。
+[`createBridgeComponent`](https://module-federation.io/zh/guide/bridge/overview.html#%E6%A0%B8%E5%BF%83-api) 用于导出应用级别模块，Modern.js 相关 API 可以查看 [createRoot](/apis/app/runtime/core/create-root)、[render](/apis/app/runtime/core/render)。
 :::
 
 ## 消费者使用模块
@@ -99,7 +99,7 @@ export default RemoteApp;
 ```
 
 :::info
-[`createRemoteAppComponent`](https://module-federation.io/zh/practice/bridge/react-bridge/load-app.html#%E4%BB%80%E4%B9%88%E6%98%AF-createremoteappcomponent) 用于加载应用级别模块。
+[`createRemoteAppComponent`](https://module-federation.io/zh/guide/bridge/overview.html#%E6%A0%B8%E5%BF%83-api) 用于加载应用级别模块。
 :::
 
 ## 启动应用
@@ -110,8 +110,8 @@ export default RemoteApp;
 
 你可以在生产者应用中，创建新的路由文件，并在代码中添加路由导航，可以发现这些功能也能够正常运行。
 
-上述用例可以参考：[Modern.js & Module Federation 应用级别模块](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/app-export)。
+上述用例可以参考：[Modern.js & Module Federation 应用级别模块](https://github.com/web-infra-dev/modern.js/tree/main/examples/module-federation/app-export)。
 
 ## 相关文档
 
-- [Module Federation Bridge](https://module-federation.io/zh/practice/bridge/index.html)
+- [Module Federation Bridge](https://module-federation.io/zh/guide/bridge/overview)

package/docs/zh/guides/topic-detail/module-federation/usage.mdx

@@ -193,7 +193,7 @@ export default defineConfig({
 在使用 `modern serve` 命令时，需要在启动生产者项目时携带 `MODERN_MF_AUTO_CORS=true` 环境变量，以自动处理跨域问题，确保消费者可以正常访问生产者的远程模块资源。
 :::
 
-上述用例可以参考：[Modern.js & Module Federation 基础用法示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/base)。
+上述用例可以参考：[Modern.js & Module Federation 基础用法示例](https://github.com/web-infra-dev/modern.js/tree/main/examples/module-federation/base)。
 
 ## 相关文档
 

package/package.json

@@ -19,12 +19,12 @@
     "modern.js",
     "ultramodern.js"
   ],
-  "version": "3.5.0-ultramodern.97",
+  "version": "3.5.0-ultramodern.99",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.5.0-ultramodern.97",
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.5.0-ultramodern.99",
     "mermaid": "^11.16.0"
   },
   "devDependencies": {