@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.57 → 3.2.0-ultramodern.61

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

@@ -107,13 +107,32 @@ When `--bff` or `--bff-runtime effect` is enabled, `modern.config.ts` enables `@
 When `--bff-runtime hono` is enabled, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/lambda/hello.ts`, and sets `bff.runtimeFramework` to `hono`.
 When `--workspace` is enabled, `@modern-js/*` dependencies use `workspace:*` versions for local monorepo linkage.
 
-If you want the public UltraModern.js SuperApp path, use the BleedingDev create
-package. It defaults to the canonical Effect + TanStack + SSR + Micro Verticals
-workspace and published BleedingDev package aliases:
+If you want the public UltraModern.js path, use the BleedingDev create package.
+It creates a simple production-ready UltraModern app by default and installs
+the published BleedingDev package aliases:
 
 ```bash
 pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
-The lower-level `--ultramodern-*` flags are reserved for release engineering
-and local package-source testing.
+Create a SuperApp workspace only when you need independently owned verticals:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
+```
+
+From a generated SuperApp workspace, add a business MicroVertical in place:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical
+```
+
+The `--vertical` command mutates the current workspace: it adds the vertical
+package and wires topology, ownership metadata, shell Module Federation,
+development overlays, package dependencies, generated contracts, route-owned
+i18n, CSS isolation, and the Effect BFF/client surface.
+
+The lower-level `--ultramodern-package-*` flags are reserved for release
+engineering and local package-source testing. BleedingDev packages are published
+through GitHub Actions trusted publishing; do not publish them manually from a
+developer machine.

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

@@ -36,7 +36,7 @@ UltraModern.js additions are designed as the default product surface for new Sup
 | 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 |
@@ -60,74 +60,74 @@ For teams already on Modern.js 3.0, the adoption path remains compatibility-awar
 
 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
+## Human Workflow
 
-`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.
-
-## Tractor Reference Workspace
-
-The BleedingDev create entrypoint now scaffolds the real Tractor reference workspace instead of the earlier visual boundary demo:
+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:
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create tractor-super-app
-cd tractor-super-app
+pnpm dlx @bleedingdev/modern-js-create myapp
+cd myapp
 mise install
 mise exec -- pnpm install
 mise exec -- pnpm ultramodern:check
 ```
 
-The generated workspace has one shell and three full-stack vertical remotes:
+Create a SuperApp workspace only when independent ownership is useful:
 
-| Package | Owner role | Port | Owns |
-| --- | --- | --- | --- |
-| `apps/shell-super-app` | platform shell | `3020` | route assembly, topology selection, MF host config, shell CSS overlays, global fallback policy |
-| `apps/remotes/remote-explore` | Explore vertical | `3021` | tractor discovery routes, header/footer/recommendations/store picker exposes, `/explore-api/effect/explore/*` |
-| `apps/remotes/remote-decide` | Decide vertical | `3022` | product selection and configuration routes, `ProductPage`, `/decide-api/effect/decide/*` |
-| `apps/remotes/remote-checkout` | Checkout vertical | `3023` | cart, checkout, thanks routes, cart exposes, `/checkout-api/effect/checkout/*` |
-
-The shell consumes remotes through Module Federation references in topology metadata and `zephyr:dependencies`; it should not hardcode deployed remote URLs in source. Each vertical owns its UI route subtree, browser-safe MF exposes, Effect BFF contract, generated client export, locale JSON, CSS entrypoint, Cloudflare Worker metadata, and build marker.
+```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
+```
 
-### Route-Owned I18n
+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:
 
-Each app emits `src/routes/ultramodern-route-metadata` with `ultramodernLocalisedUrls`. The i18n plugin reads that map in `localeDetection.localisedUrls`, serves dynamic backend JSON from `/locales/{{lng}}/{{ns}}.json`, and keeps `reactI18next` disabled for the generated shell and remotes.
+```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
+```
 
-Examples:
+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.
 
-| Vertical | Canonical route | English | Czech |
-| --- | --- | --- | --- |
-| Explore | `/tractors` | `/tractors` | `/traktory` |
-| Explore | `/stores` | `/stores` | `/prodejci` |
-| Decide | `/tractors/:slug` | `/tractors/:slug` | `/traktory/:slug` |
-| Checkout | `/cart` | `/cart` | `/kosik` |
-| Checkout | `/checkout/thank-you/:orderId?` | `/checkout/thank-you/:orderId?` | `/pokladna/dekujeme/:orderId?` |
+### Runtime Contracts
 
-The route owner changes localized paths and locale resource JSON together. Shell-owned URL rewrites are not part of the contract.
+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.
 
-### Federated CSS Contract
+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.
 
-The generated contract writes `.modernjs/ultramodern-generated-contract.json` with a `cssFederation` section:
+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"]`.
-- Remote CSS owns one vertical layer, for example `[data-app-id="remote-explore"]` with `explore-` class prefixes.
-- Tailwind CSS v4 is local to each generated app through `@tailwindcss/postcss`; shared base styles must not be duplicated by remotes.
-- SSR first paint requires shared token CSS and app-owned CSS to be emitted by Modern/Rspack assets. Remote CSS is loaded through remote manifest ownership, not copied into shell source.
+- 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 Proof
+### Validation And Deploy
 
 Local gates:
 
@@ -137,29 +137,22 @@ mise exec -- pnpm build
 mise exec -- pnpm cloudflare:build
 ```
 
-Local Cloudflare artifact validation can run without public credentials:
-
-```bash
-node scripts/ultramodern-cloudflare-ssr-validation/validate-cloudflare-ssr.js \
-  --root-dir apps/remotes/remote-explore \
-  --bff /explore-api/effect/explore/readiness \
-  --expect-en "Explore Remote" \
-  --match-build-marker \
-  --out .codex/reports/cloudflare-ssr/remote-explore-local.json
-```
-
-Generated workspaces also include `scripts/proof-cloudflare-version.mjs`:
+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_REMOTE_EXPLORE=https://remote-explore.example.workers.dev \
-ULTRAMODERN_PUBLIC_URL_REMOTE_DECIDE=https://remote-decide.example.workers.dev \
-ULTRAMODERN_PUBLIC_URL_REMOTE_CHECKOUT=https://remote-checkout.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)
 
 The generated `presetUltramodern(...)` starter enables strict platform contracts. Use these env switches to opt out per app or per environment:

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

@@ -107,11 +107,30 @@ npx @modern-js/create@latest myapp --router tanstack --bff-runtime effect --work
 当启用 `--bff-runtime hono` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/lambda/hello.ts`，并将 `bff.runtimeFramework` 设置为 `hono`。
 当启用 `--workspace` 时，`@modern-js/*` 依赖会使用 `workspace:*` 版本，便于本地 monorepo 联调。
 
-如果你需要公开的 UltraModern.js SuperApp 路径，请使用 BleedingDev create 包。
-它默认生成规范的 Effect + TanStack + SSR + Micro Verticals workspace，并使用已发布的 BleedingDev 包别名：
+如果你需要公开的 UltraModern.js 路径，请使用 BleedingDev create 包。
+它默认创建一个简单、可上线的 UltraModern 应用，并安装已发布的
+BleedingDev 包别名：
 
 ```bash
 pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
-底层 `--ultramodern-*` 参数只保留给发布工程和本地包源测试使用。
+只有在需要多个独立归属的 vertical 时，才显式创建 SuperApp workspace：
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
+```
+
+在已生成的 SuperApp workspace 根目录中，可以就地添加业务
+MicroVertical：
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical
+```
+
+`--vertical` 会修改当前 workspace：新增 vertical 包，并写入 topology、
+ownership 元数据、shell Module Federation、开发 overlays、包依赖、生成契约、
+路由归属 i18n、CSS 隔离，以及 Effect BFF/client surface。
+
+底层 `--ultramodern-package-*` 参数只保留给发布工程和本地包源测试使用。
+BleedingDev 包通过 GitHub Actions trusted publishing 发布；不要从开发机器手动发布。

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/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,71 @@ 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
+Cloudflare deploy basics:
 
-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
+mise exec -- pnpm install
+mise exec -- pnpm ultramodern:check
+```
+
+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
+mise exec -- pnpm install
+mise exec -- pnpm ultramodern:check
+```
+
+Add real business MicroVerticals as they become ownership boundaries:
 
-In this repo, the reference examples are:
+```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
+```
 
-- `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.
+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. 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.
+
+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/main-doc/docs/zh/guides/get-started/ultramodern.mdx

@@ -38,7 +38,7 @@ UltraModern.js V3 记录的是一套“更强默认值的 Modern.js 参考档案
 | Metrics 与 Trace 关联 | SSR metrics 不解析 W3C trace 上下文 | 解析 `traceparent` 并注入 `trace_id` / `span_id` 标签 | 已实现 | 提升跨系统观测关联度 |
 | 应用级 MF SSR 合约开关 | 无专门 app-level MF SSR 稳定性契约开关 | 新增 `server.ssr.moduleFederationAppSSR`，并在检测到 MF SSR 标记时自动启用环境变量握手 | 已实现 | 注入 `process.env.MODERN_MF_APP_SSR` |
 | 应用级 MF SSR 运行时桥接 | 非稳定默认桥接路径 | V3 在「服务端渲染 + MF 标记」场景下提供稳定桥接默认行为 | 已实现 | 保留显式关闭路径 |
-| MF 远程加载可靠性契约 | 远程加载重试/降级策略通常由业务自管 | 新增 timeout/network/contract-error 的确定性降级矩阵与分布式 OTEL 连续性断言 | 已实现 | 对应 `routes-tanstack-mf` 可靠性套件 |
+| MF vertical 加载可靠性契约 | 加载重试/降级策略通常由业务自管 | 新增 timeout/network/contract-error 的确定性降级矩阵与分布式 OTEL 连续性断言 | 已实现 | 对应 `routes-tanstack-mf` 可靠性套件 |
 | BFF 运行时选型 | Modern.js V3 基线仅提供 Hono 运行时路径（无内建 Effect 运行时） | 将 Effect 设为默认运行时，并采用严格运行时拆分（`effect` -> `api/effect`，`hono` -> `api/lambda`），同时补齐 Effect-Schema-only MF 数据契约与 failure-injection 覆盖 | 已实现（Effect 默认 + 严格拆分） | 该流明确不引入 Zod |
 | 模块 SDK 合约产物 | 无框架级模块契约产物 | 新增机器可读模块家族契约与类型化模块 SDK 接口 | 已实现 | `module-sdk-contracts.json` + `moduleSdk.d.ts` |
 | 边界反模式 CI 守卫 | 无专门边界反模式工作流 | 新增基于 profile 的边界检查（导入边界/必需钩子/模块禁用模式） | 已实现 | `.github/workflows/boundary-anti-patterns.yml` |
@@ -239,7 +239,7 @@ UltraModern.js V3 对应 Beads Stream D 落地了额外可靠性能力：
 
 - `@modern-js/plugin-bff` 运行时路径迁移到 Effect v4。
 - MF 数据拉取契约采用 Effect-only 指导（该流明确不引入 Zod）。
-- 远程加载可靠性矩阵覆盖 timeout/network/contract error 的确定性注入场景。
+- MF vertical 加载可靠性矩阵覆盖 timeout/network/contract error 的确定性注入场景。
 - build 与 serve 路径重新启用分布式 trace 连续性断言。
 - 数据平台架构补齐 operation identity、请求/水合 envelope 完整性、scope key 与失效路由契约。
 
@@ -247,7 +247,7 @@ UltraModern.js V3 对应 Beads Stream D 落地了额外可靠性能力：
 
 - `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` 可靠性覆盖
 
 ### 11) 发布与模块认证 Gate 模型
 
@@ -280,6 +280,65 @@ UltraModern.js V3 对应 Beads Stream D 落地了额外可靠性能力：
 - 将应用级 MF SSR 强制为所有应用的默认路径。
 - 将 Effect-only 数据获取运行时强制为所有应用的默认路径。
 
+## 人类工作流
+
+公开的 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
+```
+
+真实业务边界出现后，再添加对应 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。
+
+生成契约会在 `.modernjs/ultramodern-generated-contract.json` 中写入
+`cssFederation`：共享 design tokens 保留在 `packages/shared-design-tokens`，
+shell CSS 拥有 shell layer，每个 vertical 拥有自己的 CSS layer 与应用本地前缀，
+SSR 首屏使用 Modern/Rspack 产物和 manifest 归属的 vertical CSS。
+
+生成 workspace 包含 `scripts/proof-cloudflare-version.mjs`，用于 live Cloudflare 和
+Zephyr 证据。Live 证明需要公开 Worker URL 和 Zephyr 凭据；本地检查仍可校验
+生成契约、构建、Cloudflare 输出、dry-run Zephyr 证据计划和本地证据 schema。
+
+BleedingDev 包通过 GitHub Actions trusted publishing 发布。公开发布 workflow 不使用
+长期 npm token；不要从开发机器手动发布包。
+
 ## 基线开关（可按需关闭）
 
 生成的 `presetUltramodern(...)` create 模板会开启更严格的平台契约。以下环境变量会在生成的 `modern.config.ts` 中读取，可按应用或按环境关闭/覆盖：

package/package.json

@@ -18,14 +18,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.2.0-ultramodern.57",
+  "version": "3.2.0-ultramodern.61",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.15.0",
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.2.0-ultramodern.57"
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.2.0-ultramodern.61"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "1.5.2",