diff --git a/docs/public/AGENTS.md b/docs/public/AGENTS.md
index 2352e36c..ef4306bf 100644
--- a/docs/public/AGENTS.md
+++ b/docs/public/AGENTS.md
@@ -12,34 +12,34 @@
 
 ## 1. Positioning and Capability Boundaries
 
-- **What**: Lynx is a cross-platform rendering engine that treats the web as its semantic baseline. It targets iOS, Android, HarmonyOS, and the web with a single codebase. A unified element abstraction maps to native views or custom web elements on different hosts, avoiding the performance bottlenecks of traditional WebViews. (See [Composing Elements](https://lynxjs.org/next/guide/ui/elements-components.md))
-- **Why**: Mobile users are extremely sensitive to first-screen time and interaction latency. Lynx combines a dual-thread JavaScript runtime, Instant First-Frame Rendering (IFR), and a native rendering pipeline to deliver the React developer experience alongside near-native performance. (See [Instant First-Frame Rendering](https://lynxjs.org/next/guide/interaction/ifr.md))
-- **How**: On the tooling side, use Rspeedy (an Rspack-powered build tool) to generate a Lynx bundle. On the front end, ReactLynx (a React implementation with a Preact core) describes the UI and communicates with the host through Native Modules or Custom Elements. (See [ReactLynx](https://lynxjs.org/next/react/introduction.md), [Native Modules](https://lynxjs.org/next/guide/use-native-modules.md))
+- **What**: Lynx is a cross-platform rendering engine that treats the web as its semantic baseline. It targets iOS, Android, HarmonyOS, and the web with a single codebase. A unified element abstraction maps to native views or custom web elements on different hosts, avoiding the performance bottlenecks of traditional WebViews. (See [Composing Elements](/guide/ui/elements-components.md))
+- **Why**: Mobile users are extremely sensitive to first-screen time and interaction latency. Lynx combines a dual-thread JavaScript runtime, Instant First-Frame Rendering (IFR), and a native rendering pipeline to deliver the React developer experience alongside near-native performance. (See [Instant First-Frame Rendering](/guide/interaction/ifr.md))
+- **How**: On the tooling side, use Rspeedy (an Rspack-powered build tool) to generate a Lynx bundle. On the front end, ReactLynx (a React implementation with a Preact core) describes the UI and communicates with the host through Native Modules or Custom Elements. (See [ReactLynx](/react/introduction.md), [Native Modules](/guide/use-native-modules.md))
 
 ## 2. Mental Model: Align Lynx with the Web
 
-| Web Mental Model             | Lynx Counterpart                                                                | Key Differences                                                                                                                                                                                                                                                             |
-| ---------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `index.html` + assets        | Lynx bundle (binary that contains JS bytecode + styles) or a `template.js` file | Bundles must be compatible with the Lynx engine version; configure `engineVersion` (previously `targetSdkVersion`). (See [Compatibility](https://lynxjs.org/next/guide/compatibility.md))                                                                                   |
-| DOM + CSSOM                  | Element tree + styling system                                                   | Every element behaves like a block-level node. Custom tags such as `view`/`text` map to native controls. (See [Composing Elements](https://lynxjs.org/next/guide/ui/elements-components.md))                                                                                |
-| Browser main thread          | Lynx main thread                                                                | Handles first-screen rendering, layout, and main-thread scripts, executing PrimJS bytecode. (See [Main Thread Runtime](https://lynxjs.org/next/guide/scripting-runtime/main-thread-runtime.md))                                                                             |
-| Browser rendering-task queue | Lynx background thread                                                          | Runs ReactLynx scheduling, lifecycle, and most side effects. Executes PrimJS/JavaScriptCore with syntax support up to ES2015 (SWC transpiles during build). (See [JavaScript Runtime](https://lynxjs.org/next/guide/scripting-runtime/index.md))                            |
-| `window` / `document`        | `lynx` global object + API set                                                  | No DOM APIs. Access nodes via `lynx.getElementById`, SelectorQuery, `main-thread:ref`, etc. (See [ReactLynx](https://lynxjs.org/next/react/introduction.md), [Direct Manipulation](https://lynxjs.org/next/guide/interaction/event-handling/manipulating-element.react.md)) |
+| Web Mental Model             | Lynx Counterpart                                                                | Key Differences                                                                                                                                                                                                               |
+| ---------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.html` + assets        | Lynx bundle (binary that contains JS bytecode + styles) or a `template.js` file | Bundles must be compatible with the Lynx engine version; configure `engineVersion` (previously `targetSdkVersion`). (See [Compatibility](/guide/compatibility.md))                                                            |
+| DOM + CSSOM                  | Element tree + styling system                                                   | Every element behaves like a block-level node. Custom tags such as `view`/`text` map to native controls. (See [Composing Elements](/guide/ui/elements-components.md))                                                         |
+| Browser main thread          | Lynx main thread                                                                | Handles first-screen rendering, layout, and main-thread scripts, executing PrimJS bytecode. (See [Main Thread Runtime](/guide/scripting-runtime/main-thread-runtime.md))                                                      |
+| Browser rendering-task queue | Lynx background thread                                                          | Runs ReactLynx scheduling, lifecycle, and most side effects. Executes PrimJS/JavaScriptCore with syntax support up to ES2015 (SWC transpiles during build). (See [JavaScript Runtime](/guide/scripting-runtime/index.md))     |
+| `window` / `document`        | `lynx` global object + API set                                                  | No DOM APIs. Access nodes via `lynx.getElementById`, SelectorQuery, `main-thread:ref`, etc. (See [ReactLynx](/react/introduction.md), [Direct Manipulation](/guide/interaction/event-handling/manipulating-element.react.md)) |
 
 ## 3. Runtime Architecture: How Dual-Thread React Works
 
-- **Dual-thread parallel rendering**: The main thread renders ReactLynx output immediately for the first screen, while the background thread constructs the full node tree and syncs state back to the main thread to avoid a white screen. (See [Rendering Process and Lifecycle](https://lynxjs.org/next/react/lifecycle.md), [IFR](https://lynxjs.org/next/guide/interaction/ifr.md))
+- **Dual-thread parallel rendering**: The main thread renders ReactLynx output immediately for the first screen, while the background thread constructs the full node tree and syncs state back to the main thread to avoid a white screen. (See [Rendering Process and Lifecycle](/react/lifecycle.md), [IFR](/guide/interaction/ifr.md))
 - **“Your code runs on two threads”**: Dual-thread React means your logic can run on both threads. However, not all code can execute in both environments—some APIs are only available on the background thread, and ReactLynx only executes events, lifecycle hooks, and `useEffect`-style side effects from the background thread.
 - **`'background only'`**: Any function that does not need to run on the main thread (for example event handlers, lifecycle hooks, side effects) or that touches background-only APIs must add `'background only'` as the first statement. Modules can declare `import "background-only"` to indicate they expect to run exclusively on the background thread.
-- **Main Thread Script (MTS)**: Functions marked with the `'main thread';` directive run directly on the main thread, ideal for high-frequency gestures, animations, and zero-delay feedback. Main-thread events must use the `main-thread:` prefix (for example `main-thread:bindtap`, `useMainThreadRef`). (See [Main Thread Script](https://lynxjs.org/next/react/main-thread-script.md))
+- **Main Thread Script (MTS)**: Functions marked with the `'main thread';` directive run directly on the main thread, ideal for high-frequency gestures, animations, and zero-delay feedback. Main-thread events must use the `main-thread:` prefix (for example `main-thread:bindtap`, `useMainThreadRef`). (See [Main Thread Script](/react/main-thread-script.md))
 - **Cross-thread communication**: Use `runOnMainThread` and `runOnBackground` for asynchronous cross-thread calls. Arguments must be JSON-serializable.
 
 ## 4. UI Construction: Element System and Native Mapping
 
-- **Element tags**: Built-in tags such as `view`, `text`, `image`, `scroll-view`, etc. abstract native controls. They are not DOM nodes, but the syntax (start/end tag, attributes) stays HTML-like. (See [Composing Elements](https://lynxjs.org/next/guide/ui/elements-components.md))
+- **Element tags**: Built-in tags such as `view`, `text`, `image`, `scroll-view`, etc. abstract native controls. They are not DOM nodes, but the syntax (start/end tag, attributes) stays HTML-like. (See [Composing Elements](/guide/ui/elements-components.md))
 - **Cross-platform mapping**: The same element automatically maps to the platform’s native view (`view` → iOS `UIView`, Android `ViewGroup`; on the web it becomes a custom element), so you do not need platform-specific code.
-- **Text semantics**: Text must live inside the `text` element. You cannot drop plain text inside a `div` equivalent. Inline layout relies on nested `text` elements. (See [Typography](https://lynxjs.org/next/guide/styling/text-and-typography.md))
-- **Extensibility**: When the built-in set is not enough, register custom native elements. Implement them per platform (iOS/Android/Harmony) and use them through a unified tag. (See [Custom Element](https://lynxjs.org/next/guide/custom-native-component.md))
+- **Text semantics**: Text must live inside the `text` element. You cannot drop plain text inside a `div` equivalent. Inline layout relies on nested `text` elements. (See [Typography](/guide/styling/text-and-typography.md))
+- **Extensibility**: When the built-in set is not enough, register custom native elements. Implement them per platform (iOS/Android/Harmony) and use them through a unified tag. (See [Custom Element](/guide/custom-native-component.md))
 
 Additionally:
 
@@ -47,17 +47,17 @@ Additionally:
 
 ## 5. Layout System: Block by Default with Four Layout Modes
 
-| Layout mode         | Web counterpart                                    | Lynx-specific notes                                                                                                                                                                                                  |
-| ------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `display: linear`   | No direct counterpart; simplified flex-like layout | The main axis is vertical by default. Use `linear-direction` and `linear-weight` to distribute space—suited for linear arrangements. (See [Linear Layout](https://lynxjs.org/next/guide/ui/layout/linear-layout.md)) |
-| `display: flex`     | CSS Flexbox                                        | Most properties match CSS, but `min-content` is unsupported and the shrink lower bound is treated as `0px`. (See [Flexible Box Layout](https://lynxjs.org/next/guide/ui/layout/flexible-box-layout.md))              |
-| `display: grid`     | CSS Grid                                           | Supports common row/column definitions and gaps; currently lacks `grid-area` and line names. (See [Grid Layout](https://lynxjs.org/next/guide/ui/layout/grid-layout.md))                                             |
-| `display: relative` | Android RelativeLayout mental model                | Effective on mobile only. Use `relative-*` properties to describe positioning relative to siblings/parent. (See [Relative Layout](https://lynxjs.org/next/guide/ui/layout/relative-layout.md))                       |
+| Layout mode         | Web counterpart                                    | Lynx-specific notes                                                                                                                                                                           |
+| ------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `display: linear`   | No direct counterpart; simplified flex-like layout | The main axis is vertical by default. Use `linear-direction` and `linear-weight` to distribute space—suited for linear arrangements. (See [Linear Layout](/guide/ui/layout/linear-layout.md)) |
+| `display: flex`     | CSS Flexbox                                        | Most properties match CSS, but `min-content` is unsupported and the shrink lower bound is treated as `0px`. (See [Flexible Box Layout](/guide/ui/layout/flexible-box-layout.md))              |
+| `display: grid`     | CSS Grid                                           | Supports common row/column definitions and gaps; currently lacks `grid-area` and line names. (See [Grid Layout](/guide/ui/layout/grid-layout.md))                                             |
+| `display: relative` | Android RelativeLayout mental model                | Effective on mobile only. Use `relative-*` properties to describe positioning relative to siblings/parent. (See [Relative Layout](/guide/ui/layout/relative-layout.md))                       |
 
 Additionally:
 
-- Every element defaults to `box-sizing: border-box`; margin collapsing does not occur. (See [Understanding Layout](https://lynxjs.org/next/guide/ui/layout/index.md))
-- There is no `inline` vs. `block` toggle; text layout relies on the `text` element. (See [Typography](https://lynxjs.org/next/guide/styling/text-and-typography.md))
+- Every element defaults to `box-sizing: border-box`; margin collapsing does not occur. (See [Understanding Layout](/guide/ui/layout/index.md))
+- There is no `inline` vs. `block` toggle; text layout relies on the `text` element. (See [Typography](/guide/styling/text-and-typography.md))
 - Logical directions (such as `inline-start`) depend on `direction` and require CSS inheritance to be enabled.
 - `overflow: scroll` is unsupported. Use `<scroll-view />` and enable scrolling with either the `scroll-y` or `scroll-x` attribute.
 - `position` supports `relative`, `absolute`, and `fixed`. Nodes with `fixed` are promoted directly under the root node.
@@ -65,38 +65,38 @@ Additionally:
 ## 6. Styling System: CSS Syntax with Lynx Configuration
 
 - **Special units**: Supports the `rpx` unit to adapt to different screen sizes.
-- **Selectors and inline styles**: Largely identical to the web. Combine with PostCSS/Sass nesting if needed. (See [Styling with CSS](https://lynxjs.org/next/guide/ui/styling.md))
-- **Extended properties**: `-x-` prefixed properties expose mobile capabilities such as `-x-auto-font-size`. (See [Styling with CSS](https://lynxjs.org/next/guide/ui/styling.md))
-- **Theming and inheritance**: CSS variables and class switching are supported. Regular properties do not inherit by default—enable `enableCSSInheritance` in `pluginReactLynx` or configure `customCSSInheritanceList`. (See [Custom properties (`--*`): CSS variables](https://lynxjs.org/next/api/css/properties/css-variable.md), [Theming](https://lynxjs.org/next/guide/styling/custom-theming.md))
+- **Selectors and inline styles**: Largely identical to the web. Combine with PostCSS/Sass nesting if needed. (See [Styling with CSS](/guide/ui/styling.md))
+- **Extended properties**: `-x-` prefixed properties expose mobile capabilities such as `-x-auto-font-size`. (See [Styling with CSS](/guide/ui/styling.md))
+- **Theming and inheritance**: CSS variables and class switching are supported. Regular properties do not inherit by default—enable `enableCSSInheritance` in `pluginReactLynx` or configure `customCSSInheritanceList`. (See [Custom properties (`--*`): CSS variables](/api/css/properties/css-variable.md), [Theming](/guide/styling/custom-theming.md))
 - **Fonts**: Supports `@font-face` and `lynx.addFont`, but the host must implement font loading.
 
 ## 7. ReactLynx: Familiar APIs with Lynx Constraints
 
-- **API parity**: Almost identical to React; `import { useState } from '@lynx-js/react'`. The runtime is powered by Preact. (See [What is ReactLynx](https://lynxjs.org/next/react/introduction.md))
-- **Lifecycle**: All lifecycle hooks run asynchronously on the background thread. `useLayoutEffect` is disabled; use `main-thread:bindlayoutchange` to obtain layout information and update properties instead. (See [Rendering Process and Lifecycle](https://lynxjs.org/next/react/lifecycle.md))
+- **API parity**: Almost identical to React; `import { useState } from '@lynx-js/react'`. The runtime is powered by Preact. (See [What is ReactLynx](/react/introduction.md))
+- **Lifecycle**: All lifecycle hooks run asynchronously on the background thread. `useLayoutEffect` is disabled; use `main-thread:bindlayoutchange` to obtain layout information and update properties instead. (See [Rendering Process and Lifecycle](/react/lifecycle.md))
   ![Lifecycle diagram](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lifecycle-init-render-v3.png)
-- **Background-only restrictions**: The framework can statically infer some direct cases, but once indirection is introduced—passing event handlers through components or writing custom hooks—you must explicitly add the `'background only'` directive. (See [Thinking in ReactLynx](https://lynxjs.org/next/react/thinking-in-reactlynx.md))
+- **Background-only restrictions**: The framework can statically infer some direct cases, but once indirection is introduced—passing event handlers through components or writing custom hooks—you must explicitly add the `'background only'` directive. (See [Thinking in ReactLynx](/react/thinking-in-reactlynx.md))
 - **Main-thread functions**: Add `'main thread';` at the top of the function body. Such functions can only run on the main thread (for example in event handlers or `main-thread:ref`). Captured outer variables are snapshotted and must be JSON-serializable, so you cannot capture functions directly.
 - **Cross-thread execution**: You cannot call a function defined on the other thread directly. Use `runOnMainThread` / `runOnBackground`, which return Promises for cross-thread calls.
-- **Module system**: ESM and CommonJS are both supported and can be mixed, though ESM is recommended. Rspeedy/SWC handles module transformation during the build. (See [JavaScript Runtime](https://lynxjs.org/next/guide/scripting-runtime/index.md))
+- **Module system**: ESM and CommonJS are both supported and can be mixed, though ESM is recommended. Rspeedy/SWC handles module transformation during the build. (See [JavaScript Runtime](/guide/scripting-runtime/index.md))
 
 ## 8. Type System
 
-- **TypeScript support**: Official typings live in `@lynx-js/types`; using TypeScript throughout is highly encouraged. (See [TypeScript Support](https://lynxjs.org/next/rspeedy/typescript))
+- **TypeScript support**: Official typings live in `@lynx-js/types`; using TypeScript throughout is highly encouraged. (See [TypeScript Support](/rspeedy/typescript))
 - **`tsconfig.json`**: Set `compilerOptions.jsx` to `react-jsx` and `compilerOptions.jsxImportSource` to `@lynx-js/react`.
 - **Import types correctly**: All Lynx API types are exported from `@lynx-js/types`, for example `import type { MainThread, NodesRef } from '@lynx-js/types'`. ReactLynx APIs and types come from `@lynx-js/react`.
 
 ## 9. Event Model: Naming and Propagation
 
-- **Event attribute names**: `bindtap`, `catchtap`, `capture-bindtap`, `global-bindtap`, etc. denote phase/interception. Main-thread events require the `main-thread:` prefix. (See [Event Propagation](https://lynxjs.org/next/guide/interaction/event-handling/event-propagation.md))
+- **Event attribute names**: `bindtap`, `catchtap`, `capture-bindtap`, `global-bindtap`, etc. denote phase/interception. Main-thread events require the `main-thread:` prefix. (See [Event Propagation](/guide/interaction/event-handling/event-propagation.md))
 - **Propagation phases**: Capture plus bubble over the element tree path. Non-touch events fire only on the target node.
-- **Event object differences**: The background thread receives plain JSON. Main-thread events expose `MainThread.Element` through `currentTarget`, allowing direct node operations (such as `setStyleProperty`). (See [Event Handling](https://lynxjs.org/next/guide/interaction/event-handling.md))
-- **Global events**: `GlobalEventEmitter` supports cross-component and host broadcasts and must be used on the background thread. (See [Event Propagation](https://lynxjs.org/next/guide/interaction/event-handling/event-propagation.md))
+- **Event object differences**: The background thread receives plain JSON. Main-thread events expose `MainThread.Element` through `currentTarget`, allowing direct node operations (such as `setStyleProperty`). (See [Event Handling](/guide/interaction/event-handling.md))
+- **Global events**: `GlobalEventEmitter` supports cross-component and host broadcasts and must be used on the background thread. (See [Event Propagation](/guide/interaction/event-handling/event-propagation.md))
 - **AOP interception**: `lynx.beforePublishEvent` lets you intercept events centrally on the background thread.
 
 ## 10. Node References and Direct Manipulation
 
-- **Background thread**: Use `useRef<NodesRef>` with `ref={...}` and operate via `invoke()` / `setNativeProps()`. Remember to call `.exec()` at the end to submit batched operations. (See [Direct Manipulation](https://lynxjs.org/next/guide/interaction/event-handling/manipulating-element.react.md))
+- **Background thread**: Use `useRef<NodesRef>` with `ref={...}` and operate via `invoke()` / `setNativeProps()`. Remember to call `.exec()` at the end to submit batched operations. (See [Direct Manipulation](/guide/interaction/event-handling/manipulating-element.react.md))
 - **Main thread**: `useMainThreadRef` plus `main-thread:ref` yields `MainThread.Element`, which exposes methods such as `setStyleProperty` and `invoke`.
 - **Selector APIs**: On the background thread, `lynx.createSelectorQuery()` produces `NodesRef`. On the main thread, use `lynx.querySelector()` / `lynx.querySelectorAll()` to obtain `MainThread.Element`.
 - **Getting the event target**: Background-thread event payloads do not carry node references. On the main thread, `event.currentTarget` is a `MainThread.Element`.
@@ -106,52 +106,52 @@ Case study:
 
 - **Retrieve layout information**: Choose the approach that fits your scenario:
   - Via events: Listen to `bindlayoutchange` for layout updates—the event object contains layout data. With Main Thread Script, use the main-thread variant `main-thread:bindlayoutchange`.
-  - Direct node access: Call `boundingClientRect` on the node. Background thread uses `NodesRef.invoke`; main thread uses `MainThread.Element.invoke`. (See [Direct Manipulation](https://lynxjs.org/next/guide/interaction/event-handling/manipulating-element.react.md))
+  - Direct node access: Call `boundingClientRect` on the node. Background thread uses `NodesRef.invoke`; main thread uses `MainThread.Element.invoke`. (See [Direct Manipulation](/guide/interaction/event-handling/manipulating-element.react.md))
 
 Common APIs:
 
-- [Interface `NodesRef`](https://lynxjs.org/next/api/lynx-api/nodes-ref.md)
-- [invoke()](https://lynxjs.org/next/api/lynx-api/nodes-ref/nodes-ref-invoke.md)
-- [setNativeProps()](https://lynxjs.org/next/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md)
-- [Interface `MainThread.Element`](https://lynxjs.org/next/api/lynx-api/main-thread/main-thread-element.md)
-- [animate()](https://lynxjs.org/next/api/lynx-api/main-thread/lynx-animate-api.md)
-- [Interface `SelectorQuery`](https://lynxjs.org/next/api/lynx-api/selector-query.md)
-- [exec()](https://lynxjs.org/next/api/lynx-api/selector-query/selector-query-exec.md)
-- [select()](https://lynxjs.org/next/api/lynx-api/selector-query/selector-query-select.md)
+- [Interface `NodesRef`](/api/lynx-api/nodes-ref.md)
+- [invoke()](/api/lynx-api/nodes-ref/nodes-ref-invoke.md)
+- [setNativeProps()](/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md)
+- [Interface `MainThread.Element`](/api/lynx-api/main-thread/main-thread-element.md)
+- [animate()](/api/lynx-api/main-thread/lynx-animate-api.md)
+- [Interface `SelectorQuery`](/api/lynx-api/selector-query.md)
+- [exec()](/api/lynx-api/selector-query/selector-query-exec.md)
+- [select()](/api/lynx-api/selector-query/selector-query-select.md)
 
 ## 11. Data Input and Host Communication
 
-- **Init data**: The host injects initial data with `LynxView.loadTemplate`. Front-end code accesses it via `useInitData`; updates trigger automatic re-rendering. (See [Using Data from Host Platform](https://lynxjs.org/next/guide/use-data-from-host-platform.md))
+- **Init data**: The host injects initial data with `LynxView.loadTemplate`. Front-end code accesses it via `useInitData`; updates trigger automatic re-rendering. (See [Using Data from Host Platform](/guide/use-data-from-host-platform.md))
 - **Data processors**: Use `lynx.registerDataProcessors` to normalize multi-end data structures with named processors on the front end.
 - **Global properties**: Read host configurations (such as dark mode) from `lynx.__globalProps` and pair them with theme switching. Actual properties are host-defined; if the host does not provide them, `lynx.__globalProps` is `null` or an empty object.
-- **Guaranteeing IFR**: As long as initial data arrives synchronously and the Lynx bundle loads synchronously, the main thread can render a first frame with no white screen. (See [IFR](https://lynxjs.org/next/guide/interaction/ifr.md))
+- **Guaranteeing IFR**: As long as initial data arrives synchronously and the Lynx bundle loads synchronously, the main thread can render a first frame with no white screen. (See [IFR](/guide/interaction/ifr.md))
 
 ## 12. Extending Host Capabilities
 
-- **Native Modules**: Declare TypeScript types, implement them separately on iOS/Android/Harmony, and register them. Front-end code calls `NativeModules.xxx` on the background thread. (See [Native Modules](https://lynxjs.org/next/guide/use-native-modules.md))
-- **Custom elements**: When you need capabilities closer to native controls (for example customized inputs), extend `LynxUI` on the host, implement attributes/events/commands, and use it just like a built-in element. (See [Custom Element](https://lynxjs.org/next/guide/custom-native-component.md))
+- **Native Modules**: Declare TypeScript types, implement them separately on iOS/Android/Harmony, and register them. Front-end code calls `NativeModules.xxx` on the background thread. (See [Native Modules](/guide/use-native-modules.md))
+- **Custom elements**: When you need capabilities closer to native controls (for example customized inputs), extend `LynxUI` on the host, implement attributes/events/commands, and use it just like a built-in element. (See [Custom Element](/guide/custom-native-component.md))
 - **SelectorQuery invoking native commands**: Call `invoke({ method: 'focus' })` to trigger native methods exposed by custom elements. Consult the element’s documentation for supported commands.
 
 ## 13. Networking and Runtime Differences
 
-- **Fetch API**: The interface aligns with the web, but depends on the host-provided HTTP service. Enable streaming responses via `lynxExtension.useStreaming` and read from `response.body`. Review official compatibility notes as needed. (See [Networking](https://lynxjs.org/next/guide/interaction/networking.md))
-- **Encoding helpers**: PrimJS currently lacks `TextEncoder` / `TextDecoder`, so use `TextCodecHelper` for UTF-8 encoding/decoding. (See [Networking](https://lynxjs.org/next/guide/interaction/networking.md))
-- **Global object limitations**: There is no `window` or `document`. Replace browser APIs with `lynx` alternatives (such as `lynx.reload`). (See [ReactLynx](https://lynxjs.org/next/react/introduction.md))
-- **Polyfills and syntax**: PrimJS on the main thread supports up to ES2019; the background thread supports ES2015. The build injects polyfills automatically (primarily for iOS). (See [JavaScript Runtime](https://lynxjs.org/next/guide/scripting-runtime/index.md))
+- **Fetch API**: The interface aligns with the web, but depends on the host-provided HTTP service. Enable streaming responses via `lynxExtension.useStreaming` and read from `response.body`. Review official compatibility notes as needed. (See [Networking](/guide/interaction/networking.md))
+- **Encoding helpers**: PrimJS currently lacks `TextEncoder` / `TextDecoder`, so use `TextCodecHelper` for UTF-8 encoding/decoding. (See [Networking](/guide/interaction/networking.md))
+- **Global object limitations**: There is no `window` or `document`. Replace browser APIs with `lynx` alternatives (such as `lynx.reload`). (See [ReactLynx](/react/introduction.md))
+- **Polyfills and syntax**: PrimJS on the main thread supports up to ES2019; the background thread supports ES2015. The build injects polyfills automatically (primarily for iOS). (See [JavaScript Runtime](/guide/scripting-runtime/index.md))
 
 ## 14. Performance Tooling and Tuning
 
-- **Main Thread Script**: Keep animations/gestures responsive while respecting thread isolation and data synchronization. (See [Main Thread Script](https://lynxjs.org/next/react/main-thread-script.md))
-- **NodesRef.invoke**: Batch native operations (for example `autoScroll`) to avoid cross-thread overhead. (See [Direct Manipulation](https://lynxjs.org/next/guide/interaction/event-handling/manipulating-element.react.md))
-- **Lynx DevTool & Trace**: The desktop DevTool offers Elements/Console/Sources/Trace panels to record render pipelines and analyze the ReactLynx render process. (See [Lynx DevTool](https://lynxjs.org/next/guide/devtool.md), [Trace](https://lynxjs.org/next/guide/devtool/trace.md))
-- **Performance metrics**: Use `lynx.performance` and `PerformanceObserver` to capture metrics such as FCP and InitContainer. (See [Performance API](https://lynxjs.org/next/guide/performance/metrics/performance-api.md))
+- **Main Thread Script**: Keep animations/gestures responsive while respecting thread isolation and data synchronization. (See [Main Thread Script](/react/main-thread-script.md))
+- **NodesRef.invoke**: Batch native operations (for example `autoScroll`) to avoid cross-thread overhead. (See [Direct Manipulation](/guide/interaction/event-handling/manipulating-element.react.md))
+- **Lynx DevTool & Trace**: The desktop DevTool offers Elements/Console/Sources/Trace panels to record render pipelines and analyze the ReactLynx render process. (See [Lynx DevTool](/guide/devtool.md), [Trace](/guide/devtool/trace.md))
+- **Performance metrics**: Use `lynx.performance` and `PerformanceObserver` to capture metrics such as FCP and InitContainer. (See [Performance API](/guide/performance/metrics/performance-api.md))
 
 ## 15. Engineering Practices and Tooling
 
-- **Project initialization**: `pnpm create rspeedy` scaffolds a ReactLynx project with Rspeedy configuration and sample code. (See [Quick Start](https://lynxjs.org/next/rspeedy/start/quick-start.md))
-- **Development and debugging**: `pnpm dev` starts the Rspeedy dev server. The terminal prints a QR code—scan it with the LynxExample app (iOS/Android/Harmony emulator) for hot-update previews. (See [Quick Start](https://lynxjs.org/next/rspeedy/start/quick-start.md))
-- **DevTool debugging**: After connecting a device, use the desktop Lynx DevTool to debug JS, inspect nodes, and record performance. (See [Lynx DevTool](https://lynxjs.org/next/guide/devtool.md))
-- **Build artifacts**: Rspeedy outputs a bundle that includes the background-thread script (text), main-thread bytecode, styles, and other assets. Set `DEBUG=rspeedy` to dump intermediate artifacts (background script, main-thread bytecode, styles, source maps, etc.) into `dist/.rspeedy`; otherwise only the final bundle is produced. (See [Output Files](https://lynxjs.org/next/rspeedy/output.md))
+- **Project initialization**: `pnpm create rspeedy` scaffolds a ReactLynx project with Rspeedy configuration and sample code. (See [Quick Start](/rspeedy/start/quick-start.md))
+- **Development and debugging**: `pnpm dev` starts the Rspeedy dev server. The terminal prints a QR code—scan it with the LynxExample app (iOS/Android/Harmony emulator) for hot-update previews. (See [Quick Start](/rspeedy/start/quick-start.md))
+- **DevTool debugging**: After connecting a device, use the desktop Lynx DevTool to debug JS, inspect nodes, and record performance. (See [Lynx DevTool](/guide/devtool.md))
+- **Build artifacts**: Rspeedy outputs a bundle that includes the background-thread script (text), main-thread bytecode, styles, and other assets. Set `DEBUG=rspeedy` to dump intermediate artifacts (background script, main-thread bytecode, styles, source maps, etc.) into `dist/.rspeedy`; otherwise only the final bundle is produced. (See [Output Files](/rspeedy/output.md))
 
 ## 16. Key Differences from the Web
 
@@ -196,29 +196,29 @@ Common APIs:
 
 The following official Lynx tutorials cover scenarios from beginner to advanced—work through them hands-on:
 
-- Product gallery — build a two-column product page step by step: [Tutorial Gallery](https://lynxjs.org/next/guide/start/tutorial-gallery.md). You will learn to:
+- Product gallery — build a two-column product page step by step: [Tutorial Gallery](/guide/start/tutorial-gallery.md). You will learn to:
   - Build foundational UI with styling and interactions
   - Componentize the layout
   - Render high-performance long lists with the `<list />` element
   - Manipulate nodes directly via `NodesRef.invoke` to implement auto-scrolling
-  - Customize scrollbars and leverage [Main Thread Script](https://lynxjs.org/next/react/main-thread-script.md) to optimize scrolling performance
-- Product detail — implement a carousel component to practice high-performance interaction code: [Tutorial Product Detail](https://lynxjs.org/next/guide/start/tutorial-product-detail.md). You will learn to:
+  - Customize scrollbars and leverage [Main Thread Script](/react/main-thread-script.md) to optimize scrolling performance
+- Product detail — implement a carousel component to practice high-performance interaction code: [Tutorial Product Detail](/guide/start/tutorial-product-detail.md). You will learn to:
   - Manipulate nodes directly with `NodesRef.setNativeProps` to update styles and attributes
-  - Use [Main Thread Script](https://lynxjs.org/next/react/main-thread-script.md) to reduce latency
+  - Use [Main Thread Script](/react/main-thread-script.md) to reduce latency
   - Call between main-thread and background-thread functions
   - Pass values between main-thread and background-thread scripts
 
 ## 20. Appendix: Key Built-in Elements
 
-- [`<view>` element](https://lynxjs.org/next/api/elements/built-in/view.md)
-- [`<text>` element](https://lynxjs.org/next/api/elements/built-in/text.md)
-- [`<image>` element](https://lynxjs.org/next/api/elements/built-in/image.md)
-- [`<scroll-view>` element](https://lynxjs.org/next/api/elements/built-in/scroll-view.md)
-- [`<list>` element](https://lynxjs.org/next/api/elements/built-in/list.md)
-- [`<page>` element](https://lynxjs.org/next/api/elements/built-in/page.md)
-- [`<frame>` element](https://lynxjs.org/next/api/elements/built-in/frame.md)
-- [`<input>` element](https://lynxjs.org/next/api/elements/built-in/input.md)
-- [`<textarea>` element](https://lynxjs.org/next/api/elements/built-in/textarea.md)
+- [`<view>` element](/api/elements/built-in/view.md)
+- [`<text>` element](/api/elements/built-in/text.md)
+- [`<image>` element](/api/elements/built-in/image.md)
+- [`<scroll-view>` element](/api/elements/built-in/scroll-view.md)
+- [`<list>` element](/api/elements/built-in/list.md)
+- [`<page>` element](/api/elements/built-in/page.md)
+- [`<frame>` element](/api/elements/built-in/frame.md)
+- [`<input>` element](/api/elements/built-in/input.md)
+- [`<textarea>` element](/api/elements/built-in/textarea.md)
 
 ---
 
diff --git a/docs/public/zh/AGENTS.md b/docs/public/zh/AGENTS.md
index 6068fdad..e7b79d03 100644
--- a/docs/public/zh/AGENTS.md
+++ b/docs/public/zh/AGENTS.md
@@ -12,34 +12,34 @@
 
 ## 1. Lynx 的定位与能力边界
 
-- **What**：Lynx 是一个以 Web 技术为语义参照的跨平台渲染引擎，目标是在一套代码内覆盖 iOS、Android、HarmonyOS 以及 Web。它通过统一的元件抽象在不同宿主上创建原生视图或 Web 自定义元件，避免传统 WebView 的性能瓶颈。（参考：[Composing Elements](https://lynxjs.org/next/zh/guide/ui/elements-components.md)）
-- **Why**：移动端用户极度敏感首屏时间与交互延迟。Lynx 通过双线程 JavaScript 运行时、即时首帧渲染（Instant First-Frame Rendering, IFR）和原生渲染管线，让 React 开发体验与近原生性能同时存在。（参考：[Instant First-Frame Rendering](https://lynxjs.org/next/zh/guide/interaction/ifr.md)）
-- **How**：在工程侧使用 Rspeedy（Rspack 驱动的构建工具）生成 Lynx Bundle，前端层采用 ReactLynx（Preact 内核的 React 实现）来描述 UI，与宿主端通过 Native Modules / Custom Elements 互通。（参考：[ReactLynx](https://lynxjs.org/next/zh/react/introduction.md), [Native Modules](https://lynxjs.org/next/zh/guide/use-native-modules.md)）
+- **What**：Lynx 是一个以 Web 技术为语义参照的跨平台渲染引擎，目标是在一套代码内覆盖 iOS、Android、HarmonyOS 以及 Web。它通过统一的元件抽象在不同宿主上创建原生视图或 Web 自定义元件，避免传统 WebView 的性能瓶颈。（参考：[Composing Elements](/zh/guide/ui/elements-components.md)）
+- **Why**：移动端用户极度敏感首屏时间与交互延迟。Lynx 通过双线程 JavaScript 运行时、即时首帧渲染（Instant First-Frame Rendering, IFR）和原生渲染管线，让 React 开发体验与近原生性能同时存在。（参考：[Instant First-Frame Rendering](/zh/guide/interaction/ifr.md)）
+- **How**：在工程侧使用 Rspeedy（Rspack 驱动的构建工具）生成 Lynx Bundle，前端层采用 ReactLynx（Preact 内核的 React 实现）来描述 UI，与宿主端通过 Native Modules / Custom Elements 互通。（参考：[ReactLynx](/zh/react/introduction.md), [Native Modules](/zh/guide/use-native-modules.md)）
 
 ## 2. 心智模型：把 Lynx 对齐到 Web
 
-| Web 心智               | Lynx 对应物                                                           | 差异重点                                                                                                                                                                                                                                                                       |
-| ---------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `index.html` + 资源    | Lynx Bundle（二进制文件，包含 JS 字节码 + 样式）或 `template.js` 文件 | Bundle 需与 Lynx Engine 版本兼容，需设置 `engineVersion`（历史上曾称 `targetSdkVersion`）。（参考：[Compatibility](https://lynxjs.org/next/zh/guide/compatibility.md)）                                                                                                        |
-| DOM + CSSOM            | 元件树（Element Tree）+ 样式系统                                      | 所有元件都类比 block-level，`view`/`text` 等自定义标签映射到原生控件。（参考：[Composing Elements](https://lynxjs.org/next/zh/guide/ui/elements-components.md)）                                                                                                               |
-| 浏览器主线程           | Lynx Main Thread                                                      | 负责首屏渲染、布局、主线程脚本，运行 PrimJS 字节码。（参考：[Main Thread Runtime](https://lynxjs.org/next/zh/guide/scripting-runtime/main-thread-runtime.md)）                                                                                                                 |
-| 浏览器渲染进程任务队列 | Lynx Background Thread                                                | 执行 ReactLynx 调度、生命周期、绝大部分副作用。运行 PrimJS/JavaScriptCore，语法最高仅到 ES2015（构建期经 SWC 转译）。（参考：[JavaScript Runtime](https://lynxjs.org/next/zh/guide/scripting-runtime/index.md)）                                                               |
-| `window`/`document`    | `lynx` 全局对象 + API 集                                              | 无 DOM API；通过 `lynx.getElementById`、SelectorQuery、`main-thread:ref` 等访问节点。（参考：[ReactLynx](https://lynxjs.org/next/zh/react/introduction.md), [Direct Manipulation](https://lynxjs.org/next/zh/guide/interaction/event-handling/manipulating-element.react.md)） |
+| Web 心智               | Lynx 对应物                                                           | 差异重点                                                                                                                                                                                                                         |
+| ---------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.html` + 资源    | Lynx Bundle（二进制文件，包含 JS 字节码 + 样式）或 `template.js` 文件 | Bundle 需与 Lynx Engine 版本兼容，需设置 `engineVersion`（历史上曾称 `targetSdkVersion`）。（参考：[Compatibility](/zh/guide/compatibility.md)）                                                                                 |
+| DOM + CSSOM            | 元件树（Element Tree）+ 样式系统                                      | 所有元件都类比 block-level，`view`/`text` 等自定义标签映射到原生控件。（参考：[Composing Elements](/zh/guide/ui/elements-components.md)）                                                                                        |
+| 浏览器主线程           | Lynx Main Thread                                                      | 负责首屏渲染、布局、主线程脚本，运行 PrimJS 字节码。（参考：[Main Thread Runtime](/zh/guide/scripting-runtime/main-thread-runtime.md)）                                                                                          |
+| 浏览器渲染进程任务队列 | Lynx Background Thread                                                | 执行 ReactLynx 调度、生命周期、绝大部分副作用。运行 PrimJS/JavaScriptCore，语法最高仅到 ES2015（构建期经 SWC 转译）。（参考：[JavaScript Runtime](/zh/guide/scripting-runtime/index.md)）                                        |
+| `window`/`document`    | `lynx` 全局对象 + API 集                                              | 无 DOM API；通过 `lynx.getElementById`、SelectorQuery、`main-thread:ref` 等访问节点。（参考：[ReactLynx](/zh/react/introduction.md), [Direct Manipulation](/zh/guide/interaction/event-handling/manipulating-element.react.md)） |
 
 ## 3. 运行时架构：双线程 React 的工作方式
 
-- **双线程并行渲染**：首屏时主线程直接执行 ReactLynx 渲染输出像素，同时后台线程构建完整节点树并与主线程状态对齐，避免白屏。（参考：[Rendering Process and Lifecycle](https://lynxjs.org/next/zh/react/lifecycle.md), [IFR](https://lynxjs.org/next/zh/guide/interaction/ifr.md)）
+- **双线程并行渲染**：首屏时主线程直接执行 ReactLynx 渲染输出像素，同时后台线程构建完整节点树并与主线程状态对齐，避免白屏。（参考：[Rendering Process and Lifecycle](/zh/react/lifecycle.md), [IFR](/zh/guide/interaction/ifr.md)）
 - **“你的代码运行在两个线程”**：双线程 React 意味着你的代码会在两个线程中运行。但并不是所有的代码都能在两个线程运行——一些 API 仅在后台线程提供；ReactLynx 也只会从后台线程执行事件、生命周期和 `useEffect` 等副作用。
 - **`'background only'`**：无需运行在主线程（如事件处理、生命周期、副作用等）、或使用了仅在后台线程提供的 API 的函数，必须在函数体首行添加 `'background only'` 指示符；模块会通过 `import "background-only"` 表达自己预期只运行在后台线程。
-- **主线程脚本（MTS）**：通过 `main-thread` 指示符标注的函数可以直接在主线程响应事件，常用于高频动画、手势和无延迟反馈。主线程事件需要用 `main-thread:` 前缀标识，使用 `main-thread:bindtap`、`useMainThreadRef` 等 API。（参考：[Main Thread Script](https://lynxjs.org/next/zh/react/main-thread-script.md)）
+- **主线程脚本（MTS）**：通过 `main-thread` 指示符标注的函数可以直接在主线程响应事件，常用于高频动画、手势和无延迟反馈。主线程事件需要用 `main-thread:` 前缀标识，使用 `main-thread:bindtap`、`useMainThreadRef` 等 API。（参考：[Main Thread Script](/zh/react/main-thread-script.md)）
 - **跨线程通信**：使用 `runOnMainThread` / `runOnBackground` 进行异步调用，参数需可 JSON 序列化。
 
 ## 4. UI 构建：元件体系与原生映射
 
-- **元件标签**：`view`、`text`、`image`、`scroll-view` 等内置标签抽象原生控件。与 HTML 不同，标签不是标准 DOM，但语法（开始标签/结束标签/属性）保持类 HTML 习惯。（参考：[Composing Elements](https://lynxjs.org/next/zh/guide/ui/elements-components.md)）
+- **元件标签**：`view`、`text`、`image`、`scroll-view` 等内置标签抽象原生控件。与 HTML 不同，标签不是标准 DOM，但语法（开始标签/结束标签/属性）保持类 HTML 习惯。（参考：[Composing Elements](/zh/guide/ui/elements-components.md)）
 - **跨平台映射**：同一元件自动映射到平台原生视图（如 `view` → iOS `UIView`、Android `ViewGroup`；Web → 自定义元件），无需手动分平台写代码。
-- **文本语义**：必须使用 `text` 元件承载文字，不能像 Web 在 `div` 里直接写文本。行内布局依赖嵌套 `text`。（参考：[Typography](https://lynxjs.org/next/zh/guide/styling/text-and-typography.md)）
-- **可扩展性**：当内置元件不足，可注册自定义原生元件，分别在 iOS/Android/Harmony 实现，前端通过统一标签使用。（参考：[Custom Element](https://lynxjs.org/next/zh/guide/custom-native-component.md)）
+- **文本语义**：必须使用 `text` 元件承载文字，不能像 Web 在 `div` 里直接写文本。行内布局依赖嵌套 `text`。（参考：[Typography](/zh/guide/styling/text-and-typography.md)）
+- **可扩展性**：当内置元件不足，可注册自定义原生元件，分别在 iOS/Android/Harmony 实现，前端通过统一标签使用。（参考：[Custom Element](/zh/guide/custom-native-component.md)）
 
 此外：
 
@@ -47,17 +47,17 @@
 
 ## 5. 布局系统：默认 Block，支持四种布局模式
 
-| 布局模式            | Web 对应                      | Lynx 差异                                                                                                                                                                 |
-| ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `display: linear`   | 无直接对应，近似更简化的 Flex | 主轴默认竖向，可用 `linear-direction`、`linear-weight` 控制尺寸分配，适合线性排布。（参考：[Linear Layout](https://lynxjs.org/next/zh/guide/ui/layout/linear-layout.md)） |
-| `display: flex`     | CSS Flexbox                   | 绝大部分属性一致，但当前不支持 `min-content`，子项收缩下限视作 `0px`。（参考：[Flexible Box Layout](https://lynxjs.org/next/zh/guide/ui/layout/flexible-box-layout.md)）  |
-| `display: grid`     | CSS Grid                      | 支持常见行列定义与 gap，暂不支持 `grid-area`、line names。（参考：[Grid Layout](https://lynxjs.org/next/zh/guide/ui/layout/grid-layout.md)）                              |
-| `display: relative` | Android RelativeLayout 心智   | 仅移动端有效，通过 `relative-*` 属性描述与兄弟/父节点的相对定位。（参考：[Relative Layout](https://lynxjs.org/next/zh/guide/ui/layout/relative-layout.md)）               |
+| 布局模式            | Web 对应                      | Lynx 差异                                                                                                                                          |
+| ------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `display: linear`   | 无直接对应，近似更简化的 Flex | 主轴默认竖向，可用 `linear-direction`、`linear-weight` 控制尺寸分配，适合线性排布。（参考：[Linear Layout](/zh/guide/ui/layout/linear-layout.md)） |
+| `display: flex`     | CSS Flexbox                   | 绝大部分属性一致，但当前不支持 `min-content`，子项收缩下限视作 `0px`。（参考：[Flexible Box Layout](/zh/guide/ui/layout/flexible-box-layout.md)）  |
+| `display: grid`     | CSS Grid                      | 支持常见行列定义与 gap，暂不支持 `grid-area`、line names。（参考：[Grid Layout](/zh/guide/ui/layout/grid-layout.md)）                              |
+| `display: relative` | Android RelativeLayout 心智   | 仅移动端有效，通过 `relative-*` 属性描述与兄弟/父节点的相对定位。（参考：[Relative Layout](/zh/guide/ui/layout/relative-layout.md)）               |
 
 此外：
 
-- 所有元件默认 `box-sizing: border-box`，无 margin collapsing。（参考：[Understanding Layout](https://lynxjs.org/next/zh/guide/ui/layout/index.md)）
-- 不存在 `inline` / `block` 切换，文本布局依赖 `text` 元件。（参考：[Typography](https://lynxjs.org/next/zh/guide/styling/text-and-typography.md)）
+- 所有元件默认 `box-sizing: border-box`，无 margin collapsing。（参考：[Understanding Layout](/zh/guide/ui/layout/index.md)）
+- 不存在 `inline` / `block` 切换，文本布局依赖 `text` 元件。（参考：[Typography](/zh/guide/styling/text-and-typography.md)）
 - 逻辑方向（`inline-start` 等）依赖 `direction` 且需要开启 CSS 继承功能。
 - 不支持 `overflow: scroll`，必须使用 `<scroll-view />` 且通过指定 `scroll-y` 或 `scroll-x` 属性之一来启用滚动。
 - `position` 支持 `relative`、`absolute`、`fixed` 3种定位方式；`fixed` 的节点会被直接提升为根节点的直接子节点。
@@ -65,38 +65,38 @@
 ## 6. 样式系统：CSS 语法为基础，结合 Lynx 配置
 
 - **特有单位**：支持 `rpx` 单位，适配不同屏幕尺寸
-- **选择器与内联样式**：与 Web 基本一致，可结合 PostCSS/Sass 嵌套语法。（参考：[Styling with CSS](https://lynxjs.org/next/zh/guide/ui/styling.md)）
-- **特有属性**：以 `-x-` 开头的扩展属性提供移动端能力，如 `-x-auto-font-size`。（参考：[Styling with CSS](https://lynxjs.org/next/zh/guide/ui/styling.md)）
-- **主题与继承**：支持 CSS 变量、类切换等手法。普通属性默认不继承，需在 `pluginReactLynx` 中开启 `enableCSSInheritance` 或配置 `customCSSInheritanceList`。（参考：[Custom properties (`--*`): CSS variables](https://lynxjs.org/next/zh/api/css/properties/css-variable.md)、[Theming](https://lynxjs.org/next/zh/guide/styling/custom-theming.md)）
+- **选择器与内联样式**：与 Web 基本一致，可结合 PostCSS/Sass 嵌套语法。（参考：[Styling with CSS](/zh/guide/ui/styling.md)）
+- **特有属性**：以 `-x-` 开头的扩展属性提供移动端能力，如 `-x-auto-font-size`。（参考：[Styling with CSS](/zh/guide/ui/styling.md)）
+- **主题与继承**：支持 CSS 变量、类切换等手法。普通属性默认不继承，需在 `pluginReactLynx` 中开启 `enableCSSInheritance` 或配置 `customCSSInheritanceList`。（参考：[Custom properties (`--*`): CSS variables](/zh/api/css/properties/css-variable.md)、[Theming](/zh/guide/styling/custom-theming.md)）
 - **字体**：支持 `@font-face` 与 `lynx.addFont`，但宿主需实现字体加载。
 
 ## 7. ReactLynx：熟悉的 API + Lynx 约束
 
-- **API 一致性**：与 React 几乎一致，直接 `import { useState } from '@lynx-js/react'`。底层基于 Preact。（参考：[What is ReactLynx](https://lynxjs.org/next/zh/react/introduction.md)）
-- **生命周期**：全部在后台线程异步执行，`useLayoutEffect` 被禁用，作为替代，可通过 `main-thread:bindlayoutchange` 获得布局信息及更新属性。（参考：[Rendering Process and Lifecycle](https://lynxjs.org/next/zh/react/lifecycle.md)）
+- **API 一致性**：与 React 几乎一致，直接 `import { useState } from '@lynx-js/react'`。底层基于 Preact。（参考：[What is ReactLynx](/zh/react/introduction.md)）
+- **生命周期**：全部在后台线程异步执行，`useLayoutEffect` 被禁用，作为替代，可通过 `main-thread:bindlayoutchange` 获得布局信息及更新属性。（参考：[Rendering Process and Lifecycle](/zh/react/lifecycle.md)）
   ![生命周期图示](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lifecycle-init-render-v3.png)
-- **后台线程限定**：框架能静态分析出部分直接情形，但引入了抽象和间接之后，例如跨组件传递事件回调或自定义 Hooks 时需显式加 `'background only'` 指示符。（参考：[Thinking in ReactLynx](https://lynxjs.org/next/zh/react/thinking-in-reactlynx.md)）
+- **后台线程限定**：框架能静态分析出部分直接情形，但引入了抽象和间接之后，例如跨组件传递事件回调或自定义 Hooks 时需显式加 `'background only'` 指示符。（参考：[Thinking in ReactLynx](/zh/react/thinking-in-reactlynx.md)）
 - **主线程函数**：函数体首行加入 `'main thread';`，只可在主线程环境使用（事件处理、`main-thread:ref`）。捕获到的外部变量是快照，需可 JSON 序列化，因此无法直接调用函数。
 - **线程间执行**：无法直接调用另一个线程的函数，需要使用 `runOnMainThread` / `runOnBackground` 提供 `Promise` 风格互调。
-- **模块系统**：同时支持 ESM 与 CommonJS，可混用；推荐使用 ESM；构建期由 Rspeedy / SWC 处理。（参考：[JavaScript Runtime](https://lynxjs.org/next/zh/guide/scripting-runtime/index.md)）
+- **模块系统**：同时支持 ESM 与 CommonJS，可混用；推荐使用 ESM；构建期由 Rspeedy / SWC 处理。（参考：[JavaScript Runtime](/zh/guide/scripting-runtime/index.md)）
 
 ## 8. 类型系统
 
-- **TypeScript 支持**：官方提供 `@lynx-js/types` 类型定义，推荐全程使用 TypeScript。（参考：[TypeScript Support](https://lynxjs.org/next/zh/rspeedy/typescript)）
+- **TypeScript 支持**：官方提供 `@lynx-js/types` 类型定义，推荐全程使用 TypeScript。（参考：[TypeScript Support](/zh/rspeedy/typescript)）
 - **`tsconfig.json`**：`compilerOptions.jsx` 需设为 `react-jsx`，`compilerOptions.jsxImportSource` 需设为 `@lynx-js/react`。
 - **正确地导入类型**：Lynx API 类型均在 `@lynx-js/types` 包中，需显式导入，如 `import type { MainThread, NodesRef } from '@lynx-js/types'`；ReactLynx 的 API 和类型从 `@lynx-js/react` 导入；支持的 React API和类型从 `@lynx-js/react` 导入。
 
 ## 9. 事件模型：命名与传播机制
 
-- **事件属性命名**：`bindtap`、`catchtap`、`capture-bindtap`、`global-bindtap` 等，按阶段/是否拦截区分；主线程事件需 `main-thread:` 前缀。（参考：[Event Propagation](https://lynxjs.org/next/zh/guide/interaction/event-handling/event-propagation.md)）
+- **事件属性命名**：`bindtap`、`catchtap`、`capture-bindtap`、`global-bindtap` 等，按阶段/是否拦截区分；主线程事件需 `main-thread:` 前缀。（参考：[Event Propagation](/zh/guide/interaction/event-handling/event-propagation.md)）
 - **传播阶段**：支持捕获 + 冒泡，事件链为元件树路径。非触摸类事件仅发生在目标节点。
-- **事件对象差异**：后台线程收到纯 JSON；主线程事件通过 `currentTarget` 提供 `MainThread.Element` 可直接操作节点（如 `setStyleProperty`）。（参考：[Event Handling](https://lynxjs.org/next/zh/guide/interaction/event-handling.md)）
-- **全局事件**：`GlobalEventEmitter` 支持跨组件/宿主广播，必须在后台线程使用。（参考：[Event Propagation](https://lynxjs.org/next/zh/guide/interaction/event-handling/event-propagation.md)）
+- **事件对象差异**：后台线程收到纯 JSON；主线程事件通过 `currentTarget` 提供 `MainThread.Element` 可直接操作节点（如 `setStyleProperty`）。（参考：[Event Handling](/zh/guide/interaction/event-handling.md)）
+- **全局事件**：`GlobalEventEmitter` 支持跨组件/宿主广播，必须在后台线程使用。（参考：[Event Propagation](/zh/guide/interaction/event-handling/event-propagation.md)）
 - **AOP 监听**：`lynx.beforePublishEvent` 可在后台线程统一拦截事件。
 
 ## 10. 节点引用与直接操作
 
-- **后台线程**：`useRef<NodesRef>` + `ref={...}`，通过 `invoke()`、`setNativeProps()` 操作，末尾必须 `.exec()` 提交。（参考：[Direct Manipulation](https://lynxjs.org/next/zh/guide/interaction/event-handling/manipulating-element.react.md)）
+- **后台线程**：`useRef<NodesRef>` + `ref={...}`，通过 `invoke()`、`setNativeProps()` 操作，末尾必须 `.exec()` 提交。（参考：[Direct Manipulation](/zh/guide/interaction/event-handling/manipulating-element.react.md)）
 - **主线程**：`useMainThreadRef` + `main-thread:ref` 提供 `MainThread.Element`，可直接调用 `setStyleProperty`、`invoke`。
 - **选择器 API**：后台线程使用 `lynx.createSelectorQuery()` 得到 `NodesRef`；主线程使用 `lynx.querySelector()`/`querySelectorAll()` 得到 `MainThread.Element`。
 - **获取事件目标**：后台线程无法在事件对象中获取到节点引用；主线程事件的 `event.currentTarget` 是 `MainThread.Element`。
@@ -106,52 +106,52 @@
 
 - **获取节点布局信息**：结合具体情况选用以下之一：
   - 通过事件：使用 `bindlayoutchange` 监听布局变化事件，事件对象包含布局信息；配合 Main Thread Script 时，使用其主线程版本 `main-thread:bindlayoutchange`。
-  - 直接操作节点：调用节点的 `boundingClientRect` 方法获取布局信息，后台线程使用 `NodesRef.invoke`，主线程使用 `MainThread.Element.invoke`。（参考：[Direct Manipulation](https://lynxjs.org/next/zh/guide/interaction/event-handling/manipulating-element.react.md)）
+  - 直接操作节点：调用节点的 `boundingClientRect` 方法获取布局信息，后台线程使用 `NodesRef.invoke`，主线程使用 `MainThread.Element.invoke`。（参考：[Direct Manipulation](/zh/guide/interaction/event-handling/manipulating-element.react.md)）
 
 常用 API：
 
-- [Interface `NodesRef`](https://lynxjs.org/next/zh/api/lynx-api/nodes-ref.md)
-- [invoke()](https://lynxjs.org/next/zh/api/lynx-api/nodes-ref/nodes-ref-invoke.md)
-- [setNativeProps()](https://lynxjs.org/next/zh/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md)
-- [Interface `MainThread.Element`](https://lynxjs.org/next/zh/api/lynx-api/main-thread/main-thread-element.md)
-- [animate()](https://lynxjs.org/next/zh/api/lynx-api/main-thread/lynx-animate-api.md)
-- [Interface `SelectorQuery`](https://lynxjs.org/next/zh/api/lynx-api/selector-query.md)
-- [exec()](https://lynxjs.org/next/zh/api/lynx-api/selector-query/selector-query-exec.md)
-- [select()](https://lynxjs.org/next/zh/api/lynx-api/selector-query/selector-query-select.md)
+- [Interface `NodesRef`](/zh/api/lynx-api/nodes-ref.md)
+- [invoke()](/zh/api/lynx-api/nodes-ref/nodes-ref-invoke.md)
+- [setNativeProps()](/zh/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md)
+- [Interface `MainThread.Element`](/zh/api/lynx-api/main-thread/main-thread-element.md)
+- [animate()](/zh/api/lynx-api/main-thread/lynx-animate-api.md)
+- [Interface `SelectorQuery`](/zh/api/lynx-api/selector-query.md)
+- [exec()](/zh/api/lynx-api/selector-query/selector-query-exec.md)
+- [select()](/zh/api/lynx-api/selector-query/selector-query-select.md)
 
 ## 11. 数据输入与宿主互通
 
-- **Init Data**：宿主通过 `LynxView.loadTemplate` 注入初始数据，前端 `useInitData` 即取即用；数据更新触发自动重渲染。（参考：[Using Data from Host Platform](https://lynxjs.org/next/zh/guide/use-data-from-host-platform.md)）
+- **Init Data**：宿主通过 `LynxView.loadTemplate` 注入初始数据，前端 `useInitData` 即取即用；数据更新触发自动重渲染。（参考：[Using Data from Host Platform](/zh/guide/use-data-from-host-platform.md)）
 - **Data Processor**：`lynx.registerDataProcessors` 可在前端统一规范多端数据结构，支持命名 processor。
 - **全局属性**：`lynx.__globalProps` 可读取宿主配置（如暗黑模式），结合主题切换；具体属性由宿主定义；如宿主未主动配置，`lynx.__globalProps` 为 `null` 或空对象。
-- **确保 IFR**：只要初始数据同步传入、Lynx Bundle 可同步加载，即可在主线程实现零白屏首帧。（参考：[IFR](https://lynxjs.org/next/zh/guide/interaction/ifr.md)）
+- **确保 IFR**：只要初始数据同步传入、Lynx Bundle 可同步加载，即可在主线程实现零白屏首帧。（参考：[IFR](/zh/guide/interaction/ifr.md)）
 
 ## 12. 宿主能力扩展
 
-- **Native Modules**：声明 TypeScript 类型后，可在 iOS/Android/Harmony 各自实现并注册；前端通过 `NativeModules.xxx` 在后台线程调用。（参考：[Native Modules](https://lynxjs.org/next/zh/guide/use-native-modules.md)）
-- **Custom Elements**：当需要更贴近原生控件的能力（如自定义输入框），在宿主侧继承 `LynxUI` 实现属性、事件、命令，前端像使用内置元件一样引用。（参考：[Custom Element](https://lynxjs.org/next/zh/guide/custom-native-component.md)）
+- **Native Modules**：声明 TypeScript 类型后，可在 iOS/Android/Harmony 各自实现并注册；前端通过 `NativeModules.xxx` 在后台线程调用。（参考：[Native Modules](/zh/guide/use-native-modules.md)）
+- **Custom Elements**：当需要更贴近原生控件的能力（如自定义输入框），在宿主侧继承 `LynxUI` 实现属性、事件、命令，前端像使用内置元件一样引用。（参考：[Custom Element](/zh/guide/custom-native-component.md)）
 - **SelectorQuery 调原生命令**：可通过 `invoke({ method: 'focus' })` 调用自定义元件暴露的原生方法；查询特定元件的文档获取支持的方法列表。
 
 ## 13. 网络与运行环境差异
 
-- **Fetch API**：接口契合 Web，但依赖宿主提供 HTTP Service；支持 `lynxExtension.useStreaming` 开启流式响应，自行读取 `response.body`。某些兼容性差异需查官方说明。（参考：[Networking](https://lynxjs.org/next/zh/guide/interaction/networking.md)）
-- **编码工具**：由于 PrimJS 暂不支持 `TextEncoder`/`TextDecoder`，需使用 `TextCodecHelper` 实现 UTF-8 编解码。（参考：[Networking](https://lynxjs.org/next/zh/guide/interaction/networking.md)）
-- **全局对象限制**：无 `window`、`document`，部分浏览器 API 需通过 `lynx` 等替代（如 `lynx.reload`）。（参考：[ReactLynx](https://lynxjs.org/next/zh/react/introduction.md)）
-- **Polyfill & 语法**：主线程 PrimJS 最高支持 ES2019，后台线程 ES2015；构建阶段自动注入 polyfill（iOS 为主）。（参考：[JavaScript Runtime](https://lynxjs.org/next/zh/guide/scripting-runtime/index.md)）
+- **Fetch API**：接口契合 Web，但依赖宿主提供 HTTP Service；支持 `lynxExtension.useStreaming` 开启流式响应，自行读取 `response.body`。某些兼容性差异需查官方说明。（参考：[Networking](/zh/guide/interaction/networking.md)）
+- **编码工具**：由于 PrimJS 暂不支持 `TextEncoder`/`TextDecoder`，需使用 `TextCodecHelper` 实现 UTF-8 编解码。（参考：[Networking](/zh/guide/interaction/networking.md)）
+- **全局对象限制**：无 `window`、`document`，部分浏览器 API 需通过 `lynx` 等替代（如 `lynx.reload`）。（参考：[ReactLynx](/zh/react/introduction.md)）
+- **Polyfill & 语法**：主线程 PrimJS 最高支持 ES2019，后台线程 ES2015；构建阶段自动注入 polyfill（iOS 为主）。（参考：[JavaScript Runtime](/zh/guide/scripting-runtime/index.md)）
 
 ## 14. 性能工具与调优手段
 
-- **Main Thread Script**：确保动画/手势无延迟，注意线程隔离与数据同步。（参考：[Main Thread Script](https://lynxjs.org/next/zh/react/main-thread-script.md)）
-- **NodesRef.invoke**：批量调用原生特性（如 `autoScroll`）避免跨线程瓶颈。（参考：[Direct Manipulation](https://lynxjs.org/next/zh/guide/interaction/event-handling/manipulating-element.react.md)）
-- **Lynx DevTool & Trace**：桌面 DevTool 提供 Elements/Console/Sources/Trace 面板，可记录渲染流水、分析 ReactLynx Render Pipeline。（参考：[Lynx DevTool](https://lynxjs.org/next/zh/guide/devtool.md), [Trace](https://lynxjs.org/next/zh/guide/devtool/trace.md)）
-- **Performance Metrics**：通过 `lynx.performance`、`PerformanceObserver` 采集 FCP、InitContainer 等指标。（参考：[Performance API](https://lynxjs.org/next/zh/guide/performance/metrics/performance-api.md)）
+- **Main Thread Script**：确保动画/手势无延迟，注意线程隔离与数据同步。（参考：[Main Thread Script](/zh/react/main-thread-script.md)）
+- **NodesRef.invoke**：批量调用原生特性（如 `autoScroll`）避免跨线程瓶颈。（参考：[Direct Manipulation](/zh/guide/interaction/event-handling/manipulating-element.react.md)）
+- **Lynx DevTool & Trace**：桌面 DevTool 提供 Elements/Console/Sources/Trace 面板，可记录渲染流水、分析 ReactLynx Render Pipeline。（参考：[Lynx DevTool](/zh/guide/devtool.md), [Trace](/zh/guide/devtool/trace.md)）
+- **Performance Metrics**：通过 `lynx.performance`、`PerformanceObserver` 采集 FCP、InitContainer 等指标。（参考：[Performance API](/zh/guide/performance/metrics/performance-api.md)）
 
 ## 15. 工程实践与工具链
 
-- **项目初始化**：`pnpm create rspeedy` 一键生成 ReactLynx 工程，自动带上 Rspeedy 配置、脚手架示例。（参考：[Quick Start](https://lynxjs.org/next/zh/rspeedy/start/quick-start.md)）
-- **开发调试**：`pnpm dev` 启动 Rspeedy Dev Server，终端输出二维码，使用 LynxExample App（iOS/Android/Harmony 模拟器）扫描即可热更新预览。（参考：[Quick Start](https://lynxjs.org/next/zh/rspeedy/start/quick-start.md)）
-- **DevTool 调试**：连接设备后使用 Lynx DevTool 桌面端调试 JS、查看节点、性能记录。（参考：[Lynx DevTool](https://lynxjs.org/next/zh/guide/devtool.md)）
-- **构建产物**：Rspeedy 输出的 Bundle 包含后台线程脚本（文本）、主线程字节码、样式等资源；需要 `DEBUG=rspeedy` 环境变量以输出中间产物（组成Lynx Bundle 的后台线程脚本（文本）、主线程字节码、样式、SourceMap 等）到 `dist/.rspeedy` 目录，否则只会输出最终的 Lynx Bundle 文件。（参考：[Output Files](https://lynxjs.org/next/zh/rspeedy/output.md)）
+- **项目初始化**：`pnpm create rspeedy` 一键生成 ReactLynx 工程，自动带上 Rspeedy 配置、脚手架示例。（参考：[Quick Start](/zh/rspeedy/start/quick-start.md)）
+- **开发调试**：`pnpm dev` 启动 Rspeedy Dev Server，终端输出二维码，使用 LynxExample App（iOS/Android/Harmony 模拟器）扫描即可热更新预览。（参考：[Quick Start](/zh/rspeedy/start/quick-start.md)）
+- **DevTool 调试**：连接设备后使用 Lynx DevTool 桌面端调试 JS、查看节点、性能记录。（参考：[Lynx DevTool](/zh/guide/devtool.md)）
+- **构建产物**：Rspeedy 输出的 Bundle 包含后台线程脚本（文本）、主线程字节码、样式等资源；需要 `DEBUG=rspeedy` 环境变量以输出中间产物（组成Lynx Bundle 的后台线程脚本（文本）、主线程字节码、样式、SourceMap 等）到 `dist/.rspeedy` 目录，否则只会输出最终的 Lynx Bundle 文件。（参考：[Output Files](/zh/rspeedy/output.md)）
 
 ## 16. 与 Web 的关键差异清单
 
@@ -196,29 +196,29 @@
 
 以下是一些 Lynx 官方 Tutorial，涵盖从基础到进阶的多种使用场景，推荐跟随学习：
 
-- 产品列表——本教程将引导你逐步实现一个产品双列页面：[Tutorial Gallery](https://lynxjs.org/next/zh/guide/start/tutorial-gallery.md)，你将学到：
+- 产品列表——本教程将引导你逐步实现一个产品双列页面：[Tutorial Gallery](/zh/guide/start/tutorial-gallery.md)，你将学到：
   - 构建基本UI并添加样式、交互
   - 组件化
   - 使用 `<list />` 元件实现高性能长列表渲染
   - 直接操作节点：使用 `NodesRef.invoke` 实现自动滚动
-  - 自定义滚动条，并使用 [Main Thread Script](https://lynxjs.org/next/zh/react/main-thread-script.md) 优化滚动性能
-- 产品详情——本教程将通过实现一个轮播组件，带你学习如何编写高性能的交互代码：[Tutorial Product Detail](https://lynxjs.org/next/zh/guide/start/tutorial-product-detail.md)，你将学到：
+  - 自定义滚动条，并使用 [Main Thread Script](/zh/react/main-thread-script.md) 优化滚动性能
+- 产品详情——本教程将通过实现一个轮播组件，带你学习如何编写高性能的交互代码：[Tutorial Product Detail](/zh/guide/start/tutorial-product-detail.md)，你将学到：
   - 直接操作节点：使用 `NodesRef.setNativeProps` 更新元件的样式和属性
-  - 使用 [Main Thread Script](https://lynxjs.org/next/zh/react/main-thread-script.md) 降低延迟
+  - 使用 [Main Thread Script](/zh/react/main-thread-script.md) 降低延迟
   - 主线程函数与后台线程函数互相调用
   - 主线程脚本与后台线程脚本值的传递
 
 ## 20. 附录：部分主要内置元件
 
-- [元件 `<view>`](https://lynxjs.org/next/zh/api/elements/built-in/view.md)
-- [元件 `<text>`](https://lynxjs.org/next/zh/api/elements/built-in/text.md)
-- [元件 `<image>`](https://lynxjs.org/next/zh/api/elements/built-in/image.md)
-- [元件 `<scroll-view>`](https://lynxjs.org/next/zh/api/elements/built-in/scroll-view.md)
-- [元件 `<list>`](https://lynxjs.org/next/zh/api/elements/built-in/list.md)
-- [元件 `<page>`](https://lynxjs.org/next/zh/api/elements/built-in/page.md)
-- [元件 `<frame>`](https://lynxjs.org/next/zh/api/elements/built-in/frame.md)
-- [元件 `<input>`](https://lynxjs.org/next/zh/api/elements/built-in/input.md)
-- [元件 `<textarea>`](https://lynxjs.org/next/zh/api/elements/built-in/textarea.md)
+- [元件 `<view>`](/zh/api/elements/built-in/view.md)
+- [元件 `<text>`](/zh/api/elements/built-in/text.md)
+- [元件 `<image>`](/zh/api/elements/built-in/image.md)
+- [元件 `<scroll-view>`](/zh/api/elements/built-in/scroll-view.md)
+- [元件 `<list>`](/zh/api/elements/built-in/list.md)
+- [元件 `<page>`](/zh/api/elements/built-in/page.md)
+- [元件 `<frame>`](/zh/api/elements/built-in/frame.md)
+- [元件 `<input>`](/zh/api/elements/built-in/input.md)
+- [元件 `<textarea>`](/zh/api/elements/built-in/textarea.md)
 
 ---
 
diff --git a/plugins/llms-postprocess/scripts/main.ts b/plugins/llms-postprocess/scripts/main.ts
index 90260050..efad6e9a 100644
--- a/plugins/llms-postprocess/scripts/main.ts
+++ b/plugins/llms-postprocess/scripts/main.ts
@@ -20,7 +20,12 @@ async function main() {
       path.join(root, 'llms.txt.bak'),
     );
 
-    const result = postprocessLLMs(llmsTxt, agentsMD);
+    const result = postprocessLLMs(
+      'https://lynxjs.org',
+      '/3.5',
+      llmsTxt,
+      agentsMD,
+    );
 
     for (const [filePath, content] of Object.entries(result)) {
       const pp = path.join(root, filePath);
diff --git a/plugins/llms-postprocess/src/index.ts b/plugins/llms-postprocess/src/index.ts
index 7d1f04bb..5c152c56 100644
--- a/plugins/llms-postprocess/src/index.ts
+++ b/plugins/llms-postprocess/src/index.ts
@@ -27,7 +27,12 @@ function pluginLLMsPostprocess(): RspressPlugin {
           const llmsTxt = await fs.readFile(llmsTxtPath, 'utf-8');
           const agentsMD = await fs.readFile(agentsMDPath, 'utf-8');
 
-          const result = postprocessLLMs(llmsTxt, agentsMD);
+          const result = postprocessLLMs(
+            'https://lynxjs.org',
+            config.base ?? '',
+            llmsTxt,
+            agentsMD,
+          );
 
           for (const [filePath, content] of Object.entries(result)) {
             const pp = path.join(root, filePath);
diff --git a/plugins/llms-postprocess/src/postprocess.ts b/plugins/llms-postprocess/src/postprocess.ts
index 1ef57cc9..b864731a 100644
--- a/plugins/llms-postprocess/src/postprocess.ts
+++ b/plugins/llms-postprocess/src/postprocess.ts
@@ -1,5 +1,6 @@
 import { fromMarkdown } from 'mdast-util-from-markdown';
 import { toMarkdown } from 'mdast-util-to-markdown';
+import type { Options } from 'mdast-util-to-markdown';
 import type {
   Parent,
   Node,
@@ -9,6 +10,12 @@ import type {
   RootContentMap,
 } from 'mdast';
 
+const COMMON_TO_MARKDOWN_OPTIONS = {
+  bulletOther: '-',
+  ruleRepetition: 3,
+  rule: '-',
+} satisfies Options;
+
 interface H2Segment {
   title: string;
   heading: Heading;
@@ -38,10 +45,13 @@ function segmentByH2(root: Parent): Array<H2Segment> {
 
   return segments.map((segment) => {
     const [heading, ...rest] = segment as [Heading, ...RootContent[]];
-    const title = toMarkdown({
-      type: 'root',
-      children: heading.children,
-    }).trim();
+    const title = toMarkdown(
+      {
+        type: 'root',
+        children: heading.children,
+      },
+      COMMON_TO_MARKDOWN_OPTIONS,
+    ).trim();
 
     return {
       title,
@@ -66,10 +76,32 @@ function forEachType<T extends keyof RootContentMap>(
   }
 }
 
+/**
+ * Postprocess llms.txt
+ * @param prefix The prefix for the links, like: https://lynxjs.org
+ * @param base The base URL for the links, like: /next, /3.5
+ * @param markdown The markdown content to process
+ * @param agentsMD The agents markdown content
+ * @returns A record mapping paths to their processed content
+ */
 function postprocessLLMs(
+  prefix: string,
+  base: string,
   markdown: string,
   agentsMD: string,
 ): Record<string, string> {
+  // remove trailing slash if any
+  prefix = prefix.replace(/\/$/, '');
+  if (base === '/') {
+    base = '';
+  }
+  if (base !== '') {
+    // remove trailing slash if any
+    base = base.replace(/\/$/, '');
+    // add leading slash if missing
+    base = base.startsWith('/') ? base : `/${base}`;
+  }
+
   const root = fromMarkdown(markdown);
 
   let segments = segmentByH2(root);
@@ -79,7 +111,7 @@ function postprocessLLMs(
   segments = segments.filter((segment) => {
     const { title } = segment;
     if (title === 'API' || title === 'APIs') {
-      llmsTxtByPath['/api/llms.txt'] = toMarkdown({
+      const root = {
         type: 'root',
         children: [
           ...fromMarkdown(`\
@@ -90,17 +122,28 @@ Below is a full list of available APIs of Lynx:
           segment.heading,
           ...segment.content,
         ],
+      } satisfies Root;
+
+      // to abs path
+      forEachType('link', root, (link) => {
+        link.url = `${prefix}${link.url}`;
       });
 
+      llmsTxtByPath['/api/llms.txt'] = toMarkdown(
+        root,
+        COMMON_TO_MARKDOWN_OPTIONS,
+      );
+
       return false;
     }
 
     return true;
   });
 
-  const allLynxJsLinks: Set<string> = new Set();
+  const linksRefedInAgentsMD: Set<string> = new Set();
+
   forEachType('link', fromMarkdown(agentsMD), (link) => {
-    allLynxJsLinks.add(link.url);
+    linksRefedInAgentsMD.add(link.url);
   });
 
   const appendixSectionAst = {
@@ -116,27 +159,37 @@ Below is a full list of available APIs of Lynx:
 
   // filter unwanted links
   forEachType('link', appendixSectionAst, (link, parent) => {
-    link.url = `https://lynxjs.org${link.url}`;
+    // Normalize: “/3.4/x/y.md” -> “/x/y.md”
+    const url = link.url.replace(/^\/(?:next|\d+(?:\.\d+)*)?/, '');
     if (
       parent &&
-      (allLynxJsLinks.has(link.url) ||
+      (linksRefedInAgentsMD.has(url) ||
         // This is a trade-off:
-        // We are hiding `/guide/devtool/*` and `/guide/performance/*` from AI to avoid noise
+        // We are hiding `/guide/devtool/*` and `/guide/performance/*` from LLM to avoid noise
         link.url.match(/\/guide\/devtool/) ||
-        link.url.match(/\/guide\/performance/))
+        link.url.match(/\/guide\/performance/) ||
+        link.url.match(/\/guide\/embed/))
     ) {
       parent.children = parent.children.filter((child) => child !== link);
     }
   });
 
+  // add prefix (e.g. https://lynxjs.org)
+  forEachType('link', appendixSectionAst, (link) => {
+    link.url = `${prefix}${link.url}`;
+  });
+
   // filter "empty" list item
   forEachType('listItem', appendixSectionAst, (listItem, parent) => {
     if (parent) {
       // Modify the list item as needed
-      const listItemMD = toMarkdown({
-        type: 'root',
-        children: listItem.children,
-      });
+      const listItemMD = toMarkdown(
+        {
+          type: 'root',
+          children: listItem.children,
+        },
+        COMMON_TO_MARKDOWN_OPTIONS,
+      );
 
       if (listItemMD.trim() === '') {
         parent.children = parent.children.filter((child) => child !== listItem);
@@ -151,14 +204,24 @@ Below is a full list of available APIs of Lynx:
 
 You may find more information about Lynx and related resources in the links below:
 
-${toMarkdown(appendixSectionAst)}
+${toMarkdown(appendixSectionAst, COMMON_TO_MARKDOWN_OPTIONS)}
 
 ## 99. Appendix: Lynx APIs
 
-If you need the full list of all APIs of Lynx, please refer to the [Lynx APIs](https://lynxjs.org/next/api/llms.txt).
+If you need the full list of all APIs of Lynx, please refer to the [Lynx APIs](${prefix}${base}/api/llms.txt).
 `;
 
-  llmsTxtByPath['/llms.txt'] = agentsMD + appendixSection;
+  const agentsMDAst = fromMarkdown(agentsMD);
+
+  // to abs path
+  forEachType('link', agentsMDAst, (link) => {
+    // e.g. https://lynxjs.org/next/x/y.md
+    // NOTE: Links from AGENTS.md are always missing version segment
+    link.url = `${prefix}${base}${link.url}`;
+  });
+
+  llmsTxtByPath['/llms.txt'] =
+    toMarkdown(agentsMDAst, COMMON_TO_MARKDOWN_OPTIONS) + appendixSection;
 
   return llmsTxtByPath;
 }