@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.99 → 3.4.0-ultramodern.0

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

@@ -30,7 +30,7 @@ UltraModern.js additions are designed as the default product surface for new Sup
 
 | Area | Modern.js 3.0 baseline | UltraModern.js 3.0 |
 | --- | --- | --- |
-| Build diagnostics | RsDoctor is generally opt-in | Adds `performance.rsdoctor`, default-on diagnostics in production Rspack builds, and `.rsdoctor/ultramodern-diagnostics.json` contract artifact |
+| Build diagnostics | RsDoctor is generally opt-in | Adds a first-class `performance.rsdoctor` config surface (opt-in; the earlier default-on behavior and diagnostics contract artifact were reverted) |
 | Output and static serving | Precompression behavior is app-defined | Enables `output.precompress` by default and serves `.br` / `.gz` variants via `Accept-Encoding` negotiation |
 | BFF runtime and contracts | Standard BFF runtime/client generation | Adds `requestId`-aware producer isolation, fail-fast initialization checks, and operation/trace correlation headers |
 | BFF runtime choices | Hono runtime path only in Modern.js 3.0 baseline (no built-in Effect runtime path) | Sets Effect as default runtime, enforces strict runtime split (`effect` -> `api/effect`, `hono` -> `api/lambda`), and adds Effect-Schema-first contracts plus MF failure-injection reliability coverage |
@@ -39,8 +39,8 @@ UltraModern.js additions are designed as the default product surface for new Sup
 | MF vertical loading reliability | Retry/fallback patterns are often implemented per app | Adds deterministic timeout/network/contract-error reliability matrix and distributed OTEL continuity tests |
 | Module onboarding governance | No module-certification evidence profile in baseline | Adds module SDK contracts, boundary anti-pattern guards, and release/module certification gate workflows |
 | Router runtime | Default runtime path centers on React Router | Adds first-class TanStack Router runtime/CLI path (React Router remains supported) |
-| Scaffolding templates | Default create templates center on React Router starter path | Adds TanStack-ready and Tailwind-ready create templates |
-| Starter preset enforcement | No generated UltraModern preset gate workflow | Generated starters include `ultramodern:check`, opt-out env switches, and `.github/workflows/ultramodern-gates.yml` |
+| Scaffolding templates | Default create templates center on React Router starter path | Generates a SuperApp workspace by default with TanStack, Effect, Module Federation, i18n, Tailwind, Cloudflare, and ownership contracts |
+| Workspace preset enforcement | No generated UltraModern preset gate workflow | Generated workspaces include `.github/workflows/ultramodern-workspace-gates.yml`, `pnpm check`, primitive local gates, and generated contract validation |
 
 ## What We Intentionally Do Not Change
 
@@ -49,40 +49,55 @@ UltraModern.js additions are designed as the default product surface for new Sup
 - We keep both runtime modes (`effect`, `hono`) as explicit choices and avoid implicit fallback between them.
 - We avoid incompatible API changes unless there is a hard reliability requirement.
 
-## Adoption Notes
+## Migration Guide
 
-For teams already on Modern.js 3.0, the adoption path remains compatibility-aware: keep the pieces that reduce risk, move toward MV-first / TanStack-first / Effect-first defaults, and keep fallback lanes explicit while you adopt UltraModern.js 3.0 as a separate framework.
+For teams already on Modern.js 3.0 or an older BleedingDev UltraModern scaffold, the adoption path remains compatibility-aware: keep the pieces that reduce risk, move toward MV-first / TanStack-first / Effect-first defaults, and keep fallback lanes explicit while you adopt UltraModern.js 3.0 as a separate framework.
 
 1. Keep existing React Router apps running as-is. TanStack Router is the preferred path for new scaffolds and incremental route adoption, but the React Router lane remains supported while teams move on their own schedule.
 2. Prefer `bff.runtimeFramework: 'effect'` for new BFF work, with the entry implemented at `api/effect/index.ts`. If your app already uses Hono handlers under `api/lambda/**`, keep `bff.runtimeFramework: 'hono'` until you are ready to move them; Hono remains a supported compatibility lane.
 3. Treat the baseline contracts as progressive defaults, not a forced cutover. `MODERN_BASELINE_ENABLE_MF_SSR`, `MODERN_BASELINE_ENABLE_BFF_REQUEST_ID`, and `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` already let each app opt out while it converges on the preferred stack.
