@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.120 → 3.2.0-ultramodern.122

package/docs/en/apis/app/commands.mdx

@@ -8,12 +8,12 @@ UltraModern.js has some built-in commands that can help you quickly start a deve
 
 Through this chapter, you can learn about the built-in commands of UltraModern.js and how to use them.
 
-## ultramodern dev
+## modern dev
 
-The `ultramodern dev` command is used to start a local development server and compile the source code in the development environment.
+The `modern dev` command is used to start a local development server and compile the source code in the development environment.
 
 ```bash
-Usage: ultramodern dev [options]
+Usage: modern dev [options]
 
 Options:
   -e --entry <entry>    compiler by entry
@@ -23,10 +23,10 @@ Options:
   --api-only            only start API service
 ```
 
-After running `ultramodern dev`, UltraModern.js will watch source file changes and apply hot module replacement.
+After running `modern dev`, UltraModern.js will watch source file changes and apply hot module replacement.
 
 ```bash
-$ ultramodern dev
+$ modern dev
 
 info    Starting dev server...
 
@@ -38,10 +38,10 @@ info    Starting dev server...
 
 In multi-page (MPA) projects, the `--entry` option can be added to specify one or more pages to compile. In this way, only part of the code in the project will be compiled, and the dev startup speed will be faster.
 
-For example, execute `ultramodern dev --entry`, the entry selector will be displayed in the command line interface:
+For example, execute `modern dev --entry`, the entry selector will be displayed in the command line interface:
 
 ```text
-$ ultramodern dev --entry
+$ modern dev --entry
 
 ? Please select the entry that needs to be built
 ❯ ◯ foo
@@ -57,22 +57,22 @@ You can also specify the page name through parameters after `--entry`, and the n
 
 ```bash
 # Compile foo page
-ultramodern dev --entry foo
+modern dev --entry foo
 
 # Compile foo and bar pages
-ultramodern dev --entry foo,bar
+modern dev --entry foo,bar
 ```
 
-## ultramodern start
+## modern start
 
-`ultramodern start` is an alias of `ultramodern dev` command, the usage of the two are exactly the same.
+`modern start` is an alias of `modern dev` command, the usage of the two are exactly the same.
 
-## ultramodern build
+## modern build
 
-The `ultramodern build` command will build production-ready artifacts in the `dist/` directory by default. You can specify the output directory by modifying the configuration [`output.distPath`](/configure/app/output/dist-path).
+The `modern build` command will build production-ready artifacts in the `dist/` directory by default. You can specify the output directory by modifying the configuration [`output.distPath`](/configure/app/output/dist-path).
 
 ```bash
-Usage: ultramodern build [options]
+Usage: modern build [options]
 
 Options:
   -c --config <config>  specify the configuration file, which can be a relative or absolute path
@@ -80,80 +80,70 @@ Options:
   -w --watch            turn on watch mode, watch for changes and rebuild
 ```
 
-## ultramodern new
+## modern runtime status
 
-The `ultramodern new` command is used to enable features in an existing project.
-
-For example, add application entry, enable some optional features such as BFF, micro frontend, etc.
+The `modern runtime status` command reads the runtime status endpoint and prints the response. It targets `http://127.0.0.1:8080/_modern/runtime/status` by default.
 
 ```bash
-Usage: ultramodern new [options]
+Usage: modern runtime status [options]
 
 Options:
-  --config-file <configFile>  specify the configuration file, which can be a relative or absolute path
-  --lang <lang>          set the language (zh or en) for the new command.
-  -d, --debug            using debug mode to log something (default: false)
-  -c, --config <config>  set default generator config(json string)
-  --dist-tag <tag>       use specified tag version for its generator
-  --registry             set npm registry url to run npm command
-  -h, --help             show command help
+  --endpoint <endpoint>  runtime status endpoint URL or path
+  --token <token>        runtime status auth token
+  --token-env <name>     environment variable name that stores runtime status auth token (default: "MODERN_RUNTIME_SIGNAL_TOKEN")
+  --header-name <name>   auth header name (default: "x-modernjs-runtime-signal-token")
+  --timeout <ms>         request timeout in milliseconds (default: "5000")
+  --json                 output as JSON format for machine reading
+  -h, --help             display help for command
 ```
 
