@bleedingdev/modern-js-main-doc 3.4.0-ultramodern.8 → 3.5.0-ultramodern.0

package/docs/en/community/blog/v3-release-note.mdx

@@ -591,7 +591,7 @@ As Node.js continues to evolve, Node.js 18 has reached EOL. In Modern.js 3.0, we
 
 #### Storybook Rsbuild
 
-In Modern.js 3.0, we implemented Storybook for Modern.js applications based on [Storybook Rsbuild](https://github.com/rspack-contrib/storybook-rsbuild).
+In Modern.js 3.0, we implemented Storybook for Modern.js applications based on [Storybook Rsbuild](https://github.com/rstackjs/storybook-rsbuild).
 
 Through a Storybook Addon, we convert and merge Modern.js configuration into Rsbuild configuration, and use Storybook Rsbuild to drive the build, keeping Storybook debugging aligned with development command configurations.
 

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

@@ -9,6 +9,7 @@ title: effect
 ```ts
 type BffEffectUserConfig = {
   entry?: string;
+  strictEffectApproach?: true;
   openapi?: boolean | { path?: string };
   dataPlatform?: {
     enabled?: boolean;
@@ -58,7 +59,7 @@ For Effect v4, TypeScript should use export-map aware module resolution.
 ## bff.effect.entry
 
 - **Type:** `string`
-- **Default:** `<apiDirectory>/effect/index`
+- **Default:** `<apiDirectory>/index`
 
 Specifies the entry module for Effect HttpApi runtime.
 
@@ -67,12 +68,23 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
-      entry: './api/effect/index',
+      entry: './api/index',
     },
   },
 });
 ```
 
+## bff.effect.strictEffectApproach
+
+- **Type:** `true`
+- **Default:** `true`
+
+Effect BFF modules must expose the strict Effect API surface
+(`defineEffectBff(...)` or `{ api, layer }`) and raw request handlers are
+rejected. Generated UltraModern apps write this marker explicitly and pair it
+with source checks that reject Hono server imports, manual request parsing, and
+manual `Response` construction in generated API modules.
+
 ## bff.effect.openapi
 
 - **Type:** `boolean | { path?: string }`
@@ -173,4 +185,4 @@ 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.
 
-The generated `effectBff.client.*` API only exists for loader-materialized `@api/effect/*` imports. Directly importing the server entry (`api/effect/index`) exposes the Effect BFF definition; its `client` property is a placeholder that fails on operation access.
+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.

package/docs/en/configure/app/bff/runtime-framework.mdx

@@ -21,8 +21,10 @@ export default defineConfig({
 });
 ```
 
-- Set to `'effect'` to run BFF only from `api/effect/index` (Effect HttpApi runtime).
+- Set to `'effect'` to run BFF only from `api/index` (Effect HttpApi runtime).
 - Set to `'hono'` to run BFF only from file-convention handlers under `api/lambda/**`.
 
 There is no implicit fallback between runtimes. Choose one runtime mode per app.
-Generated UltraModern apps use the Effect lane by default; set `runtimeFramework: 'hono'` only for the compatibility runtime.
+Generated UltraModern apps use strict Effect APIs by default and set
+`bff.effect.strictEffectApproach: true`; `hono` and `api/lambda/**` are not
+valid generated UltraModern HTTP API paths.

package/docs/en/configure/app/experiments/source-build.mdx

@@ -19,7 +19,7 @@ More detail can see ["Source Code Build Mode"](https://modernjs.dev/en/guides/ad
 
 ### Options
 
-`experiments.sourceBuild` is implemented based on [@rsbuild/plugin-source-build](https://github.com/rspack-contrib/rsbuild-plugin-source-build?tab=readme-ov-file#options). You can pass plugin options like this:
+`experiments.sourceBuild` is implemented based on [@rsbuild/plugin-source-build](https://github.com/rstackjs/rsbuild-plugin-source-build?tab=readme-ov-file#options). You can pass plugin options like this:
 
 ```ts
 export default {

package/docs/en/configure/app/html/template-parameters.mdx

@@ -30,7 +30,7 @@ type DefaultParameters = {
 };
 ```
 
-Define the parameters in the HTML template, corresponding to the `templateParameters` config of [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin). You can use the config as an object or a function.
+Define the parameters in the HTML template, corresponding to the `templateParameters` config of [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin). You can use the config as an object or a function.
 
 import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
 

package/docs/en/configure/app/output/convert-to-rem.mdx

@@ -80,4 +80,4 @@ export default {
 };
 ```
 
-For detailed usage, please refer to [rsbuild-plugin-rem](https://github.com/rspack-contrib/rsbuild-plugin-rem).
+For detailed usage, please refer to [rsbuild-plugin-rem](https://github.com/rstackjs/rsbuild-plugin-rem).

package/docs/en/configure/app/security/check-syntax.mdx

@@ -70,4 +70,4 @@ If a syntax error is detected, you can handle it in the following ways:
 
 ### Options
 
-`security.checkSyntax` is implemented based on `@rsbuild/plugin-check-syntax`. For specific options, please refer to [@rsbuild/plugin-check-syntax](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax).
+`security.checkSyntax` is implemented based on `@rsbuild/plugin-check-syntax`. For specific options, please refer to [@rsbuild/plugin-check-syntax](https://github.com/rstackjs/rsbuild-plugin-check-syntax).

package/docs/en/configure/app/tools/html-plugin.mdx

@@ -38,7 +38,7 @@ const defaultOptions = {
 SSR Application does not enable the `minify.removeComments` configuration, otherwise the SSR rendering will fail.
 :::
 
-The configs of [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) can be modified through `tools.htmlPlugin`.
+The configs of [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) can be modified through `tools.htmlPlugin`.
 
 import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
 

package/docs/en/configure/app/tools/ts-checker.mdx

@@ -43,7 +43,9 @@ By default, the [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild
 
 ## Example
 
-When the value of `tsChecker` is of type Object, it will be deeply merged with the default configuration.
+### Object Type
+
+When the value of `tsChecker` is an object, it will be deeply merged with the default configuration.
 
 ```ts
 export default {
@@ -57,6 +59,23 @@ export default {
 };
 ```
 
+### Function Type
+
+When the value of `tsChecker` is a function, the default configuration will be passed as the first argument. You can directly modify the configuration object or return an object as the final configuration.
+
+```ts
+export default {
+  tools: {
+    tsChecker(options) {
+      options.async = false;
+      return options;
+    },
+  },
+};
+```
+
+> Please refer to [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) for more details.
+
 ## TypeScript Go by Default
 
 Type checking runs on [TypeScript Go](https://github.com/microsoft/typescript-go) (`tsgo`) by default in this fork. The capability is provided by [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin), which is integrated by [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check), and reduces type-checking time by about 5-10x.

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

@@ -4,7 +4,7 @@ title: Data Platform
 
 # Data Platform
 
-Modern.js Effect BFF now supports a request-envelope based data platform contract for safer and more predictable data orchestration in complex applications such as Module Federation and micro frontends.
+Modern.js Effect API runtime now supports a request-envelope based data platform contract for safer and more predictable data orchestration in complex applications such as Module Federation and micro frontends.
 
 ## What it solves
 
@@ -57,11 +57,11 @@ export default defineConfig({
 
 Envelope validation is enabled by default but does not require an envelope unless `requireEnvelope` is set. Origin validation is enabled by default; set `validateOrigin: false` to skip comparing the envelope origin against the incoming `Origin` header, or the request URL origin when the header is absent.
 
-## Generated Effect client behavior
+## Generated API client behavior
 
-When using the generated Effect client (`@api/effect/index`), Modern.js automatically attaches a serialized data envelope header (`x-modernjs-data-envelope`) for same-origin requests.
+When using the generated API client (`@api/index`), Modern.js automatically attaches a serialized data envelope header (`x-modernjs-data-envelope`) for same-origin requests.
 
-The generated client is loader-materialized. Import it from `@api/effect/*` in browser or client-bundled code; direct imports of the server entry (`api/effect/index`) expose the Effect BFF definition and only provide a placeholder `client`.
+The generated client is loader-materialized. Import it from `@api/index` in browser or client-bundled code; direct imports of the server entry (`api/index`) expose the Effect API definition and only provide a placeholder `client`.
 
 The envelope includes:
 

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

@@ -7,11 +7,20 @@ title: Runtime Framework
 
 Modern.js supports two BFF runtime frameworks:
 
-- `effect` (default): use [Effect HttpApi](https://effect.website/) runtime from `api/effect/index`.
+- `effect` (default): use [Effect HttpApi](https://effect.website/) runtime from `api/index`.
 - `hono`: use file-convention BFF handlers from `api/lambda/**`.
 
 `effect` and `hono` are strict runtime modes. There is no automatic fallback between them.
 
+::::info
+This page documents generic Modern.js runtime support. Generated UltraModern
+workspaces always use the `effect` runtime with
+`bff.effect.strictEffectApproach: true`. Add or change generated UltraModern
+HTTP API work through `shared/api.ts` and `api/index.ts`; do not add
+Hono/file-convention handlers, raw request parsing, or manual `Response`
+construction inside those workspaces.
+::::
+
 ## Switch to Effect runtime
 
 ```ts title="modern.config.ts"
@@ -23,6 +32,8 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
+      entry: './api/index',
+      strictEffectApproach: true,
       openapi: {
         path: '/openapi.json',
       },
@@ -33,7 +44,7 @@ export default defineConfig({
 
 Define a shared Effect HttpApi contract (for type-safe client + server):
 
-```ts title="shared/effect/api.ts"
+```ts title="shared/api.ts"
 import {
   HttpApi,
   HttpApiEndpoint,
@@ -41,18 +52,18 @@ import {
   Schema,
 } from '@modern-js/plugin-bff/effect-client';
 
-export const bffEffectApi = HttpApi.make('MyApi').add(
+export const bffApi = HttpApi.make('MyApi').add(
   HttpApiGroup.make('hello').add(
-    HttpApiEndpoint.get('ping', '/effect/ping', {
+    HttpApiEndpoint.get('ping', '/ping', {
       success: Schema.String,
     }),
   ),
 );
 ```
 
-Implement your Effect BFF entry at `api/effect/index.ts`:
+Implement your Effect API entry at `api/index.ts`:
 
-```ts title="api/effect/index.ts"
+```ts title="api/index.ts"
 import {
   Schema,
   Effect,
@@ -61,7 +72,7 @@ import {
   Layer,
   ServiceMap,
 } from '@modern-js/plugin-bff/effect-server';
-import { bffEffectApi } from '../../shared/effect/api';
+import { bffApi } from '../shared/api';
 
 class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
   'GreetingUnavailableError',
@@ -87,7 +98,7 @@ class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingSer
   static readonly layer = Layer.effect(this, this.make);
 }
 
-const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
+const group = HttpApiBuilder.group(bffApi, 'hello', handlers =>
   handlers.handle('ping', () =>
     GreetingService.use(service => service.hello()).pipe(
       Effect.catchTag('GreetingUnavailableError', error =>
@@ -97,23 +108,23 @@ const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
   ),
 );
 
-const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
+const layer = HttpApiBuilder.layer(bffApi).pipe(
   Layer.provide(group),
   Layer.provide(GreetingService.layer),
 );
 
-export default defineEffectBff({ api: bffEffectApi, layer });
+export default defineEffectBff({ api: bffApi, layer });
 ```
 
-Call Effect endpoints from browser code via `@api/effect/index`:
+Call Effect endpoints from browser code via `@api/index`:
 
 ```ts title="src/routes/page.tsx"
-import effectBff from '@api/effect/index';
+import api from '@api/index';
 
-const response = await effectBff.client.hello.ping({});
+const response = await api.client.hello.ping({});
 ```
 
-The `effectBff.client.*` surface is materialized by the BFF loader for `@api/effect/*` imports. Do not import `api/effect/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.
+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.
 
 import Hono from '@site-docs-en/components/hono';
 

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

@@ -2,6 +2,10 @@
 
 In a Modern.js application, developers can define API files under the `api/lambda` directory and export API functions from these files. In the frontend code, these API functions can be directly invoked by importing the file, which initiates the API requests.
 
+:::warning
+`api/lambda/**` is the Hono/file-function compatibility runtime. New UltraModern generated API work should use the strict Effect runtime with `api/index.ts`, `shared/api.ts`, `defineEffectBff(...)`, and Effect `HttpApi` schemas instead.
+:::
+
 This invocation method is called **unified invocation**, where developers do not need to write glue code for the frontend and backend separately, thereby ensuring type safety across both.
 
 ## Enable BFF

package/docs/en/guides/advanced-features/page-performance/optimize-bundle.mdx

@@ -92,7 +92,7 @@ export default {
 };
 ```
 
-See details in [plugin-image-compress](https://github.com/rspack-contrib/rsbuild-plugin-image-compress).
+See details in [plugin-image-compress](https://github.com/rstackjs/rsbuild-plugin-image-compress).
 
 ## Split Chunk
 

package/docs/en/guides/basic-features/debug/using-storybook.mdx

@@ -97,4 +97,4 @@ Now you can request the path configured in `bff.prefix`; if not configured, use
 
 ## Example
 
-You can check out the [example](https://github.com/rspack-contrib/storybook-rsbuild/tree/main/sandboxes/modernjs-react) to learn how to use Storybook in Modern.js.
+You can check out the [example](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react) to learn how to use Storybook in Modern.js.

package/docs/en/guides/basic-features/static-assets/json-files.mdx

@@ -38,7 +38,7 @@ import { name } from './example.json';
 
 YAML is a data serialization language commonly used for writing configuration files.
 
-You can configure the [YAML plugin](https://github.com/rspack-contrib/rsbuild-plugin-yaml) in `modern.config.ts` to support importing `.yaml` or `.yml` files, they will be automatically converted to JSON format.
+You can configure the [YAML plugin](https://github.com/rstackjs/rsbuild-plugin-yaml) in `modern.config.ts` to support importing `.yaml` or `.yml` files, they will be automatically converted to JSON format.
 
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
@@ -85,7 +85,7 @@ declare module '*.yml' {
 
 Toml is a semantically explicit, easy-to-read configuration file format.
 
-You can configure the [TOML plugin](https://github.com/rspack-contrib/rsbuild-plugin-toml) in `modern.config.ts` to support importing `.toml` files, it will be automatically converted to JSON format.
+You can configure the [TOML plugin](https://github.com/rstackjs/rsbuild-plugin-toml) in `modern.config.ts` to support importing `.toml` files, it will be automatically converted to JSON format.
 
 ```ts
 import { defineConfig } from '@modern-js/app-tools';

package/docs/en/guides/get-started/_meta.json

@@ -4,5 +4,6 @@
   "quick-start",
   "upgrade",
   "glossary",
-  "tech-stack"
+  "tech-stack",
+  "ai-coding-agents"
 ]

package/docs/en/guides/get-started/ai-coding-agents.mdx

@@ -0,0 +1,48 @@
+---
+title: AI Tools
+sidebar_position: 6
+---
+
+# Modern.js For AI
+
+Modern.js provides a toolkit for AI agents that helps developers use AI to efficiently complete feature development, dependency upgrades, and version migration for Modern.js applications.
+
+## llms.txt
+
+Modern.js docs follow the [llms.txt specification](https://llmstxt.org/), auto-generated by [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms), accessible via `/llms.txt` or `/llms-full.txt`:
+
+- Index: [`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
+- Full text: `https://modernjs.dev/llms-full.txt` (large — fetch on demand)
+
+Most "what is this API / config" questions can be answered from llms.txt. Just let your agent retrieve it on demand; no need to copy docs into your project.
+
+## Skills
+
+Skills are on-demand AI capabilities following the [Agent Skills open standard](https://github.com/vercel-labs/skills). User-facing Skills:
+
+| Skill | Identifier | Description |
+|---|---|---|
+| Upgrade to v3 | `modernjs-migrate-to-v3` | Migrate a v2 app to v3: safe rewrites + manual checklist + migration report |
+| Enable features | `modernjs-feature-enable` | Enable BFF / SSG / styled-components for v3 apps, and scaffold Tailwind CSS / custom Web Server |
+
+> Skills are not force-installed or implicitly installed — you install them explicitly. RSC and micro-frontend setups are configuration or architecture decisions, not one-click `modernjs-feature-enable` actions.
+
+## Installing Skills
+
+Modern.js user-facing Skills live in the repo's root `skills/` directory and follow the [Agent Skills open standard](https://github.com/vercel-labs/skills). The recommended way is the standard `skills` CLI, installing straight from GitHub:
+
+```bash
+# List installable Skills
+npx skills add web-infra-dev/modern.js --list
+
+# Install a single Skill into your agent directory (--agent: claude-code / codex / cursor / ...)
+npx skills add web-infra-dev/modern.js --skill modernjs-migrate-to-v3 --agent codex -y
+```
+
+It installs the entire Skill directory (`SKILL.md` + `scripts/` + `references/`) into the corresponding agent directory, ready to trigger there.
+
+> To pin a specific version, append `#<ref>` (a tag, branch, or commit) to the repo — it installs the Skill as of that ref (replace `<tag>` with a release tag that contains this Skill):
+>
+> ```bash
+> npx skills add web-infra-dev/modern.js#<tag> --skill modernjs-migrate-to-v3 --agent codex -y
+> ```

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

@@ -7,14 +7,16 @@ sidebar_position: 2
 
 This page compares **UltraModern.js 3.0** with the Modern.js 3.x line this fork tracks. The baseline is the current merged Modern.js `release-v3.x` baseline, not a frozen patch-version snapshot.
 
-UltraModern.js 3.0 is our SuperApp framework forked from Modern.js. It keeps compatibility with the Modern.js plugin/runtime mental model where that helps adoption, but it is positioned as a separate framework for Effect-first BFFs, TanStack Router, SSR, Module Federation, and independently deployable Micro Verticals.
+UltraModern.js 3.0 is our SuperApp framework forked from Modern.js. It keeps the Modern.js plugin/runtime mental model where that helps adoption, but it is positioned as a separate framework for Effect HttpApi-first HTTP APIs, TanStack Router, SSR, Module Federation, and independently deployable Micro Verticals.
 
 ## Design Principles
 
 - Keep deltas explicit and auditable.
-- Preserve compatibility with useful Modern.js concepts without presenting UltraModern.js as a preset-only variant.
+- Keep upstream Modern.js merge compatibility explicit: generic Modern.js runtime
+  code can remain where it belongs, while UltraModern-generated surfaces stay
+  strict.
 - Add platform-level contracts only where they improve cross-team reliability.
-- Keep opt-out switches and explicit compatibility lanes available.
+- Keep escape hatches explicit and outside the generated HTTP API path.
 
 ## Compatibility Contract
 
@@ -24,7 +26,9 @@ UltraModern.js 3.0 keeps:
 - 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. Compatibility lanes remain available when they reduce migration risk, but the framework direction is Effect + TanStack + SSR + Micro Verticals.
+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.
 
 ## Intentional Differences (v3 line)
 
@@ -33,7 +37,7 @@ UltraModern.js additions are designed as the default product surface for new Sup
 | Build diagnostics | RsDoctor is generally opt-in | Adds a first-class `performance.rsdoctor` config surface (opt-in; the earlier default-on behavior and diagnostics contract artifact were reverted) |
 | Output and static serving | Precompression behavior is app-defined | Enables `output.precompress` by default and serves `.br` / `.gz` variants via `Accept-Encoding` negotiation |
 | BFF runtime and contracts | Standard BFF runtime/client generation | Adds `requestId`-aware producer isolation, fail-fast initialization checks, and operation/trace correlation headers |
-| BFF runtime choices | Hono runtime path only in Modern.js 3.0 baseline (no built-in Effect runtime path) | Sets Effect as default runtime, enforces strict runtime split (`effect` -> `api/effect`, `hono` -> `api/lambda`), and adds Effect-Schema-first contracts plus MF failure-injection reliability coverage |
+| BFF runtime choices | Standard request-handler oriented BFF paths | Uses Effect `HttpApi` as the only generated HTTP API path (`api/index.ts`, `shared/api.ts`, `src/api/*`) and rejects raw handlers, manual parsing, manual `Response` construction, and Hono server imports in generated workspaces |
 | 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 vertical loading reliability | Retry/fallback patterns are often implemented per app | Adds deterministic timeout/network/contract-error reliability matrix and distributed OTEL continuity tests |
@@ -46,16 +50,19 @@ UltraModern.js additions are designed as the default product surface for new Sup
 
 - We do not hide the fork behind legacy Modern.js branding.
 - We do not optimize for generic Modern.js defaults when they conflict with SuperApp reliability.
-- We keep both runtime modes (`effect`, `hono`) as explicit choices and avoid implicit fallback between them.
-- We avoid incompatible API changes unless there is a hard reliability requirement.
+- We do not delete generic Modern.js Hono/file-convention runtime support just
+  to enforce UltraModern policy; the enforcement lives in UltraModern
+  generator, config, checks, and generated workspaces.
+- 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 remains compatibility-aware: keep the pieces that reduce risk, move toward MV-first / TanStack-first / Effect-first defaults, and keep fallback lanes explicit while you adopt UltraModern.js 3.0 as a separate framework.
+For teams already on Modern.js 3.0 or an older BleedingDev UltraModern scaffold, the adoption path is to move API work onto the strict Effect HttpApi surface instead of preserving older raw handler layouts.
 
-1. Keep existing React Router apps running as-is. TanStack Router is the preferred path for new scaffolds and incremental route adoption, but the React Router lane remains supported while teams move on their own schedule.
-2. Prefer `bff.runtimeFramework: 'effect'` for new BFF work, with the entry implemented at `api/effect/index.ts`. If your app already uses Hono handlers under `api/lambda/**`, keep `bff.runtimeFramework: 'hono'` until you are ready to move them; Hono remains a supported compatibility lane.
-3. Treat the baseline contracts as progressive defaults, not a forced cutover. `MODERN_BASELINE_ENABLE_MF_SSR`, `MODERN_BASELINE_ENABLE_BFF_REQUEST_ID`, and `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` already let each app opt out while it converges on the preferred stack.
+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
@@ -71,14 +78,58 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
+Strict generated API migration requires `3.5.0-ultramodern.0` or newer.
+`3.4.0-ultramodern.20` and earlier cohorts do not include this full direct
+`api/index.ts` generator, generated `.mts` checks, and strict Oxlint boundary
+rule set. Agents that cannot install that BleedingDev cohort yet should use the
+local Modern.js workspace for migration validation; otherwise pin
+`3.5.0-ultramodern.0` or newer with `--ultramodern-package-version`.
+
+Gradual migration means old, unmigrated Modern.js apps can keep their existing
+runtime until they are converted. Once a surface is generated or migrated as
+UltraModern HTTP API, it uses Effect HttpApi only; do not keep Hono, lambda
+handlers, or raw request handlers inside that UltraModern API surface.
+
+When migrating a generated workspace that already has nested Effect API files, make the
+move explicit and do not keep compatibility aliases:
+
+1. Move each vertical server entry from `verticals/<id>/api/effect/index.ts` to
+   `verticals/<id>/api/index.ts`.
+2. Move each shared API contract from `verticals/<id>/shared/effect/api.ts` to
+   `verticals/<id>/shared/api.ts`.
+3. Move generated clients from `verticals/<id>/src/effect/*-client.ts` to
+   `verticals/<id>/src/api/*-client.ts`.
+4. Move shell API aggregates from `apps/shell-super-app/src/effect/*` to
+   `apps/shell-super-app/src/api/*`.
+5. Update imports and package exports to use `./api`, `./api/client`, and
+   `@<workspace>/<vertical>/api/client`; remove `./effect/client`,
+   `./shared/effect/api`, and shared Effect API packages.
+6. Update every vertical `modern.config.ts` to use
+   `bff.effect.entry: './api/index'` and
+   `bff.effect.strictEffectApproach: true`.
+7. Update topology so API metadata lives directly under `api` with
+   `api.bff.strictEffectApproach: true`; do not keep `api.effect`.
+8. Run `pnpm api:check`,
+   `scripts/validate-ultramodern-workspace.mts`, `pnpm check`, and
+   `pnpm build`.
+
+If a migration fails, fix the owning generated contract, topology, package
+exports, or API module. Do not add app-level aliases, raw request handlers,
+manual `Response` construction, local type casts, or package shims to make the
+old layout pass.
+
+Effect RPC, WebSockets, and other transports should be added as explicit
+transport surfaces when needed. They do not make raw request handlers valid
+inside generated HTTP API modules.
+
 Use one package-source strategy per repo. The published BleedingDev create
 package defaults to `--ultramodern-package-source=install` and records the
-exact cohort in `.modernjs/ultramodern-package-source.json`. Keep `--workspace`
-only for local monorepo testing against unreleased packages. Release proof and
-CI should pin the exact cohort with `--ultramodern-package-version` when a
-repo must prove a specific published framework version.
+exact cohort in `.modernjs/ultramodern.json`. Keep `--workspace` only for local
+monorepo testing against unreleased packages. Release proof and CI should pin
+the exact cohort with `--ultramodern-package-version` when a repo must prove a
+specific published framework version.
 
-Older repos with Effect BFF entries and `verbatimModuleSyntax` should update to
+Older repos with nested Effect entries and `verbatimModuleSyntax` should update to
 the latest BleedingDev cohort instead of adding app-level `"type": "module"`
 metadata, Module Federation shims, or custom server wrappers. The framework BFF
 compiler normalizes CommonJS server output while generated app packages keep
@@ -92,7 +143,7 @@ repos by hand-editing generated worker output; upgrade the framework cohort and
 rerun the generated validation instead.
 
 After installing the new cohort, run the generated
-`scripts/validate-ultramodern-workspace.mjs` contract check before accepting
+`scripts/validate-ultramodern-workspace.mts` contract check before accepting
 manual edits. Fix topology, ownership, package-source, local overlay, generated
 contract, Tailwind prefix, or Module Federation conflicts in the owning files
 instead of patching generated output by hand.
@@ -182,10 +233,10 @@ addUltramodernVertical({
 ```
 
 The public result includes the workspace root, package source, created apps,
-created paths, rewritten paths, assigned ports, Module Federation names, Effect
-API prefixes, generated contract path, and warnings. MicroVertical dry-run
+created paths, rewritten paths, assigned ports, Module Federation names, API
+prefixes, generated contract path, and warnings. MicroVertical dry-run
 returns the same shape plus `dryRun`, `selectedPort`, `moduleFederationRemote`,
-`effectApiPrefix`, `jsonMutations`, `shellDependencyChanges`, and
+`apiPrefix`, `jsonMutations`, `shellDependencyChanges`, and
 `generatedContractChanges`; it prints JSON from the CLI and writes no files.
 
 CodeSmith consumers can use the adapter subpath:
@@ -239,8 +290,8 @@ non-indexable routes emit no JSON-LD by default. Public route owners can add
 `jsonLd` beside localized paths and use the generated
 `src/routes/ultramodern-jsonld.ts` helpers for common schema.org shapes.
 
-The generated contract writes `.modernjs/ultramodern-generated-contract.json`
-with a `cssFederation` section:
+The generated contract writes `.modernjs/ultramodern.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"]`.
@@ -248,7 +299,7 @@ with a `cssFederation` section:
 - 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.
+Version switching must select UI, API, CSS, i18n JSON, and MF manifest evidence from the same vertical build marker. A shell render that only changes the UI marker is not enough.
 
 ### Validation And Deploy
 

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

@@ -314,7 +314,7 @@ export default {
 
 ### tools.pug
 
-**Change**: This configuration has been deprecated, use Rsbuild's [Pug plugin](https://github.com/rspack-contrib/rsbuild-plugin-pug) to enable support.
+**Change**: This configuration has been deprecated, use Rsbuild's [Pug plugin](https://github.com/rstackjs/rsbuild-plugin-pug) to enable support.
 
 **Migration Example**:
 

package/docs/en/plugin/introduction.mdx

@@ -131,21 +131,21 @@ The following are official Rsbuild plugins that are already built into Modern.js
 | [React Plugin](https://v2.rsbuild.rs/plugins/list/plugin-react)                        | Provides support for React                                                                                                                      | -                                                                                                                                     |
 | [SVGR Plugin](https://v2.rsbuild.rs/plugins/list/plugin-svgr)                          | Supports converting SVG images into React components                                                                                            | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export)     |
 | [Assets Retry Plugin](https://github.com/rstackjs/rsbuild-plugin-assets-retry)          | Automatically retries requests when static asset loading fails                                                                                  | [output.assetsRetry](/configure/app/output/assets-retry.html)                                                                         |
-| [Type Check Plugin](https://github.com/rspack-contrib/rsbuild-plugin-type-check)       | Runs TypeScript type checking in a separate process                                                                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
-| [Source Build Plugin](https://github.com/rspack-contrib/rsbuild-plugin-source-build)   | For monorepo scenarios, supports referencing source code from other subdirectories and completing builds and hot updates                        | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |
-| [Check Syntax Plugin](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax)   | Analyzes the syntax compatibility of the build artifacts to determine if there are any advanced syntax features that cause compatibility issues | [security.checkSyntax](/configure/app/security/check-syntax.html)                                                                     |
-| [CSS Minimizer Plugin](https://github.com/rspack-contrib/rsbuild-plugin-css-minimizer) | Used to customize the CSS compression tool, switch to [cssnano](https://cssnano.co/) or other tools for CSS compression                         | [tools.minifyCss](/configure/app/tools/minify-css.html)                                                                               |
-| [Rem Plugin](https://github.com/rspack-contrib/rsbuild-plugin-rem)                     | Implements rem adaptive layout for mobile pages                                                                                                 | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
+| [Type Check Plugin](https://github.com/rstackjs/rsbuild-plugin-type-check)             | Runs TypeScript type checking in a separate process                                                                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
+| [Source Build Plugin](https://github.com/rstackjs/rsbuild-plugin-source-build)   | For monorepo scenarios, supports referencing source code from other subdirectories and completing builds and hot updates                        | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |
+| [Check Syntax Plugin](https://github.com/rstackjs/rsbuild-plugin-check-syntax)   | Analyzes the syntax compatibility of the build artifacts to determine if there are any advanced syntax features that cause compatibility issues | [security.checkSyntax](/configure/app/security/check-syntax.html)                                                                     |
+| [CSS Minimizer Plugin](https://github.com/rstackjs/rsbuild-plugin-css-minimizer) | Used to customize the CSS compression tool, switch to [cssnano](https://cssnano.co/) or other tools for CSS compression                         | [tools.minifyCss](/configure/app/tools/minify-css.html)                                                                               |
+| [Rem Plugin](https://github.com/rstackjs/rsbuild-plugin-rem)                     | Implements rem adaptive layout for mobile pages                                                                                                 | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
 
 #### Plugins Not Built-in
 
 The following are official Rsbuild plugins that are not built into Modern.js:
 
-- [Image Compress Plugin](https://github.com/rspack-contrib/rsbuild-plugin-image-compress): Compresses image resources used in the project.
+- [Image Compress Plugin](https://github.com/rstackjs/rsbuild-plugin-image-compress): Compresses image resources used in the project.
 - [Stylus Plugin](https://v2.rsbuild.rs/plugins/list/plugin-stylus): Uses Stylus as the CSS preprocessor.
-- [UMD Plugin](https://github.com/rspack-contrib/rsbuild-plugin-umd): Used to build UMD format artifacts.
-- [YAML Plugin](https://github.com/rspack-contrib/rsbuild-plugin-yaml): Used to reference YAML files and convert them to JavaScript objects.
-- [TOML Plugin](https://github.com/rspack-contrib/rsbuild-plugin-toml): Used to reference TOML files and convert them to JavaScript objects.
+- [UMD Plugin](https://github.com/rstackjs/rsbuild-plugin-umd): Used to build UMD format artifacts.
+- [YAML Plugin](https://github.com/rstackjs/rsbuild-plugin-yaml): Used to reference YAML files and convert them to JavaScript objects.
+- [TOML Plugin](https://github.com/rstackjs/rsbuild-plugin-toml): Used to reference TOML files and convert them to JavaScript objects.
 
 import OtherPlugins from '@site-docs-en/components/other-plugins.mdx';