-4. The public preset now ships with explicit release and certification gates. The generated starter also ships `.github/workflows/ultramodern-gates.yml`, so `pnpm run ultramodern:check` and `pnpm run build` stay part of the adoption contract from day one.
+4. The public preset now ships with explicit release and certification gates. Generated workspaces include `.github/workflows/ultramodern-workspace-gates.yml`, so `pnpm check` and `pnpm build` stay part of the local adoption contract from day one while CI runs the primitive gates as parallel matrix jobs.
 
-This page is not a migration guide or codemod plan. Migration guidance for existing applications is intentionally deferred from the current Micro Verticals framework scope.
-
-## Human Workflow
-
-The public BleedingDev create package starts small. The default command creates
-one production-ready UltraModern app with `presetUltramodern(...)`, SSR,
-TanStack Router, Tailwind CSS v4, i18n, Effect BFF, generated quality gates, and
-Cloudflare deploy basics:
+For an older generated workspace, migrate by treating the published cohort as
+the source of truth:
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create myapp
-cd myapp
+pnpm dlx @bleedingdev/modern-js-create@latest --help
+pnpm dlx @bleedingdev/modern-js-create@latest catalog --vertical --dry-run
+pnpm dlx @bleedingdev/modern-js-create@latest catalog --vertical
 mise install
 mise exec -- pnpm install
-mise exec -- pnpm ultramodern:check
+mise exec -- pnpm check
+mise exec -- pnpm build
 ```
 
-Create a SuperApp workspace only when independent ownership is useful:
+Use one package-source strategy per repo. The published BleedingDev create
+package defaults to `--ultramodern-package-source=install` and records the
+exact cohort in `.modernjs/ultramodern-package-source.json`. Keep `--workspace`
+only for local monorepo testing against unreleased packages. Release proof and
+CI should pin the exact cohort with `--ultramodern-package-version` when a
+repo must prove a specific published framework version.
+
+After installing the new cohort, run the generated
+`scripts/validate-ultramodern-workspace.mjs` contract check before accepting
+manual edits. Fix topology, ownership, package-source, local overlay, generated
+contract, Tailwind prefix, or Module Federation conflicts in the owning files
+instead of patching generated output by hand.
+
+## Human Workflow
+
+The public BleedingDev create package has one supported generated product. The
+default command creates a production-ready UltraModern SuperApp workspace with
+`presetUltramodern(...)`, SSR, TanStack Router, Tailwind CSS v4, i18n, Effect
+BFF, Module Federation topology, generated quality gates, and Cloudflare deploy
+basics:
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
-cd my-super-app
+pnpm dlx @bleedingdev/modern-js-create myapp
+cd myapp
 mise install
 mise exec -- pnpm install
-mise exec -- pnpm ultramodern:check
+mise exec -- pnpm check
 ```
 
 The workspace starts from a shell and generated platform contracts. It does not
@@ -94,7 +109,7 @@ pnpm dlx @bleedingdev/modern-js-create transportation --vertical
 pnpm dlx @bleedingdev/modern-js-create food-delivery --vertical
 pnpm dlx @bleedingdev/modern-js-create payments --vertical
 pnpm dlx @bleedingdev/modern-js-create maps --vertical