-### Add Entry
+If `--endpoint` is a path, it is resolved against `http://127.0.0.1:8080`. If `--token` is omitted, the command reads the token from the environment variable named by `--token-env`.
 
-In the project, execute the `new` command to add entries as follows:
+By default, the command formats the response as readable key/value lines. Add `--json` to print the raw JSON payload.
 
-```text
-$ npx ultramodern new
-? Please select the operation you want: Create Element
-? Please select the type of element to create: New "entry"
-? Please fill in the entry name: entry
+```bash
+modern runtime status --json
 ```
 
-### Enable Features
+## modern runtime fallback-signal
 
-In the project, execute the `new` command to enable features as follows:
+The `modern runtime fallback-signal` command posts a runtime fallback signal to the canary contract-gate endpoint. It targets `http://127.0.0.1:8080/_modern/contract-gates/runtime-fallback` by default.
 
-```text
-$ npx ultramodern new
-? Please select the operation you want: Enable Features
-? Please select the feature name: (Use arrow keys)
-❯ Enable BFF
-  Enable SSG
-  Enable Micro Frontend
+```bash
+Usage: modern runtime fallback-signal [options]
+
+Options:
+  --app <appName>          remote app name
+  --endpoint <endpoint>    runtime fallback signal endpoint URL or path
+  --reason <reason>        fallback reason (default: "runtime_fallback")
+  --phase <phase>          fallback phase (default: "load")
+  --entry <entry>          remote entry URL
+  --runtime-digest <digest>  runtime digest value
+  --metadata <json>        metadata JSON object string
+  --token <token>          runtime signal auth token
+  --token-env <name>       environment variable name that stores runtime signal auth token (default: "MODERN_RUNTIME_SIGNAL_TOKEN")
+  --header-name <name>     auth header name (default: "x-modernjs-runtime-signal-token")
+  --timeout <ms>           request timeout in milliseconds (default: "5000")
+  --json                   output as JSON format for machine reading
+  -h, --help               display help for command
 ```
 
-:::tip
-The `--config` parameter needs to use a JSON string.
+The request body always includes `appName`, `reason`, and `phase`. It includes `entry`, `runtimeDigest`, and `metadata` only when those options are provided. `--metadata` must be a JSON object string.
 
-pnpm does not support the use of JSON strings as parameter values currently. Use `npm new` to turn on.【[Relate Issue](https://github.com/pnpm/pnpm/issues/3876)】
-:::
+```bash
+modern runtime fallback-signal --app crm-shell --reason remote_load_failed --phase load --json
+```
 
 import ServeCommand from '@site-docs-en/components/serve-command';
 
 <ServeCommand />
 
-## ultramodern upgrade
-
-Execute the command `npx ultramodern upgrade` in the project, by default, dependencies in the `package.json` are updated to the latest version.
-
-```bash
-Usage: ultramodern upgrade [options]
-
-Options:
-  --config <config> specify the configuration file, which can be a relative or absolute path
-  --registry <registry>  specify npm registry (default: "")
-  -d,--debug             using debug mode to log something (default: false)
-  --cwd <cwd>            app directory (default: "")
-  -h, --help             show command help
-```
-
-## ultramodern inspect
+## modern inspect
 
-The `ultramodern inspect` command is used to view the UltraModern.js config, [Rsbuild config](https://v2.rsbuild.rs/config/index) and Rspack config of the project.
+The `modern inspect` command is used to view the UltraModern.js config, [Rsbuild config](https://v2.rsbuild.rs/config/index) and Rspack config of the project.
 
 ```bash
-Usage: ultramodern inspect [options]
+Usage: modern inspect [options]
 
 Options:
   --env <env>           view the configuration in the target environment (default: "development")
@@ -163,14 +153,14 @@ Options:
   -h, --help            show command help
 ```
 
-After executing the command `npx ultramodern inspect` in the project root directory, the following files will be generated in the `dist` directory of the project:
+After executing the command `npx modern inspect` in the project root directory, the following files will be generated in the `dist` directory of the project:
 
 - `modern.js.config.mjs`:The Modern.js configuration currently used.
 - `rsbuild.config.mjs`: The Rsbuild config to use at build time.
 - `rspack.config.web.mjs`: The Rspack config used by to use at build time.
 
 ```bash
