@bleedingdev/modern-js-main-doc 3.9.0-ultramodern.4 → 3.9.0-ultramodern.6

package/docs/en/components/hono.mdx

@@ -21,7 +21,7 @@ For more details, refer to [useHonoContext](/apis/app/runtime/bff/use-backend-co
 When getting cookies in BFF functions, you need to get the request context through `useHonoContext`, then use `c.req.header('cookie')` to get the Cookie string and parse it manually:
 
 ```ts title="api/lambda/cookies.ts"
-import { Api, Get } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get } from '@modern-js/plugin-bff/server';
 import { useHonoContext } from '@modern-js/server-runtime';
 
 // Helper function to parse Cookie string
@@ -64,7 +64,7 @@ The `c.req.cookie()` method does not exist in the current version. You need to u
 When using Hono as the runtime framework, you can define interfaces through [Api functions](/guides/advanced-features/bff/operators.html):
 
 ```ts title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const QuerySchema = z.object({
@@ -93,7 +93,7 @@ For more details about Api functions and operators, refer to [Creating Extensibl
 Hono supports a rich middleware ecosystem, and you can use middleware in BFF functions:
 
 ```ts title="api/lambda/user.ts"
-import { Api, Get, Middleware } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Middleware } from '@modern-js/plugin-bff/server';
 
 export const getUser = Api(
   Get('/user'),

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

@@ -71,11 +71,7 @@ Now, the project structure is as follows:
 ```
 
 The default workspace starts shell-only and installs the published BleedingDev
-package aliases:
-
-```bash
-pnpm dlx @bleedingdev/modern-js-ultramodern-create my-super-app
-```
+package aliases.
 
 From a generated SuperApp workspace, add a business MicroVertical in place:
 

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

@@ -47,21 +47,33 @@ import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
 
 :::caution Install the Effect peers yourself
 `effect` and `@effect/opentelemetry` are **optional exact peer dependencies** of
-`@modern-js/plugin-bff`, not dependencies. The plugin no longer bundles a copy —
-Effect 4 derives `Context` / `Service` keys per module instance, so a bundled copy
-would give your app a second Effect identity. Before setting
-`runtimeFramework: 'effect'` or importing `@modern-js/plugin-bff/effect`,
-`/effect-server`, `/effect-edge` or `/effect-client`, install the exact cohort:
+`@modern-js/bff-effect`. Install them in the application so its API modules and
+the framework use the same Effect instance. Before setting
+`runtimeFramework: 'effect'` or importing `@modern-js/bff-effect/effect`,
+`/effect-edge` or `/effect-client`, install the exact cohort:
 
 ```bash
 pnpm add effect@4.0.0-rc.112 @effect/opentelemetry@4.0.0-rc.112
 ```
 
 The pin is exact because UltraModern ships Effect as one lockstep cohort. Apps
-using only `runtimeFramework: 'hono'` or the `./data-platform` lane need neither
-package.
+using only native `runtimeFramework: 'hono'` or
+`@modern-js/bff-effect/data-platform` need neither package.
 :::
 
+Use `bffPlugin` from `@modern-js/plugin-bff-build-extensions` to register the
+Effect runtime. It composes the native BFF plugin. Install
+`@modern-js/bff-effect` and `@modern-js/plugin-bff-extensions` from the same
+framework cohort as application production dependencies, so the adapter remains
+available after development dependencies are removed. The build plugin can be a
+development dependency. See the [runtime configuration example](/guides/advanced-features/bff/frameworks).
+
+Native `@modern-js/plugin-bff/server` exports Hono APIs. For Node Effect APIs,
+import framework helpers such as `defineEffectBff` from
+`@modern-js/bff-effect/effect` and namespaces from the corresponding `effect/*`
+modules. Worker handlers and worker request context use
+`@modern-js/bff-effect/effect-edge`.
+
 Generated UltraModern workspaces use this runtime as the only generated HTTP API
 path. The API contract lives at `shared/api.ts`, the server runtime lives at
 `api/index.ts`, clients live under `src/api/*-client.ts`, and generated checks
@@ -173,7 +185,6 @@ export default defineConfig({
     endpoint: '/_data/batch',
     maxBatchSize: 16,
     maxBatchBytes: 64 * 1024,
-    flushIntervalMs: 8,
     maxConcurrency: 4,
     requestTimeoutMs: 10000,
     allowedMethods: ['GET'],
@@ -207,9 +218,9 @@ export default defineConfig({
 });
 ```
 
-`batch.flushIntervalMs` controls the client-side micro-batch window in the generated Effect client. `maxConcurrency` and `requestTimeoutMs` are applied by the server batch gateway when dispatching items.
+`maxConcurrency` and `requestTimeoutMs` control the server batch gateway. Native `HttpApiClient` calls send individual requests; they do not automatically batch requests.
 
-The generated `api.client.*` API only exists for loader-materialized `@api/index` imports. Directly importing the server entry (`api/index`) exposes the Effect BFF definition; its `client` property is a placeholder that fails on operation access.
+Import a shared `HttpApi` contract and pass it to `HttpApiClient.make` or `makeEffectHttpApiClient`. The client is fully type-inferred; `defineEffectBff` exposes server handlers and does not contain a client.
 
 ## Effect cohort
 
@@ -244,7 +255,7 @@ Strict Effect APIs should test the declared `HttpApi` contract, not a raw
 request handler. Edge-compatible tests can use the framework helper:
 
 ```ts
-import { createEffectBffTestHandler } from '@modern-js/plugin-bff/effect-edge';
+import { createEffectBffTestHandler } from '@modern-js/bff-effect/effect-edge';
 import apiModule from '../api/index';
 
 const testApi = await createEffectBffTestHandler({
@@ -259,12 +270,9 @@ If you manually compose an Effect web handler in a low-level proof, provide the
 platform services explicitly:
 
 ```ts
-import {
-  HttpApiBuilder,
-  HttpRouter,
-  HttpServer,
-  Layer,
-} from '@modern-js/plugin-bff/effect-server';
+import * as Layer from 'effect/Layer';
+import { HttpRouter, HttpServer } from 'effect/unstable/http';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 
 const handler = HttpRouter.toWebHandler(
   HttpApiBuilder.layer(api).pipe(
@@ -284,13 +292,10 @@ current Effect v4 beta cohort, `HttpRouter.middleware(...)` returns a `Layer`
 directly:
 
 ```ts
-import {
-  Effect,
-  HttpApiBuilder,
-  HttpMiddleware,
-  HttpRouter,
-  Layer,
-} from '@modern-js/plugin-bff/effect-server';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { HttpMiddleware, HttpRouter } from 'effect/unstable/http';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 
 const corsLayer = HttpRouter.middleware(
   Effect.succeed(

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

@@ -17,7 +17,7 @@ Modern.js Effect API runtime now supports a request-envelope based data platform
 
 ## Runtime contract helpers
 
-Use `@modern-js/plugin-bff/data-platform` helpers to build and validate contracts:
+Use `@modern-js/bff-effect/data-platform` helpers to build and validate contracts:
 
 ```ts
 import {
@@ -30,7 +30,7 @@ import {
   validateHydrationEnvelope,
   createInvalidationEvent,
   shouldApplyInvalidation,
-} from '@modern-js/plugin-bff/data-platform';
+} from '@modern-js/bff-effect/data-platform';
 ```
 
 ## Effect runtime validation

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

@@ -5,10 +5,10 @@ title: Runtime Framework
 
 # Runtime Framework
 
-Modern.js supports two BFF runtime frameworks:
+Modern.js and the UltraModern BFF extension provide two runtime frameworks:
 
-- `effect` (default): use [Effect HttpApi](https://effect.website/) runtime from `api/index`.
-- `hono`: use file-convention BFF handlers from `api/lambda/**`.
+- `hono` is the native plugin default and uses file-convention handlers from `api/lambda/**`.
+- `effect` is the UltraModern extension default and uses [Effect HttpApi](https://effect.website/) from `api/index`.
 
 `effect` and `hono` are strict runtime modes. There is no automatic fallback between them.
 
@@ -19,12 +19,18 @@ Generated UltraModern workspaces use strict Effect APIs: author HTTP APIs in
 
 ## Switch to Effect runtime
 
+Use the fork build plugin below. It includes the native BFF plugin and registers
+the Effect adapter. The application needs `@modern-js/bff-effect` and
+`@modern-js/plugin-bff-extensions` as production dependencies from the same
+framework cohort. Install the exact Effect peers described in
+[`bff.effect`](/configure/app/bff/effect).
+
 ```ts title="modern.config.ts"
-import { bffPlugin } from '@modern-js/plugin-bff';
-import { defineConfig } from '@modern-js/app-tools';
+import { bffPlugin } from '@modern-js/plugin-bff-build-extensions';
+import { appTools, defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
-  plugins: [bffPlugin()],
+  plugins: [appTools(), bffPlugin()],
   bff: {
     runtimeFramework: 'effect',
     effect: {
@@ -46,7 +52,7 @@ import {
   HttpApiEndpoint,
   HttpApiGroup,
   Schema,
-} from '@modern-js/plugin-bff/effect-client';
+} from '@modern-js/bff-effect/effect-client';
 
 export const bffApi = HttpApi.make('MyApi').add(
   HttpApiGroup.make('hello').add(
@@ -60,14 +66,12 @@ export const bffApi = HttpApi.make('MyApi').add(
 Implement your Effect API entry at `api/index.ts`:
 
 ```ts title="api/index.ts"
-import {
-  Schema,
-  Effect,
-  HttpApiBuilder,
-  defineEffectBff,
-  Layer,
-  ServiceMap,
-} from '@modern-js/plugin-bff/effect-server';
+import { defineEffectBff } from '@modern-js/bff-effect/effect';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 import { bffApi } from '../shared/api';
 
 class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
@@ -77,7 +81,7 @@ class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableErr
   },
 ) {}
 
-class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingService', {
+class GreetingService extends Context.Service<GreetingService>()('GreetingService', {
   make: Effect.succeed({
     hello: Effect.fn('GreetingService.hello')(function* () {
       if (Date.now() < 0) {
@@ -112,19 +116,27 @@ const layer = HttpApiBuilder.layer(bffApi).pipe(
 export default defineEffectBff({ api: bffApi, layer });
 ```
 
-Call Effect endpoints from browser code via `@api/index`:
+Create a native, fully inferred client from the shared contract:
 
 ```ts title="src/routes/page.tsx"
-import api from '@api/index';
+import { Effect, makeEffectHttpApiClient } from '@modern-js/bff-effect/effect-client';
+import { bffApi } from '../../shared/api';
 
-const response = await api.client.hello.ping({});
+const response = await Effect.runPromise(
+  makeEffectHttpApiClient(bffApi, { baseUrl: '/api' }).pipe(
+    Effect.flatMap(client => client.hello.ping({})),
+  ),
+);
 ```
 
-The `api.client.*` surface is materialized by the BFF loader for `@api/index` imports. Do not import `api/index` directly and expect `client` to run in server code, scripts, or tests; direct entry imports expose the server runtime definition, and `client` is only a typed placeholder there.
+Requests, responses, and declared errors are inferred from `bffApi`. No client generation or server-entry import is needed.
 
 For UltraModern, Effect `HttpApi` plus Effect BFF is the single blessed authored HTTP path. Use `HttpApi` endpoints with `query`, `params`, `payload`, `success`, and declared errors such as `HttpApiSchema.status(...)`; implement them with `HttpApiBuilder.group(...).handle(...)` and `HttpApiBuilder.layer(...).pipe(Layer.provide(...))`, then default-export the entry as `defineEffectBff({ api, layer })`. See `packages/server/bff-effect/tests/effect-edge-runtime.test.ts` for the live runtime shape.
 
-Hono and `api/lambda/**` are internal compatibility only and feature-frozen.
+Native Hono applications import operators from `@modern-js/plugin-bff/server`.
+UltraModern-generated applications keep their strict Effect API model. Worker
+handlers use `@modern-js/bff-effect/effect-edge`, including its worker request
+context exports; Node handlers use the Effect entry shown above.
 
 import Hono from '@site-docs-en/components/hono';
 

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

@@ -191,7 +191,7 @@ Parameters following the dynamic path are an object called `RequestOption`, whic
 In a standard function without dynamic routes, `RequestOption` can be obtained from the first parameter, for example:
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 export async function post({
   query,
@@ -204,7 +204,7 @@ export async function post({
 Custom types can also be used here:
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 type IQuery = {
   // some types

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

@@ -36,7 +36,7 @@ import BFFOperatorCode from '@site-docs/components/bff-operator-code';
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Post, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Post, Query, Data } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -89,7 +89,7 @@ As shown in the example below, you can specify the route and HTTP Method through
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query, Data } from '@modern-js/plugin-bff/server';
 
 // Specify the interface route, Modern.js sets `bff.prefix` to `/api` by default,
 // so the interface route is `/api/user`, and the HTTP Method is GET.
@@ -107,7 +107,7 @@ When the route is not specified, the interface route is defined according to the
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query, Data } from '@modern-js/plugin-bff/server';
 
 // No interface route specified, according to file convention and function name, the interface is api/user, HTTP Method is get.
 export const get = Api(Query(UserSchema), async ({ query }) => query);
@@ -144,7 +144,7 @@ Using the `Query` function, you can define the type of query. After using the `Q
 
 ```typescript title="api/lambda/user.ts"
 // Server-side code
-import { Api, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -176,7 +176,7 @@ URL query parameters are strings by default. If you need numeric types, you need
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const QuerySchema = z.object({
@@ -216,7 +216,7 @@ If you use the Data function, you must follow the HTTP protocol. When the HTTP M
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Data } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const DataSchema = z.object({
@@ -249,7 +249,7 @@ Route parameters can implement dynamic routes and get parameters from the path.
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, Params } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Params } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -274,7 +274,7 @@ You can define the request headers required by the interface through the `Header
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Headers } from '@modern-js/plugin-bff/hono-server';
+import { Api, Headers } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const headerSchema = z.object({
@@ -336,7 +336,7 @@ The `Middleware` operator can be configured multiple times, and the execution or
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Middleware } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Middleware } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -376,7 +376,7 @@ The `Pipe` operator can be configured multiple times. The execution order of fun
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -408,7 +408,7 @@ Also,
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -443,7 +443,7 @@ If you need to do more custom operations on the response, you can pass a functio
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -487,7 +487,7 @@ You can specify the status code returned by the interface through the `HttpCode(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -523,7 +523,7 @@ Supports setting response headers through the `SetHeaders(headers: Record<string
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/server';
 
 export default Api(
   Get('/hello'),
@@ -543,7 +543,7 @@ Supports redirecting the interface through `Redirect(url: string)`:
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, Redirect } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Redirect } from '@modern-js/plugin-bff/server';
 
 export default Api(
   Get('/hello'),
@@ -561,7 +561,7 @@ As mentioned above, through operators, you can get `query`, `data`, `params`, et
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { useHonoContext } from '@modern-js/server-runtime';
 import { z } from 'zod';
 
@@ -610,7 +610,7 @@ In frontend development, some server interfaces (such as some configuration inte
 <BFFOperatorCode>
 
 ```typescript
-import { Api, SetHeaders } from '@modern-js/plugin-bff/hono-server';
+import { Api, SetHeaders } from '@modern-js/plugin-bff/server';
 
 export const get = Api(
   // Cache will only take effect when using integrated calls or fetch for requests

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

@@ -18,17 +18,9 @@ UltraModern.js 3.0 is our SuperApp framework forked from Modern.js. It keeps the
 - Add platform-level contracts only where they improve cross-team reliability.
 - Keep escape hatches explicit and outside the generated HTTP API path.
 
-## Compatibility Contract
+## Current Workspace Contract
 
-UltraModern.js 3.0 keeps:
-
-- Modern.js app/config/plugin mental model.
-- Existing project structure and command flow.
-- Progressive adoption path (apps can stay mostly unchanged).
-
-UltraModern.js additions are designed as the default product surface for new SuperApps. The framework direction is Effect + TanStack + SSR + Micro Verticals, and generated HTTP API work uses that direction by default instead of preserving parallel raw-handler layouts.
-Existing Modern.js apps can migrate gradually; once an API surface is generated
-or migrated as UltraModern HTTP API, it must use the strict Effect HttpApi path.
+UltraModern.js uses Effect HttpApi, TanStack Router, SSR, and independently deployable Micro Verticals. Generated workspaces use `api/index.ts`, `shared/api.ts`, and `src/api/*` with concrete Effect schemas. The CLI creates, adds to, and validates workspaces against the current contract.
 
 ## Intentional Differences (v3 line)
 
@@ -56,21 +48,9 @@ or migrated as UltraModern HTTP API, it must use the strict Effect HttpApi path.
 - Generated UltraModern API work uses the Effect runtime only; raw Hono/function handlers are not part of the generated API architecture.
 - We make incompatible scaffold changes when they remove architecture drift.
 
-## Migration Guide
-
-For teams already on Modern.js 3.0 or an older BleedingDev UltraModern scaffold, the adoption path is to move API work onto the strict Effect HttpApi surface instead of preserving older raw handler layouts.
-
-1. Keep existing Modern.js apps running as-is while they are outside the generated UltraModern surface. TanStack Router is the preferred path for new scaffolds and incremental route adoption, but route migration can happen on the team's schedule.
-2. Use `bff.runtimeFramework: 'effect'` with `bff.effect.strictEffectApproach: true` for API work. Entries live at `api/index.ts`, contracts live at `shared/api.ts`, clients live under `src/api/*`, and request/response/error shapes come from Effect `Schema` plus `HttpApi`.
-3. Treat raw handlers, `api/lambda/**`, manual `Response` construction, and manual request parsing as migration defects in generated or migrated UltraModern workspaces.
-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.
-
-For an older generated workspace, migrate by treating the published cohort as
-the source of truth:
+## Create and Validate a Workspace
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest --help
-pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest catalog --vertical --dry-run
 pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest catalog --vertical
 mise install
 mise exec -- pnpm install
@@ -78,73 +58,12 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
-### Migrating localized Cloudflare SSR workspaces
-
-Current cohorts localize Cloudflare SSR workspaces.
-The framework moves bare locale-root redirects into the framework-owned
-Cloudflare Worker entry and the i18n server runtime. A request for `/` is
-redirected server-side with `302` to the negotiated locale path, for example
-`/cs` for `Accept-Language: cs-CZ` or `/en` for English and fallback traffic.
-
-Existing generated workspaces should upgrade the whole BleedingDev Modern
-package cohort together. Resolve the current cohort version first, then run
-the matching migration:
-
-```bash
-COHORT="$(npm view @bleedingdev/modern-js-ultramodern-create version)"
-pnpm dlx "@bleedingdev/modern-js-ultramodern-create@$COHORT" ultramodern \
-  migrate-strict-effect --version "$COHORT"
-pnpm install
-pnpm check
-pnpm build
-pnpm cloudflare:build
-```
-
-For deployed Cloudflare Workers, redeploy after the cohort update and verify
-the root response before accepting the migration:
+Localized Cloudflare SSR workspaces redirect `/` on the server to the negotiated locale. For example, `Accept-Language: cs-CZ` returns `302` with `Location: /cs`, `Cache-Control: private, no-store`, and `Vary` covering locale detection headers. Validate the deployed Worker with:
 
 ```bash
 curl -I -H 'Accept-Language: cs-CZ,cs;q=0.9,en;q=0.1' https://<worker-host>/
 ```
 
-The expected response is `302` with `Location: /cs` or the matching locale,
-`Cache-Control: private, no-store`, and `Vary` covering the locale detection
-headers. Following the redirect should return the SSR locale page with the
-matching document language and i18n SSR data.
-
-Do not fix older root `404` responses by adding app-owned root route files,
-client-side redirects, custom navigation wrappers, Cloudflare Worker
-postprocessing, generated output edits, or local redirect shims. If `/` still
-returns `404` after upgrading, confirm the production build log shows
-`Modern.js Framework v<cohort-version>` for the cohort you migrated to and
-redeploy the Worker.
-
-Strict generated API migration is part of every current cohort: the direct
-`api/index.ts` generator, generated `.mts` checks, the strict Oxlint boundary
-rule set, Effect cohort overrides, and the strict Effect migration command.
-Agents that cannot install the BleedingDev cohort yet should use the local
-Modern.js workspace for migration validation; otherwise pin the target cohort
-with `--ultramodern-package-version`.
-
-Before hand-editing package aliases or generated metadata, run the framework
-migration command from the target workspace:
-
-```bash
-COHORT="$(npm view @bleedingdev/modern-js-ultramodern-create version)"
-pnpm dlx "@bleedingdev/modern-js-ultramodern-create@$COHORT" ultramodern \
-  migrate-strict-effect --version "$COHORT"
-pnpm api:check
-pnpm contract:check
-```
-
-The command updates `.modernjs/ultramodern.json`, root
-`modernjs.packageSource`, generated Modern package aliases, framework-owned
-toolchain pins, direct topology API metadata, strict Effect pnpm
-overrides/trust policy, and the pnpm lockfile. Remaining failures are source
-migration work: move code to `shared/api.ts`, `api/index.ts`, and
-`src/api/*-client.ts`, then delete `api/effect`, `api/lambda`, `shared/effect`,
-and `src/effect`.
-
 Generated strict Effect workspaces pin the compatible Effect cohort with pnpm
 overrides: `effect@4.0.0-rc.112`, `@effect/opentelemetry@4.0.0-rc.112`,
 and `@effect/vitest@4.0.0-rc.112`. Do not add app-local direct Effect
@@ -213,7 +132,7 @@ transport surfaces when needed. They do not make raw request handlers valid
 inside generated HTTP API modules.
 
 Strict API tests should exercise the `HttpApi` contract. Use
-`createEffectBffTestHandler` from `@modern-js/plugin-bff/effect-edge` for
+`createEffectBffTestHandler` from `@modern-js/bff-effect/effect-edge` for
 edge-compatible proof tests; if you manually compose a web handler, provide
 `HttpServer.layerServices` beside your API group layer before calling
 `HttpRouter.toWebHandler`.

package/docs/zh/components/bff-operator-code.mdx

@@ -1,5 +1,5 @@
 import FrameworkCode from '@site/src/components/FrameworkCode';
 
-<FrameworkCode sourcePath="@modern-js/plugin-bff/hono-server">
+<FrameworkCode sourcePath="@modern-js/plugin-bff/server">
   {props.children}
 </FrameworkCode>

package/docs/zh/components/hono.mdx

@@ -21,7 +21,7 @@ export const get = async () => {
 在 BFF 函数中获取 Cookie 时，需要通过 `useHonoContext` 获取请求上下文，然后使用 `c.req.header('cookie')` 获取 Cookie 字符串并手动解析：
 
 ```ts title="api/lambda/cookies.ts"
-import { Api, Get } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get } from '@modern-js/plugin-bff/server';
 import { useHonoContext } from '@modern-js/server-runtime';
 
 // 解析 Cookie 字符串的辅助函数
@@ -64,7 +64,7 @@ export const getCookies = Api(Get('/cookies'), async () => {
 使用 Hono 作为运行时框架时，可以通过 [Api 函数](/guides/advanced-features/bff/operators.html) 定义接口：
 
 ```ts title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const QuerySchema = z.object({
@@ -93,7 +93,7 @@ export const getUser = Api(
 Hono 支持丰富的中间件生态，可以在 BFF 函数中使用中间件：
 
 ```ts title="api/lambda/user.ts"
-import { Api, Get, Middleware } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Middleware } from '@modern-js/plugin-bff/server';
 
 export const getUser = Api(
   Get('/user'),

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

@@ -46,10 +46,9 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 仅当 `bff.runtimeFramework` 设置为 `'effect'` 时，`bff.effect` 才会生效。
 
 :::caution 需要自行安装 Effect peer 依赖
-`effect` 与 `@effect/opentelemetry` 是 `@modern-js/plugin-bff` 的**可选精确 peer
-依赖**，而不是直接依赖。插件不再自带副本——Effect 4 的 `Context` / `Service` 键按模块
-实例生成，自带副本会让应用出现第二份 Effect 身份。在设置 `runtimeFramework: 'effect'`
-或引入 `@modern-js/plugin-bff/effect`、`/effect-server`、`/effect-edge`、
+`effect` 与 `@effect/opentelemetry` 是 `@modern-js/bff-effect` 的**可选精确 peer
+依赖**。应用必须安装这些依赖，让 API 模块与框架使用同一个 Effect 实例。在设置
+`runtimeFramework: 'effect'` 或引入 `@modern-js/bff-effect/effect`、`/effect-edge`、
 `/effect-client` 之前，请安装精确版本的依赖组：
 
 ```bash
@@ -57,9 +56,19 @@ pnpm add effect@4.0.0-rc.112 @effect/opentelemetry@4.0.0-rc.112
 ```
 
 采用精确版本是因为 UltraModern 以锁步依赖组的方式发布 Effect。只使用
-`runtimeFramework: 'hono'` 或 `./data-platform` 通道的应用无需安装这两个包。
+原生 `runtimeFramework: 'hono'` 或 `@modern-js/bff-effect/data-platform` 的应用无需安装这两个包。
 :::
 
+使用 `@modern-js/plugin-bff-build-extensions` 导出的 `bffPlugin` 注册 Effect
+运行时，它会组合原生 BFF 插件。将同一框架版本组中的 `@modern-js/bff-effect` 和
+`@modern-js/plugin-bff-extensions` 安装为应用的生产依赖，保证移除开发依赖后仍能加载
+运行时适配器。构建插件可以作为开发依赖。参见[运行时配置示例](/guides/advanced-features/bff/frameworks)。
+
+原生 `@modern-js/plugin-bff/server` 导出 Hono API。Node Effect API 从
+`@modern-js/bff-effect/effect` 导入 `defineEffectBff` 等框架 helper，命名空间从对应的
+`effect/*` 模块导入。Worker handler 和 Worker 请求上下文使用
+`@modern-js/bff-effect/effect-edge`。
+
 生成的 UltraModern workspace 只把这个运行时作为生成 HTTP API 路径。API 契约固定在
 `shared/api.ts`，服务端运行时固定在 `api/index.ts`，客户端固定在
 `src/api/*-client.ts`。生成检查会拒绝 `api/effect`、`api/lambda`、
@@ -169,7 +178,6 @@ export default defineConfig({
     endpoint: '/_data/batch',
     maxBatchSize: 16,
     maxBatchBytes: 64 * 1024,
-    flushIntervalMs: 8,
     maxConcurrency: 4,
     requestTimeoutMs: 10000,
     allowedMethods: ['GET'],
@@ -203,9 +211,9 @@ export default defineConfig({
 });
 ```
 
-`batch.flushIntervalMs` 用于控制生成的 Effect 客户端微批处理窗口；`maxConcurrency` 与 `requestTimeoutMs` 由服务端批处理网关用于内部请求分发。
+`maxConcurrency` 与 `requestTimeoutMs` 控制服务端批处理网关。原生 `HttpApiClient` 发送独立请求，不会自动批处理。
 
-生成的 `api.client.*` API 只存在于 loader 物化后的 `@api/index` 导入中。直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。
+导入共享 `HttpApi` 契约并传给 `HttpApiClient.make` 或 `makeEffectHttpApiClient`，即可获得完全类型推导的客户端。`defineEffectBff` 只提供服务端 handler，不包含客户端。
 
 ## Effect 版本组
 
@@ -237,7 +245,7 @@ attestation 的迁移，并不等同于 release-age 审批。
 Edge 兼容测试可以使用框架 helper：
 
 ```ts
-import { createEffectBffTestHandler } from '@modern-js/plugin-bff/effect-edge';
+import { createEffectBffTestHandler } from '@modern-js/bff-effect/effect-edge';
 import apiModule from '../api/index';
 
 const testApi = await createEffectBffTestHandler({
@@ -252,12 +260,9 @@ const response = await testApi.handler(new Request('http://localhost/api/ping'))
 `HttpServer.layerServices`：
 
 ```ts
-import {
-  HttpApiBuilder,
-  HttpRouter,
-  HttpServer,
-  Layer,
-} from '@modern-js/plugin-bff/effect-server';
+import * as Layer from 'effect/Layer';
+import { HttpRouter, HttpServer } from 'effect/unstable/http';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 
 const handler = HttpRouter.toWebHandler(
   HttpApiBuilder.layer(api).pipe(
@@ -275,13 +280,10 @@ const handler = HttpRouter.toWebHandler(
 Effect v4 beta 版本组中，`HttpRouter.middleware(...)` 直接返回 `Layer`：
 
 ```ts
-import {
-  Effect,
-  HttpApiBuilder,
-  HttpMiddleware,
-  HttpRouter,
-  Layer,
-} from '@modern-js/plugin-bff/effect-server';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { HttpMiddleware, HttpRouter } from 'effect/unstable/http';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 
 const corsLayer = HttpRouter.middleware(
   Effect.succeed(

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

@@ -17,7 +17,7 @@ Modern.js 的 Effect BFF 已支持基于请求信封（request envelope）的数
 
 ## 运行时契约工具
 
-可通过 `@modern-js/plugin-bff/data-platform` 使用以下能力：
+可通过 `@modern-js/bff-effect/data-platform` 使用以下能力：
 
 ```ts
 import {
@@ -30,7 +30,7 @@ import {
   validateHydrationEnvelope,
   createInvalidationEvent,
   shouldApplyInvalidation,
-} from '@modern-js/plugin-bff/data-platform';
+} from '@modern-js/bff-effect/data-platform';
 ```
 
 ## Effect 运行时校验

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

@@ -5,10 +5,10 @@ title: 运行时框架
 
 # 运行时框架
 
-Modern.js 目前支持两种 BFF 运行时框架：
+Modern.js 与 UltraModern BFF 扩展提供两种运行时框架：
 
-- `effect`（默认）：使用 `api/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
-- `hono`：使用 `api/lambda/**` 的文件约定 BFF 处理函数。
+- `hono` 是原生插件的默认运行时，使用 `api/lambda/**` 的文件约定处理函数。
+- `effect` 是 UltraModern 扩展的默认运行时，使用 `api/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
 
 `effect` 与 `hono` 为严格模式，两者之间不会自动回退。
 
@@ -22,12 +22,16 @@ workspace 中加入 Hono/file-convention handler、原始 request parsing 或手
 
 ## 切换到 Effect 运行时
 
+使用下面的 fork 构建插件，它会包含原生 BFF 插件并注册 Effect 适配器。应用需要将
+同一框架版本组中的 `@modern-js/bff-effect` 和 `@modern-js/plugin-bff-extensions`
+安装为生产依赖。Effect 的精确 peer 版本见 [`bff.effect`](/configure/app/bff/effect)。
+
 ```ts title="modern.config.ts"
-import { bffPlugin } from '@modern-js/plugin-bff';
-import { defineConfig } from '@modern-js/app-tools';
+import { bffPlugin } from '@modern-js/plugin-bff-build-extensions';
+import { appTools, defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
-  plugins: [bffPlugin()],
+  plugins: [appTools(), bffPlugin()],
   bff: {
     runtimeFramework: 'effect',
     effect: {
@@ -49,7 +53,7 @@ import {
   HttpApiEndpoint,
   HttpApiGroup,
   Schema,
-} from '@modern-js/plugin-bff/effect-client';
+} from '@modern-js/bff-effect/effect-client';
 
 export const bffApi = HttpApi.make('MyApi').add(
   HttpApiGroup.make('hello').add(
@@ -63,14 +67,12 @@ export const bffApi = HttpApi.make('MyApi').add(
 然后在 `api/index.ts` 中实现 Effect BFF 入口：
 
 ```ts title="api/index.ts"
-import {
-  Schema,
-  Effect,
-  HttpApiBuilder,
-  defineEffectBff,
-  Layer,
-  ServiceMap,
-} from '@modern-js/plugin-bff/effect-server';
+import { defineEffectBff } from '@modern-js/bff-effect/effect';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 import { bffApi } from '../shared/api';
 
 class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
@@ -80,7 +82,7 @@ class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableErr
   },
 ) {}
 
-class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingService', {
+class GreetingService extends Context.Service<GreetingService>()('GreetingService', {
   make: Effect.succeed({
     hello: Effect.fn('GreetingService.hello')(function* () {
       if (Date.now() < 0) {
@@ -115,15 +117,24 @@ const layer = HttpApiBuilder.layer(bffApi).pipe(
 export default defineEffectBff({ api: bffApi, layer });
 ```
 
-在浏览器代码中通过 `@api/index` 调用接口：
+从共享契约创建原生、完全类型推导的客户端：
 
 ```ts title="src/routes/page.tsx"
-import api from '@api/index';
+import { Effect, makeEffectHttpApiClient } from '@modern-js/bff-effect/effect-client';
+import { bffApi } from '../../shared/api';
 
-const response = await api.client.hello.ping({});
+const response = await Effect.runPromise(
+  makeEffectHttpApiClient(bffApi, { baseUrl: '/api' }).pipe(
+    Effect.flatMap(client => client.hello.ping({})),
+  ),
+);
 ```
 
-`api.client.*` 由 BFF loader 针对 `@api/index` 导入物化生成。不要直接导入 `api/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
+请求、响应和声明的错误类型均从 `bffApi` 推导，无需生成客户端代码或导入服务端入口。
+
+原生 Hono 应用从 `@modern-js/plugin-bff/server` 导入操作符。生成的 UltraModern
+应用继续使用严格 Effect API。Worker handler 及其请求上下文使用
+`@modern-js/bff-effect/effect-edge`；Node handler 使用上面示例中的 Effect 入口。
 
 import Hono from '@site-docs/components/hono';
 

package/docs/zh/guides/advanced-features/bff/function.mdx

@@ -188,7 +188,7 @@ Dynamic Path 之后的参数是包含 querystring、request body 的对象 `Requ
 在不存在动态路由的普通函数中，可以从第一个入参中获取传入的 `data` 和 `query`，例如：
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 export async function post({
   query,
@@ -201,7 +201,7 @@ export async function post({
 这里你也可以使用自定义类型：
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 type IQuery = {
   // some types

package/docs/zh/guides/advanced-features/bff/operators.mdx

@@ -36,7 +36,7 @@ import BFFOperatorCode from '@site-docs/components/bff-operator-code';
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Post, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Post, Query, Data } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -89,7 +89,7 @@ addUser({
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query, Data } from '@modern-js/plugin-bff/server';
 
 // 指定接口路由，Modern.js 默认设置 `bff.prefix` 为 `/api`，
 // 因此该接口路由为 `/api/user`，Http Method 为 GET。
@@ -107,7 +107,7 @@ export const getHello = Api(
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query, Data } from '@modern-js/plugin-bff/server';
 
 // 未指定接口路由，根据文件约定和函数名，该接口为 api/user，Http Method 为 get。
 export const get = Api(Query(UserSchema), async ({ query }) => query);
@@ -144,7 +144,7 @@ Modern.js 推荐基于文件约定去定义接口，保持项目中路由清晰
 
 ```typescript title="api/lambda/user.ts"
 // 服务端代码
-import { Api, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -176,7 +176,7 @@ URL query 参数默认是字符串类型，如果需要数字类型，需要使
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const QuerySchema = z.object({
@@ -216,7 +216,7 @@ URL query 参数都是字符串类型，如果需要数字类型，需要使用
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Data } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const DataSchema = z.object({
@@ -249,7 +249,7 @@ post({
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, Params } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Params } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -274,7 +274,7 @@ export const queryUser = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Headers } from '@modern-js/plugin-bff/hono-server';
+import { Api, Headers } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const headerSchema = z.object({
@@ -336,7 +336,7 @@ try {
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Middleware } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Middleware } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -376,7 +376,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -408,7 +408,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -443,7 +443,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -487,7 +487,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -523,7 +523,7 @@ export const post = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/server';
 
 export default Api(
   Get('/hello'),
@@ -543,7 +543,7 @@ export default Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, Redirect } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Redirect } from '@modern-js/plugin-bff/server';
 
 export default Api(
   Get('/hello'),
@@ -561,7 +561,7 @@ export default Api(
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { useHonoContext } from '@modern-js/server-runtime';
 import { z } from 'zod';
 
@@ -610,7 +610,7 @@ export const queryUser = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, SetHeaders } from '@modern-js/plugin-bff/hono-server';
+import { Api, SetHeaders } from '@modern-js/plugin-bff/server';
 
 export const get = Api(
   // 缓存使用一体化调用或者 fetch 进行请求才会生效

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

@@ -16,15 +16,11 @@ UltraModern.js 3.0 是我们从 Modern.js 分叉出来的 SuperApp 框架。它
 - 仅在跨团队稳定性场景增加平台契约。
 - 保留显式 escape hatch，但它们必须位于生成 HTTP API 模块之外。
 
-## 兼容性承诺
+## 当前 Workspace 契约
 
-UltraModern.js 3.0 保持以下不变：
-
-- Modern.js 的应用/配置/插件心智模型。
-- 既有项目结构与命令使用方式。
-- 渐进式接入路径（应用无需大规模重构）。
-
-UltraModern.js 的增强能力是新 SuperApp 的默认产品面。框架方向是 Effect + TanStack + SSR + Micro Verticals，生成的 HTTP API 只走严格 Effect HttpApi surface。既有 Modern.js 应用可以渐进迁移；一旦某个 API surface 被生成为或迁移为 UltraModern HTTP API，就必须使用严格 Effect HttpApi 路径。
+UltraModern.js 使用 Effect HttpApi、TanStack Router、SSR 和可独立部署的 Micro Verticals。
+生成的 workspace 使用 `api/index.ts`、`shared/api.ts`、`src/api/*` 和具体的 Effect schema。
+CLI 按当前契约创建、扩展和验证 workspace。
 
 ## 有意引入的差异（3.0 线）
 
@@ -50,20 +46,9 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。框架方向
 - 生成的 UltraModern HTTP API 只走严格 Effect HttpApi surface；原始 request handler 和 Hono/file-function API 不属于生成架构。
 - 除非稳定性硬需求，否则避免引入破坏性 API 变更。
 
-## 迁移指南
-
-对于已经在使用 Modern.js 3.0 或旧版 BleedingDev UltraModern scaffold 的团队，迁移路径是把 API 工作迁到严格 Effect HttpApi surface，而不是保留旧的原始 handler 布局。
-
-1. 既有 Modern.js 应用在尚未进入生成 UltraModern surface 前可以继续按现状运行。TanStack Router 是新脚手架与增量迁移的优先路径，团队可以按自己的节奏迁移路由层。
-2. 新建或迁移中的 BFF 能力使用 `bff.runtimeFramework: 'effect'`、`bff.effect.entry: './api/index'` 和 `bff.effect.strictEffectApproach: true`。接口先改 `shared/api.ts` 的 `HttpApi` 契约，再在 `api/index.ts` 用 `defineEffectBff(...)` / `HttpApiBuilder` 实现。
-3. 在生成或已迁移的 UltraModern workspace 中，把 raw handler、`api/lambda/**`、手写 `Response` 和手写 request parsing 视为迁移缺陷。
-4. 这套公开预设现在已经附带显式的发布 / 认证 gate。生成 workspace 会自带 `.github/workflows/ultramodern-workspace-gates.yml`，因此 `pnpm check` 与 `pnpm build` 从第一天开始就是本地接入契约的一部分；CI 会以并行矩阵运行这些基础 gate。
-
-旧版生成 workspace 迁移时，以已发布的包 cohort 作为事实来源：
+## 创建并验证 Workspace
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest --help
-pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest catalog --vertical --dry-run
 pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest catalog --vertical
 mise install
 mise exec -- pnpm install
@@ -71,62 +56,14 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
-### 迁移本地化 Cloudflare SSR workspace
-
-当前 cohort 均支持本地化 Cloudflare SSR workspace。框架将裸 locale root 重定向移动到框架拥有的 Cloudflare Worker entry 和 i18n
-server runtime 中。请求 `/` 时，框架会按语言协商在服务端返回 `302`，例如
-`Accept-Language: cs-CZ` 会跳转到 `/cs`，英语或 fallback 流量会跳转到 `/en`。
-
-既有生成 workspace 应整体升级同一个 BleedingDev Modern package cohort。
-先解析当前 cohort 版本，再运行同版本迁移命令：
-
-```bash
-COHORT="$(npm view @bleedingdev/modern-js-ultramodern-create version)"
-pnpm dlx "@bleedingdev/modern-js-ultramodern-create@$COHORT" ultramodern \
-  migrate-strict-effect --version "$COHORT"
-pnpm install
-pnpm check
-pnpm build
-pnpm cloudflare:build
-```
-
-Cloudflare Workers 已部署环境需要在 cohort 更新后重新部署，并在接受迁移前验证 root
-响应：
+本地化 Cloudflare SSR workspace 在服务端将 `/` 重定向到协商的语言路径。
+`Accept-Language: cs-CZ` 返回 `302`、`Location: /cs`、
+`Cache-Control: private, no-store`，以及覆盖语言检测 Header 的 `Vary`。
 
 ```bash
 curl -I -H 'Accept-Language: cs-CZ,cs;q=0.9,en;q=0.1' https://<worker-host>/
 ```
 
-期望响应是 `302`，并带有 `Location: /cs` 或匹配的 locale、
-`Cache-Control: private, no-store`，以及覆盖语言检测 Header 的 `Vary`。继续跟随该
-redirect 后，应返回匹配语言的 SSR 页面，文档语言和 i18n SSR 数据也应一致。
-
-不要通过 app 自有 root route、客户端 redirect、自定义导航 wrapper、Cloudflare Worker
-postprocess、生成产物编辑或本地 redirect shim 来修复旧版本的 root `404`。如果升级后
-`/` 仍然返回 `404`，先确认生产构建日志显示的
-`Modern.js Framework v<cohort-version>` 就是迁移目标 cohort，然后重新部署 Worker。
-
-严格生成 API 迁移是当前每个 cohort 的组成部分：直接 `api/index.ts` 生成器、生成的
-`.mts` 检查、严格 Oxlint 边界规则、Effect 版本组 overrides 和严格 Effect 迁移命令。
-还不能安装 BleedingDev cohort 的 agent 应使用本地 Modern.js workspace 做迁移校验；
-否则用 `--ultramodern-package-version` 固定目标 cohort。
-
-手写 package alias 或生成 metadata 之前，先在目标 workspace 运行框架迁移命令：
-
-```bash
-COHORT="$(npm view @bleedingdev/modern-js-ultramodern-create version)"
-pnpm dlx "@bleedingdev/modern-js-ultramodern-create@$COHORT" ultramodern \
-  migrate-strict-effect --version "$COHORT"
-pnpm api:check
-pnpm contract:check
-```
-
-该命令会更新 `.modernjs/ultramodern.json`、根 `modernjs.packageSource`、生成的
-Modern package alias、框架拥有的 toolchain pin、直接 topology API metadata、严格 Effect
-pnpm overrides/trust policy 和 pnpm lockfile。剩余失败就是源码迁移：把代码移到
-`shared/api.ts`、`api/index.ts` 和 `src/api/*-client.ts`，再删除 `api/effect`、
-`api/lambda`、`shared/effect` 和 `src/effect`。
-
 严格 Effect 生成 workspace 会通过 pnpm overrides 固定兼容版本组：
 `effect@4.0.0-rc.112`、`@effect/opentelemetry@4.0.0-rc.112` 和
 `@effect/vitest@4.0.0-rc.112`。不要添加与这些 overrides 冲突的 app 本地直接
@@ -190,7 +127,7 @@ Effect RPC、WebSockets 和其他传输方式应在需要时作为显式 transpo
 它们不能作为在生成 HTTP API 模块中重新引入原始 request handler 的理由。
 
 严格 API 测试应执行 `HttpApi` 契约。Edge 兼容 proof 测试使用
-`@modern-js/plugin-bff/effect-edge` 的 `createEffectBffTestHandler`；如果必须手动组合
+`@modern-js/bff-effect/effect-edge` 的 `createEffectBffTestHandler`；如果必须手动组合
 web handler，在调用 `HttpRouter.toWebHandler` 前要把 `HttpServer.layerServices` 和
 API group layer 一起提供。
 

package/package.json

@@ -19,13 +19,13 @@
     "modern.js",
     "ultramodern.js"
   ],
-  "version": "3.9.0-ultramodern.4",
+  "version": "3.9.0-ultramodern.6",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.9.0-ultramodern.4",
-    "@modern-js/ultramodern-sandpack-profile": "npm:@bleedingdev/modern-js-ultramodern-sandpack-profile@3.9.0-ultramodern.4",
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.9.0-ultramodern.6",
+    "@modern-js/ultramodern-sandpack-profile": "npm:@bleedingdev/modern-js-ultramodern-sandpack-profile@3.9.0-ultramodern.6",
     "mermaid": "^11.17.2"
   },
   "devDependencies": {

package/src/sandbox/csr-auth/src/routes/Auth-tsx.txt

@@ -1,6 +1,6 @@
 import {
   Navigate,
-  useLocation,
+  useMatch,
   useNavigate,
 } from '@modern-js/plugin-tanstack/runtime';
 import React from 'react';
@@ -52,8 +52,9 @@ export function AuthStatus() {
       Welcome {auth.user}!{' '}
       <button
         type="button"
-        onClick={() => {
-          auth.signout(() => void navigate({ to: '/' }));
+        onClick={async () => {
+          await navigate({ to: '/' });
+          auth.signout(() => {});
         }}
       >
         Sign out
@@ -62,9 +63,12 @@ export function AuthStatus() {
   );
 }
 
-export function RequireAuth({ children }: { children: JSX.Element }) {
+export function RequireAuth({ children }: { children: React.JSX.Element }) {
   const auth = useAuth();
-  const location = useLocation();
+  const pathname = useMatch({
+    strict: false,
+    select: match => match.pathname,
+  });
 
   if (!auth.user) {
     // Redirect them to the /login page, but save the current location they were
@@ -74,7 +78,7 @@ export function RequireAuth({ children }: { children: JSX.Element }) {
     return (
       <Navigate
         replace
-        search={{ redirect: location.pathname }}
+        search={{ redirect: pathname }}
         to="/login"
       />
     );

package/src/sandbox/csr-auth/src/routes/page-tsx.txt

@@ -1,4 +1,5 @@
 import { Helmet } from '@modern-js/runtime/head';
+import type { JSX } from 'react';
 import './index.css';
 
 const PublicPage = (): JSX.Element => (