-mise exec -- pnpm ultramodern:check
+mise exec -- pnpm check
 ```
 
 The `--vertical` command mutates the current workspace. It creates the vertical
@@ -103,6 +118,94 @@ Federation wiring, local development overlays, package dependencies, generated
 contracts, ports, route-owned i18n, CSS isolation, and the vertical-owned Effect
 BFF/client surface.
 
+### Generator Automation
+
+Automation can use explicit MicroVertical syntax instead of relying on the
+positional form:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create --vertical=transportation
+pnpm dlx @bleedingdev/modern-js-create --vertical-name transportation
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical --dry-run
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical \
+  --codesmith-overlay ./generators/vertical-overlay
+```
+
+The BleedingDev package defaults to installing the published package cohort.
+Use `--workspace` or `--ultramodern-package-source=workspace` for local monorepo
+testing. Release proof and package-source automation can also pass
+`--ultramodern-package-source=install`,
+`--ultramodern-package-version`, `--ultramodern-package-registry`,
+`--ultramodern-package-scope`, and
+`--ultramodern-package-name-prefix`.
+
+The supported public generator import is:
+
+```ts
+import {
+  addUltramodernVertical,
+  generateUltramodernWorkspace,
+  planUltramodernVertical,
+} from '@modern-js/create/ultramodern-workspace';
+
+const workspace = generateUltramodernWorkspace({
+  targetDir: '/tmp/my-workspace',
+  packageName: 'my-workspace',
+  modernVersion: '3.4.0',
+});
+
+const plan = planUltramodernVertical({
+  workspaceRoot: workspace.workspaceRoot,
+  name: 'transportation',
+  modernVersion: '3.4.0',
+});
+
+addUltramodernVertical({
+  workspaceRoot: workspace.workspaceRoot,
+  name: 'transportation',
+  modernVersion: '3.4.0',
+  overlays: [{ generator: './generators/vertical-overlay' }],
+});
+```
+
+The public result includes the workspace root, package source, created apps,
+created paths, rewritten paths, assigned ports, Module Federation names, Effect
+API prefixes, generated contract path, and warnings. MicroVertical dry-run
+returns the same shape plus `dryRun`, `selectedPort`, `moduleFederationRemote`,
+`effectApiPrefix`, `jsonMutations`, `shellDependencyChanges`, and
+`generatedContractChanges`; it prints JSON from the CLI and writes no files.
+
+CodeSmith consumers can use the adapter subpath:
+
+```ts
+import ultramodernCodeSmith from '@modern-js/create/ultramodern-workspace/codesmith';
+
+await ultramodernCodeSmith({
+  config: {
+    mode: 'vertical',
+    name: 'transportation',
+    workspaceRoot: process.cwd(),
+    dryRun: true,
+    logResult: true,
+  },
+});
+```
+
+Validation runs before the first write and reports the owning contract when a
+vertical name is missing or invalid, an existing topology already owns the app
+ID/path/package suffix/port/Module Federation name/API prefix/manifest key, a
+workspace JSON contract is missing or not an object, or a Tailwind prefix would
+collide. Fix the workspace contract or choose a different vertical name before
+rerunning.
+
+Overlays are explicit CodeSmith generators that run after base workspace or
+MicroVertical generation. They extend generated output; they do not replace,
+inherit, or shadow the base templates. The generator and CodeSmith adapter are
+plain Node generator surfaces. The package build emits declaration files through
+the TS-Go toolchain. Generated app packages install the TypeScript 7 RC package
+line and use TS-Go only for local tooling; runtime code does not depend on
+native-preview compiler internals.
+
 ### Runtime Contracts
 
 Generated apps and verticals keep SSR on the normal Modern.js path. SuperApp
@@ -112,9 +215,15 @@ every app.
 
 Each app emits `src/routes/ultramodern-route-metadata` with
 `ultramodernLocalisedUrls`. The i18n plugin reads that map in
-`localeDetection.localisedUrls` and serves dynamic backend JSON from
-`/locales/{{lng}}/{{ns}}.json`. The route owner changes localized paths and
-locale resource JSON together.
+`localeDetection.localisedUrls`; this is the explicit non-empty map that enables
+translated path segments on top of `localePathRedirect`. The i18n plugin also
+serves dynamic backend JSON from `/locales/{{lng}}/{{ns}}.json`. The route owner
+changes localized paths and locale resource JSON together.
+
+JSON-LD is optional route metadata, not inferred output. Private and
+non-indexable routes emit no JSON-LD by default. Public route owners can add
+`jsonLd` beside localized paths and use the generated
+`src/routes/ultramodern-jsonld.ts` helpers for common schema.org shapes.
 
 The generated contract writes `.modernjs/ultramodern-generated-contract.json`
 with a `cssFederation` section:
@@ -132,7 +241,7 @@ Version switching must select UI, Effect API, CSS, i18n JSON, and MF manifest ev
 Local gates:
 
 ```bash
-mise exec -- pnpm ultramodern:check
+mise exec -- pnpm check
 mise exec -- pnpm build
 mise exec -- pnpm cloudflare:build
 ```

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

@@ -103,7 +103,7 @@ export default RemoteApp;
 
 ## Start the Application
 