-➜ npx ultramodern inspect
+➜ npx modern inspect
 
 Inspect config succeed, open following files to view the content:
 
@@ -184,7 +174,7 @@ Inspect config succeed, open following files to view the content:
 By default, the inspect command will output the development configs, you can use the `--env production` option to output the production configs:
 
 ```bash
-ultramodern inspect --env production
+modern inspect --env production
 ```
 
 ### Verbose content
@@ -192,7 +182,7 @@ ultramodern inspect --env production
 By default, the inspect command will omit the function content in the config object, you can use the `--verbose` option to output the full content of the function:
 
 ```bash
-ultramodern inspect --verbose
+modern inspect --verbose
 ```
 
 ### SSR Configuration
@@ -200,7 +190,7 @@ ultramodern inspect --verbose
 If the project has enabled SSR, an additional `rspack.config.node.mjs` file will be generated in the `dist/`, corresponding to the Rspack configuration at SSR build time.
 
 ```bash
-➜ npx ultramodern inspect
+➜ npx modern inspect
 
 Inspect config succeed, open following files to view the content:
 

package/docs/en/community/blog/v2-release-note.mdx

@@ -86,20 +86,20 @@ title: Modern.js v2 发布
 
 大家对 Modern.js 框架的第一印象可能是「一个大而全的框架」，但事实上，为了避免变得臃肿，**Modern.js 采取了渐进式设计**，将所有功能建立在灵活的插件系统之上，因此具备按需启用和可插拔的能力。
 
-Modern.js 期望能支持不同规模的项目研发，考虑到中大型项目和小型项目对功能的诉求存在差异，**Modern.js 的大多数功能都是按需启用的**。在创建项目时，Modern.js 默认只安装核心模块，使 npm 依赖保持轻量；当需要用到额外功能时，你可以通过 ultramodern new 命令一键开启，并自动安装相关依赖。
+Modern.js 期望能支持不同规模的项目研发，考虑到中大型项目和小型项目对功能的诉求存在差异，**Modern.js 的大多数功能都是按需启用的**。在创建项目时，Modern.js 默认只安装核心模块，使 npm 依赖保持轻量；当需要用到额外功能时，你可以通过 modern new 命令一键开启，并自动安装相关依赖。
 
-![ultramodern new 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new-code.png)
+![modern new 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new-code.png)
 
-<div style={{ textAlign: 'center', fontStyle: 'italic' }}>ultramodern new 命令</div>
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>modern new 命令</div>
 
 比如：
 
 - 对于基础的开发场景，项目中只需安装 Modern.js 的 CLI 工具 `@modern-js/app-tools`，即具备了开发调试、生产构建的能力。
-- 当你需要在应用中增加一些 BFF 接口时，可以执行 ultramodern new 命令来启用 BFF 功能。启用后，Modern.js 会自动安装所需的 BFF 插件，以及某个 Node.js 框架对应的插件（如 Koa / Express）：
+- 当你需要在应用中增加一些 BFF 接口时，可以执行 modern new 命令来启用 BFF 功能。启用后，Modern.js 会自动安装所需的 BFF 插件，以及某个 Node.js 框架对应的插件（如 Koa / Express）：
 
 ![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/bff-plugins.png)
 
-目前，你可以通过 `ultramodern new` 命令来按需开启以下功能，未来我们也会将更多功能加入到 `new` 命令中，使其能够被便捷地集成。
+目前，你可以通过 `modern new` 命令来按需开启以下功能，未来我们也会将更多功能加入到 `new` 命令中，使其能够被便捷地集成。
 
 ![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new.png)
 

package/docs/en/community/blog/v3-release-note.mdx

@@ -339,7 +339,7 @@ For more on config-based routing, see the docs: [Config-Based Routing](/guides/b
 
 #### Route Debugging
 
-Run the `npx ultramodern routes` command to generate a complete route structure analysis report in the `dist/routes-inspect.json` file.
+Run the `npx modern routes` command to generate a complete route structure analysis report in the `dist/routes-inspect.json` file.
 
 The report displays each route's path, component file, data loader, error boundary, loading component, and other details, helping developers quickly understand the project's route configuration and troubleshoot routing issues. The structured JSON format is also easy for AI agents to understand and analyze, improving the efficiency of AI-assisted development.
 

package/docs/en/community/releases.mdx

@@ -24,8 +24,4 @@ Modern.js follows the [Semantic Versioning](https://semver.org) specification.
 
 ## Version Upgrade
 
-When you need to upgrade the Modern.js version in your project, you can use the `ultramodern upgrade` command, refer to [Upgrade](/guides/get-started/upgrade).
-
-```bash
-npx ultramodern upgrade
-```
+Modern.js 3.0 no longer ships the `modern upgrade` command. When you need to upgrade a project, follow the manual migration steps in [Upgrade](/guides/get-started/upgrade).

package/docs/en/components/build-output.mdx

@@ -3,7 +3,7 @@ To build the production artifacts of the project, run `pnpm run build` in the pr
 ```bash
 $ pnpm run build
 
