@bleedingdev/modern-js-create 3.2.0-ultramodern.5 → 3.2.0-ultramodern.7

package/template-workspace/.agents/skills/rsdoctor-analysis/references/install-rsdoctor-common.md

@@ -0,0 +1,88 @@
+# Common Steps for Rsdoctor Installation
+
+This document contains common steps that apply to both Rspack and Webpack projects.
+
+## Step 3: Locate the rsdoctor-data.json
+
+First, use the fast path to check whether `rsdoctor-data.json` already exists. If the user provided a path, check that path first. Otherwise check common build artifact/output locations before any package-manager, install, config, or build command:
+
+- `dist/rsdoctor-data.json` (most common)
+- `output/rsdoctor-data.json`
+- `static/rsdoctor-data.json`
+- `.rsdoctor/rsdoctor-data.json` (if using custom reportDir)
+
+If common paths do not contain the file, run one bounded local file search that excludes expensive directories, for example `rg --files -g 'rsdoctor-data.json' -g '!node_modules' -g '!**/.git/**'`. If `rsdoctor-data.json` is found, skip the generation/version gate and go directly to JSON analysis. If it is not found, do not run any `rsdoctor-agent` analysis command; ask for the data path or generate the file first.
+
+For repeated analysis in the same repository, use a lightweight project-local cache such as `.rsdoctor-analysis-cache.json`. Reuse it only when the cached data-file path still exists and cached modification times match the current `rsdoctor-data.json`, dependency files (`package.json`, lock files), relevant build config files, and plugin `package.json` if recorded. Refresh the cache after locating a new data file or confirming a plugin version.
+
+When the runtime supports parallel execution, run independent local initialization checks concurrently: common path checks, bounded `rg --files` lookup, and local plugin-version file reads. Do not run `rsdoctor-agent` CLI checks until a real `rsdoctor-data.json` path exists. Treat plugin-version results as speculative until the data file is confirmed missing; never let parallel plugin checks trigger generation by themselves.
+
+If you cannot find the file, ask the user to provide the path to `rsdoctor-data.json`. If the file truly does not exist and generation/setup is required, check the installed `@rsdoctor/rspack-plugin` or `@rsdoctor/webpack-plugin` version before changing config or running a build. The `@rsdoctor/agent-cli` version does not prove plugin support for `RSDOCTOR_OUTPUT=json`.
+
+Required version gate (use exactly this if/else order):
+
+1. Identify `pluginName`: `@rsdoctor/rspack-plugin` or `@rsdoctor/webpack-plugin`.
+2. Determine `pluginVersion` from local files first: dependency declarations in `package.json`, lockfile entries, then installed `node_modules/<plugin>/package.json`. Use package-manager output such as `pnpm why @rsdoctor/rspack-plugin` / `npm ls @rsdoctor/rspack-plugin` only as a fallback.
+3. Choose one branch; do not merge branches:
+
+```text
+if pluginName is missing:
+  install/register the matching Rsdoctor plugin, then MUST configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+else if pluginVersion is unknown:
+  resolve pluginVersion first; if still unknown, MUST configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+else if pluginVersion >= 1.5.11:
+  do not modify plugin config just for JSON; build with RSDOCTOR_OUTPUT=json and RSDOCTOR=true if needed
+else: # pluginVersion < 1.5.11
+  MUST configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+```
+
+Preflight every build command: `RSDOCTOR_OUTPUT=json` is allowed only in the `pluginVersion >= 1.5.11` branch. For missing, unknown, or `< 1.5.11` versions, a command such as `RSDOCTOR_OUTPUT=json RSDOCTOR=true pnpm run build:rspack` is incorrect.
+
+The file is typically generated in the same directory as your build output (e.g., `dist`, `output`, `static`). For plugin versions < `1.5.11`, configure a custom output directory using the `output.reportDir` option:
+
+```js
+// Example for Rspack: use RsdoctorRspackPlugin
+// Example for Webpack: use RsdoctorWebpackPlugin
+new RsdoctorRspackPlugin({
+  // or RsdoctorWebpackPlugin
+  disableClientServer: true,
+  output: {
+    mode: 'brief',
+    options: {
+      type: ['json'],
+    },
+    reportDir: './dist', // Custom output directory (defaults to build output directory)
+  },
+});
+```
+
+---
+
+## Step 4: Use JSON file for analysis
+
+Once you have the `rsdoctor-data.json` file, you can use it for analysis. This JSON file contains all the build analysis data and can be used without starting the Rsdoctor server.
+
+Analyze the JSON file with the `rsdoctor-agent` CLI from the repository root or another directory that can access the JSON file:
+
+```bash
+rsdoctor-agent build summary --data-file ./dist/rsdoctor-data.json --filter "<fields>"
+```
+
+Keep analysis output small:
+
+- Reuse already returned results from context/history first, then run only missing queries.
+- Use `--filter` on data-fetch commands to return only fields required for the current question.
+- Use first-pass summaries for duplicate packages and tree-shaking issues; ask before continuing reference-chain tracing.
+- Stop broad commands when one response exceeds `5k` tokens (o200k_base) or `500 KB` raw output, then switch to filtered or targeted queries.
+
+For command names, option scopes, tree-shaking command selection, and `--filter` guidance, use [command-map.md](command-map.md). For raw data field names, use [rsdoctor-data-types.md](rsdoctor-data-types.md).
+
+**Benefits of JSON Mode:**
+
+- ✅ No need to keep the build process running
+- ✅ Works in CI/CD environments
+- ✅ Can be shared and version controlled
+- ✅ Faster analysis for large projects
+- ✅ No server connection required
+
+Note: `rsdoctor-data.json` can be large in complex projects. Add it to `.gitignore` if you do not want to commit it.

