@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.12 → 3.2.0-ultramodern.121

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

@@ -32,7 +32,50 @@ i18nPlugin({
 | `/en/about` | Visits normally, language is `en` |
 | `/zh/about` | Visits normally, language is `zh` |
 
-Some paths, such as API routes and static assets, do not need locale prefixes. Use `ignoreRedirectRoutes` to skip redirects. 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
+
+`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.
+
+```ts
+// modern.config.ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['en', 'cs'],
+    fallbackLanguage: 'en',
+    localisedUrls: {
+      '/terms-of-service': {
+        en: '/terms-of-service',
+        cs: '/podminky-pouzivani',
+      },
+      '/products': {
+        en: '/products',
+        cs: '/produkty',
+      },
+      '/products/:slug': {
+        en: '/products/:slug',
+        cs: '/produkty/:slug',
+      },
+    },
+  },
+});
+```
+
+**Result:**
+
+| Visited path | Result |
+| --- | --- |
+| `/terms-of-service` | Redirects to `/en/terms-of-service` |
+| `/cs/terms-of-service` | Redirects to `/cs/podminky-pouzivani` |
+| `/cs/podminky-pouzivani` | Visits normally, language is `cs` |
+
+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
 
@@ -131,4 +174,4 @@ function Navigation() {
 <I18nLink to="/en/about">About</I18nLink>
 ```
 
