docs: polish website documentation

Author: chenjiahan

website/README.md

@@ -2,25 +2,26 @@
 
 This website is built with [Rspress](https://rspress.rs/) through Rstack CLI.
 
-Documentation can be written with Markdown or MDX.
+The documentation source lives in `docs` and is written in Markdown or MDX.
 
 ## Development
 
-Run the development server from the repository root:
+Start the development server from the repository root:
 
 ```bash
 pnpm doc
 ```
 
-Build or preview the website from this directory:
+Alternatively, run the website scripts from this directory:
 
 ```bash
+pnpm dev
 pnpm build
 pnpm preview
 ```
 
 ## Contributing
 
-The website provides English and Chinese documentation. Keep both versions in
-sync when possible. Placeholder pages marked with `TODO` are ready for future
-documentation.
+Keep corresponding English and Chinese pages aligned in structure, meaning,
+links, and examples. When a translated heading would generate a different
+anchor, add an explicit anchor that matches the English heading.

website/docs/en/guide/api-reference.mdx

@@ -1,6 +1,6 @@
 # API reference
 
-Rstack provides a unified configuration API and re-exports the public APIs of Rsbuild, Rslib, Rstest, and Rslint through dedicated subpaths. Prefer these subpaths to direct imports from each tool's core package so that dependency entry points and tool versions remain aligned with Rstack.
+Rstack exposes a unified configuration API and dedicated entry points for the public APIs of Rsbuild, Rslib, Rstest, and Rslint. Prefer these entry points over direct imports from each tool's core package so that import paths and tool versions stay aligned with Rstack.
 
 ## Import paths
 
@@ -19,11 +19,11 @@ Rstack provides a unified configuration API and re-exports the public APIs of Rs
 
 ### `define`
 
-Import `define` from `rstack` to register tool configurations in `rstack.config.ts`; see [Configuration APIs](./configuration#configuration-apis) for details.
+Import `define` from `rstack` to register tool configurations in `rstack.config.ts`. For details, see [Configuration APIs](./configuration#configuration-apis).
 
 ## Re-exports
 
-The tool-specific subpaths below re-export the public APIs from their corresponding core packages. Using these Rstack entry points keeps dependency entry points and tool versions aligned with the toolchain integrated by Rstack.
+Each tool-specific subpath re-exports the public APIs of its corresponding core package.
 
 ### `rstack/app`
 
@@ -53,7 +53,7 @@ For details, see the [Rslib core APIs](https://rslib.rs/api/javascript-api/core)
 import { describe, expect, test } from 'rstack/test';
 ```
 
-See the [Rstest runtime API](https://rstest.rs/api/runtime-api/) for test APIs and the [Rstest core APIs](https://rstest.rs/api/javascript-api/rstest-core) for configuration helpers.
+For test APIs, see the [Rstest runtime API](https://rstest.rs/api/runtime-api/). For configuration helpers, see the [Rstest core APIs](https://rstest.rs/api/javascript-api/rstest-core).
 
 > For more guidance on testing, see [Testing](./testing).
 
@@ -69,7 +69,7 @@ For details about the available presets and plugins, see [Rslint rules and prese
 
 ## TypeScript types
 
-These type-only entry points add ambient declarations to a TypeScript project. Add only the entries your project needs to [`compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) in `tsconfig.json`.
+The following type-only entry points add ambient declarations to a TypeScript project. Add only the entries your project needs to [`compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) in `tsconfig.json`.
 
 ### `rstack/types`
 
@@ -85,7 +85,7 @@ These type-only entry points add ambient declarations to a TypeScript project. A
 
 ### `rstack/test/globals`
 
-`rstack/test/globals` declares Rstest APIs such as `test`, `expect`, and lifecycle hooks as globals. Add it when tests use these APIs without explicit imports.
+`rstack/test/globals` declares Rstest APIs such as `test`, `expect`, and lifecycle hooks as globals. Add it when Rstest's [`globals`](https://rstest.rs/config/test/globals) option is enabled and tests use these APIs without explicit imports.
 
 ```json title="tsconfig.json"
 {
@@ -97,7 +97,7 @@ These type-only entry points add ambient declarations to a TypeScript project. A
 
 ### `rstack/test/importMeta`
 
-`rstack/test/importMeta` augments `ImportMeta` with the optional `rstest` property, enabling `import.meta.rstest` in in-source tests.
+`rstack/test/importMeta` augments `ImportMeta` with the optional `rstest` property, providing type support for `import.meta.rstest` in in-source tests.
 
 ```json title="tsconfig.json"
 {

website/docs/en/guide/cli/build.mdx

@@ -20,7 +20,7 @@ Examples:
 # Write output files to the output directory
 rs build --dist-path output
 
-# Generate source maps for the output files
+# Generate source maps for output files
 rs build --source-map
 
 # Rebuild when files change
@@ -29,7 +29,7 @@ rs build --watch
 
 ## Configuration
 
-Configure the production build through [`define.app()`](../configuration#define-app) in the [Rstack configuration file](/guide/configuration#configuration-file). It accepts the standard [Rsbuild configuration](https://rsbuild.rs/config/):
+Configure production builds with [`define.app()`](../configuration#define-app) in `rstack.config.ts`. The API accepts the standard [Rsbuild configuration](https://rsbuild.rs/config/):
 
 ```ts title="rstack.config.ts"
 import { define } from 'rstack';

website/docs/en/guide/cli/dev.mdx

@@ -20,7 +20,7 @@ Examples:
 # Start the server and open the page in the browser
 rs dev --open
 
-# Use port 8080 and fail if it is already in use
+# Use port 8080 and exit if it is already in use
 rs dev --port 8080 --strict-port
 
 # Make the server available on the local network
@@ -29,7 +29,7 @@ rs dev --host
 
 ## Configuration
 
-Configure the development server through [`define.app()`](../configuration#define-app) in the [Rstack configuration file](/guide/configuration#configuration-file). It accepts the standard [Rsbuild configuration](https://rsbuild.rs/config/):
+Configure the development server with [`define.app()`](../configuration#define-app) in `rstack.config.ts`. The API accepts the standard [Rsbuild configuration](https://rsbuild.rs/config/):
 
 ```ts title="rstack.config.ts"
 import { define } from 'rstack';

website/docs/en/guide/cli/doc.mdx

@@ -2,9 +2,9 @@
 
 import { PackageManagerTabs } from '@rspress/core/theme';
 
-The `rs doc` command uses [Rspress](https://rspress.rs/guide/start/introduction) to develop, build, and preview a documentation site.
+The `rs doc` command uses [Rspress](https://rspress.rs/guide/start/introduction) to develop, build, and locally preview a documentation site.
 
-Install [`@rspress/core`](https://www.npmjs.com/package/@rspress/core) before using the command:
+[`@rspress/core`](https://www.npmjs.com/package/@rspress/core) is an optional dependency. Install it before using `rs doc`:
 
 <PackageManagerTabs command="install -D @rspress/core" />
 
@@ -54,15 +54,15 @@ rs doc preview
 
 ### eject
 
-[`rs doc eject`](https://rspress.rs/api/commands#rspress-eject) copies a built-in Rspress theme component into the project for customization. Run it without a component name to list all ejectable components.
+[`rs doc eject`](https://rspress.rs/api/commands#rspress-eject) copies a built-in Rspress theme component into the project for customization. Run it without a component name to list the available components.
 
 ```bash
 rs doc eject
 ```
 
 ## Configuration
 
-Configure the documentation site through [`define.doc()`](../configuration#define-doc) in the [Rstack configuration file](/guide/configuration#configuration-file). It accepts the standard [Rspress configuration](https://rspress.rs/api/config/config-basic):
+Configure the documentation site with [`define.doc()`](../configuration#define-doc) in `rstack.config.ts`. The API accepts the standard [Rspress configuration](https://rspress.rs/api/config/config-basic):
 
 ```ts title="rstack.config.ts"
 import { define } from 'rstack';

website/docs/en/guide/cli/lib.mdx

@@ -44,7 +44,7 @@ rs lib mf-dev
 
 ## Configuration
 
-Configure library builds through [`define.lib()`](../configuration#define-lib) in the [Rstack configuration file](/guide/configuration#configuration-file). It accepts the standard [Rslib configuration](https://rslib.rs/config/):
+Configure library builds with [`define.lib()`](../configuration#define-lib) in `rstack.config.ts`. The API accepts the standard [Rslib configuration](https://rslib.rs/config/):
 
 ```ts title="rstack.config.ts"
 import { define } from 'rstack';

website/docs/en/guide/cli/lint.mdx

@@ -1,6 +1,6 @@
 # lint
 
-The `rs lint` command uses [Rslint](https://rslint.rs/guide/) to lint source code.
+The `rs lint` command uses [Rslint](https://rslint.rs/guide/) to lint source files.
 
 ## Usage
 
@@ -29,7 +29,7 @@ rs lint --type-check
 
 ## Configuration
 
-Configure linting through [`define.lint()`](../configuration#define-lint) in the [Rstack configuration file](/guide/configuration#configuration-file). It accepts the standard [Rslint configuration](https://rslint.rs/config/). Presets and plugins can be imported from `rstack/lint` on demand:
+Configure linting with [`define.lint()`](../configuration#define-lint) in `rstack.config.ts`. The API accepts the standard [Rslint configuration](https://rslint.rs/config/). Presets and plugins can be imported from `rstack/lint` on demand:
 
 ```ts title="rstack.config.ts"
 import { define } from 'rstack';

website/docs/en/guide/cli/preview.mdx

@@ -1,14 +1,14 @@
 # preview
 
-The `rs preview` command uses [Rsbuild](https://rsbuild.rs/guide/basic/cli#rsbuild-preview) to preview an application's production build locally.
+The `rs preview` command uses [Rsbuild](https://rsbuild.rs/guide/basic/cli#rsbuild-preview) to preview an application's production output locally.
 
 ## Usage
 
 ```bash
 rs preview [options]
 ```
 
-The command loads the application configuration registered with [`define.app()`](../configuration#define-app). Run [`rs build`](./build) before starting the preview server to generate the production output:
+The command loads the application configuration registered with [`define.app()`](../configuration#define-app). Before starting the preview server, run [`rs build`](./build) to generate the production output:
 
 ```bash
 rs build
@@ -27,7 +27,7 @@ Examples:
 # Start the preview server and open the page in the browser
 rs preview --open
 
-# Use port 8080 and fail if it is already in use
+# Use port 8080 and exit if it is already in use
 rs preview --port 8080 --strict-port
 
 # Make the preview server available on the local network
@@ -36,7 +36,7 @@ rs preview --host
 
 ## Configuration
 
-Configure the preview server through [`define.app()`](../configuration#define-app) in the [Rstack configuration file](/guide/configuration#configuration-file). It accepts the standard [Rsbuild configuration](https://rsbuild.rs/config/):
+Configure the preview server with [`define.app()`](../configuration#define-app) in `rstack.config.ts`. The API accepts the standard [Rsbuild configuration](https://rsbuild.rs/config/):
 
 ```ts title="rstack.config.ts"
 import { define } from 'rstack';

website/docs/en/guide/cli/staged.mdx

@@ -1,8 +1,8 @@
 # staged
 
-The `rs staged` command uses [lint-staged](https://github.com/lint-staged/lint-staged) to run tasks against files staged in Git.
+The `rs staged` command uses [lint-staged](https://github.com/lint-staged/lint-staged) to run tasks against files staged for commit.
 
-A common use case is to run linters, formatters, or other checks on staged files before committing code.
+It is typically used in a Git hook to lint, format, or otherwise check files before a commit.
 
 ## Usage
 
@@ -16,7 +16,7 @@ The command loads the staged-file tasks registered with [`define.staged()`](../c
 
 ### `--allow-empty`
 
-`--allow-empty` allows an empty commit when tasks revert all staged changes.
+`--allow-empty` allows the commit to proceed if tasks revert all staged changes.
 
 ```bash
 rs staged --allow-empty
@@ -48,7 +48,7 @@ rs staged --debug
 
 ### `--no-stash`
 
-`--no-stash` disables the backup stash and keeps changes made by tasks when an error occurs.
+`--no-stash` disables the backup stash and automatic reversion when a task fails.
 
 ```bash
 rs staged --no-stash
@@ -88,7 +88,7 @@ rs staged --help
 
 ## Configuration
 
-Configure staged-file tasks through [`define.staged()`](../configuration#define-staged) in the [Rstack configuration file](/guide/configuration#configuration-file). It accepts the standard [lint-staged configuration](https://github.com/lint-staged/lint-staged#configuration):
+Configure staged-file tasks with [`define.staged()`](../configuration#define-staged) in `rstack.config.ts`. The API accepts the standard [lint-staged configuration](https://github.com/lint-staged/lint-staged#configuration):
 
 ```ts title="rstack.config.ts"
 import { define } from 'rstack';

website/docs/en/guide/cli/test.mdx

@@ -2,7 +2,7 @@
 
 The `rs test` command uses [Rstest](https://rstest.rs/guide/basic/cli) to run tests.
 
-For more guidance on testing, see [Testing](../testing).
+> For more guidance on testing, see [Testing](../testing).
 
 ## Usage
 
@@ -65,15 +65,15 @@ rs test merge-reports
 
 ### init
 
-[`rs test init`](https://rstest.rs/guide/basic/cli#rstest-init) creates starter files for a supported Rstest project type.
+[`rs test init`](https://rstest.rs/guide/basic/cli#rstest-init) initializes an Rstest configuration for a supported project type.
 
 ```bash
 rs test init browser
 ```
 
 ## Configuration
 
-Configure tests through [`define.test()`](../configuration#define-test) in the [Rstack configuration file](/guide/configuration#configuration-file). It accepts the standard [Rstest configuration](https://rstest.rs/config/):
+Configure tests with [`define.test()`](../configuration#define-test) in `rstack.config.ts`. The API accepts the standard [Rstest configuration](https://rstest.rs/config/):
 
 ```ts title="rstack.config.ts"
 import { define } from 'rstack';