@bleedingdev/modern-js-main-doc 3.5.0-ultramodern.1 → 3.5.0-ultramodern.100

package/docs/en/apis/app/hooks/config/mock.mdx

@@ -4,4 +4,7 @@ sidebar_position: 5
 ---
 # mock/
 
-When there is a `config/mock/index.js` file in the project directory, Modern.js will automatically enable the Mock service during development.
+When there is a `config/mock/index.ts` or `config/mock/index.js` file in the
+project directory, Modern.js will automatically enable the Mock service during
+development. Use [`dev.mockDir`](/configure/app/dev/mock-dir) to customize
+this directory.

package/docs/en/apis/app/hooks/src/routes.mdx

@@ -85,6 +85,6 @@ export default () => {
 ```
 
 :::note
-`<Outlet>` is a new API in React Router 7. For details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+`<Outlet>` is an API provided by React Router. For details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
 
 :::

package/docs/en/apis/app/runtime/router/router.mdx

@@ -6,7 +6,7 @@ sidebar_position: 1
 # router
 
 :::info
-The router solution based on [react-router v7](https://reactrouter.com/).
+The router solution based on [react-router](https://reactrouter.com/).
 
 This page documents the React Router runtime export (`@modern-js/runtime/router`).  
 If your app uses TanStack Router (`--router tanstack`), use `@modern-js/plugin-tanstack/runtime` and refer to TanStack Router API docs.

package/docs/en/components/prerequisites.mdx

@@ -9,7 +9,7 @@ import NodeVersion from '@site-docs-en/components/nodeVersion.mdx';
 It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
 
 ```bash
-mise use pnpm@11.7.0
+mise use pnpm@11.17.0
 ```
 
 :::note

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

@@ -45,6 +45,23 @@ import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
 
 `bff.effect` is only effective when `bff.runtimeFramework` is set to `'effect'`.
 
+:::caution Install the Effect peers yourself
+`effect` and `@effect/opentelemetry` are **optional exact peer dependencies** of
+`@modern-js/plugin-bff`, not dependencies. The plugin no longer bundles a copy —
+Effect 4 derives `Context` / `Service` keys per module instance, so a bundled copy
+would give your app a second Effect identity. Before setting
+`runtimeFramework: 'effect'` or importing `@modern-js/plugin-bff/effect`,
+`/effect-server`, `/effect-edge` or `/effect-client`, install the exact cohort:
+
+```bash
+pnpm add effect@4.0.0-beta.102 @effect/opentelemetry@4.0.0-beta.102
+```
+
+The pin is exact because UltraModern ships Effect as one lockstep cohort. Apps
+using only `runtimeFramework: 'hono'` or the `./data-platform` lane need neither
+package.
+:::
+
 Generated UltraModern workspaces use this runtime as the only generated HTTP API
 path. The API contract lives at `shared/api.ts`, the server runtime lives at
 `api/index.ts`, clients live under `src/api/*-client.ts`, and generated checks
@@ -197,18 +214,31 @@ The generated `api.client.*` API only exists for loader-materialized `@api/index
 ## Effect cohort
 
 UltraModern-generated workspaces pin the framework-compatible Effect cohort
-through `pnpm-workspace.yaml` overrides. For `3.5.0-ultramodern.1`, generated
-apps use:
+through `pnpm-workspace.yaml` overrides. For the current UltraModern cohort,
+generated apps use:
 
 ```yaml
+minimumReleaseAgeExclude:
+  - 'effect@4.0.0-beta.102'
+  - '@effect/opentelemetry@4.0.0-beta.102'
+
+trustPolicyExclude:
+  - 'effect@4.0.0-beta.102'
+  - '@effect/opentelemetry@4.0.0-beta.102'
+
 overrides:
-  '@effect/vitest': 4.0.0-beta.89
-  effect: 4.0.0-beta.89
+  '@effect/opentelemetry': 4.0.0-beta.102
+  '@effect/vitest': 4.0.0-beta.102
+  effect: 4.0.0-beta.102
 ```
 
 Do not add a different direct `effect` version in an app package. A mismatched
 Effect beta can fail while building layers or HTTP middleware because runtime
-services come from different package instances.
+services come from different package instances. Keep the generated
+policy exclusion entries with the same Effect cohort; they handle the
+framework-selected Effect beta versions before the 24-hour maturity window and
+the `effect`/`@effect/opentelemetry` trusted-publisher to provenance metadata
+transition without weakening UltraModern API architecture checks.
 
 ## Contract tests
 

package/docs/en/configure/app/dev/mock-dir.mdx

@@ -0,0 +1,35 @@
+---
+title: mockDir
+---
+
+# dev.mockDir
+
+- **Type:** `string`
+- **Default:** `'./config/mock'`
+
+Sets the directory containing the Mock API entry file. Relative paths are
+resolved from the application directory, and absolute paths are also supported.
+Modern.js loads `index.ts` or `index.js` from this directory during development.
+
+For example, move the Mock API entry to `mocks/index.ts`:
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  dev: {
+    mockDir: './mocks',
+  },
+});
+```
+
+This is also useful in a monorepo when multiple applications share one Mock
+directory:
+
+```js title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    mockDir: '../../shared/mocks',
+  },
+});
+```

package/docs/en/configure/app/performance/build-cache.mdx

@@ -28,6 +28,11 @@ type BuildCacheConfig =
 
 Controls the caching behavior during the build process.
 
+When persistent Rspack cache is enabled, Modern.js treats `cacheDirectory` as a
+base directory and stores each Rsbuild/Rspack environment in its own child
+directory, such as `client`, `server`, or `workerSSR`. This avoids concurrent
+environment compilers writing to the same filesystem cache root.
+
 Modern.js will enable build cache by default to improve the compile speed. You can disable the build cache by setting it to `false`:
 
 ```js

package/docs/en/configure/app/server/rsc.mdx

@@ -22,7 +22,7 @@ export default defineConfig({
 :::tip Prerequisites
 Before enabling RSC, ensure:
 1. React and React DOM are upgraded to version 19 (recommended 19.2.4 or above)
-2. Install the `react-server-dom-rspack@0.0.1-beta.1` dependency
+2. Install the `react-server-dom-rspack@0.0.2` dependency
 
 :::
 

package/docs/en/configure/app/source/react-compiler.mdx

@@ -0,0 +1,72 @@
+---
+title: reactCompiler
+---
+
+# source.reactCompiler
+
+- **Type:** `boolean | ReactCompilerOptions`
+- **Default:** `undefined` (disabled)
+
+Whether to enable [React Compiler](https://react.dev/learn/react-compiler). React Compiler is a build-time tool that optimizes re-rendering performance of React applications through automatic memoization.
+
+Modern.js implements this capability based on the Rust-based React Compiler built into Rspack's `builtin:swc-loader` (equivalent to setting SWC's `jsc.transform.reactCompiler`), reusing Rspack's built-in SWC transform chain without introducing Babel.
+
+:::tip
+This option is disabled by default. It must be enabled explicitly for any React version, including React 19.
+:::
+
+## Example
+
+### Enable React Compiler (React 19)
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: true,
+  },
+});
+```
+
+### Using with React 18
+
+The compiled output targets React 19 by default. To use it in React 18 projects, you need to:
+
+1. Install [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) as a **runtime dependency** (the compiled output references it at runtime):
+
+```bash
+npm add react-compiler-runtime
+```
+
+2. Specify the React version via `target`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      target: '18',
+    },
+  },
+});
+```
+
+### Customize compilation behavior
+
+When passing an object, the options are the same as Rspack's `jsc.transform.reactCompiler`. For example, use `compilationMode: 'annotation'` to only compile functions annotated with the `"use memo"` directive:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      compilationMode: 'annotation',
+    },
+  },
+});
+```
+
+For the complete list of options, see [Rsbuild - reactCompiler](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) and the [React Compiler configuration docs](https://react.dev/reference/react-compiler/configuration).

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

@@ -19,7 +19,7 @@ const defaultOptions = {
     // use TypeScript Go checker by default
     tsgo: true,
     // use TS-Go native preview of user project
-    typescriptPath: require.resolve('@typescript/native-preview/package.json'),
+    typescriptPath: require.resolve('typescript/package.json'),
   },
   issue: {
     exclude: [
@@ -80,11 +80,11 @@ export 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.
 
-`@typescript/native-preview` ships with the builder, so no extra install is needed. To pin your own version, install it in your project:
+Modern.js prefers the project's stable `typescript` package when it is TypeScript 7 or newer, and falls back to `@typescript/native-preview` for projects still on the preview lane. To pin stable TypeScript 7, install it in your project:
 
-<PackageManagerTabs command="install @typescript/native-preview -D" />
+<PackageManagerTabs command="install typescript -D" />
 
-When `tsgo` is enabled, the default `typescript.typescriptPath` resolves to `@typescript/native-preview/package.json`. If you manually set `typescript.typescriptPath`, it must be an absolute path to `@typescript/native-preview/package.json`.
+When `tsgo` is enabled, the default `typescript.typescriptPath` resolves to `typescript/package.json` for TypeScript 7 projects. If you manually set `typescript.typescriptPath`, it must be an absolute path to `typescript/package.json` or `@typescript/native-preview/package.json`.
 
 To fall back to the classic TypeScript checker, set `typescript.tsgo` to `false` and make sure `typescript` is installed in your project:
 

package/docs/en/guides/advanced-features/international/api.mdx

@@ -145,19 +145,52 @@ const myPlugin = (): RuntimePlugin => ({
 
 The i18next instance type used by the plugin. It is a subset of the i18next `i18n` type and only lists fields actually used by the plugin:
 
+:::warning BREAKING (UltraModern)
+`I18nInstance` no longer declares a top-level `[key: string]: unknown` index
+signature: TypeScript never grants an interface an implicit index signature, so
+that member made the documented `runtime: { i18n: { i18nInstance: i18next } }`
+usage fail to typecheck. Reading a property that is not declared below is now a
+type error (TS2339) — cast to the concrete instance type instead. `t` is now a
+REQUIRED member, so object literals that produce an `I18nInstance` must supply
+one.
+:::
+
 ```ts
+type TranslateFn = (
+  key: string | string[],
+  options?: Record<string, unknown>,
+) => string;
+
 interface I18nInstance {
   language: string;
-  isInitialized: boolean;
-  init: (options?: I18nInitOptions) => void | Promise<void>;
-  changeLanguage: (lang: string) => void | Promise<void>;
-  use: (plugin: any) => void;
-  createInstance: (options?: I18nInitOptions) => I18nInstance;
+  isInitialized?: boolean;
+  init(options?: any, callback?: any): Promise<any>;
+  changeLanguage?(lng?: string, callback?: any): Promise<any>;
+  setLang?: (lang: string) => void | Promise<void>;
+  use(plugin: any): unknown;
+  t: TranslateFn;
+  exists?: (key: string | string[], options?: Record<string, unknown>) => boolean;
+  getFixedT?: (
+    lng: string | readonly string[] | null,
+    ns?: string | readonly string[] | null,
+    keyPrefix?: string,
+  ) => TranslateFn;
+  hasLoadedNamespace?: (
+    ns: string | readonly string[],
+    options?: Record<string, unknown>,
+  ) => boolean;
+  dir?: (lng?: string) => string;
+  languages?: readonly string[];
+  resolvedLanguage?: string;
+  createInstance?(options?: any, callback?: any): I18nInstance;
+  cloneInstance?(options?: any, callback?: any): I18nInstance;
   options?: {
-    backend?: BackendOptions;
-    supportedLngs?: string[];
-    [key: string]: any;
+    detection?: any;
+    backend?: any;
+    ns?: any;
+    defaultNS?: any;
   };
+  // ...see src/runtime/i18n/instance.ts for the full member list.
 }
 ```
 

package/docs/en/guides/basic-features/debug/mock.mdx

@@ -20,6 +20,17 @@ By convention, when there is an `index.ts` in the `config/mock/` directory, mock
 └── modern.config.ts
 ```
 
+You can use [`dev.mockDir`](/configure/app/dev/mock-dir) to place the
+Mock entry in another directory:
+
+```js title="modern.config.ts"
+export default {
+  dev: {
+    mockDir: './mocks',
+  },
+};
+```
+
 ## Writing Mock Files
 
 The `config/mock/index.ts` file only needs to export an object containing all Mock APIs. The properties of the object are composed of the request configuration `method` and `url`, and the corresponding property values can be `Object`, `Array`, or `Function`:

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

@@ -112,7 +112,7 @@ Add the following content to `netlify.toml`:
 ```
 
 :::info
-You can refer to the [deployment project example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+You can refer to the [deployment project example](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-csr).
 
 :::
 
@@ -137,7 +137,7 @@ Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. Th
 :::info
 
 1. Currently, Modern.js does not support deployment on Netlify Edge Functions. We will support it in future versions.
-2. You can refer to the [deployment project example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr).
+2. You can refer to the [deployment project example](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-ssr).
 
 :::
 
@@ -223,7 +223,7 @@ Commit your project to git, select Framework Preset as `Other` on the Vercel pla
 <img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/vercel-framework-preset.png" />
 
 :::info
-You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-csr).
 
 :::
 
@@ -237,7 +237,7 @@ In addition to configuring `vercel.json` in the same way as a [pure front-end pr
 2. The Node.js version for function execution is determined by the project configuration on the Vercel platform.
 
 :::info
-You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr).
+You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-ssr).
 
 :::
 
@@ -335,10 +335,10 @@ For branch deployment, follow these steps:
 :::info
 
 1. Running `MODERNJS_DEPLOY=ghPages modern deploy` will build the production output for GitHub in the .output directory.
-2. You can refer to the [project](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)
+2. You can refer to the [project](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-csr)
    :::
 
-For GitHub Actions deployment, select Settings > Pages > Source > GitHub Actions, and add a workflow file to the project. You can refer to the [example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+For GitHub Actions deployment, select Settings > Pages > Source > GitHub Actions, and add a workflow file to the project. You can refer to the [example](https://github.com/web-infra-dev/modern.js/tree/main/examples/modern-js-deploy-csr).
 
 ## Using Self-Built Node.js Server
 

package/docs/en/guides/basic-features/render/rsc.mdx

@@ -23,10 +23,10 @@ Before starting, we recommend reading React's official [Server Components docume
 
 1. **Ensure React and React DOM are upgraded to version 19** (recommended version 19.2.4 or above)
 
-2. **Install the `react-server-dom-rspack@0.0.1-beta.1` dependency**
+2. **Install the `react-server-dom-rspack@0.0.2` dependency**
 
 ```bash
-npm install react-server-dom-rspack@0.0.1-beta.1
+npm install react-server-dom-rspack@0.0.2
 ```
 
 :::warning Notes

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

@@ -4,7 +4,7 @@ sidebar_position: 2
 
 # Routing
 
-Modern.js supports conventional routing on top of both [React Router v7](https://reactrouter.com/en/main) and [TanStack Router](https://tanstack.com/router), offering file convention-based routing capabilities and supporting the industry-popular **nested routing** pattern. When an entry is recognized as [conventional routing](/guides/concept/entries.html#conventional-routing), Modern.js automatically generates the corresponding routing structure based on the file system.
+Modern.js supports conventional routing on top of both [React Router](https://reactrouter.com/en/main) and [TanStack Router](https://tanstack.com/router), offering file convention-based routing capabilities and supporting the industry-popular **nested routing** pattern. When an entry is recognized as [conventional routing](/guides/concept/entries.html#conventional-routing), Modern.js automatically generates the corresponding routing structure based on the file system.
 
 :::note
 
@@ -93,7 +93,7 @@ export default () => {
 
 :::note
 
-`<Outlet>` is an API provided by React Router v7. For more details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+`<Outlet>` is an API provided by React Router. For more details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
 
 :::
 

package/docs/en/guides/concept/entries.mdx

@@ -156,7 +156,7 @@ If there is an `App.tsx?` file in the entry, this entry is a self-controlled rou
 │   └── App.tsx
 ```
 
-For the entry defined as `src/App.tsx`, Modern.js does not perform additional routing operations. Developers can use the [React Router v7](https://reactrouter.com/en/main) API to set up client-side routes, or not set up client-side routes. For example, the following code sets up client-side routes in the application:
+For the entry defined as `src/App.tsx`, Modern.js does not perform additional routing operations. Developers can use the [React Router](https://reactrouter.com/en/main) API to set up client-side routes, or not set up client-side routes. For example, the following code sets up client-side routes in the application:
 
 ```tsx title="src/App.tsx"
 import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';

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

@@ -5,16 +5,31 @@ 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.
+Modern.js provides a toolkit for AI agents that makes your project agent-ready out of the box, helping you use AI to develop, upgrade, and migrate Modern.js applications more accurately and efficiently.
+
+## Bundled docs
+
+Modern.js ships the English docs that match your installed version together with `@modern-js/app-tools`. After you install or upgrade, they live at `node_modules/@modern-js/app-tools/docs/`, available offline with no extra setup.
+
+AI agents use them to get APIs, config, and conventions that exactly match your framework version, rather than relying on potentially outdated training data.
+
+## AGENTS.md
+
+`AGENTS.md` gives AI coding agents project-level guidance — telling them to read the bundled docs before making changes and to follow Modern.js conventions. A `CLAUDE.md` is generated alongside it, reusing the same guidance for Claude Code via the `@AGENTS.md` import.
+
+- **New projects**: `npx @modern-js/create` generates both files by default; pass `--no-agents-md` to skip them.
+- **Existing projects**: run `npx @modern-js/create agents-md` at the project root to create or update them. Re-run it any time; your own additions are preserved.
+
+Modern.js only maintains the content inside the `<!-- BEGIN:modernjs-agent-rules -->` markers in `AGENTS.md`; anything you write outside them is left untouched.
 
 ## 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`:
+llms.txt is an online documentation index following the [llms.txt specification](https://llmstxt.org/), auto-generated by [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms) for AI tools to retrieve the full docs online:
 
 - Index: [`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
-- Full text: `https://modernjs.dev/llms-full.txt` (large — fetch on demand)
+- Full text: [`https://modernjs.dev/llms-full.txt`](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.
+Use it when you need content beyond the bundled docs — just let your agent retrieve it on demand, no need to copy docs into your project. Typical cases: looking up another framework version, a section not included in the bundle, or getting Modern.js information outside of a project (for example before a project exists, or when researching on its own).
 
 ## Skills
 

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

@@ -10,7 +10,7 @@ In this document, you can learn about the main technology stack involved in the
 
 ## UI Library
 
-Modern.js uses [React 18](https://react.dev/) to build user interfaces and is also compatible with React 17.
+Modern.js uses [React 19](https://react.dev/) to build user interfaces and is also compatible with React 18.
 
 Rsbuild supports building Vue applications. If you need to use Vue, you can refer to ["Rsbuild - Vue"](https://v2.rsbuild.rs/guide/framework/vue).
 
@@ -19,7 +19,7 @@ Rsbuild supports building Vue applications. If you need to use Vue, you can refe
 Modern.js provides two first-party routing frameworks:
 
 - [TanStack Router](https://tanstack.com/router) (UltraModern default), via `@modern-js/plugin-tanstack/runtime`.
-- [React Router v7](https://reactrouter.com/en/main) (compatibility path), via `@modern-js/runtime/router`.
+- [React Router](https://reactrouter.com/en/main), via `@modern-js/runtime/router`.
 
 When creating an UltraModern project, TanStack Router is included by default:
 

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

@@ -78,33 +78,78 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
-Strict generated API migration requires `3.5.0-ultramodern.1` or newer.
+### Migrating to `3.5.0-ultramodern.18`
+
+Use `3.5.0-ultramodern.18` or newer for localized Cloudflare SSR workspaces.
+This cohort moves bare locale-root redirects into the framework-owned
+Cloudflare Worker entry and the i18n server runtime. A request for `/` is
+redirected server-side with `302` to the negotiated locale path, for example
+`/cs` for `Accept-Language: cs-CZ` or `/en` for English and fallback traffic.
+
+Existing generated workspaces should upgrade the whole BleedingDev Modern
+package cohort together:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create@3.5.0-ultramodern.18 ultramodern \
+  migrate-strict-effect --version 3.5.0-ultramodern.18
+pnpm install
+pnpm check
+pnpm build
+pnpm cloudflare:build
+```
+
+For deployed Cloudflare Workers, redeploy after the cohort update and verify
+the root response before accepting the migration:
+
+```bash
+curl -I -H 'Accept-Language: cs-CZ,cs;q=0.9,en;q=0.1' https://<worker-host>/
+```
+
+The expected response is `302` with `Location: /cs` or the matching locale,
+`Cache-Control: private, no-store`, and `Vary` covering the locale detection
+headers. Following the redirect should return the SSR locale page with the
+matching document language and i18n SSR data.
+
+Do not fix older root `404` responses by adding app-owned root route files,
+client-side redirects, custom navigation wrappers, Cloudflare Worker
+postprocessing, generated output edits, or local redirect shims. If `/` still
+returns `404` after upgrading, confirm the production build log shows
+`Modern.js Framework v3.5.0-ultramodern.18` or newer and redeploy the Worker.
+
+Strict generated API migration requires `3.5.0-ultramodern.10` or newer.
 `3.4.0-ultramodern.20` and earlier cohorts do not include this full direct
 `api/index.ts` generator, generated `.mts` checks, strict Oxlint boundary rule
 set, Effect cohort overrides, and strict Effect migration command. Agents that
 cannot install that BleedingDev cohort yet should use the local Modern.js
-workspace for migration validation; otherwise pin `3.5.0-ultramodern.1` or
+workspace for migration validation; otherwise pin `3.5.0-ultramodern.10` or
 newer with `--ultramodern-package-version`.
 
 Before hand-editing package aliases or generated metadata, run the framework
 migration command from the target workspace:
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create@3.5.0-ultramodern.1 ultramodern \
-  migrate-strict-effect --version 3.5.0-ultramodern.1
+pnpm dlx @bleedingdev/modern-js-create@3.5.0-ultramodern.10 ultramodern \
+  migrate-strict-effect --version 3.5.0-ultramodern.10
 pnpm api:check
 pnpm contract:check
 ```
 
 The command updates `.modernjs/ultramodern.json`, root
-`modernjs.packageSource`, generated Modern package aliases, direct topology API
-metadata, and the pnpm lockfile. Remaining failures are source migration work:
-move code to `shared/api.ts`, `api/index.ts`, and `src/api/*-client.ts`, then
-delete `api/effect`, `api/lambda`, `shared/effect`, and `src/effect`.
+`modernjs.packageSource`, generated Modern package aliases, framework-owned
+toolchain pins, direct topology API metadata, strict Effect pnpm
+overrides/trust policy, and the pnpm lockfile. Remaining failures are source
+migration work: move code to `shared/api.ts`, `api/index.ts`, and
+`src/api/*-client.ts`, then delete `api/effect`, `api/lambda`, `shared/effect`,
+and `src/effect`.
 
 Generated strict Effect workspaces pin the compatible Effect cohort with pnpm
-overrides: `effect@4.0.0-beta.89` and `@effect/vitest@4.0.0-beta.89`. Do not
-add app-local direct Effect versions that disagree with those overrides.
+overrides: `effect@4.0.0-beta.102`, `@effect/opentelemetry@4.0.0-beta.102`,
+and `@effect/vitest@4.0.0-beta.102`. Do not add app-local direct Effect
+versions that disagree with those overrides. They also carry generated pnpm
+policy exclusions for `effect@4.0.0-beta.102` and
+`@effect/opentelemetry@4.0.0-beta.102` so the framework-selected Effect beta
+cohort is not blocked by the 24-hour age gate or trusted-publisher to
+provenance metadata transition.
 
 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
@@ -165,8 +210,8 @@ Older repos with nested Effect entries and `verbatimModuleSyntax` should update
 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
-stable `typescript` for Module Federation DTS generation and use the pinned
-`@typescript/native-preview` toolchain for TS-Go checks.
+stable TypeScript 7 so Module Federation DTS generation and TS-Go checks use
+the same modern compiler lane.
 
 Cloudflare SSR deploys are also split by runtime responsibility: `.output` is an
 ESM module-worker package, while `.output/worker` remains a CommonJS package
@@ -183,9 +228,10 @@ instead of patching generated output by hand.
 Cloudflare D1 bindings are first-class on `deploy.worker.d1Databases`; use that
 config instead of app-local postprocessing when a generated app owns D1
 migrations. Cloudflare public output excludes server-only `api` and `shared`
-directories by default, and generated Modern/Rspack caches are isolated per app
-and build target so local `build` and `cloudflare:build` runs do not share the
-same Rspack cache directory.
+directories by default, and generated Modern/Rspack output roots, temp
+directories, and caches are isolated per app, build target, and Rspack
+environment so local `build`, `cloudflare:build`, and multi-environment
+compilers do not share mutable build state.
 
 ## Human Workflow
 
@@ -305,10 +351,9 @@ Overlays are explicit CodeSmith generators that run after base workspace or
 MicroVertical generation. They extend generated output; they do not replace,
 inherit, or shadow the base templates. The generator and CodeSmith adapter are
 plain Node generator surfaces. The package build emits declaration files through
-the TS-Go toolchain. Generated app packages keep stable `typescript` for classic
-compiler consumers such as Module Federation DTS generation, while TS-Go uses
-the pinned `@typescript/native-preview` toolchain; runtime code does not depend
-on native-preview compiler internals.
+the TS-Go toolchain. Generated app packages keep stable `typescript` on TS7 so
+Module Federation DTS generation and TS-Go use the same compiler lane; runtime
+code does not depend on compiler internals.
 
 ### Runtime Contracts
 
@@ -335,7 +380,7 @@ The generated contract writes `.modernjs/ultramodern.json` with a
 - `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"]`.
 - Each vertical owns one CSS layer, for example `[data-app-id="vertical-transportation"]` with app-local class prefixes.
-- Tailwind CSS v4 is local to each generated app through `@tailwindcss/postcss`; shared base styles must not be duplicated by verticals.
+- Tailwind CSS v4 is local to each generated app through `@rsbuild/plugin-tailwindcss`; 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, 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.
@@ -357,7 +402,7 @@ Cloudflare and Zephyr proof:
 ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
 ULTRAMODERN_PUBLIC_URL_TRANSPORTATION=https://transportation.example.workers.dev \
 ULTRAMODERN_PUBLIC_URL_PAYMENTS=https://payments.example.workers.dev \
-mise exec -- pnpm cloudflare:proof -- --require-public-urls
+mise exec -- pnpm cloudflare:proof --require-public-urls
 ```
 
 Live Cloudflare and Zephyr proof requires public Worker URLs and Zephyr credentials. Without those, the repo can validate generated contracts, local builds, local Cloudflare output, dry-run Zephyr evidence plans, and local evidence schemas, but it cannot prove shell-driven live version selection.