@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.11 → 3.2.0-ultramodern.111

package/docs/zh/guides/basic-features/deploy.mdx

@@ -15,11 +15,11 @@ sidebar_position: 15
 
 ## 构建部署产物
 
-执行 `modern deploy` 命令将自动输出部署产物。此过程包括优化 Bundler 构建产物及产物依赖，检测当前部署平台，并自动生成可以在该平台运行的产物。
+执行 `ultramodern deploy` 命令将自动输出部署产物。此过程包括优化 Bundler 构建产物及产物依赖，检测当前部署平台，并自动生成可以在该平台运行的产物。
 如果你希望在本地生成并测试特定部署平台的产物，可以通过设置环境变量来指定平台：
 
 ```bash
-MODERNJS_DEPLOY=netlify npx modern deploy
+MODERNJS_DEPLOY=netlify npx ultramodern deploy
 ```
 
 :::info
@@ -35,10 +35,10 @@ MODERNJS_DEPLOY=netlify npx modern deploy
 你可以使用以下命令构建项目：
 
 ```bash
-npx modern deploy
+npx ultramodern deploy
 ```
 
-当执行 `modern deploy` 命令时，Modern.js 将生成可执行的部署产物，并在控制台输出以下内容：
+当执行 `ultramodern deploy` 命令时，UltraModern.js 将生成可执行的部署产物，并在控制台输出以下内容：
 
 ```bash
 Static directory: `.output/static`
@@ -66,7 +66,7 @@ PORT=3000 node .output/index
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && modern deploy"
+    "deploy": "pnpm run build:packages && ultramodern deploy"
   }
 }
 ```
@@ -77,7 +77,7 @@ PORT=3000 node .output/index
 {
   "scripts": {
     "build:packages": "rush rebuild --to-except app",
-    "deploy": "rushx build:packages && modern deploy"
+    "deploy": "rushx build:packages && ultramodern deploy"
   }
 }
 ```
@@ -105,7 +105,7 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 ```toml
 [build]
   publish = "dist"
-  command = "modern deploy"
+  command = "ultramodern deploy"
 ```
 
 :::info
@@ -121,7 +121,7 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 ```toml title="netlify.toml"
 [build]
   publish = "dist"
-  command = "modern deploy"
+  command = "ultramodern deploy"
 
 [functions]
   directory = ".netlify/functions"
@@ -167,7 +167,7 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && modern deploy"
+    "deploy": "pnpm run build:packages && ultramodern deploy"
   }
 }
 ```
@@ -207,7 +207,7 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 
 ```json title="vercel.json"
 {
-  "buildCommand": "modern deploy",
+  "buildCommand": "ultramodern deploy",
   "outputDirectory": ".vercel/output"
 }
 ```
@@ -272,7 +272,7 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && modern deploy"
+    "deploy": "pnpm run build:packages && ultramodern deploy"
   }
 }
 ```
@@ -311,12 +311,12 @@ Github Pages 支持两种部署方式，通过分支部署或通过 Github Actio
 
 1. 在 github 仓库中，选择 `Settings > Pages > Source > Deploy from a branch`。
 2. 安装 `gh-pages` 依赖作为开发依赖。
-3. 在 package.json 的 `scripts` 中添加 `"deploy:gh-pages": "MODERNJS_DEPLOY=ghPages modern deploy && gh-pages -d .output"`。
+3. 在 package.json 的 `scripts` 中添加 `"deploy:gh-pages": "MODERNJS_DEPLOY=ghPages ultramodern deploy && gh-pages -d .output"`。
 4. 执行 `npm run deploy:gh-pages`。
 
 :::info
 