-`I18nLink` extends the `Link` component from `@modern-js/runtime/router` and supports all standard Link props such as `replace`, `state`, and `className`. For the full Props type, see [API Reference](./api.md#i18nlink-component).
+`I18nLink` uses the active Modern.js router. In React Router projects it renders the React Router `Link`; in TanStack Router projects it navigates through TanStack Router. For the full Props type, see [API Reference](./api.md#i18nlink-component).

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

@@ -39,7 +39,7 @@ Use the following command to build the project:
 npx modern deploy
 ```
 
-When running the `modern deploy` command, Modern.js will generate runnable products and output the following content in terminal:
+When running the `modern deploy` command, UltraModern.js will generate runnable products and output the following content in terminal:
 
 ```bash
 Static directory: `.output/static`

package/docs/en/guides/basic-features/render/_meta.json

@@ -1,10 +1 @@
-[
-  "overview",
-  "ssr",
-  "streaming-ssr",
-  "ssr-cache",
-  "ssg",
-  "rsc",
-  "tanstack-rsc",
-  "before-render"
-]
+["overview", "ssr", "streaming-ssr", "ssr-cache", "ssg", "rsc", "before-render"]

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

@@ -47,6 +47,5 @@ Modern.js supports combining multiple rendering modes:
 - [Server-Side Rendering (SSR)](/guides/basic-features/render/ssr)
 - [Streaming Server-Side Rendering (Streaming SSR)](/guides/basic-features/render/streaming-ssr)
 - [React Server Components (RSC)](/guides/basic-features/render/rsc)
-- [TanStack Router RSC](/guides/basic-features/render/tanstack-rsc)
 - [Static Site Generation (SSG)](/guides/basic-features/render/ssg)
 - [Rendering Cache](/guides/basic-features/render/ssr-cache)

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

@@ -531,4 +531,3 @@ The project's bundle has introduced a non-19 React version, commonly seen in mon
 - [Data Cache](/guides/basic-features/data/data-cache)
 - [Server-Side Rendering (SSR)](/guides/basic-features/render/ssr)
 - [Streaming SSR](/guides/basic-features/render/streaming-ssr)
-- [TanStack Router RSC](/guides/basic-features/render/tanstack-rsc)

package/docs/en/guides/basic-features/routes/routes.mdx

@@ -464,7 +464,7 @@ When defining a `loading.tsx`, if the route transitions from `/` to `/blog` or f
 
 ## Prefetching
 
-Most white screens during route transitions can be optimized by defining a `<Loading>` component. Modern.js also supports preloading static resources and data with the `prefetch` attribute on `<Link>` components.
+Most white screens during route transitions can be optimized by defining a `<Loading>` component. Modern.js also supports navigation warmup with the `prefetch` and `preload` attributes on `<Link>` components.
 
 For applications with higher performance requirements, prefetching can further enhance the user experience by reducing the time spent displaying the `<Loading>` component:
 
@@ -474,21 +474,36 @@ For applications with higher performance requirements, prefetching can further e
 
 :::tip
 
-Data preloading currently only preloads data returned by the [Data Loader](/guides/basic-features/data/data-fetch) in SSR projects.
+In SSR projects, same-origin route data returned by the [Data Loader](/guides/basic-features/data/data-fetch) is prefetched for matched routes with callable loaders. Set `handle.navigationWarmup.data` to `false` on a route when its loader data should not be requested before navigation.
 
 :::
 
-The `prefetch` attribute has three optional values:
+By default, same-origin links prefetch the route module and matching loader data when the `<Link>` renders. Modern.js skips these automatic warmups on Save-Data or slow network connections.
 
-- `none`: The default value. No prefetching, no additional behavior.
-- `intent`: This is the recommended value for most scenarios. When you hover over the Link, it will automatically start loading the corresponding chunk and the data defined in the Data Loader. If the mouse moves away, the loading is automatically canceled. In our tests, even quick clicks can reduce load time by approximately 200ms.
-- `render`: When the `<Link>` component is rendered, it begins loading the corresponding chunk and data defined in the Data Loader.
+The `prefetch` attribute has four optional values:
+
+- `render`: The default value. When the `<Link>` component is rendered, it begins warming the corresponding route module.
+- `intent`: When users focus, hover, or touch the link, it starts warming the corresponding route module. If the intent is canceled before warmup starts, the warmup is canceled.
+- `viewport`: When the `<Link>` component enters the viewport, it begins warming the corresponding route module.
+- `none`: Disables automatic prefetching. It also disables implicit preload unless an explicit `preload` value is provided.
+
+The `preload` attribute accepts the same timing values and defaults to the `prefetch` timing. Explicit `preload` values always win, and `preload={false}` disables preload behavior.
+
+To opt a route out of SSR data warmup:
+
+```ts title="routes/page.config.ts"
+export const handle = {
+  navigationWarmup: {
+    data: false,
+  },
+};
+```
 
 :::details Difference Between "render" and Not Using Route Splitting
 
-- `render` allows you to control the timing of route splitting, triggering only when the `<Link>` component enters the viewport. You can control the loading timing of the split by adjusting the rendering position of the `<Link>` component.
-- `render` loads static resources only during idle times, thus not occupying the loading time of critical modules.
-- Besides preloading route splits, `render` will also initiate data prefetching in SSR projects.
+- `render` allows you to control route-module warmup with the position of the `<Link>` component in the tree.
+- `viewport` lets you defer module warmup until the link is close to becoming actionable.
+- SSR data prefetching is enabled by default; use `handle.navigationWarmup.data = false` for routes whose loader data is not safe or useful to fetch before navigation.
 
 :::
 

package/docs/en/guides/basic-features/testing/_meta.json

@@ -1 +1 @@
-["playwright", "rstest", "vitest", "jest", "cypress"]
+["rstest", "playwright"]

package/docs/en/guides/concept/server.mdx

@@ -26,10 +26,10 @@ Static asset files can be directly hosted by Modern.js' server, but it is highly
 
 Modern.js supports running built artifacts in any Node.js environment. Typically, the CI environment has already installed all application dependencies.
 
-You can run the [`modern build`](/apis/app/commands#modern-build) command to build the application and the [`modern serve`](/apis/app/commands#modern-serve) command to run the Web server, starting the Modern.js application.
+You can run the [`modern build`](/apis/app/commands#modern-build) command to build the application and the [`modern serve`](/apis/app/commands#modern-serve) command to run the Web server, starting the UltraModern.js application.
 
 ## Running in Production Environments
 
 When deploying to production, the artifact size should be as small as possible. The aforementioned method for running in CI environments keeps all artifacts from the original project. Therefore, it is not recommended to run the application using the above commands in a production environment.
 
-Modern.js offers a standalone deployment solution. When running the [`modern deploy`](/apis/app/commands#modern-deploy) command, the artifacts will include an entry file for running the Web server.
+UltraModern.js offers a standalone deployment solution. When running the [`modern deploy`](/apis/app/commands#modern-deploy) command, the artifacts will include an entry file for running the Web server.

package/docs/en/guides/get-started/quick-start.mdx

@@ -27,7 +27,7 @@ import DebugApp from '@site-docs-en/components/debug-app';
 
 ## Configuration
 
-In a Modern.js project created using `@modern-js/create`, a `modern.config.ts` file is generated by default.
+In an UltraModern.js project created using `@bleedingdev/modern-js-create`, a `modern.config.ts` file is generated by default.
 
 You can modify the configuration through this file to override the default behavior of Modern.js. For example, to enable SSR, add the following configuration:
 

package/docs/en/guides/get-started/tech-stack.mdx

@@ -18,13 +18,13 @@ Rsbuild supports building Vue applications. If you need to use Vue, you can refe
 
 Modern.js provides two first-party routing frameworks:
 
-- [React Router v7](https://reactrouter.com/en/main) (default), via `@modern-js/runtime/router`.
-- [TanStack Router](https://tanstack.com/router), via `@modern-js/plugin-tanstack/runtime`.
+- [TanStack Router](https://tanstack.com/router) (UltraModern default), via `@modern-js/plugin-tanstack/runtime`.
+- [React Router v7](https://reactrouter.com/en/main) (compatibility path), via `@modern-js/runtime/router`.
 
-When creating a project, you can choose TanStack Router by using:
+When creating an UltraModern project, TanStack Router is included by default:
 
 ```bash
-npx @modern-js/create@latest myapp --router tanstack
+pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
 Modern.js supports conventional routing, self-controlled routing, or other routing schemes. Please refer to ["Routing"](/guides/basic-features/routes/routes) to make your choice.
@@ -84,6 +84,12 @@ Modern.js can be used with any React UI component library from the community, su
 
 Modern.js supports the use of [Storybook](https://storybook.js.org/) for developing UI components. This feature is optional. Please refer to ["Using Storybook"](/guides/basic-features/debug/using-storybook) to enable it.
 
+## Testing Framework
+
+Modern.js recommends [Rstest](https://rstest.rs/) for unit tests and component tests. Rstest is built on Rspack for fast startup and execution, and it can reuse your Modern.js app configuration through [`@modern-js/adapter-rstest`](/guides/basic-features/testing/rstest).
+
+For end-to-end (E2E) tests, you can use [Playwright](/guides/basic-features/testing/playwright).
+
 ## Node.js Framework
 
 import TechStackNodeFramework from '@site-docs-en/components/tech-stack-node-framework';

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

@@ -30,17 +30,17 @@ 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 |
 | Telemetry standardization | Observability wiring is often app-specific | Adds framework-level telemetry pipeline with OTLP/VictoriaMetrics exporters, redaction, batching, and backpressure controls |
 | App-level MF SSR handshake | No dedicated super-app app-level stability contract focus | Adds `server.ssr.moduleFederationAppSSR` plus integration-tested env/config handshake |
-| MF remote reliability | Retry/fallback patterns are often implemented per app | Adds deterministic timeout/network/contract-error reliability matrix and distributed OTEL continuity tests |
+| 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
 
@@ -56,25 +56,99 @@ For teams already on Modern.js 3.0, the adoption path remains compatibility-awar
 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.
 
-## Micro Vertical Delivery Path
-
-`presetUltramodern(...)` is also the single public entrypoint for Micro Verticals. The intended adoption sequence is:
-
-1. start with one app and keep route/data ownership inside the shell,
-2. extract stable route subtrees into MF remotes once fallback and compatibility behavior are explicit,
-3. extract shared workflows into strict Effect services when request, identity, locale, and trace context must survive deployment boundaries,
-4. keep Hono only as an explicit compatibility lane for existing Modern.js-style BFF handlers.
-
-In this repo, the reference examples are:
-
-- `routes-tanstack-mf` for shell + remote composition and MF SSR contracts,
-- `bff-corss-project` for cross-project producer/consumer wiring,
-- `bff-runtime-parity` for generated-client build/serve parity,
-- `bff-hono` for the compatibility lane.
+## 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 myapp
+cd myapp
+mise install
+mise exec -- pnpm install
+mise exec -- pnpm check
+```
+
+The workspace starts from a shell and generated platform contracts. It does not
+generate a demo domain by default. Add real business MicroVerticals when they
+become real ownership boundaries:
+
+```bash
+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 check
+```
+
+The `--vertical` command mutates the current workspace. It creates the vertical
+package and updates topology metadata, ownership records, shell Module
+Federation wiring, local development overlays, package dependencies, generated
+contracts, ports, route-owned i18n, CSS isolation, and the vertical-owned Effect
+BFF/client surface.
+
+### Runtime Contracts
+
+Generated apps and verticals keep SSR on the normal Modern.js path. SuperApp
+workspaces add `server.ssr.moduleFederationAppSSR` when Module Federation SSR is
+needed, but the flag remains an explicit contract rather than a requirement for
+every app.
+
+Each app emits `src/routes/ultramodern-route-metadata` with
+`ultramodernLocalisedUrls`. The i18n plugin reads that map in
+`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:
+
+- `packages/shared-design-tokens` owns the shared token layer and exports `./tokens.css`.
+- Shell CSS owns only shell base and overlay layers under `[data-app-id="shell-super-app"]`.
+- Each vertical owns one CSS layer, for example `[data-app-id="vertical-transportation"]` with app-local class prefixes.
+- Tailwind CSS v4 is local to each generated app through `@tailwindcss/postcss`; shared base styles must not be duplicated by verticals.
+- SSR first paint requires shared token CSS and app-owned CSS to be emitted by Modern/Rspack assets. Vertical CSS is loaded through manifest ownership, not copied into shell source.
+
+Version switching must select UI, Effect API, CSS, i18n JSON, and MF manifest evidence from the same vertical build marker. A shell render that only changes the UI marker is not enough.
+
+### Validation And Deploy
+
+Local gates:
+
+```bash
+mise exec -- pnpm check
+mise exec -- pnpm build
+mise exec -- pnpm cloudflare:build
+```
+
+Generated workspaces include `scripts/proof-cloudflare-version.mjs` for live
+Cloudflare and Zephyr proof:
+
+```bash
+ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_TRANSPORTATION=https://transportation.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_PAYMENTS=https://payments.example.workers.dev \
+mise exec -- pnpm cloudflare:proof -- --require-public-urls
+```
+
+Live Cloudflare and Zephyr proof requires public Worker URLs and Zephyr credentials. Without those, the repo can validate generated contracts, local builds, local Cloudflare output, dry-run Zephyr evidence plans, and local evidence schemas, but it cannot prove shell-driven live version selection.
+
+BleedingDev packages are published through GitHub Actions trusted publishing.
+The public workflow is tokenless; do not publish packages manually from a
+developer machine.
 
 ## Baseline Switches (Opt-out)
 

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

@@ -87,14 +87,14 @@ Modern.js 3.0 uses React Router v7 as the default routing library. React Router
 
 If you need to use React Router v5 or React Router v6, you need to use **self-controlled routing** mode. Self-controlled routing allows you to fully control routing configuration without being limited by Modern.js convention-based routing.
 
-## Using @modern-js/create to Create Monorepo and Modern.js Module
+## Using @bleedingdev/modern-js-create to Create Monorepo and Modern.js Module
 
-Modern.js 3.0 no longer supports creating Monorepo projects and Modern.js Module projects through `@modern-js/create`.
+Modern.js 3.0 no longer supports creating Monorepo projects and Modern.js Module projects through `@bleedingdev/modern-js-create`.
 
 **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 `@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 `@modern-js/create` and `modern new` commands was removed
+- 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 `modern new` commands was removed
 
 **Handling**:
 

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

@@ -4,9 +4,9 @@ sidebar_position: 1
 
 # 命令
 
-Modern.js 内置了一些命令，可以帮助你快速启动开发服务器、构建生产环境代码等。
+UltraModern.js 内置了一些命令，可以帮助你快速启动开发服务器、构建生产环境代码等。
 
-通过本章节，你可以了解到 Modern.js 内置的命令有哪些，以及如何使用这些命令。
+通过本章节，你可以了解到 UltraModern.js 内置的命令有哪些，以及如何使用这些命令。
 
 ## modern dev
 
@@ -23,7 +23,7 @@ Options:
   --api-only            仅启动 API 接口服务
 ```
 
-运行 `modern dev` 后，Modern.js 会监听源文件变化并进行模块热更新。
+运行 `modern dev` 后，UltraModern.js 会监听源文件变化并进行模块热更新。
 
 ```bash
 $ modern dev
@@ -80,77 +80,67 @@ Options:
   -w --watch  开启 watch 模式, 监听文件变更并重新构建
 ```
 
-## modern new
+## modern runtime status
 
-`modern new` 命令用于在已有项目中添加项目元素。
-
-比如添加应用入口、启用一些可选功能如 BFF、微前端开发模式等。
+`modern runtime status` 命令用于读取运行时状态端点并打印响应。默认请求 `http://127.0.0.1:8080/_modern/runtime/status`。
 
 ```bash
-Usage: modern 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 modern 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 modern 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 />
 
-## modern upgrade
-
-在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。
-
-```bash
-Usage: modern 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
-```
-
 ## modern inspect
 
-`modern inspect` 命令用于查看项目的 Modern.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: modern inspect [options]

package/docs/zh/community/blog/2022-0708-updates.md

@@ -17,7 +17,7 @@ Modern.js 7 ~ 8 月的最新版本为 v1.17.0，本双月的主要更新有：
 
 Modern.js 框架和相关插件完成对 React 18 的适配。现在，只需要将项目中的 `react`、`react-dom` 两个包的版本，升级到最新的 React 18 大版本，就可以使用 React 18 的新功能。
 
-注意，使用 `@modern-js/create` 命令默认创建的项目，安装的依赖 `react`、`react-dom` 的版本仍然为 17，如果希望使用 React 18，请手动升级这两个包的版本。
+注意，使用 `@bleedingdev/modern-js-create` 命令默认创建的项目，安装的依赖 `react`、`react-dom` 的版本仍然为 17，如果希望使用 React 18，请手动升级这两个包的版本。
 
 另外，SSR 流式渲染功能，目前尚在开发中，暂不支持。
 

package/docs/zh/community/blog/2022-0910-updates.md

@@ -15,7 +15,7 @@ Modern.js 9 ~ 10 月的最新版本为 v1.21.0，本双月的主要更新有：
 
 Modern.js 框架完成了对 pnpm v7 的变更适配。
 
-使用 `npx @modern-js/create@modern-1` 创建项目时会根据用户当前环境的 pnpm 版本进行安装依赖操作，并且在初始化项目中会在 `.npmrc` 中添加
+使用 `pnpm dlx @bleedingdev/modern-js-create` 创建项目时会根据用户当前环境的 pnpm 版本进行安装依赖操作，并且在初始化项目中会在 `.npmrc` 中添加
 `strict-peer-dependencies=false` 配置，避免安装时由于 `peerDependencies` 缺失导致安装依赖失败问题。
 同时适配 `release`、`deploy` 命令对 pnpm v7 的支持。
 
@@ -67,7 +67,7 @@ pnpm run command --options
 
 - husky 升级至 v8
 
-使用 `npx @modern-js/create@modern-1` 创建项目时，husky 会默认安装 v8 版本，并移除 `package.json` 中 husky 的配置，使用 `.husky` 文件夹的形式管理 husky 配置。
+使用 `pnpm dlx @bleedingdev/modern-js-create` 创建项目时，husky 会默认安装 v8 版本，并移除 `package.json` 中 husky 的配置，使用 `.husky` 文件夹的形式管理 husky 配置。
 
 在初次安装依赖时需要执行 `npx husky install` 进行 husky 初始化，默认项目会在 prepare 命令中完成，如果 husky 配置未生效，可通过手动执行完成 husky 配置。
 

package/docs/zh/community/contributing-guide.mdx

@@ -38,8 +38,7 @@ nvm use 22
 ### 安装 pnpm
 
 ```bash
-# 使用 corepack 启用 pnpm，仅在 Node.js >= `v14.19.0` 上可用
-corepack enable
+mise install
 ```
 
 ### 安装依赖
@@ -124,7 +123,7 @@ pnpm run reset
 
 如果你进行了 bugfix，或者添加了需要测试的代码，请添加一些测试代码。
 
-你可以在 `<PACKAGE_DIR>/tests` 文件夹中添加单元测试用例。测试语法基于 [Rstest](https://rstest.rs/)。
+Modern.js 仓库的单元测试统一使用 [Rstest](https://rstest.rs/)。你可以在 `<PACKAGE_DIR>/tests` 文件夹中添加测试用例，测试语法基于 Rstest。
 
 ### 运行单元测试
 

package/docs/zh/community/releases.mdx

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