-> ultramodern build
+> modern build
 
   Modern.js Framework
 

package/docs/en/components/debug-app.mdx

@@ -2,7 +2,7 @@ Run `pnpm run dev` in the project to start the project:
 
 ```bash
 $ pnpm run dev
-> ultramodern dev
+> modern dev
 
   Modern.js Framework
 

package/docs/en/components/deploy-command.mdx

@@ -1,9 +1,9 @@
-## ultramodern deploy
+## modern deploy
 
-The `ultramodern deploy` command is used to generate artifacts required for the deployment platform.
+The `modern deploy` command is used to generate artifacts required for the deployment platform.
 
 ```bash
-Usage: ultramodern deploy [options]
+Usage: modern deploy [options]
 
 Options:
   -c --config <config>  Specify configuration file path, either relative or absolute

package/docs/en/components/init-app.mdx

@@ -2,6 +2,10 @@ UltraModern.js provides the BleedingDev create package to create SuperApp
 workspaces. It does not require global installation and can be run on-demand
 using `pnpm dlx`.
 
+The supported pnpm command is the scoped package specifier:
+`pnpm dlx @bleedingdev/modern-js-create <target>`. Do not shorten it to
+`pnpm dlx modern-js-create`; there is no unscoped package by that name.
+
 You can initialize the empty directory you are already in:
 
 ```bash

package/docs/en/components/serve-command.mdx

@@ -1,9 +1,9 @@
-## ultramodern serve
+## modern serve
 
-The `ultramodern serve` command is used to start an UltraModern.js project in the production environment. It can also be used to preview the artifacts built for the production environment locally. Please note that you need to execute the [`build`](/apis/app/commands#ultramodern-build) command beforehand to generate the corresponding artifacts.
+The `modern serve` command is used to start an UltraModern.js project in the production environment. It can also be used to preview the artifacts built for the production environment locally. Please note that you need to execute the [`build`](/apis/app/commands#modern-build) command beforehand to generate the corresponding artifacts.
 
 ```bash
-Usage: ultramodern serve [options]
+Usage: modern serve [options]
 
 Options:
   -c --config <config>  specify the configuration file, which can be a relative or absolute path

package/docs/en/configure/app/bff/effect.mdx