package/template-workspace/.agents/skills/rsdoctor-analysis/references/install-rsdoctor-rspack.md

@@ -0,0 +1,138 @@
+# Install Rsdoctor Plugin for Rspack Projects
+
+This guide covers installation for Rspack-based projects, including:
+
+- Rspack CLI
+- Rsbuild
+- Modern.js
+- Rslib
+- Rspress
+
+## Step 1: Install Dependencies
+
+For projects based on Rspack, such as Rsbuild or Rslib:
+
+**Note:** Prefer using the latest versions of the above dependencies when available.
+
+```bash
+npm add @rsdoctor/rspack-plugin -D
+pnpm add @rsdoctor/rspack-plugin -D
+```
+
+## Step 2: Register Plugin
+
+After the dependency installation, check the installed `@rsdoctor/rspack-plugin` version before changing config or running a build. Do not infer plugin capabilities from `@rsdoctor/agent-cli --version`.
+
+Required version gate (use exactly this if/else order):
+
+1. Set `pluginName = '@rsdoctor/rspack-plugin'`.
+2. Determine `pluginVersion` from local files first: dependency declarations in `package.json`, lockfile entries, then `node_modules/@rsdoctor/rspack-plugin/package.json` if installed. Use `pnpm why @rsdoctor/rspack-plugin` / `npm ls @rsdoctor/rspack-plugin` only as a fallback. When repeating analysis, reuse a valid `.rsdoctor-analysis-cache.json` plugin entry before re-reading files; invalidate it if `package.json`, lock files, or the plugin package file modification time changed.
+3. Choose one branch; do not merge branches:
+
+```text
+if @rsdoctor/rspack-plugin is missing:
+  install/register @rsdoctor/rspack-plugin, then configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+else if pluginVersion is unknown:
+  resolve pluginVersion first; if still unknown, configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+else if pluginVersion >= 1.5.11:
+  do not modify plugin config just for JSON; build with RSDOCTOR_OUTPUT=json and RSDOCTOR=true if needed
+else: # pluginVersion < 1.5.11
+  MUST configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+```
+
+Preflight every build command: `RSDOCTOR_OUTPUT=json` is allowed only in the `pluginVersion >= 1.5.11` branch. For missing, unknown, or `< 1.5.11`, `RSDOCTOR_OUTPUT=json` is forbidden. For example, when `@rsdoctor/rspack-plugin` is `1.5.7`, this command is incorrect:
+
+```bash
+RSDOCTOR_OUTPUT=json RSDOCTOR=true pnpm run build:rspack
+```
+
+Below are configuration examples for old Rspack plugin versions, unknown versions, missing plugins, or projects that still need to register the plugin:
+
+### Rspack CLI
+
+Initialize the plugin in the [plugins](https://www.rspack.rs/config/plugins.html#plugins) of `rspack.config.ts`:
+
+```ts title="rspack.config.ts"
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  plugins: [
+    // Only register the plugin when RSDOCTOR is true, as the plugin will increase the build time.
+    process.env.RSDOCTOR &&
+      new RsdoctorRspackPlugin({
+        disableClientServer: true,
+        // Required for @rsdoctor/rspack-plugin < 1.5.11.
+        output: {
+          mode: 'brief',
+          options: {
+            type: ['json'],
+          },
+        },
+      }),
+  ],
+};
+```
+
+### Rsbuild/Rslib/Modern.js
+
+See [Rsbuild - Use Rsdoctor](https://rsbuild.rs/guide/debug/rsdoctor) for more details.
+If this is Modern.js project can see [tools.rspack](https://modernjs.dev/configure/app/tools/rspack) of `modern.config.ts`:
+
+For `@rsdoctor/rspack-plugin` < `1.5.11`, configure JSON output in `rsbuild.config.ts`:
+
+```ts title="rsbuild.config.ts"
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  tools: {
+    rspack: {
+      plugins: [
+        process.env.RSDOCTOR === 'true' &&
+          new RsdoctorRspackPlugin({
+            disableClientServer: true, // Prevent starting local server
+            output: {
+              mode: 'brief', // Required for plugin versions < 1.5.11
+              options: {
+                type: ['json'], // Only generate JSON data
+              },
+            },
+          }),
+      ],
+    },
+  },
+};
+```
+
+### Rspress
+
+For Rspress projects, configure the plugin in `builderConfig.tools.rspack`:
+
+```ts title="rspress.config.ts"
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+import { defineConfig } from 'rspress/config';
+
+export default defineConfig({
+  builderConfig: {
+    tools: {
+      rspack: {
+        plugins: [
+          process.env.RSDOCTOR === 'true' &&
+            new RsdoctorRspackPlugin({
+              disableClientServer: true, // Prevent starting local server
+              output: {
+                mode: 'brief', // Required for plugin versions < 1.5.11
+                options: {
+                  type: ['json'], // Only generate JSON data
+                },
+              },
+            }),
+        ],
+      },
+    },
+  },
+});
+```
+
+## Step 3 & 4: Locate and Use rsdoctor-data.json
+
+For steps on locating the `rsdoctor-data.json` file and using it for analysis, see the [common installation guide](./install-rsdoctor-common.md).

package/template-workspace/.agents/skills/rsdoctor-analysis/references/install-rsdoctor-webpack.md

@@ -0,0 +1,71 @@
+# Install Rsdoctor Plugin for Webpack Projects
+
+This guide covers installation for Webpack projects (webpack >= 5).
+
+## Step 1: Install Dependencies
+
+Rsdoctor only supports webpack >= 5.
+
+For projects based on webpack:
+
+```bash
+npm add @rsdoctor/webpack-plugin -D
+pnpm add @rsdoctor/webpack-plugin -D
+```
+
+## Step 2: Register Plugin
+
+After the dependency installation, check the installed `@rsdoctor/webpack-plugin` version before changing config or running a build. Do not infer plugin capabilities from `@rsdoctor/agent-cli --version`.
+
+Required version gate (use exactly this if/else order):
+
+1. Set `pluginName = '@rsdoctor/webpack-plugin'`.
+2. Determine `pluginVersion` from local files first: dependency declarations in `package.json`, lockfile entries, then `node_modules/@rsdoctor/webpack-plugin/package.json` if installed. Use `pnpm why @rsdoctor/webpack-plugin` / `npm ls @rsdoctor/webpack-plugin` only as a fallback. When repeating analysis, reuse a valid `.rsdoctor-analysis-cache.json` plugin entry before re-reading files; invalidate it if `package.json`, lock files, or the plugin package file modification time changed.
+3. Choose one branch; do not merge branches:
+
+```text
+if @rsdoctor/webpack-plugin is missing:
+  install/register @rsdoctor/webpack-plugin, then configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+else if pluginVersion is unknown:
+  resolve pluginVersion first; if still unknown, configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+else if pluginVersion >= 1.5.11:
+  do not modify plugin config just for JSON; build with RSDOCTOR_OUTPUT=json and RSDOCTOR=true if needed
+else: # pluginVersion < 1.5.11
+  MUST configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+```
+
+Preflight every build command: `RSDOCTOR_OUTPUT=json` is allowed only in the `pluginVersion >= 1.5.11` branch. For missing, unknown, or `< 1.5.11`, `RSDOCTOR_OUTPUT=json` is forbidden. For example, when `@rsdoctor/webpack-plugin` is `1.5.7`, this command is incorrect:
+
+```bash
+RSDOCTOR_OUTPUT=json RSDOCTOR=true pnpm run build
+```
+
+### Webpack
+
+For old Webpack plugin versions, unknown versions, missing plugins, or projects that still need to register the plugin, initialize it in the [plugins](https://webpack.js.org/configuration/plugins/#plugins) of `webpack.config.js`:
+
+```js title="webpack.config.js"
+const { RsdoctorWebpackPlugin } = require('@rsdoctor/webpack-plugin');
+
+module.exports = {
+  // ...
+  plugins: [
+    // Only register the plugin when RSDOCTOR is true, as the plugin will increase the build time.
+    process.env.RSDOCTOR &&
+      new RsdoctorWebpackPlugin({
+        disableClientServer: true,
+        // Required for @rsdoctor/webpack-plugin < 1.5.11.
+        output: {
+          mode: 'brief',
+          options: {
+            type: ['json'],
+          },
+        },
+      }),
+  ].filter(Boolean),
+};
+```
+
+## Step 3 & 4: Locate and Use rsdoctor-data.json
+
+For steps on locating the `rsdoctor-data.json` file and using it for analysis, see the [common installation guide](./install-rsdoctor-common.md).

package/template-workspace/.agents/skills/rsdoctor-analysis/references/install-rsdoctor.md

@@ -0,0 +1,39 @@
+# Install Rsdoctor Plugin
+
+This documentation has been split into project-specific guides:
+
+## Choose Your Project Type
+
+- **For Rspack/Rsbuild/Modern.js projects:** See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+- **For Webpack projects:** See [install-rsdoctor-webpack.md](./install-rsdoctor-webpack.md)
+
+## Quick Decision Guide
+
+**Determine your project type:**
+
+1. **Check project type** (`projectType`):
+   - If project uses **Rspack** (including Rsbuild, Rslib, or any Rspack-based project) → Use `projectType: 'rspack'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If project uses **Webpack** (webpack >= 5) → Use `projectType: 'webpack'` → See [install-rsdoctor-webpack.md](./install-rsdoctor-webpack.md)
+
+2. **Check framework** (`framework`):
+   - If using **Rspack CLI** → `framework: 'rspack'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If using **Rsbuild** → `framework: 'rsbuild'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If using **Modern.js** → `framework: 'modern.js'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If using **Rslib** → `framework: 'rslib'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If using **Rspress** → `framework: 'rspress'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If using **Webpack** → `framework: 'webpack'` → See [install-rsdoctor-webpack.md](./install-rsdoctor-webpack.md)
+
+**Decision flow:**
+
+```
+User's project
+├─ Is it Rspack-based? (Rsbuild, Rslib, Rspress, etc.)
+│  ├─ Yes → projectType: 'rspack'
+│  │  ├─ Rspack CLI? → framework: 'rspack' → install-rsdoctor-rspack.md
+│  │  ├─ Rsbuild? → framework: 'rsbuild' → install-rsdoctor-rspack.md
+│  │  ├─ Rslib? → framework: 'rslib' → install-rsdoctor-rspack.md
+│  │  ├─ Rspress? → framework: 'rspress' → install-rsdoctor-rspack.md
+│  │  └─ Modern.js? → framework: 'modern.js' → install-rsdoctor-rspack.md
+│  └─ No → Is it Webpack >= 5?
+│     └─ Yes → projectType: 'webpack', framework: 'webpack' → install-rsdoctor-webpack.md
+```

package/template-workspace/.agents/skills/rsdoctor-analysis/references/rsdoctor-data-types.md

@@ -0,0 +1,103 @@
+# Rsdoctor Data Type Context
+
+Use this reference when a task requires understanding raw `rsdoctor-data.json` fields, schema, or nested data attributes.
+
+## Source of Truth
+
+Read type definitions from the published npm package `@rsdoctor/types`. Do not use local repository `dist/` artifacts unless the user explicitly asks for local development branch behavior.
+
+Brief JSON output has this wrapper shape:
+
+```ts
+import type { Manifest, SDK } from '@rsdoctor/types';
+
+export interface RsdoctorDataJson {
+  data: SDK.BuilderStoreData;
+  clientRoutes: Manifest.RsdoctorManifestClientRoutes[];
+}
+```
+
+The core payload type is `SDK.BuilderStoreData`.
+
+## npm Lookup Flow
+
+Prefer the npm registry/package interface.
+
+Use the latest published package unless the user gives a specific Rsdoctor package version or asks to match an installed project version.
+
+```bash
+npm view @rsdoctor/types version dist.tarball --json
+```
+
+If command execution is unavailable, use the registry endpoint directly:
+
+```text
+https://registry.npmjs.org/@rsdoctor%2Ftypes/latest
+```
+
+Read the `dist.tarball` URL from the response, download the tarball, and inspect `.d.ts` files under `package/dist/`.
+
+If matching an installed project version is important:
+
+1. Inspect the project package versions for `@rsdoctor/rspack-plugin`, `@rsdoctor/webpack-plugin`, `@rsdoctor/core`, `@rsdoctor/sdk`, or `@rsdoctor/types`.
+2. Query the matching type package:
+
+```bash
+npm view @rsdoctor/types@<version> version dist.tarball --json
+```
+
+3. If that exact version does not exist, use the closest compatible published `@rsdoctor/types` version and state the version mismatch.
+
+## Files to Inspect
+
+Start here:
+
+- `package/dist/index.d.ts`: namespace exports. `SDK` comes from `./sdk/index.js`; `Manifest` comes from `./manifest.js`.
+- `package/dist/sdk/index.d.ts`: exports all SDK data subtypes.
+- `package/dist/sdk/result.d.ts`: defines `BuilderStoreData`, the `rsdoctor-data.json.data` payload.
+- `package/dist/manifest.d.ts`: defines client routes and manifest types.
+
+Then load nested files as needed:
+
+- `package/dist/sdk/module.d.ts`: `moduleGraph`, modules, dependencies, source ranges, module code, tree-shaking-linked module data.
+- `package/dist/sdk/chunk.d.ts`: `chunkGraph`, assets, chunks, entrypoints.
+- `package/dist/sdk/package.d.ts`: `packageGraph`, package dependency data, duplicate package reports, other reports.
+- `package/dist/sdk/loader.d.ts`: loader timing/input/output data.
+- `package/dist/sdk/resolver.d.ts`: resolver data.
+- `package/dist/sdk/plugin.d.ts`: plugin hook/tap timing data.
+- `package/dist/sdk/summary.d.ts`: build summary/cost data.
+- `package/dist/sdk/config.d.ts`: collected bundler config data.
+- `package/dist/sdk/envinfo.d.ts`: environment info data.
+- `package/dist/rule/data.d.ts`: `errors`/rule store data.
+
+## Field Map
+
+`SDK.BuilderStoreData` contains:
+
+- `hash`: build hash.
+- `root`: project root.
+- `pid`: process id.
+- `envinfo`: environment information.
+- `errors`: rule/error store data.
+- `configs`: collected bundler config data.
+- `summary`: build summary data.
+- `resolver`: resolver events.
+- `loader`: loader transform events.
+- `plugin`: plugin hook/tap events.
+- `moduleGraph`: module graph data.
+- `chunkGraph`: asset/chunk/entrypoint graph data.
+- `packageGraph`: package/dependency graph data.
+- `moduleCodeMap`: module source/code map data.
+- `treeShaking`: optional tree-shaking data.
+- `otherReports`: optional extra report payloads.
+
+In brief JSON mode, `moduleCodeMap` is normally `{}` and `treeShaking` is normally absent unless generated by a mode that includes it.
+
+## Usage Guidance
+
+- Cite the npm package version used when explaining fields.
+- Distinguish wrapper fields (`data`, `clientRoutes`) from `SDK.BuilderStoreData` fields.
+- When a nested field is unclear, inspect the specific `.d.ts` file instead of guessing.
+- Use these types to construct `@rsdoctor/agent-cli --filter` field selections before each data fetch. Prefer the smallest field set that can answer the current question.
+- Match filters to the relevant data domain: chunks from `chunkGraph`, modules and tree-shaking module details from `moduleGraph`/`treeShaking`, packages from `packageGraph`, loader cost from `loader`, build cost from `summary`, and rule findings from `errors`.
+- For analysis recommendations, prefer `@rsdoctor/agent-cli` commands. Use these types for schema explanation, prompt grounding, or validating raw JSON field names.

package/template-workspace/.agents/skills/rslib-best-practices/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: rslib-best-practices
+description: Rslib best practices for config, CLI workflow, output, declaration files, dependency handling, build optimization and toolchain integration. Use when writing, reviewing, or troubleshooting Rslib projects.
+---
+
+# Rslib Best Practices
+
+Apply these rules when writing or reviewing Rslib library projects.
+
+## Configuration
+
+- Use `rslib.config.ts` and `defineConfig`
+- Check Rslib-specific configurations first (e.g., `lib.*`), and also leverage Rsbuild configurations (e.g., `source.*`, `output.*`, `tools.*`) as needed
+- For deep-level or advanced configuration needs, use `tools.rspack` or `tools.bundlerChain` to access Rspack's native configurations
+- In TypeScript projects, prefer `tsconfig.json` path aliases
+
+## CLI
+
+- Use `rslib` to build
+- Use `rslib --watch` to build in watch mode for local development
+- Use `rslib inspect` to inspect final Rslib/Rsbuild/Rspack configs
+
+## Output
+
+- Prefer to build pure-ESM package with `"type": "module"` in `package.json`
+- Prefer to use bundleless mode with `output.target` set to `'web'` when building component libraries
+- Prefer to use bundle mode when building Node.js utility libraries
+- Ensure `exports` field in `package.json` is correctly configured and matches the actual JavaScript output and declaration files output of different formats (ESM, CJS, etc.)
+
+## Declaration files
+
+- Prefer to enable declaration file generation with `lib.dts: true` or detailed configurations
+- For faster type generation, enable `lib.dts.tsgo` experimental feature with `@typescript/native-preview` installed
+
+## Dependencies
+
+- Prefer to place dependencies to be bundled in `devDependencies` in bundle mode and dependencies in `dependencies` and `peerDependencies` will be automatically externalized (not bundled) by default
+- Verify the build output and dependency specifiers in `package.json` carefully to ensure no missing dependency errors occur when consumers install and use this package
+
+## Build optimization
+
+- Keep syntax target in `lib.syntax` aligned with real compatibility requirements to enable better optimizations
+- Avoid format-specific APIs in source code for better compatibility with different output formats
+- Prefer lightweight dependencies to reduce bundle size
+
+## Toolchain integration
+
+- Prefer to use Rstest with `@rstest/adapter-rslib` for writing tests
+- Prefer to use Rspress for writing library documentation, with `@rspress/plugin-preview` and `@rspress/plugin-api-docgen` for component previews and API docs
+
+## Debugging
+
+- Run with `DEBUG=rsbuild` when diagnosing config resolution or plugin behavior
+- Read generated files in `dist/.rsbuild` to confirm final Rsbuild/Rspack config, not assumed config
+
+## Documentation
+
+- For the latest Rslib docs, read https://rslib.rs/llms.txt