-Now, both the producer and consumer applications are set up. We can run `ultramodern dev` locally to start both applications.
+Now, both the producer and consumer applications are set up. We can run `modern dev` locally to start both applications.
 
 After startup, when the consumer application accesses the `/remote` route, it will enter the producer application. Accessing `http://localhost:8080/remote` will display a complete page of the producer's remote module in the browser.
 

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

@@ -88,10 +88,10 @@ export default createModuleFederationConfig({
 
 ## Local Deployment Verification
 
-Modern.js provides the `ultramodern deploy` command, which can easily generate products that can run in a Node.js environment.
+Modern.js provides the `modern deploy` command, which can easily generate products that can run in a Node.js environment.
 
 ```bash
-ultramodern deploy
+modern deploy
 ```
 
 After executing the command, you can see the following output in the console:

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

@@ -154,7 +154,7 @@ The second part, `remoteExpose`, is the `key` configured in the `exposes` field
 
 ## Start the Applications
 
-Now, both the producer and consumer applications are set up. You can run `ultramodern dev` locally to start both applications.
+Now, both the producer and consumer applications are set up. You can run `modern dev` locally to start both applications.
 
 Once started, the imports of the producer's modules in the consumer will no longer throw errors, and the types will be downloaded to the consumer application.
 
@@ -164,7 +164,7 @@ After modifying the producer's code, the consumer will automatically fetch the p
 
 Access `http://localhost:8080/remote`, and you will see that the page includes the `Button` component from the producer's remote module.
 
-We can also execute `ultramodern serve` locally to simulate the production environment.
+We can also execute `modern serve` locally to simulate the production environment.
 
 Because the Module Federation plugin will automatically read Modern.js's `output.assetPrefix` configuration as the access address for remote modules, and this value defaults to `/` after building in the production environment.
 
@@ -180,7 +180,7 @@ export default defineConfig({
     port: 3051,
   },
   output: {
-    // Now this configuration is only used in the local when you run ultramodern serve command.
+    // Now this configuration is only used in the local when you run modern serve command.
     // If you want to deploy the application to the platform, use your own domain name.
     // Module federation will automatically write it to mf-manifest.json, which influences consumer to fetch remoteEntry.js.
     assetPrefix: 'http://127.0.0.1:3051',
@@ -189,10 +189,10 @@ export default defineConfig({
 });
 ```
 
-Now, in the producer, run `ultramodern build && MODERN_MF_AUTO_CORS=true  ultramodern serve`, and in the consumer, run `ultramodern build && ultramodern serve` to simulate the production environment locally and access the remote modules.
+Now, in the producer, run `modern build && MODERN_MF_AUTO_CORS=true  modern serve`, and in the consumer, run `modern build && modern serve` to simulate the production environment locally and access the remote modules.
 
 :::tip
-When using the `ultramodern 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.
+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).

package/docs/en/guides/troubleshooting/builder.mdx

@@ -23,7 +23,7 @@ Modern.js is internally based on [Rsbuild](https://v2.rsbuild.rs/) and encapsula
 Modern.js provides [inspect command](https://modernjs.dev/en/apis/app/commands.html) to view the final Modern.js configuration and Rspack configuration generated by the project.
 
 ```bash
-➜ npx ultramodern inspect
+➜ npx modern inspect
 
 Inspect config succeed, open following files to view the content:
 

package/docs/en/guides/upgrade/config.mdx

@@ -334,7 +334,7 @@ export default {
 
 ### tools.rsdoctor
 
-**Change**: This configuration has been deprecated. In v3, Modern.js enables Rsdoctor by default in production build. Use [`performance.rsdoctor`](/configure/app/performance/rsdoctor) to configure or disable it.
+**Change**: This configuration has been deprecated. In v3, use [`performance.rsdoctor`](/configure/app/performance/rsdoctor) to opt in to Rsdoctor diagnostics.
 
 **Migration Example**:
 
@@ -350,7 +350,6 @@ tools: {
 // v3
 export default {
   performance: {
-    // enabled by default in production build
     rsdoctor: {
       enabled: true,
     },

package/docs/en/guides/upgrade/other.mdx

@@ -94,7 +94,7 @@ Modern.js 3.0 no longer supports creating Monorepo projects and Modern.js Module
 **Changes**:
 
 - In [v2.53.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.53.0), the functionality to create Monorepo projects using `@bleedingdev/modern-js-create` was removed
-- In [v2.61.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.61.0), the functionality to create Modern.js Module projects using `@bleedingdev/modern-js-create` and `ultramodern new` commands was removed
+- In [v2.61.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.61.0), the functionality to create Modern.js Module projects using `@bleedingdev/modern-js-create` and `modern new` commands was removed
 
 **Handling**:
 
@@ -103,12 +103,12 @@ Modern.js 3.0 no longer supports creating Monorepo projects and Modern.js Module
 
 ## new and upgrade Commands Removed
 
-Modern.js 3.0 removed the `ultramodern new` and `ultramodern upgrade` commands, and you need to perform operations manually according to the documentation.
+Modern.js 3.0 removed the `modern new` and `modern upgrade` commands, and you need to perform operations manually according to the documentation.
 
 **Changes**:
 
-- The `ultramodern new` command is no longer supported in Modern.js 3.0, and you cannot add entries or enable features through commands
-- The `ultramodern upgrade` command is no longer supported in Modern.js 3.0, and you cannot automatically upgrade dependencies through commands
+- The `modern new` command is no longer supported in Modern.js 3.0, and you cannot add entries or enable features through commands
+- The `modern upgrade` command is no longer supported in Modern.js 3.0, and you cannot automatically upgrade dependencies through commands
 
 **Handling**:
 

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

@@ -8,12 +8,12 @@ UltraModern.js 内置了一些命令，可以帮助你快速启动开发服务
 
 通过本章节，你可以了解到 UltraModern.js 内置的命令有哪些，以及如何使用这些命令。
 
-## ultramodern dev
+## modern dev
 
-`ultramodern dev` 命令用于启动一个本地开发服务器，对源代码进行开发环境编译。
+`modern dev` 命令用于启动一个本地开发服务器，对源代码进行开发环境编译。
 
 ```bash
-Usage: ultramodern dev [options]
+Usage: modern dev [options]
 
 Options:
   -e --entry <entry>    指定入口，只编译特定的页面
@@ -23,10 +23,10 @@ Options:
   --api-only            仅启动 API 接口服务
 ```
 
-运行 `ultramodern dev` 后，UltraModern.js 会监听源文件变化并进行模块热更新。
+运行 `modern dev` 后，UltraModern.js 会监听源文件变化并进行模块热更新。
 
 ```bash
-$ ultramodern dev
+$ modern dev
 
 info    Starting dev server...
 
@@ -38,10 +38,10 @@ info    Starting dev server...
 
 在多页面（MPA）项目中，可以添加 `--entry` 参数来指定编译其中的一个或多个页面。这样可以只编译项目中的部分代码，从而提升 dev 启动速度。
 
-比如执行 `ultramodern dev --entry`，在命令行界面中会展示入口选择框：
+比如执行 `modern dev --entry`，在命令行界面中会展示入口选择框：
 
 ```bash
-$ ultramodern dev --entry
+$ modern dev --entry
 
 ? 请选择需要构建的入口
 ❯ ◯ foo
@@ -57,22 +57,22 @@ $ ultramodern dev --entry
 
 ```bash
 # 编译 foo 页面
-ultramodern dev --entry foo
+modern dev --entry foo
 
 # 编译 foo 和 bar 页面
-ultramodern dev --entry foo,bar
+modern dev --entry foo,bar
 ```
 
-## ultramodern start
+## modern start
 
-`ultramodern start` 是 `ultramodern dev` 命令的别名，两者的功能和用法完全一致。
+`modern start` 是 `modern dev` 命令的别名，两者的功能和用法完全一致。
 
-## ultramodern build
+## modern build
 
-`ultramodern build` 命令默认会在 `dist/` 目录下构建出可用于生产环境的产物。你可以通过修改配置 [`output.distPath`](/configure/app/output/dist-path) 指定产物的输出目录。
+`modern build` 命令默认会在 `dist/` 目录下构建出可用于生产环境的产物。你可以通过修改配置 [`output.distPath`](/configure/app/output/dist-path) 指定产物的输出目录。
 
 ```bash
-Usage: ultramodern build [options]
+Usage: modern build [options]
 
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
@@ -80,80 +80,70 @@ Options:
   -w --watch  开启 watch 模式, 监听文件变更并重新构建
 ```
 
-## ultramodern new
+## modern runtime status
 
-`ultramodern new` 命令用于在已有项目中添加项目元素。
-
-比如添加应用入口、启用一些可选功能如 BFF、微前端开发模式等。
+`modern runtime status` 命令用于读取运行时状态端点并打印响应。默认请求 `http://127.0.0.1:8080/_modern/runtime/status`。
 
 ```bash
-Usage: ultramodern new [options]
+Usage: modern runtime status [options]
 
 Options:
-  --config-file <configFile>  指定配置文件路径，可以为相对路径或绝对路径
-  --lang <lang>          设置 new 命令执行语言(zh 或者 en)
-  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
-  -c, --config <config>  生成器运行默认配置(JSON 字符串)
-  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
-  --registry             生成器运行过程中定制 npm Registry
+  --endpoint <endpoint>  运行时状态端点 URL 或路径
+  --token <token>        运行时状态鉴权 Token
+  --token-env <name>     保存运行时状态鉴权 Token 的环境变量名称 (default: "MODERN_RUNTIME_SIGNAL_TOKEN")
+  --header-name <name>   鉴权请求头名称 (default: "x-modernjs-runtime-signal-token")
+  --timeout <ms>         请求超时时间，单位毫秒 (default: "5000")
+  --json                 以 JSON 格式输出，便于机器读取
   -h, --help             显示命令帮助
 ```
 
-### 添加入口
+如果 `--endpoint` 是路径，命令会基于 `http://127.0.0.1:8080` 解析该路径。如果省略 `--token`，命令会从 `--token-env` 指定的环境变量中读取 Token。
 
-在 Modern.js 工程中，执行 `new` 命令添加入口的步骤如下：
+默认情况下，命令会将响应格式化为可读的键值行。添加 `--json` 后会打印原始 JSON 载荷。
 
 ```bash
-$ npx ultramodern new
-? 请选择你想要的操作 创建工程元素
-? 请选择创建元素类型 新建「应用入口」
-? 请填写入口名称 entry
+modern runtime status --json
 ```
 
-### 启用可选功能
+## modern runtime fallback-signal
 
-在 Modern.js 工程中，执行 `new` 命令启用可选能力的步骤如下：
+`modern runtime fallback-signal` 命令用于向金丝雀 contract-gate 端点发送运行时 fallback 信号。默认请求 `http://127.0.0.1:8080/_modern/contract-gates/runtime-fallback`。
 
 ```bash
-$ npx ultramodern new
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 (Use arrow keys)
-❯ 启用「BFF」功能
-  启用「微前端」模式
-```
+Usage: modern runtime fallback-signal [options]
 
-:::tip
-`--config` 参数对应参数值需要使用 JSON 字符串。
+Options:
+  --app <appName>          远程应用名称
+  --endpoint <endpoint>    运行时 fallback 信号端点 URL 或路径
+  --reason <reason>        fallback 原因 (default: "runtime_fallback")
+  --phase <phase>          fallback 阶段 (default: "load")
+  --entry <entry>          远程入口 URL
+  --runtime-digest <digest>  运行时 digest 值
+  --metadata <json>        metadata JSON 对象字符串
+  --token <token>          运行时信号鉴权 Token
+  --token-env <name>       保存运行时信号鉴权 Token 的环境变量名称 (default: "MODERN_RUNTIME_SIGNAL_TOKEN")
+  --header-name <name>     鉴权请求头名称 (default: "x-modernjs-runtime-signal-token")
+  --timeout <ms>           请求超时时间，单位毫秒 (default: "5000")
+  --json                   以 JSON 格式输出，便于机器读取
+  -h, --help               显示命令帮助
+```
 
-pnpm 暂不支持使用 JSON 字符串作为参数值，可使用 `npm new` 开启相关功能。【[相关 Issue](https://github.com/pnpm/pnpm/issues/3876)】
+请求体始终包含 `appName`、`reason` 和 `phase`。只有在提供对应选项时，才会包含 `entry`、`runtimeDigest` 和 `metadata`。`--metadata` 必须是 JSON 对象字符串。
 
-:::
+```bash
+modern runtime fallback-signal --app crm-shell --reason remote_load_failed --phase load --json
+```
 
 import ServeCommand from '@site-docs/components/serve-command';
 
 <ServeCommand />
 
-## ultramodern upgrade
-
-在项目根目录下执行命令 `npx ultramodern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 UltraModern.js 相关依赖更新至最新版本。
-
-```bash
-Usage: ultramodern upgrade [options]
-
-Options:
-  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
-  --registry <registry>  定制 npm registry (default: "")
-  -d,--debug             开启 Debug 模式，打印调试日志信息 (default: false)
-  --cwd <cwd>            项目路径 (default: "")
-  -h, --help             display help for command
-```
-
-## ultramodern inspect
+## modern inspect
 
-`ultramodern inspect` 命令用于查看项目的 UltraModern.js 配置、[Rsbuild 配置](https://v2.rsbuild.rs/zh/config/index) 以及 Rspack 配置。
+`modern inspect` 命令用于查看项目的 UltraModern.js 配置、[Rsbuild 配置](https://v2.rsbuild.rs/zh/config/index) 以及 Rspack 配置。
 
 ```bash
-Usage: ultramodern inspect [options]
+Usage: modern inspect [options]
 
 Options:
   --env <env>           查看指定环境下的配置 (default: "development")
@@ -163,14 +153,14 @@ Options:
   -h, --help            显示命令帮助
 ```
 
-在项目根目录下执行命令 `npx ultramodern inspect` 后，会在项目的 `dist` 目录生成以下文件：
+在项目根目录下执行命令 `npx modern inspect` 后，会在项目的 `dist` 目录生成以下文件：
 
 - `modern.js.config.mjs`: 表示当前使用的 Modern.js 配置。
 - `rsbuild.config.mjs`: 表示在构建时使用的 Rsbuild 配置。
 - `rspack.config.web.mjs`: 表示在构建时使用的 Rspack 配置。
 
 ```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:
 默认情况下，inspect 命令会输出开发环境的配置，你可以添加 `--env production` 选项来输出生产环境的配置：
 
 ```bash
-ultramodern inspect --env production
+modern inspect --env production
 ```
 
 ### 完整内容
@@ -192,7 +182,7 @@ ultramodern inspect --env production
 默认情况下，inspect 命令会省略配置对象中的函数内容，你可以添加 `--verbose` 选项来输出函数的完整内容：
 
 ```bash
-ultramodern inspect --verbose
+modern inspect --verbose
 ```
 
 ### SSR 构建配置
@@ -200,7 +190,7 @@ ultramodern inspect --verbose
 如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `rspack.config.node.mjs` 文件，对应 SSR 构建时的 Rspack 配置。
 
 ```bash
-➜ npx ultramodern inspect
+➜ npx modern inspect
 
 Inspect config succeed, open following files to view the content:
 

package/docs/zh/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/zh/community/blog/v3-release-note.mdx

@@ -338,7 +338,7 @@ export default defineRoutes(({ route, layout, page }) => {
 
 #### 路由调试
 
-运行 `npx ultramodern routes` 命令即可在 `dist/routes-inspect.json` 文件中生成完整的路由结构分析报告。
+运行 `npx modern routes` 命令即可在 `dist/routes-inspect.json` 文件中生成完整的路由结构分析报告。
 
 报告中会显示每个路由的路径、组件文件、数据加载器、错误边界、Loading 组件等完整信息，帮助开发者快速了解项目的路由配置，快速定位和排查路由相关问题。结构化的 JSON 格式也便于 AI agent 理解和分析路由结构，提升 AI 辅助开发的效率。
 

package/docs/zh/community/releases.mdx

@@ -24,8 +24,4 @@ Modern.js 遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/) 语义化
 
 ## 版本升级
 
-当你需要升级项目中的 Modern.js 版本时，可以使用 `ultramodern upgrade` 命令，参考 [版本升级](/guides/get-started/upgrade)。
-
-```bash
-npx ultramodern upgrade
-```
+Modern.js 3.0 不再提供 `modern upgrade` 命令。需要升级项目时，请按照[版本升级](/guides/get-started/upgrade)中的手动迁移步骤操作。

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

@@ -3,7 +3,7 @@
 ```bash
 $ pnpm run build
 
-> ultramodern build
+> modern build
 
   Modern.js Framework
 

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

@@ -3,7 +3,7 @@
 ```bash
 $ pnpm run dev
 
-> ultramodern dev
+> modern dev
 
   Modern.js Framework