@@ -123,13 +123,35 @@ export default defineConfig({
 }
 ```
 
-- **Default:** `{ enabled: true }`
+- **Default:**
+
+```ts
+{
+  enabled: true,
+  requireEnvelope: false,
+  envelopeHeader: 'x-modernjs-data-envelope',
+  validateOrigin: true,
+  requireTraceContext: false,
+  batch: {
+    enabled: true,
+    endpoint: '/_data/batch',
+    maxBatchSize: 16,
+    maxBatchBytes: 64 * 1024,
+    flushIntervalMs: 8,
+    maxConcurrency: 4,
+    requestTimeoutMs: 10000,
+    allowedMethods: ['GET'],
+  },
+}
+```
 
 Configure request-envelope validation for Effect runtime.
 
 Generated Effect client requests batching against `${bff.prefix}${batch.endpoint}` (for example, `/bff-api/_data/batch`).
 
-When `validateOrigin` is enabled, runtime compares envelope origin with request `Origin` header first, then falls back to request URL origin.
+Envelope validation is enabled by default but optional: requests without an envelope pass unless `requireEnvelope` is `true`. If an envelope is present, runtime validates it against the configured namespace, origin, trace, and selection policy. `expectedNamespace` is unset by default, and `selection` has no default limits unless configured.
+
+Origin validation is enabled by default. Runtime compares envelope origin with request `Origin` header first, then falls back to request URL origin; set `validateOrigin: false` to disable that comparison.
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -149,4 +171,6 @@ export default defineConfig({
 });
 ```
 
-`batch.flushIntervalMs` controls client-side micro-batch window in generated Effect client. `maxConcurrency` and `requestTimeoutMs` are applied by the server batch gateway when dispatching items.
+`batch.flushIntervalMs` controls the client-side micro-batch window in the generated Effect client. `maxConcurrency` and `requestTimeoutMs` are applied by the server batch gateway when dispatching items.
+
+The generated `effectBff.client.*` API only exists for loader-materialized `@api/effect/*` imports. Directly importing the server entry (`api/effect/index`) exposes the Effect BFF definition; its `client` property is a placeholder that fails on operation access.

package/docs/en/configure/app/performance/rsdoctor.mdx

@@ -11,22 +11,23 @@ type RsdoctorConfig =
   | boolean
   | {
       enabled?: boolean;
+      disableClientServer?: boolean;
     };
 ```
 
-- **Default:** `true` in production build, `false` in development mode.
+- **Default:** `undefined`, Rsdoctor is disabled unless this option is configured.
 
-Configure Rsdoctor diagnostics in Modern.js build.
+Configure Rsdoctor diagnostics in Modern.js build. Set this option to `true` to enable Rsdoctor:
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   performance: {
-    rsdoctor: false,
+    rsdoctor: true,
   },
 });
 ```
 
-You can also use object form:
+You can also use object form. When an object is provided, Rsdoctor is enabled unless `enabled` is set to `false`:
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -37,3 +38,5 @@ export default defineConfig({
   },
 });
 ```
+
+To disable Rsdoctor after enabling it in shared config, set `rsdoctor` to `false` or set `enabled` to `false`.

package/docs/en/configure/app/usage.mdx

@@ -86,8 +86,8 @@ export default defineConfig(({ env, command }) => ({
 This function accepts the following parameters:
 
 - `env`: Corresponds to the value of `process.env.NODE_ENV`.
-  - When running `ultramodern dev`, the value of `env` is `development`.
-  - When running `ultramodern build` or `ultramodern serve`, the value of `env` is `production`.
+  - When running `modern dev`, the value of `env` is `development`.
+  - When running `modern build` or `modern serve`, the value of `env` is `production`.
 - `command`: Corresponds to the current command being run, such as `dev`, `build`, or `serve`.
 
 #### Exporting Asynchronous Functions
@@ -117,8 +117,8 @@ For example, if you need to use the `modern.prod.config.js` file when executing
 ```json title="package.json"
 {
   "scripts": {
-    "dev": "ultramodern dev",
-    "build": "ultramodern build --config modern.prod.config.js"
+    "dev": "modern dev",
+    "build": "modern build --config modern.prod.config.js"
   }
 }
 ```
@@ -126,7 +126,7 @@ For example, if you need to use the `modern.prod.config.js` file when executing
 You can also abbreviate the `--config` option as `-c`:
 
 ```bash
-$ ultramodern build -c modern.prod.config.js
+$ modern build -c modern.prod.config.js
 ```
 
 ### Configuring in package.json (Not Recommended)
@@ -187,7 +187,7 @@ The configuration in the `modern.config.local.ts` file will be deeply merged wit
 
 When using `modern.config.local.ts`, please note the following:
 
-- The `modern.config.local.ts` file will only be loaded when executing the `ultramodern dev` commands and will not be loaded during `ultramodern build`.
+- The `modern.config.local.ts` file will only be loaded when executing the `modern dev` commands and will not be loaded during `modern build`.
 - The priority of the `modern.config.local.ts` file is higher than both `modern.config.ts` and the `modernConfig` field in `package.json`.
 - Since `modern.config.local.ts` is only used for local debugging, it is not recommended to commit it to the code repository. Ensure that the project's `.gitignore` file includes `modern.config.local.ts` and similar files.
 

package/docs/en/guides/advanced-features/bff/data-platform.mdx

@@ -55,12 +55,14 @@ export default defineConfig({
 });
 ```
 