-1. 执行 `MODERNJS_DEPLOY=ghPages modern deploy`，Modern.js 会把可用于 github 部署的产物构建到 `.output` 目录。
+1. 执行 `MODERNJS_DEPLOY=ghPages ultramodern deploy`，UltraModern.js 会把可用于 github 部署的产物构建到 `.output` 目录。
 2. 可以参考项目[示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
 
 :::

package/docs/zh/guides/basic-features/env-vars.mdx

@@ -16,8 +16,8 @@ Modern.js 提供了对环境变量的支持，包含内置的环境变量和自
 
 表示当前的执行环境，是**只读的**的环境变量，其值在不同的执行命令下具有不同的值：
 
-- `production`：执行 `modern build`、`modern serve` 命令时的默认值。
-- `development`：执行 `modern dev` 命令时的默认值，同时也是其他所有情况下的默认值。
+- `production`：执行 `ultramodern build`、`ultramodern serve` 命令时的默认值。
+- `development`：执行 `ultramodern dev` 命令时的默认值，同时也是其他所有情况下的默认值。
 
 ### MODERN_ENV
 

package/docs/zh/guides/basic-features/routes/config-routes.mdx

@@ -270,7 +270,7 @@ Modern.js 会自动查找并加载：
 
 :::info
 
-当前路由结构可以通过 [`modern routes`](#调试路由) 命令查看
+当前路由结构可以通过 [`ultramodern routes`](#调试路由) 命令查看
 
 :::
 
@@ -318,7 +318,7 @@ export default defineRoutes(({ page }, fileRoutes) => {
 
 ```bash
 # 生成路由结构分析报告
-npx modern routes
+npx ultramodern routes
 ```
 
 该命令会在 `dist/routes-inspect.json` 文件中生成最终的路由结构，帮助你了解合并后的完整路由信息。

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

@@ -466,7 +466,7 @@ Modern.js 支持通过 `loading.tsx` 文件来解决这个问题，`routes/` 下
 
 ## 预加载
 
-大多数切换路由时白屏的情况，都可以通过定义 `<Loading>` 组件来优化体验。Modern.js 也支持在 `<Link>` 组件上定义 `prefetch` 属性，提前对静态资源和数据进行加载。
+大多数切换路由时白屏的情况，都可以通过定义 `<Loading>` 组件来优化体验。Modern.js 也支持在 `<Link>` 组件上定义 `prefetch` 和 `preload` 属性，提前对导航进行预热。
 
 对于有更高性能要求的应用，预加载可以进一步提升用户体验，减少展示 `<Loading>` 组件的时间：
 
@@ -476,21 +476,36 @@ Modern.js 支持通过 `loading.tsx` 文件来解决这个问题，`routes/` 下
 
 :::tip
 
-对数据的预加载目前只会预加载 SSR 项目中 [Data Loader](/guides/basic-features/data/data-fetch) 中返回的数据。
+路由数据预热需要显式开启。在 SSR 项目中，只有匹配到的路由通过 `handle.navigationWarmup.data` 开启后，才会预取 [Data Loader](/guides/basic-features/data/data-fetch) 返回的数据。
 
 :::
 
-`prefetch` 属性有三个可选值：
+默认情况下，同源链接会在 `<Link>` 渲染时预取路由模块，并在链接进入视窗时进行预加载。当用户开启 Save-Data 或处于慢速网络时，Modern.js 会跳过这些自动预热。
 
-- `none`， 默认值，不会做 prefetch，没有任何额外的行为。
-- `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 Data Loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是快速点击，也能减少大约 200ms 的加载时间。
-- `render`，当 `<Link>` 组件渲染时，就会加载对应的分片和 Data Loader 中定义的数据。
+`prefetch` 属性有四个可选值：
+
+- `render`，默认值。当 `<Link>` 组件渲染时，就会预热对应的路由模块。
+- `intent`，当用户聚焦、悬停或触摸链接时，会开始预热对应的路由模块。如果意图在预热开始前取消，预热也会取消。
+- `viewport`，当 `<Link>` 组件进入视窗时，会开始预热对应的路由模块。
+- `none`，关闭自动 render prefetch。如果没有显式设置 `preload`，也会关闭默认的 viewport preload。
+
+`preload` 属性接受同样的时机值，默认值为 `viewport`。显式设置的 `preload` 总是优先生效，`preload={false}` 会关闭 preload 行为。
+
+如果要让某个路由开启 SSR 数据预热：
+
+```ts title="routes/page.config.ts"
+export const handle = {
+  navigationWarmup: {
+    data: true,
+  },
+};
+```
 
 :::details 值为 render 和不做路由分片的区别
 
-- `render` 加载路由分片的时机是可控的，只有在 `<Link>` 组件进入视窗时才触发，可以通过控制 `<Link>` 组件的渲染位置来控制分片加载时机。
-- `render` 仅在空闲时对静态资源进行加载，不占用重要模块的加载时间。
-- 除了预加载路由分片，`render` 在 SSR 项目中还会发起数据预取。
+- `render` 可以通过 `<Link>` 组件在组件树中的位置控制路由模块预热时机。
+- `viewport` 可以把模块预热推迟到链接接近可操作时再触发。
+- SSR 数据预取默认不开启；只有当路由的 loader 数据适合在导航前获取时，才应该使用 `handle.navigationWarmup.data`。
 
 :::
 

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

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

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

@@ -26,10 +26,10 @@ Modern.js 开发环境和生产环境的 Web 服务器流程是完全同构的
 
 Modern.js 支持在任何 Node.js 环境运行构建产物。在 CI 环境中，通常情况下已经安装了应用全部的依赖。
 
-你可以执行 [`modern build`](/apis/app/commands#modern-build) 来构建应用，执行 [`modern serve`](/apis/app/commands#modern-serve) 命令来运行 Web 服务器，启动 Modern.js 应用。
+你可以执行 [`ultramodern build`](/apis/app/commands#ultramodern-build) 来构建应用，执行 [`ultramodern serve`](/apis/app/commands#ultramodern-serve) 命令来运行 Web 服务器，启动 UltraModern.js 应用。
 
 ## 在生产环境中运行
 
 在部署到生产环境时，产物体积应该尽可能小，而上述在 CI 中运行的方案，会保留原项目的所有产物。因此在生产环境，不推荐通过上述命令运行应用。
 
-Modern.js 提供了独立的部署方案，当运行 [`modern deploy`](/apis/app/commands#modern-deploy) 命令时，产物中会包含可运行 Web 服务器的入口文件。
+UltraModern.js 提供了独立的部署方案，当运行 [`ultramodern deploy`](/apis/app/commands#ultramodern-deploy) 命令时，产物中会包含可运行 Web 服务器的入口文件。

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

@@ -25,7 +25,7 @@ import DebugApp from '@site-docs/components/debug-app';
 
 ## 使用配置
 
-通过 `@modern-js/create` 创建的 Modern.js 项目中，会默认生成 `modern.config.ts` 文件。
+通过 `@bleedingdev/modern-js-create` 创建的 UltraModern.js 项目中，会默认生成 `modern.config.ts` 文件。
 
 你可以通过该配置文件修改配置，覆盖 Modern.js 的默认行为。例如添加如下配置，开启 SSR：
 
@@ -46,7 +46,7 @@ export default defineConfig({
 
 在新创建的工程中，默认会安装 `@modern-js/app-tools` npm 包，它是 Modern.js 框架的核心包，主要提供以下能力：
 
-- 提供 `modern dev`, `modern build` 等常用的 CLI 命令。
+- 提供 `ultramodern dev`, `ultramodern build` 等常用的 CLI 命令。
 - 集成 Rsbuild，提供构建能力。
 - 集成 Modern.js Server，提供开发和生产服务器相关能力。
 

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

@@ -18,13 +18,13 @@ Modern.js 底层的 Rsbuild 支持构建 Vue 应用，如果你需要使用 Vue
 
 Modern.js 提供两套一方路由方案：
 
-- 默认使用 [React Router 7](https://reactrouter.com/en/main)，通过 `@modern-js/runtime/router` 导出 API。
-- 支持 [TanStack Router](https://tanstack.com/router)，通过 `@modern-js/plugin-tanstack/runtime` 导出 API。
+- 默认使用 [TanStack Router](https://tanstack.com/router)，通过 `@modern-js/plugin-tanstack/runtime` 导出 API。
+- 兼容 [React Router 7](https://reactrouter.com/en/main)，通过 `@modern-js/runtime/router` 导出 API。
 
-创建项目时，可通过以下命令选择 TanStack Router：
+创建 UltraModern 项目时，默认会包含 TanStack Router：
 
 ```bash
-npx @modern-js/create@latest myapp --router tanstack
+pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
 Modern.js 支持约定式路由、自控式路由或其他路由方案，请参考 [页面入口](/guides/concept/entries) 进行选择。
@@ -84,6 +84,12 @@ Modern.js 可以与社区中任意的 React 组件库搭配使用，比如 [MUI]
 
 Modern.js 支持使用 [Storybook](https://storybook.js.org/) 来开发 UI 组件。该功能为可选功能，请参考 [使用 Storybook](/guides/basic-features/debug/using-storybook) 启用。
 
+## 测试框架
+
+Modern.js 推荐使用 [Rstest](https://rstest.rs/) 编写单元测试和组件测试。Rstest 基于 Rspack 构建，启动和执行速度快，并且可以通过 [`@modern-js/adapter-rstest`](/guides/basic-features/testing/rstest) 复用 Modern.js 的应用配置。
+
+如果需要编写端到端（E2E）测试，可以使用 [Playwright](/guides/basic-features/testing/playwright)。
+
 ## Node.js 框架
 
 import TechStackNodeFramework from '@site-docs/components/tech-stack-node-framework';

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

@@ -36,7 +36,7 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 | BFF 运行时选型 | Modern.js 3.0 基线仅提供 Hono 运行时路径（无内建 Effect 运行时） | 将 Effect 设为默认运行时，并采用严格运行时拆分（`effect` -> `api/effect`，`hono` -> `api/lambda`），同时补齐 Effect-Schema-first 契约与 MF failure-injection 覆盖 |
 | Telemetry 标准化 | 可观测链路通常由业务侧自行拼装 | 增加框架级 telemetry 管线，内置 OTLP/VictoriaMetrics，支持脱敏、批处理与背压 |
 | 应用级 MF SSR 协议 | 没有以 super-app 为重点的应用级稳定性契约开关 | 增加 `server.ssr.moduleFederationAppSSR` 配置/环境变量握手，并补齐集成级回归保障 |
-| MF 远程加载可靠性 | 重试/降级策略通常由各业务单独实现 | 增加 timeout/network/contract-error 的确定性可靠性矩阵与分布式 OTEL 连续性断言 |
+| MF vertical 加载可靠性 | 重试/降级策略通常由各业务单独实现 | 增加 timeout/network/contract-error 的确定性可靠性矩阵与分布式 OTEL 连续性断言 |
 | 模块准入治理 | 基线无模块认证证据化 gate profile | 新增模块 SDK 契约、边界反模式守卫与发布/模块认证 gate 工作流 |
 | 路由运行时 | 默认运行时路径以 React Router 为中心 | 增加 TanStack Router 运行时/CLI 一等支持（React Router 继续可用） |
 | 脚手架模板 | 默认 create 模板以 React Router 起步路径为中心 | 增加 TanStack-ready 与 Tailwind-ready 的 create 模板 |
@@ -58,6 +58,95 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 3. 将基线契约视为渐进式默认值，而不是一次性强制切换。`MODERN_BASELINE_ENABLE_MF_SSR`、`MODERN_BASELINE_ENABLE_BFF_REQUEST_ID` 和 `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` 已经提供了按应用、按环境关闭的能力，方便在收敛到目标栈之前逐步过渡。
 4. 这套公开预设现在已经附带显式的发布 / 认证 gate。生成脚手架也会自带 `.github/workflows/ultramodern-gates.yml`，因此 `pnpm run ultramodern:check` 与 `pnpm run build` 从第一天开始就是接入契约的一部分。
 
+## 人类工作流
+
+公开的 BleedingDev create 包默认从简单路径开始。默认命令会创建一个
+可上线的 UltraModern 单应用，包含 `presetUltramodern(...)`、SSR、
+TanStack Router、Tailwind CSS v4、i18n、Effect BFF、生成质量 gate，以及
+Cloudflare 部署基础：
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create myapp
+cd myapp
+mise install
+mise exec -- pnpm install
+mise exec -- pnpm ultramodern:check
+```
+
+只有当独立归属边界有实际价值时，才创建 SuperApp workspace：
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
+cd my-super-app
+mise install
+mise exec -- pnpm install
+mise exec -- pnpm ultramodern:check
+```
+
+workspace 从 shell 和平台契约起步，不强制生成演示业务域。真实业务边界出现后，
+再添加对应 MicroVertical：
+
+```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 ultramodern:check
+```
+
+`--vertical` 会修改当前 workspace：创建 vertical 包，并更新 topology 元数据、
+ownership 记录、shell Module Federation、开发 overlays、包依赖、生成契约、
+端口、路由归属 i18n、CSS 隔离，以及 vertical 自己拥有的 Effect BFF/client surface。
+
+### 运行时契约
+
+生成应用和 vertical 沿用正常的 Modern.js SSR 路径。SuperApp workspace 在需要
+Module Federation SSR 时会加入 `server.ssr.moduleFederationAppSSR`，但这个开关是
+显式契约，不是所有应用的强制要求。
+
+每个应用都会产出 `src/routes/ultramodern-route-metadata` 和
+`ultramodernLocalisedUrls`。i18n 插件在 `localeDetection.localisedUrls` 中读取它，
+并从 `/locales/{{lng}}/{{ns}}.json` 提供动态后端 JSON。路由 owner 需要同时维护
+本地化路径和 locale resource JSON。
+
+生成契约会在 `.modernjs/ultramodern-generated-contract.json` 中写入
+`cssFederation`：
+
+- `packages/shared-design-tokens` 拥有共享 token layer，并导出 `./tokens.css`。
+- Shell CSS 只拥有 `[data-app-id="shell-super-app"]` 下的 shell base 和 overlay layer。
+- 每个 vertical 拥有自己的 CSS layer，例如 `[data-app-id="vertical-transportation"]` 和应用本地 class 前缀。
+- Tailwind CSS v4 通过 `@tailwindcss/postcss` 保持在每个生成应用内部；共享 base style 不应由 vertical 重复定义。
+- SSR 首屏依赖 Modern/Rspack 产出共享 token CSS 和应用自己的 CSS。Vertical CSS 通过 manifest 归属加载，不复制到 shell 源码中。
+
+版本切换必须从同一个 vertical build marker 选择 UI、Effect API、CSS、i18n JSON 与 MF manifest 证据。只切换 shell 渲染里的 UI marker 不足以证明完整版本切换。
+
+### 校验与部署
+
+本地 gate：
+
+```bash
+mise exec -- pnpm ultramodern:check
+mise exec -- pnpm build
+mise exec -- pnpm cloudflare:build
+```
+
+生成 workspace 包含 `scripts/proof-cloudflare-version.mjs`，用于 live Cloudflare 和
+Zephyr 证据：
+
+```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 与 Zephyr 证明需要公开 Worker URL 和 Zephyr 凭据。没有这些凭据时，
+仓库仍可校验生成契约、本地构建、本地 Cloudflare 输出、dry-run Zephyr 证据计划和
+本地证据 schema，但不能证明由 shell 驱动的 live 版本选择。
+
+BleedingDev 包通过 GitHub Actions trusted publishing 发布。公开发布 workflow 不使用
+长期 npm token；不要从开发机器手动发布包。
+
 ## 基线开关（可按需关闭）
 
 生成的 `presetUltramodern(...)` 脚手架会开启更严格的平台契约。以下环境变量会在生成的 `modern.config.ts` 中读取，可按应用或按环境关闭/覆盖：

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

@@ -104,7 +104,7 @@ export default RemoteApp;
 
 ## 启动应用
 
-现在，生产者应用和消费者应用都已经搭建完毕，我们可以在本地运行 `modern dev` 启动两个应用。
+现在，生产者应用和消费者应用都已经搭建完毕，我们可以在本地运行 `ultramodern dev` 启动两个应用。
 
 启动后，消费者应用访问 `/remote` 路由时，会进入生产者应用中。访问 `http://localhost:8080/remote`，可以看到页面中已经包含了生产者的远程模块的完整页面。
 

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

@@ -88,10 +88,10 @@ export default createModuleFederationConfig({
 
 ## 本地验证部署
 
-Modern.js 提供了 `modern deploy` 命令，可以方便生成可运行在 Node.js 环境的产物。
+Modern.js 提供了 `ultramodern deploy` 命令，可以方便生成可运行在 Node.js 环境的产物。
 
 ```bash
-modern deploy
+ultramodern deploy
 ```
 
 执行命令后，可以在控制台看到以下输出：

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

@@ -154,7 +154,7 @@ export default Index;
 
 ## 启动应用
 
-现在，生产者应用和消费者应用都已经搭建完毕，我们可以在本地运行 `modern dev` 启动两个应用。
+现在，生产者应用和消费者应用都已经搭建完毕，我们可以在本地运行 `ultramodern dev` 启动两个应用。
 
 启动后，消费者中对生产者模块的引入，不会再出现抛错，类型已经下载到消费者应用中。
 
@@ -164,7 +164,7 @@ export default Index;
 
 访问 `http://localhost:8080/remote`，可以看到页面中已经包含了生产者的远程模块 `Button` 组件。
 
-我们也可以在本地执行 `modern serve` 来模拟生产环境。
+我们也可以在本地执行 `ultramodern serve` 来模拟生产环境。
 
 因为 Module Federation 插件会自动读取 Modern.js 的 `output.assetPrefix` 配置作为远程模块的访问地址，而该值在生产环境下构建后默认是 `/`。如果不做特殊处理，消费者将从自己的域名下拉取远程模块的入口文件。我们可以添加如下配置：
 
@@ -178,7 +178,7 @@ export default defineConfig({
     port: 3051,
   },
   output: {
-    // Now this configuration is only used in the local when you run modern serve command.
+    // Now this configuration is only used in the local when you run ultramodern 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',
@@ -187,10 +187,10 @@ export default defineConfig({
 });
 ```
 
-现在，在生产者中运行 `modern build && MODERN_MF_AUTO_CORS=true modern serve`，在消费者中运行 `modern build && modern serve`，即可在本地模拟生产环境，访问到远程模块。
+现在，在生产者中运行 `ultramodern build && MODERN_MF_AUTO_CORS=true ultramodern serve`，在消费者中运行 `ultramodern build && ultramodern serve`，即可在本地模拟生产环境，访问到远程模块。
 
 :::tip
-在使用 `modern serve` 命令时，需要在启动生产者项目时携带 `MODERN_MF_AUTO_CORS=true` 环境变量，以自动处理跨域问题，确保消费者可以正常访问生产者的远程模块资源。
+在使用 `ultramodern serve` 命令时，需要在启动生产者项目时携带 `MODERN_MF_AUTO_CORS=true` 环境变量，以自动处理跨域问题，确保消费者可以正常访问生产者的远程模块资源。
 :::
 
 上述用例可以参考：[Modern.js & Module Federation 基础用法示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/base)。

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

@@ -23,7 +23,7 @@ Modern.js 内部基于 [Rsbuild](https://v2.rsbuild.rs/) 封装了自身的构
 Modern.js 提供 [inspect 命令](/apis/app/commands.html) 用于查看项目最终生成的 Modern.js 配置以及 Rspack 配置。
 
 ```bash
-➜ npx modern inspect
+➜ npx ultramodern inspect
 
 Inspect config succeed, open following files to view the content:
 

package/docs/zh/guides/upgrade/other.md

@@ -88,14 +88,14 @@ Modern.js 3.0 默认使用 React Router v7 作为路由库。React Router v7 相
 
 如果需要使用 React Router v5 或 React Router v6，需要使用**自控式路由**模式。自控式路由允许你完全控制路由配置，不受 Modern.js 约定式路由的限制。
 
-## 使用 @modern-js/create 创建 Monorepo 和 Modern.js Module
+## 使用 @bleedingdev/modern-js-create 创建 Monorepo 和 Modern.js Module
 
-Modern.js 3.0 不再支持通过 `@modern-js/create` 创建 Monorepo 项目和 Modern.js Module 项目。
+Modern.js 3.0 不再支持通过 `@bleedingdev/modern-js-create` 创建 Monorepo 项目和 Modern.js Module 项目。
 
 **变更内容**：
 
-- 在 [v2.53.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.53.0) 版本中，移除了使用 `@modern-js/create` 创建 Monorepo 项目的功能
-- 在 [v2.61.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.61.0) 版本中，移除了使用 `@modern-js/create` 和 `modern new` 命令创建 Modern.js Module 项目的功能
+- 在 [v2.53.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.53.0) 版本中，移除了使用 `@bleedingdev/modern-js-create` 创建 Monorepo 项目的功能
+- 在 [v2.61.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.61.0) 版本中，移除了使用 `@bleedingdev/modern-js-create` 和 `ultramodern new` 命令创建 Modern.js Module 项目的功能
 
 **处理方式**：
 
@@ -104,12 +104,12 @@ Modern.js 3.0 不再支持通过 `@modern-js/create` 创建 Monorepo 项目和 M
 
 ## new 命令和 upgrade 命令移除
 
-Modern.js 3.0 移除了 `modern new` 和 `modern upgrade` 命令，需要按照文档手动操作。
+Modern.js 3.0 移除了 `ultramodern new` 和 `ultramodern upgrade` 命令，需要按照文档手动操作。
 
 **变更内容**：
 
-- `modern new` 命令在 Modern.js 3.0 中不再支持，无法通过命令添加入口或启用功能
-- `modern upgrade` 命令在 Modern.js 3.0 中不再支持，无法通过命令自动升级依赖
+- `ultramodern new` 命令在 Modern.js 3.0 中不再支持，无法通过命令添加入口或启用功能
+- `ultramodern upgrade` 命令在 Modern.js 3.0 中不再支持，无法通过命令自动升级依赖
 
 **处理方式**：
 
@@ -187,4 +187,3 @@ Modern.js 之前提供了 ESLint 的完整规则集，涵盖了 @modern-js（针
 
 
 
-

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

@@ -38,7 +38,7 @@ This page is the complete public difference reference for the UltraModern.js 3.0
 | Metrics/trace correlation | SSR metrics tags do not parse W3C trace context | `traceparent` is parsed and emits `trace_id` / `span_id` tags | Implemented | Improves cross-system observability joins |
 | App-level MF SSR contract flag | No dedicated app-level MF SSR stability contract switch | Adds `server.ssr.moduleFederationAppSSR` contract and auto-enables env wiring when MF SSR markers are detected | Implemented | Sets `process.env.MODERN_MF_APP_SSR` |
 | App-level MF SSR runtime bridge | Not a stable default bridge path | V3 applies stable bridge defaults for MF SSR node output/runtime env when server rendering + MF markers are present | Implemented | Keeps explicit opt-out path via config/env |
-| MF remote loader reliability contracts | Remote loading fallback patterns are typically app-defined | Adds deterministic timeout/network/contract-error fallback matrix and distributed OTEL continuity assertions | Implemented | `routes-tanstack-mf` reliability suite |
+| MF vertical loading reliability contracts | Loading fallback patterns are typically app-defined | Adds deterministic timeout/network/contract-error fallback matrix and distributed OTEL continuity assertions | Implemented | `routes-tanstack-mf` reliability suite |
 | 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-only MF data contracts plus failure-injection coverage for federated data fetch | Implemented (Effect-default + strict split) | Stream is explicit about no Zod introduction |
 | Module SDK contract artifact | No framework-level module contract artifact | Adds machine-readable module contract + typed module SDK interfaces | Implemented | `module-sdk-contracts.json` + `moduleSdk.d.ts` |
 | Boundary anti-pattern CI guards | No dedicated boundary anti-pattern workflow | Adds profile-driven CI checks for boundary imports, required hooks, and forbidden module patterns | Implemented | `.github/workflows/boundary-anti-patterns.yml` |
@@ -239,7 +239,7 @@ UltraModern.js 3.0 shipped additional reliability work aligned to Beads stream D
 
 - `@modern-js/plugin-bff` runtime path migrated to Effect v4.
 - Effect-only MF data-fetch contract guidance (explicitly no Zod layer in this stream).
-- MF reliability matrix includes deterministic failure injection (timeout/network/contract error).
+- MF vertical loading reliability matrix includes deterministic failure injection (timeout/network/contract error).
 - Distributed trace continuity checks were re-enabled for build and serve paths.
 - Data-platform architecture defines operation identity, envelope integrity, scoped invalidation, and trace propagation contracts.
 
@@ -247,7 +247,7 @@ Reference materials:
 
 - `docs/super-app-rfc-adr/ADR-0003-effect-only-mf-data-fetch-reliability.md`
 - `packages/cli/plugin-bff/docs/data-platform-architecture.md`
-- `tests/integration/routes-tanstack-mf/test/remote-loader-reliability.test.ts`
+- `routes-tanstack-mf` reliability coverage
 
 ### 11) Release and module certification gate model
 
@@ -280,21 +280,104 @@ The following are intentionally out of scope for this public V3 preset profile:
 - Forcing Effect-only data-fetch runtime as the mandatory default for every app.
 - Forcing app-level MF SSR for every app regardless of readiness.
 
-## Micro Vertical Delivery Path
+## Human Workflow
 
-`presetUltramodern(...)` is also the single public entrypoint for Micro Verticals. The intended adoption sequence is:
+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
+production URL metadata:
 
-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.
+```bash
+pnpm dlx @bleedingdev/modern-js-create myapp
+cd myapp
+mise install
+pnpm install
+pnpm run ultramodern:check
+MODERN_PUBLIC_SITE_URL=https://example.com pnpm build
+```
+
+Create a SuperApp workspace only when independent ownership is useful:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
+cd my-super-app
+mise install
+pnpm install
+pnpm check
+pnpm build
+```
+
+The initial SuperApp workspace is shell-only: `apps/shell-super-app` owns route
+assembly and Module Federation host wiring, `verticals/*` starts empty, and
+`packages/shared-*` holds placeholders for contracts, tokens, and API support.
+Add verticals only when a real business domain needs independent ownership.
 
-In this repo, the reference examples are:
+Add real business MicroVerticals as they become 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
+pnpm check
+pnpm build
+```
+
+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.
+
+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` and serves dynamic backend JSON from
+`/locales/{{lng}}/{{ns}}.json`.
+
+The generated contract writes `.modernjs/ultramodern-generated-contract.json`
+with `cssFederation`: shared design tokens stay in `packages/shared-design-tokens`,
+shell CSS owns shell layers, each vertical owns one CSS layer with app-local
+prefixes, and SSR first paint uses Modern/Rspack assets plus manifest-owned
+vertical CSS.
+
+Generated workspaces include `scripts/proof-cloudflare-version.mjs` for live
+Cloudflare and Zephyr proof. Deploy first, then pass each deployed app's
+generated public URL env key into the proof step. Shell-only workspaces only
+need the shell URL; added verticals use the same
+`ULTRAMODERN_PUBLIC_URL_<APP_ID>` pattern with hyphens converted to underscores
+and uppercased.
+
+```bash
+pnpm cloudflare:deploy
+ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_TRANSPORTATION=https://transportation.example.workers.dev \
+pnpm cloudflare:proof -- --require-public-urls
+```
 
-- `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.
+Live proof requires public Worker URLs and Zephyr credentials; local checks
+still validate generated contracts, builds, Cloudflare output, dry-run Zephyr
+evidence plans, and local evidence schemas.
+
+## Current Troubleshooting
+
+| Symptom | Current check | Owner |
+| --- | --- | --- |
+| Package cohort mismatch | Regenerate with one package source strategy, run `mise install`, then rerun `pnpm install` from the activated shell. | Generated workspace package source metadata |
+| Install failure | Check the active Node/pnpm from `mise install`; rerun `pnpm install` after the shell sees the pinned versions. | Toolchain setup |
+| Build failure | Run `pnpm check` before `pnpm build`; fix reported format, lint, type, skill, i18n, or generated-contract failures first. | Owning package or generated contract |
+| Missing public URL | Set the env key from `.modernjs/ultramodern-generated-contract.json`, for example `ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP`. | Deployment operator |
+| Cloudflare credentials | Confirm Wrangler credentials before `pnpm cloudflare:deploy`; local checks do not prove live Worker access. | Deployment operator |
+| Asset or CSS 404 | Rebuild with `pnpm build` or `pnpm cloudflare:deploy` and inspect emitted Modern/Rspack asset paths instead of hardcoding CSS URLs. | Framework/runtime asset pipeline |
+| Federation manifest failure | Run the shell and vertical build scripts, then check each deployed `/mf-manifest.json` URL used by the shell. | Module Federation owner |
+
+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)