docs(clean): clarify clean wipes entire output dirs, not only generated files (#3657)

Clarifies that output.clean removes all files in the target and schemas
directories, not just files produced by orval. Adds a warning against
pointing target/schemas at package or library entrypoint roots that hold
sentinel files (package.json, ng-package.json, public-api.ts), and a
keep-file example (clean: ['!**/swagger.json']) for preserving specific
files in-place. Brings the Chinese (zh) docs for clean to parity.

Refs #3538

Author: aqeelat

docs/content/docs/reference/cli.mdx

@@ -59,7 +59,7 @@ orval --watch ./src
 
 ### --clean
 
-Clean generated files:
+Clean the output directories before regenerating:
 
 ```bash
 orval --clean

docs/content/docs/reference/configuration/output.mdx

@@ -782,9 +782,9 @@ export default defineConfig({
 **Type:** `Boolean | String[]`
 **Default:** `false`
 
-Clean generated files before regenerating. Removes every file in the `target` and `schemas` directories (`.d.ts` files are preserved).
+Wipe the `target` and `schemas` directories before regenerating. Every file in those folders is removed (`.d.ts` files are preserved) — not only files produced by Orval, but also any other file that happens to live there.
 
-When set to a `String[]`, the array entries are extra glob patterns appended to the deletion list, applied to both the `target` and `schemas` directories. Use negated globs (prefixed with `!`) to preserve files from removal, or positive globs to also remove files that would otherwise be kept.
+When set to a `String[]`, the array entries are extra glob patterns appended to the deletion list, applied to both the `target` and `schemas` directories. Use negated globs (prefixed with `!`) to preserve specific files from removal, or positive globs to also remove files that would otherwise be kept.
 
 ```ts title="orval.config.ts"
 export default defineConfig({
@@ -797,7 +797,24 @@ export default defineConfig({
 });
 ```
 
-Keep hand-written files (mutators, transformers, app code) outside the `target` and `schemas` directories — use a dedicated subfolder such as `./gen/` for output so `clean` does not remove them.
+For example, to keep a committed `swagger.json` next to the generated output:
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      target: './src/generated',
+      clean: ['!**/swagger.json'],
+    },
+  },
+});
+```
+
+<Callout type="warn">
+`clean` removes the entire contents of the configured folders, not just generated files. Do not point `target` or `schemas` directly at a package or library entrypoint root that holds files you need to keep (`package.json`, `ng-package.json`, `public-api.ts`, etc.). Place generated output in a dedicated subdirectory such as `./generated/` so those files are never touched.
+</Callout>
+
+Keep hand-written files (mutators, transformers, app code) outside the `target` and `schemas` directories for the same reason.
 
 ## formatter
 

docs/content/docs/zh/reference/cli.mdx

@@ -35,7 +35,7 @@ orval --input ./openapi.yaml --output ./src/api.ts
 
 ### --clean
 
-生成前清理输出目录或目标文件。谨慎使用，避免把非生成文件放进输出目录。
+生成前清空输出目录（`target` 和 `schemas`）——会删除其中的所有文件，而不只是生成文件。
 
 ### --formatter
 

docs/content/docs/zh/reference/configuration/output.mdx

@@ -161,7 +161,42 @@ export default defineConfig({
 
 ## clean
 
-生成前清理输出。不要把手写代码放进被清理的生成目录。
+**类型：** `Boolean | String[]`
+**默认：** `false`
+
+在重新生成前清空 `target` 和 `schemas` 目录。这两个目录中的**所有**文件都会被删除（`.d.ts` 文件会被保留）——不仅仅是 Orval 生成的文件，还包括其中存放的任何其他文件。
+
+设为 `String[]` 时，数组项是追加到删除列表的额外 glob 模式，同时作用于 `target` 和 `schemas` 目录。用取反 glob（以 `!` 开头）来保留特定文件不被删除，或用正向 glob 来额外删除本会被保留的文件。
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      // 保留 `important.ts`，并额外删除 `.d.ts` 文件
+      clean: ['!**/important.ts', '**/*.d.ts'],
+    },
+  },
+});
+```
+
+例如，要在生成产物旁保留已提交的 `swagger.json`：
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      target: './src/generated',
+      clean: ['!**/swagger.json'],
+    },
+  },
+});
+```
+
+<Callout type="warn">
+`clean` 会删除所配置目录中的全部内容，而不只是生成文件。不要把 `target` 或 `schemas` 直接指向包含你需要保留文件的包或库入口根目录（如 `package.json`、`ng-package.json`、`public-api.ts` 等）。请把生成产物放在专用子目录（例如 `./generated/`）中，以免这些文件被误删。
+</Callout>
+
+出于同样的原因，请将手写文件（mutator、transformer、应用代码）放在 `target` 和 `schemas` 目录之外。
 
 ## formatter