-When `validateOrigin` is enabled, Effect runtime validates envelope origin against the incoming `Origin` header (if present), otherwise falls back to request URL origin.
+Envelope validation is enabled by default but does not require an envelope unless `requireEnvelope` is set. Origin validation is enabled by default; set `validateOrigin: false` to skip comparing the envelope origin against the incoming `Origin` header, or the request URL origin when the header is absent.
 
 ## Generated Effect client behavior
 
 When using the generated Effect client (`@api/effect/index`), Modern.js automatically attaches a serialized data envelope header (`x-modernjs-data-envelope`) for same-origin requests.
 
+The generated client is loader-materialized. Import it from `@api/effect/*` in browser or client-bundled code; direct imports of the server entry (`api/effect/index`) expose the Effect BFF definition and only provide a placeholder `client`.
+
 The envelope includes:
 
 - operation metadata

package/docs/en/guides/advanced-features/bff/frameworks.mdx

@@ -105,7 +105,7 @@ const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
 export default defineEffectBff({ api: bffEffectApi, layer });
 ```
 
-Call Effect endpoints from the browser via `@api/effect/index`:
+Call Effect endpoints from browser code via `@api/effect/index`:
 
 ```ts title="src/routes/page.tsx"
 import effectBff from '@api/effect/index';
