npm - @bleedingdev/modern-js-main-doc - Versions diffs - 3.4.0-ultramodern.2 → 3.4.0-ultramodern.20 - Mend

@bleedingdev/modern-js-main-doc 3.4.0-ultramodern.2 → 3.4.0-ultramodern.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (40) hide show

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

@@ -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 CHANGED Viewed

@@ -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,19 @@ 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.
 ## bff.effect.openapi
 - **Type:** `boolean | { path?: string }`
@@ -173,4 +181,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 CHANGED Viewed

@@ -21,8 +21,8 @@ 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`.

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -7,7 +7,7 @@ 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.
@@ -23,6 +23,8 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
+      entry: './api/index',
+      strictEffectApproach: true,
       openapi: {
         path: '/openapi.json',
       },
@@ -33,7 +35,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 +43,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 +63,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 +89,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 +99,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -33,7 +33,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 | Hono runtime path only in Modern.js 3.0 baseline (no built-in Effect runtime path) | Sets Effect as the strict default API runtime (`api/index.ts`, `shared/api.ts`, `src/api/*`) and keeps raw Hono handlers as an explicit compatibility lane |
 | 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 +46,16 @@ 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.
+- 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 API 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.
+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 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 +71,49 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
+Strict Effect API migration is not compatible with
+`3.4.0-ultramodern.19` or older package cohorts. Those packages do not include
+the `strictEffectApproach` config type or the direct `api/index.ts`
+generator/checks. Until a newer BleedingDev cohort is published, use the local
+Modern.js workspace for migration validation; after publication, pin that exact
+new cohort with `--ultramodern-package-version`.
+When migrating a generated workspace that already has 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.mjs`, `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.
 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
@@ -239,8 +274,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 +283,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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';

package/docs/zh/community/blog/v3-release-note.mdx CHANGED Viewed

@@ -591,7 +591,7 @@ Modern.js 3.0 新项目默认使用 React 19，最低支持 React 18。
 #### Storybook Rsbuild
-在 Modern.js 3.0 中，我们基于 [Storybook Rsbuild](https://github.com/rspack-contrib/storybook-rsbuild) 实现了使用 Storybook 构建 Modern.js 应用。
+在 Modern.js 3.0 中，我们基于 [Storybook Rsbuild](https://github.com/rstackjs/storybook-rsbuild) 实现了使用 Storybook 构建 Modern.js 应用。
 通过 Storybook Addon，我们将 Modern.js 配置转换合并为 Rsbuild 配置，并通过 Storybook Rsbuild 驱动构建，让 Storybook 调试与开发命令保持配置对齐。

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

@@ -9,6 +9,7 @@ title: effect
 ```ts
 type BffEffectUserConfig = {
   entry?: string;
+  strictEffectApproach?: true;
   openapi?: boolean | { path?: string };
   dataPlatform?: {
     enabled?: boolean;
@@ -58,7 +59,7 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 ## bff.effect.entry
 - **类型：** `string`
-- **默认值：** `<apiDirectory>/effect/index`
+- **默认值：** `<apiDirectory>/index`
 用于指定 Effect HttpApi 运行时入口模块。
@@ -67,12 +68,19 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
-      entry: './api/effect/index',
+      entry: './api/index',
     },
   },
 });
 ```
+## bff.effect.strictEffectApproach
+- **类型：** `true`
+- **默认值：** `true`
+Effect BFF 模块必须导出严格 Effect API surface（`defineEffectBff(...)` 或 `{ api, layer }`），原始 request handler 会被拒绝。生成的 UltraModern 应用会显式写入这个标记。
 ## bff.effect.openapi
 - **类型：** `boolean | { path?: string }`
@@ -173,4 +181,4 @@ export default defineConfig({
 `batch.flushIntervalMs` 用于控制生成的 Effect 客户端微批处理窗口；`maxConcurrency` 与 `requestTimeoutMs` 由服务端批处理网关用于内部请求分发。
-生成的 `effectBff.client.*` API 只存在于 loader 物化后的 `@api/effect/*` 导入中。直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。
+生成的 `api.client.*` API 只存在于 loader 物化后的 `@api/index` 导入中。直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。

package/docs/zh/configure/app/bff/runtime-framework.mdx CHANGED Viewed

@@ -21,8 +21,8 @@ export default defineConfig({
 });
 ```
-- 设置为 `'effect'` 时，仅从 `api/effect/index` 运行 BFF（Effect HttpApi 运行时）。
+- 设置为 `'effect'` 时，仅从 `api/index` 运行 BFF（Effect HttpApi 运行时）。
 - 设置为 `'hono'` 时，仅从 `api/lambda/**` 的文件约定处理函数运行 BFF。
 两种运行时之间没有隐式回退，应用需要显式选择其一。
-生成的 UltraModern 应用默认使用 Effect 分支；仅在需要兼容运行时时设置 `runtimeFramework: 'hono'`。
+生成的 UltraModern 应用默认使用严格 Effect API，并设置 `bff.effect.strictEffectApproach: true`。

package/docs/zh/configure/app/experiments/source-build.mdx CHANGED Viewed

@@ -21,7 +21,7 @@ export default {
 ### 选项
-`experiments.sourceBuild` 底层基于 [@rsbuild/plugin-source-build](https://github.com/rspack-contrib/rsbuild-plugin-source-build?tab=readme-ov-file#options) 实现，你可以传入插件选项，比如：
+`experiments.sourceBuild` 底层基于 [@rsbuild/plugin-source-build](https://github.com/rstackjs/rsbuild-plugin-source-build?tab=readme-ov-file#options) 实现，你可以传入插件选项，比如：
 ```ts
 export default {

package/docs/zh/configure/app/html/template-parameters.mdx CHANGED Viewed

@@ -30,7 +30,7 @@ type DefaultParameters = {
 };
 ```
-定义 HTML 模板中的参数，对应 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的 `templateParameters` 配置项。
+定义 HTML 模板中的参数，对应 [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) 的 `templateParameters` 配置项。
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';

package/docs/zh/configure/app/output/convert-to-rem.mdx CHANGED Viewed

@@ -80,5 +80,5 @@ export default {
 };
 ```
-详细用法可参考 [rsbuild-plugin-rem](https://github.com/rspack-contrib/rsbuild-plugin-rem)。
+详细用法可参考 [rsbuild-plugin-rem](https://github.com/rstackjs/rsbuild-plugin-rem)。

package/docs/zh/configure/app/security/check-syntax.mdx CHANGED Viewed

@@ -70,4 +70,4 @@ error   [Syntax Checker] Find some syntax errors after production build:
 ### 选项
-`security.checkSyntax` 底层基于 `@rsbuild/plugin-check-syntax` 实现，具体选项可参考 [@rsbuild/plugin-check-syntax](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax)。
+`security.checkSyntax` 底层基于 `@rsbuild/plugin-check-syntax` 实现，具体选项可参考 [@rsbuild/plugin-check-syntax](https://github.com/rstackjs/rsbuild-plugin-check-syntax)。

package/docs/zh/configure/app/tools/html-plugin.mdx CHANGED Viewed

@@ -38,7 +38,7 @@ const defaultOptions = {
 SSR 应用请勿启用 `minify.removeComments` 配置项，否则会导致 SSR 渲染失败。
 :::
-通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的配置项。
+通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) 的配置项。
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';

package/docs/zh/configure/app/tools/ts-checker.mdx CHANGED Viewed

@@ -43,6 +43,8 @@ const defaultOptions = {
 ## 示例
+### Object 类型
 当 `tsChecker` 的值为 Object 类型时，会与默认配置进行深层合并。
 ```ts
@@ -57,6 +59,23 @@ export default {
 };
 ```
+### Function 类型
+当 `tsChecker` 的值为函数时，默认配置会作为第一个参数传入。你可以直接修改配置对象，也可以返回一个对象作为最终配置。
+```ts
+export default {
+  tools: {
+    tsChecker(options) {
+      options.async = false;
+      return options;
+    },
+  },
+};
+```
+> 更多详情请参考 [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check)。
 ## TypeScript Go 默认开启
 类型检查默认使用 [TypeScript Go](https://github.com/microsoft/typescript-go)（`tsgo`）。该能力由 [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check) 底层集成的 [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin) 提供，可以将类型检查耗时减少约 5-10 倍。

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

@@ -59,9 +59,9 @@ Envelope 校验默认开启，但只有设置 `requireEnvelope` 时才强制要
 ## Effect 客户端自动行为
-使用生成的 Effect 客户端（`@api/effect/index`）时，Modern.js 会在同源请求中自动附加序列化的 envelope 请求头（`x-modernjs-data-envelope`）。
+使用生成的 Effect 客户端（`@api/index`）时，Modern.js 会在同源请求中自动附加序列化的 envelope 请求头（`x-modernjs-data-envelope`）。
-生成客户端由 loader 物化。请在浏览器或会被客户端打包的代码中通过 `@api/effect/*` 导入；直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义，其中只包含占位的 `client`。
+生成客户端由 loader 物化。请在浏览器或会被客户端打包的代码中通过 `@api/index` 导入；直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义，其中只包含占位的 `client`。
 Envelope 默认包含：

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

@@ -7,7 +7,7 @@ title: 运行时框架
 Modern.js 目前支持两种 BFF 运行时框架：
-- `effect`（默认）：使用 `api/effect/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
+- `effect`（默认）：使用 `api/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
 - `hono`：使用 `api/lambda/**` 的文件约定 BFF 处理函数。
 `effect` 与 `hono` 为严格模式，两者之间不会自动回退。
@@ -23,6 +23,8 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
+      entry: './api/index',
+      strictEffectApproach: true,
       openapi: {
         path: '/openapi.json',
       },
@@ -33,7 +35,7 @@ export default defineConfig({
 先在共享目录中定义 Effect HttpApi 契约（前后端共享类型）：
-```ts title="shared/effect/api.ts"
+```ts title="shared/api.ts"
 import {
   HttpApi,
   HttpApiEndpoint,
@@ -41,18 +43,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,
     }),
   ),
 );
 ```
-然后在 `api/effect/index.ts` 中实现 Effect BFF 入口：
+然后在 `api/index.ts` 中实现 Effect BFF 入口：
-```ts title="api/effect/index.ts"
+```ts title="api/index.ts"
 import {
   Schema,
   Effect,
@@ -61,7 +63,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 +89,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 +99,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 });
 ```
-在浏览器代码中通过 `@api/effect/index` 调用接口：
+在浏览器代码中通过 `@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({});
 ```
-`effectBff.client.*` 由 BFF loader 针对 `@api/effect/*` 导入物化生成。不要直接导入 `api/effect/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
+`api.client.*` 由 BFF loader 针对 `@api/index` 导入物化生成。不要直接导入 `api/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
 import Hono from '@site-docs/components/hono';

package/docs/zh/guides/advanced-features/page-performance/optimize-bundle.mdx CHANGED Viewed

@@ -92,7 +92,7 @@ export default {
 };
 ```
-详见 [Image Compress 插件](https://github.com/rspack-contrib/rsbuild-plugin-image-compress)。
+详见 [Image Compress 插件](https://github.com/rstackjs/rsbuild-plugin-image-compress)。
 ## 代码拆包

package/docs/zh/guides/basic-features/debug/using-storybook.mdx CHANGED Viewed

@@ -89,4 +89,4 @@ pnpm storybook
 ## 示例
-你可以查看 [示例](https://github.com/rspack-contrib/storybook-rsbuild/tree/main/sandboxes/modernjs-react) 了解 Modern.js 中使用 Storybook 的方式。
+你可以查看 [示例](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react) 了解 Modern.js 中使用 Storybook 的方式。

package/docs/zh/guides/basic-features/static-assets/json-files.mdx CHANGED Viewed

@@ -38,7 +38,7 @@ import { name } from './example.json';
 YAML 是一种数据序列化语言，通常用于编写配置文件。
-你可以 `modern.config.ts` 中配置 [YAML 插件](https://github.com/rspack-contrib/rsbuild-plugin-yaml) 来支持引用 `.yaml` 或 `.yml` 文件，它们会被自动转换为 JSON 格式。
+你可以 `modern.config.ts` 中配置 [YAML 插件](https://github.com/rstackjs/rsbuild-plugin-yaml) 来支持引用 `.yaml` 或 `.yml` 文件，它们会被自动转换为 JSON 格式。
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
@@ -85,7 +85,7 @@ declare module '*.yml' {
 TOML 是一种语义明显、易于阅读的配置文件格式。
-你可以 `modern.config.ts` 中配置 [TOML 插件](https://github.com/rspack-contrib/rsbuild-plugin-toml) 来支持引用 `.toml` 文件，它会被自动转换为 JSON 格式。
+你可以 `modern.config.ts` 中配置 [TOML 插件](https://github.com/rstackjs/rsbuild-plugin-toml) 来支持引用 `.toml` 文件，它会被自动转换为 JSON 格式。
 ```ts
 import { defineConfig } from '@modern-js/app-tools';

package/docs/zh/guides/get-started/_meta.json CHANGED Viewed

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

package/docs/zh/guides/get-started/ai-coding-agents.mdx ADDED Viewed

@@ -0,0 +1,48 @@
+---
+title: AI 工具
+sidebar_position: 6
+---
+# Modern.js For AI
+Modern.js 为 AI Agent 提供了一套工具套件，帮助开发者利用 AI 高效完成 Modern.js 应用的功能开发、依赖升级与版本迁移工作。
+## llms.txt
+Modern.js 文档遵循 [llms.txt 规范](https://llmstxt.org/)，由 [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms) 自动生成，可通过 `/llms.txt` 或 `/llms-full.txt` 供 AI 工具检索：
+- 索引：[`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
+- 全文：`https://modernjs.dev/llms-full.txt`（体积较大，按需取片段）
+大部分「这个 API / 配置是什么」类问题，靠 llms.txt 即可解决。让你的 Agent 按需检索它即可，不必把文档复制进项目。
+## Skills
+Skills 是按需触发的 AI 辅助能力，遵循 [Agent Skills 开放标准](https://github.com/vercel-labs/skills)。用户向 Skills：
+| Skill | 标识 | 说明 |
+|---|---|---|
+| 升级到 v3 | `modernjs-migrate-to-v3` | v2 应用迁移到 v3：安全改写 + 复杂项人工清单 + 迁移报告 |
+| 启用特性 | `modernjs-feature-enable` | 为 v3 应用启用 BFF / SSG / styled-components，并脚手架化 Tailwind CSS / 自定义 Web Server |
+> Skills 默认不强装、不隐式安装，由你显式安装。RSC、微前端等属于配置或架构决策，不是 `modernjs-feature-enable` 的一键启用项。
+## 安装 Skills
+Modern.js 的用户向 Skill 就放在仓库根 `skills/` 目录，遵循 [Agent Skills 开放标准](https://github.com/vercel-labs/skills)。推荐用标准的 `skills` CLI 直接从 GitHub 安装：
+```bash
+# 列出可安装的 Skills
+npx skills add web-infra-dev/modern.js --list
+# 安装单个 Skill 到你的 Agent 目录（--agent 可选 claude-code / codex / cursor 等）
+npx skills add web-infra-dev/modern.js --skill modernjs-migrate-to-v3 --agent codex -y
+```
+它会把整个 Skill 目录（`SKILL.md` + `scripts/` + `references/`）安装到对应 Agent 目录，随后即可在该 Agent 里触发。
+> 需锁定到某个版本时，在仓库后加 `#<ref>`（ref 可为 tag / 分支 / commit），即安装该版本上的 Skill（把 `<tag>` 换成含本 Skill 的发布 tag）：
+>
+> ```bash
+> npx skills add web-infra-dev/modern.js#<tag> --skill modernjs-migrate-to-v3 --agent codex -y
+> ```

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

@@ -33,7 +33,7 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 | 构建诊断能力 | RsDoctor 多为显式开启 | 新增一等的 `performance.rsdoctor` 配置项（按需开启；早期的默认开启行为与诊断契约产物已回退） |
 | 输出与静态资源回源 | 预压缩策略通常由业务自定义 | 默认开启 `output.precompress`，并按 `Accept-Encoding` 协商 `.br` / `.gz` 回源 |
 | BFF 运行时与契约 | 提供标准 BFF 运行时与客户端生成能力 | 增加 `requestId` 维度隔离、初始化 fail-fast 校验与操作/追踪关联 Header |
-| BFF 运行时选型 | Modern.js 3.0 基线仅提供 Hono 运行时路径（无内建 Effect 运行时） | 将 Effect 设为默认运行时，并采用严格运行时拆分（`effect` -> `api/effect`，`hono` -> `api/lambda`），同时补齐 Effect-Schema-first 契约与 MF failure-injection 覆盖 |
+| BFF 运行时选型 | Modern.js 3.0 基线仅提供 Hono 运行时路径（无内建 Effect 运行时） | 将 Effect HttpApi 设为默认 API surface，入口固定为 `api/index.ts`，共享契约固定为 `shared/api.ts`，并通过 `strictEffectApproach` 拒绝原始 request handler |
 | Telemetry 标准化 | 可观测链路通常由业务侧自行拼装 | 增加框架级 telemetry 管线，内置 OTLP/VictoriaMetrics，支持脱敏、批处理与背压 |
 | 应用级 MF SSR 协议 | 没有以 super-app 为重点的应用级稳定性契约开关 | 增加 `server.ssr.moduleFederationAppSSR` 配置/环境变量握手，并补齐集成级回归保障 |
 | MF vertical 加载可靠性 | 重试/降级策略通常由各业务单独实现 | 增加 timeout/network/contract-error 的确定性可靠性矩阵与分布式 OTEL 连续性断言 |
@@ -46,7 +46,7 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 - 不再把这个 fork 隐藏在旧 Modern.js 品牌后面。
 - 当通用 Modern.js 默认值与 SuperApp 可靠性冲突时，不优先优化通用默认值。
-- 运行时保持 `effect` 与 `hono` 双模式并存，但不提供隐式回退。
+- 生成的 UltraModern API 只走严格 Effect surface；原始 request handler 和 Hono/file-function API 是显式非默认路径。
 - 除非稳定性硬需求，否则避免引入破坏性 API 变更。
 ## 迁移指南
@@ -54,7 +54,7 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 对于已经在使用 Modern.js 3.0 或旧版 BleedingDev UltraModern scaffold 的团队，迁移路径是“兼容感知”：保留能降低风险的部分，逐步向 MV-first / TanStack-first / Effect-first 默认方向收敛，并把 UltraModern.js 3.0 作为独立框架采用。
 1. 既有 React Router 应用可以继续按现状运行。TanStack Router 是新脚手架与增量迁移的优先路径，但 React Router 兼容分支仍然保留，团队可以按自己的节奏迁移。
-2. 新建或迁移中的 BFF 能力优先使用 `bff.runtimeFramework: 'effect'`，并将入口实现放在 `api/effect/index.ts`。如果当前应用已经在 `api/lambda/**` 下使用 Hono 处理函数，就继续显式使用 `bff.runtimeFramework: 'hono'`，等准备好再迁移；Hono 仍是受支持的兼容分支。
+2. 新建或迁移中的 BFF 能力使用 `bff.runtimeFramework: 'effect'`、`bff.effect.entry: './api/index'` 和 `bff.effect.strictEffectApproach: true`。接口先改 `shared/api.ts` 的 `HttpApi` 契约，再在 `api/index.ts` 用 `defineEffectBff(...)` / `HttpApiBuilder` 实现。
 3. 将基线契约视为渐进式默认值，而不是一次性强制切换。`MODERN_BASELINE_ENABLE_MF_SSR`、`MODERN_BASELINE_ENABLE_BFF_REQUEST_ID` 和 `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` 已经提供了按应用、按环境关闭的能力，方便在收敛到目标栈之前逐步过渡。
 4. 这套公开预设现在已经附带显式的发布 / 认证 gate。生成 workspace 会自带 `.github/workflows/ultramodern-workspace-gates.yml`，因此 `pnpm check` 与 `pnpm build` 从第一天开始就是本地接入契约的一部分；CI 会以并行矩阵运行这些基础 gate。
@@ -70,9 +70,40 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
+严格 Effect API 迁移不兼容 `3.4.0-ultramodern.19` 或更早的包 cohort。
+这些包还没有 `strictEffectApproach` 配置类型，也没有直接 `api/index.ts`
+的生成器和检查。新的 BleedingDev cohort 发布前，迁移校验应使用本地
+Modern.js workspace；发布后，用 `--ultramodern-package-version` 固定该新
+cohort。
+迁移已经带有 Effect API 文件的生成 workspace 时，明确移动文件，不保留兼容别名：
+1. 将每个 vertical 服务端入口从 `verticals/<id>/api/effect/index.ts` 移到
+   `verticals/<id>/api/index.ts`。
+2. 将每个共享 API 契约从 `verticals/<id>/shared/effect/api.ts` 移到
+   `verticals/<id>/shared/api.ts`。
+3. 将生成客户端从 `verticals/<id>/src/effect/*-client.ts` 移到
+   `verticals/<id>/src/api/*-client.ts`。
+4. 将 shell API 聚合从 `apps/shell-super-app/src/effect/*` 移到
+   `apps/shell-super-app/src/api/*`。
+5. 更新 imports 和 package exports，使用 `./api`、`./api/client` 与
+   `@<workspace>/<vertical>/api/client`；删除 `./effect/client`、
+   `./shared/effect/api` 和 shared Effect API 包。
+6. 更新每个 vertical 的 `modern.config.ts`，设置
+   `bff.effect.entry: './api/index'` 和
+   `bff.effect.strictEffectApproach: true`。
+7. 更新 topology，让 API metadata 直接位于 `api` 下，并设置
+   `api.bff.strictEffectApproach: true`；不要保留 `api.effect`。
+8. 运行 `pnpm api:check`、`scripts/validate-ultramodern-workspace.mjs`、
+   `pnpm check` 和 `pnpm build`。
+如果迁移失败，应修复归属的生成契约、topology、package exports 或 API 模块。
+不要添加 app 级 alias、原始 request handler、手写 `Response`、本地类型断言或包
+shim 来让旧布局通过。
 每个仓库只使用一种 package-source 策略。已发布的 BleedingDev create 包默认使用
 `--ultramodern-package-source=install`，并把精确 cohort 记录到
-`.modernjs/ultramodern-package-source.json`。`--workspace` 只用于本地 monorepo
+`.modernjs/ultramodern.json`。`--workspace` 只用于本地 monorepo
 联调未发布包。发布证明和 CI 如果需要证明某个已发布框架版本，应使用
 `--ultramodern-package-version` 固定精确 cohort。
@@ -82,7 +113,7 @@ Federation shim 或自定义 server wrapper。框架 BFF compiler 会把服务
 CommonJS，同时生成的 app package 继续为 Module Federation DTS 保留稳定的
 `typescript`，并使用固定的 `@typescript/native-preview` 工具链执行 TS-Go 检查。
-安装新 cohort 后，先运行生成的
+安装新 cohort 后，先运行生成的 `pnpm api:check` 与
 `scripts/validate-ultramodern-workspace.mjs` 契约校验，再接受人工改动。topology、
 ownership、package-source、本地 overlay、生成契约、Tailwind prefix 或 Module
 Federation 冲突，都应在对应归属文件中修复，不要手写补丁覆盖生成结果。
@@ -215,7 +246,7 @@ JSON-LD 是可选的路由 metadata，不会自动推断。私有路由和不可
 JSON-LD。公开路由 owner 可以在本地化路径旁显式添加 `jsonLd`，并使用生成的
 `src/routes/ultramodern-jsonld.ts` helper 编写常见 schema.org 结构。
-生成契约会在 `.modernjs/ultramodern-generated-contract.json` 中写入
+生成契约会在 `.modernjs/ultramodern.json` 中写入
 `cssFederation`：
 - `packages/shared-design-tokens` 拥有共享 token layer，并导出 `./tokens.css`。

package/docs/zh/guides/upgrade/config.mdx CHANGED Viewed

@@ -314,7 +314,7 @@ export default {
 ### tools.pug
-**变更内容**：该配置已废弃，使用 Rsbuild 的 [Pug 插件](https://github.com/rspack-contrib/rsbuild-plugin-pug) 来启用支持。
+**变更内容**：该配置已废弃，使用 Rsbuild 的 [Pug 插件](https://github.com/rstackjs/rsbuild-plugin-pug) 来启用支持。
 **迁移示例**：

package/docs/zh/plugin/introduction.mdx CHANGED Viewed

@@ -131,21 +131,21 @@ Rsbuild 是 Modern.js 底层的构建工具，通过添加 Rsbuild 插件可修
 | [React 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-react)                        | 提供对 React 的支持                                                                    | -                                                                                                                                     |
 | [SVGR 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-svgr)                          | 支持将 SVG 图片转换为一个 React 组件                                                   | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export)     |
 | [Assets Retry 插件](https://github.com/rstackjs/rsbuild-plugin-assets-retry)          | 用于在静态资源加载失败时自动发起重试请求                                               | [output.assetsRetry](/configure/app/output/assets-retry.html)                                                                         |
-| [Type Check 插件](https://github.com/rspack-contrib/rsbuild-plugin-type-check)       | 用于在单独的进程中运行 TypeScript 类型检查                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
-| [Source Build 插件](https://github.com/rspack-contrib/rsbuild-plugin-source-build)   | 用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新                     | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |
-| [Check Syntax 插件](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax)   | 用于分析产物的语法兼容性，判断是否存在导致兼容性问题的高级语法                         | [security.checkSyntax](/configure/app/security/check-syntax.html)                                                                     |
-| [CSS Minimizer 插件](https://github.com/rspack-contrib/rsbuild-plugin-css-minimizer) | 用于自定义 CSS 压缩工具，切换到 [cssnano](https://cssnano.co/) 或其他工具进行 CSS 压缩 | [tools.minifyCss](/configure/app/tools/minify-css.html)                                                                               |
-| [Rem 插件](https://github.com/rspack-contrib/rsbuild-plugin-rem)                     | 用于实现移动端页面的 rem 自适应布局                                                    | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
+| [Type Check 插件](https://github.com/rstackjs/rsbuild-plugin-type-check)             | 用于在单独的进程中运行 TypeScript 类型检查                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
+| [Source Build 插件](https://github.com/rstackjs/rsbuild-plugin-source-build)   | 用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新                     | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |
+| [Check Syntax 插件](https://github.com/rstackjs/rsbuild-plugin-check-syntax)   | 用于分析产物的语法兼容性，判断是否存在导致兼容性问题的高级语法                         | [security.checkSyntax](/configure/app/security/check-syntax.html)                                                                     |
+| [CSS Minimizer 插件](https://github.com/rstackjs/rsbuild-plugin-css-minimizer) | 用于自定义 CSS 压缩工具，切换到 [cssnano](https://cssnano.co/) 或其他工具进行 CSS 压缩 | [tools.minifyCss](/configure/app/tools/minify-css.html)                                                                               |
+| [Rem 插件](https://github.com/rstackjs/rsbuild-plugin-rem)                     | 用于实现移动端页面的 rem 自适应布局                                                    | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
 #### 未内置的插件
 以下是未在 Modern.js 中内置的 Rsbuild 官方插件：
-- [Image Compress 插件](https://github.com/rspack-contrib/rsbuild-plugin-image-compress)：将项目中用到的图片资源进行压缩处理。
+- [Image Compress 插件](https://github.com/rstackjs/rsbuild-plugin-image-compress)：将项目中用到的图片资源进行压缩处理。
 - [Stylus 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-stylus)：使用 Stylus 作为 CSS 预处理器。
-- [UMD 插件](https://github.com/rspack-contrib/rsbuild-plugin-umd)：用于构建 UMD 格式的产物。
-- [YAML 插件](https://github.com/rspack-contrib/rsbuild-plugin-yaml)：用于引用 YAML 文件，并将其转换为 JavaScript 对象。
-- [TOML 插件](https://github.com/rspack-contrib/rsbuild-plugin-toml)：用于引用 TOML 文件，并将其转换为 JavaScript 对象。
+- [UMD 插件](https://github.com/rstackjs/rsbuild-plugin-umd)：用于构建 UMD 格式的产物。
+- [YAML 插件](https://github.com/rstackjs/rsbuild-plugin-yaml)：用于引用 YAML 文件，并将其转换为 JavaScript 对象。
+- [TOML 插件](https://github.com/rstackjs/rsbuild-plugin-toml)：用于引用 TOML 文件，并将其转换为 JavaScript 对象。
 import OtherPlugins from '@site-docs/components/other-plugins.mdx';

package/package.json CHANGED Viewed

@@ -19,14 +19,14 @@
     "modern.js",
     "ultramodern.js"
   ],
-  "version": "3.4.0-ultramodern.2",
+  "version": "3.4.0-ultramodern.20",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.15.0",
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.4.0-ultramodern.2"
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.4.0-ultramodern.20"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "2.0.0",