@@ -113,6 +113,8 @@ import effectBff from '@api/effect/index';
 const response = await effectBff.client.hello.ping({});
 ```
 
+The `effectBff.client.*` surface is materialized by the BFF loader for `@api/effect/*` imports. Do not import `api/effect/index` directly and expect `client` to run in server code, scripts, or tests; direct entry imports expose the server runtime definition, and `client` is only a typed placeholder there.
+
 import Hono from '@site-docs-en/components/hono';
 
 <Hono />

package/docs/en/guides/advanced-features/international/api.mdx

@@ -20,7 +20,7 @@ title: API Reference
 | `isResourcesReady` | `boolean` | Whether translation resources for the current language have finished loading |
 | `i18nInstance` | `I18nInstance` | i18next instance for advanced scenarios |
 
-When `localePathRedirect` is enabled and `localisedUrls` is omitted, Modern.js treats localised URL paths as enabled. Route generation still requires every localisable path to define every configured language unless you set `localisedUrls: false`.
+When `localePathRedirect` is enabled and `localisedUrls` is omitted, Modern.js keeps prefix-only paths such as `/en/about`. Translated path segments are enabled only by a non-empty `localisedUrls` map. Route generation validates every localisable path and every configured language only while that map is enabled.
 
 ### Basic Usage
 

package/docs/en/guides/advanced-features/international/configuration.mdx

@@ -49,7 +49,7 @@ export default defineConfig({
 | `languages` | `string[]` | `[]` | Supported language list |
 | `fallbackLanguage` | `string` | `''` | Fallback language when detection fails |
 | `localePathRedirect` | `boolean` | `false` | Handles URL locale prefix recognition, redirects, and switching. See [Routing Integration](./routing.md#enable-locale-path-prefixes) |
-| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | `true` when `localePathRedirect` is enabled | Localised route path map. Every localisable route must define every configured language. Set `false` to keep locale prefixes without translating path segments. |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | Prefix-only behavior | Localised route path map. Only a non-empty map enables translated path segments; omitted, `true`, `false`, and `{}` keep locale prefixes without translating path segments. |
 | `i18nextDetector` | `boolean` | `false` | Enables the i18next detector (Cookie / Header, etc.) |
 | `detection` | `LanguageDetectorOptions` | - | Detailed i18next detector configuration. See [Locale Detection](./locale-detection.md) |
 | `ignoreRedirectRoutes` | `string[] \| Function` | - | Routes that skip redirects. See [Locale Detection](./locale-detection.md#ignoreredirectroutes) |

package/docs/en/guides/advanced-features/international/locale-detection.mdx

@@ -113,7 +113,7 @@ i18nPlugin({
 
 ## ignoreRedirectRoutes
 
-Specify which additional paths should skip locale path redirects. Modern.js automatically skips server API routes and BFF prefixes, including configured `bff.prefix` values. Use `ignoreRedirectRoutes` for non-API application paths that also do not need a locale prefix.
+Specify which additional paths should skip locale path redirects. Modern.js automatically skips server API routes, the default `/api` BFF prefix when BFF is configured, and custom `bff.prefix` values. Use `ignoreRedirectRoutes` for non-API application paths that also do not need a locale prefix.
 
 **Syntax 1: string array** (supports exact match and prefix match)
 

package/docs/en/guides/advanced-features/international/routing.mdx

@@ -32,11 +32,13 @@ i18nPlugin({
 | `/en/about` | Visits normally, language is `en` |
 | `/zh/about` | Visits normally, language is `zh` |
 
-API and BFF prefixes are skipped automatically, so server API routes do not need locale prefixes or `localisedUrls` entries. For additional application paths that should not redirect, use `ignoreRedirectRoutes`. See [Locale Detection -> ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes).
+API and BFF prefixes are skipped automatically, including server API routes, the default `/api` BFF prefix when BFF is configured, and custom `bff.prefix` values. Those routes do not need locale prefixes or `localisedUrls` entries. For additional application paths that should not redirect, use `ignoreRedirectRoutes`. See [Locale Detection -> ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes).
 
 ## Localised URL Paths
 
-When `localePathRedirect` is enabled, `localisedUrls` is enabled by default. This means every localisable route path must define a URL for every configured language. If you add a new language to `languages`, Modern.js will fail route generation until each localised URL entry includes that language too.
+`localePathRedirect` only adds and reads locale prefixes by default, for example `/en/about`. Translated path segments are opt-in: `localisedUrls` is enabled only when you provide a non-empty map. Omitting `localisedUrls`, setting it to `true`, setting it to `false`, or passing an empty object keeps prefix-only behavior.
+
+When a non-empty `localisedUrls` map is configured, every localisable route path must define a URL for every configured language. If you add a new language to `languages`, Modern.js will fail route generation until each localised URL entry includes that language too.
 
 `localisedUrls` applies to file-system routes generated for both React Router and TanStack Router projects. Do not configure localised URL entries for API routes, BFF prefixes, or configured `bff.prefix` values; those paths are excluded from locale redirects automatically.
 
@@ -73,7 +75,7 @@ i18nPlugin({
 | `/cs/terms-of-service` | Redirects to `/cs/podminky-pouzivani` |
 | `/cs/podminky-pouzivani` | Visits normally, language is `cs` |
 
-Set `localisedUrls: false` only when you want locale prefixes without translated path segments.
+Set `localisedUrls: false` as the escape hatch when a preset, shared config, or generated metadata would otherwise provide a map but this entry should keep locale prefixes without translated path segments.
 
 ## Route Configuration
 

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

@@ -2,14 +2,13 @@
 
 Rsdoctor is a Rspack build analysis tool. In Modern.js, we recommend using Rsdoctor to diagnose and analyze the build process and build outputs.
 
-Modern.js enables Rsdoctor by default for production builds.
+Modern.js does not enable Rsdoctor by default. Configure `performance.rsdoctor` when you want to run Rsdoctor for a build.
 
 ## Execute Build
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   performance: {
-    // Enabled by default in production build.
     rsdoctor: true,
   },
 });
@@ -21,7 +20,7 @@ npm run build
 
 ## Disable Rsdoctor
 
-If you want to disable Rsdoctor:
+If you want to disable Rsdoctor after enabling it in shared config:
 
 ```ts title="modern.config.ts"
 export default defineConfig({

package/docs/en/guides/basic-features/debug/using-storybook.mdx

@@ -55,7 +55,7 @@ Add the following scripts to `package.json` to start the BFF server and Storyboo
 ```json
 {
   "scripts": {
-    "dev:api": "ultramodern dev --api-only",
+    "dev:api": "modern dev --api-only",
     "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open",
   }
 }