@bleedingdev/modern-js-create 3.2.0-ultramodern.98 → 3.2.0-ultramodern.99

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

@@ -0,0 +1,190 @@
+# Common Analysis Patterns
+
+Use this reference for common Rspack/Webpack bundle analysis questions after locating `rsdoctor-data.json`.
+
+## Similar Packages
+
+Use direct dependency package data to inspect similar packages. Start with `packages direct-dependencies` or `query packages_direct_dependencies`, then check known package families and other potentially similar packages.
+
+Suggested flow:
+
+1. Fetch direct dependency package data with `packages direct-dependencies` or `query packages_direct_dependencies`. Use `--filter` fields for package name, version, issuer/dependency relation, and size when available.
+2. Treat this direct dependency list as the replacement-candidate set. Do not make replacement recommendations from indirect package-only evidence.
+3. Check the known families below. The presence of one package from a family is fine; only consider replacement when multiple packages from the same family are present.
+4. After known-family checks, inspect the direct dependency list for other potentially similar packages not listed below. Treat these as candidates only when package purpose overlaps clearly; avoid speculative replacement advice.
+5. Use `packages similar` or `query packages_similar` as an additional signal, not the only source of evidence.
+
+Similar package families:
+
+1. `lodash`, `lodash-es`
+   - Consider migrating from `lodash` to `lodash-es` for better tree-shaking support when both are present.
+2. `dayjs`, `moment`, `date-fns`, `js-joda`
+   - Consider replacing `moment` with `dayjs` for smaller bundle size when both are present and project requirements allow it.
+3. `antd`, `material-ui`, `semantic-ui-react`, `arco-design`
+4. `axios`, `node-fetch`
+5. `redux`, `mobx`, `zustand`, `recoil`, `jotai`
+6. `chalk`, `colors`, `picocolors`, `kleur`
+7. `fs-extra`, `graceful-fs`
+
+If there are no similar packages, simply say there are no similar packages. Do not list packages that merely exist in the project.
+
+Keep the response simple: name only coexisting known-family packages or other direct-dependency candidates with clear overlap, explain why coexistence is worth reviewing, and give one replacement direction if the evidence supports it.
+
+## Media Asset Analysis
+
+Use `assets media` or `bundle optimize` when checking oversized image, font, or video assets. Return recommendations only for assets that are actually oversized or relevant to the user's question.
+
+Image thresholds:
+
+- Mobile: one image file should ideally be under `60 KB`; Base64 SVG should ideally be under `7 KB`.
+- PC: one image file should ideally be under `200 KB`; Base64 SVG should ideally be under `20 KB`.
+
+Image recommendations:
+
+- Compress large images with image compression tools such as `@rsbuild/plugin-image-compress` (`svgo` for SVG and `@napi-rs/image` for other images).
+- Optimize SVG paths with tools such as SVGO.
+- Consider whether SVG is necessary for the asset.
+- Choose formats by compression characteristics:
+  - PNG works best for images with few colors and sharp boundaries, such as text or simple patterns.
+  - JPG works best for natural images with gradients and irregular transitions, such as landscapes and portraits.
+  - Base64 is suitable for important small images that should avoid extra requests and render immediately. Base64 increases binary size by about one third, but after gzip the increase is usually no more than about 10%.
+
+Font thresholds:
+
+- Prefer `.woff2`.
+- Keep a single font file under `100 KB` when possible.
+- Keep total font size under `300 KB` for the page, and under `200 KB` for mobile when possible.
+- Avoid font formats other than `ttf`, `woff`, and `woff2` unless there is a compatibility requirement.
+
+Font recommendations:
+
+- Prefer system fonts when custom fonts are not required.
+- Use `font-display: swap` or `@font-face unicode-range` for more efficient loading.
+- Ensure server-side Gzip or Brotli compression is enabled.
+- Consider variable fonts when they replace multiple weight or width files.
+
+Video thresholds:
+
+- Keep a single video file under `500 KB` when possible.
+- Keep total video resources loaded on a page under `1 MB` when possible.
+
+Video recommendations:
+
+- Compress video files with tools such as HandBrake or FFmpeg.
+- Use MP4 (H.264) as the compatibility default.
+- Use WebM (VP9) when modern-browser compression benefits justify it.
+- Lazy-load non-critical videos.
+- Use HLS or DASH for long videos.
+- Remove unused videos.
+- Tune `preload`:
+  - `none`: do not download until playback starts; useful for videos unlikely to be played.
+  - `metadata`: downloads metadata only, often around 3% of file size.
+  - `auto`: downloads the full video; use only when playback is very likely.
+
+## Bundle Optimize
+
+Use `bundle optimize` / `build optimize` as an aggregate optimization pass. It can combine evidence from:
+
+- Duplicate package rules (`getRuleInfo` / `errors list` / rule details).
+- Similar package checks (`packages similar` / `query packages_similar`).
+- Media asset checks (`assets media`).
+- Chunk checks (`chunks list`, `chunks large`, or chunk details) for oversized resources and `splitChunks` recommendations.
+
+Do not run `bundle optimize` / `build optimize` in the default analysis path. Use it only for a user-requested optimization deep dive or when the compact default evidence set is missing required fields.
+
+When using it, keep output compact with `--compact`, narrow `--filter` fields, and pagination options such as `--side-effects-page-size 10`. If the command still returns thousands of lines, stop and switch to narrower supporting commands.
+
+Do not treat aggregate output as enough by itself when the recommendation needs concrete evidence. Fetch the narrow supporting data before recommending a config or dependency change.
+
+## Build Performance
+
+Use these as short recommendation candidates when Rsdoctor evidence points to build-time cost, loader cost, too many modules, or slow dev rebuilds. Source: [Rsbuild build performance guide](https://rsbuild.rs/zh/guide/optimization/build-performance).
+
+- Start with build performance analysis. Use measured bottlenecks before recommending config changes. Use Rsdoctor loader costs data.
+- General improvements: upgrade Rsbuild, enable `performance.buildCache` for faster rebuilds, reduce module count, and keep Tailwind CSS v3 `content` narrow and correct.
+- Tooling choices: prefer SWC over Babel transforms, avoid Less-heavy pipelines when possible, and prefer faster minification such as Rsbuild/Rspack SWC minification over Terser when compatible.
+- Sass handling: do not send already-built `node_modules/**/*.css` through `sass-loader`; prefer third-party `dist/*.css` outputs when available. Compile third-party `.scss` / `.sass` only when Sass source features are required, such as variables, mixins, functions, or theme customization, and use an allowlist for those packages instead of all `node_modules`.
+- Less projects: if many Less files are present, consider `@rsbuild/plugin-less` parallel compilation.
+- Development mode: consider `dev.lazyCompilation`, Rspack `experiments.nativeWatcher`, cheaper or disabled dev source maps, and a narrower development Browserslist.
+- Rsdoctor loader evidence: if `sass-loader` time is concentrated in third-party package directories and those packages ship CSS artifacts, recommend importing the CSS artifact or narrowing Sass rule `include` to app source plus specific allowlisted theme packages.
+- Call out tradeoffs: development Browserslist and source map changes can make dev output differ from production or reduce debugging detail.
+
+## Retained Module Tree-shaking Analysis
+
+Use `tree-shaking retained-modules` for first-pass tree-shaking evidence when the goal is to find retained emitted modules by reason category. Prefer it over broad `tree-shaking summary` when the user asks for top retained modules, CommonJS retention, barrel imports, side effects, or gzip-size priority.
+
+Recommended first-pass command shape:
+
+```bash
+rsdoctor-agent tree-shaking retained-modules \
+  --data-file dist/rsdoctor-data.json \
+  --emitted-only \
+  --category cjs,barrel,side-effects \
+  --sort gzipSize \
+  --limit 10 \
+  --filter id,path,packageName,version,category,size,chunks,bailoutReason,recommendation
+```
+
+Guidance:
+
+1. Keep `--emitted-only` by default so findings map to shipped bundle impact.
+2. Use `--category cjs,barrel,side-effects` for optimization scans; narrow `--category` when the user asks about one class.
+3. Sort by `gzipSize` for bundle impact, unless the user asks for source or parsed size.
+4. Keep `--limit` bounded. Use `--limit 10` for default analysis. Increase to `50` only for user-requested deep dives.
+5. Do not add `--compact`; `tree-shaking retained-modules` output size is controlled with `--limit` and `--filter`.
+6. Report rows as `Path | Package | Category | Gzip/Parsed Size | Chunks | Bailout | Recommendation`.
+7. Treat results as first-pass evidence. Use `modules issuer` only after the user asks to trace who imported a retained module.
+
+## Common Questions
+
+### Why is a module not tree-shaken?
+
+Example: "Why is `node_modules/rc-tree/lib/util.js` not tree-shaken?"
+
+- Start with `tree-shaking retained-modules` filtered to id, path, package, category, size, chunks, bailout reason, and recommendation when the module appears in emitted output.
+- Use `tree-shaking summary` only when retained modules do not include the needed field or the question needs broader aggregate context.
+- Return the module's `bailoutReason`.
+- Explain the bailout in plain language.
+- Show `issuerPath` only when the user asks for chain tracing or when it is necessary to explain the issue.
+
+### Who imported a module?
+
+Example: "Who imported `lodash-es/constant.js`?"
+
+- Use module lookup by path, then issuer/import-chain data.
+- Show the dependency chain using arrow notation or a tree.
+
+### Show modules with side effects
+
+Example: "Show all modules with side effects."
+
+- Prefer `tree-shaking retained-modules --emitted-only --category side-effects` for emitted side-effect modules.
+- Fall back to `tree-shaking summary` or the relevant module-side-effects command only when retained-module output is insufficient.
+- Filter to module id, path, package, size, chunks, bailout reason, and recommendation.
+- List modules with non-empty `bailoutReason` containing `side_effects`.
+- Use `--limit 10` for default output. Increase only after user confirmation.
+- If falling back to `tree-shaking summary` or `modules side-effects`, use `--page-size 10` or `--side-effects-page-size 10`, keep the same narrow fields, and stop expanding when one command exceeds `5k` tokens or `500 KB` raw output.
+- Sort by size, give priority to the largest emitted modules.
+
+### Why is a package duplicated?
+
+Example: "Why is package X duplicated?"
+
+- Use duplicate package rule data (`E1001` / `E1002`) and package graph fields.
+- Show which chunks and modules contain the duplicate versions.
+- Explain the dependency path if the user asks to continue chain tracing.
+
+### Which modules are not tree-shaken because of side effects?
+
+- Use the E1007 rule results directly to identify modules that are not tree-shaken due to side effects. By `tree-shaking summary`.
+- If further details are needed, you may also use `tree-shaking retained-modules --emitted-only --category side-effects` and filter to module id, path, package, size, chunks, bailout reason, and recommendation.
+- List modules with `bailoutReason` containing `side_effects`.
+- Use `--limit 10` by default and the same `5k` token / `500 KB` raw-output stop rule for fallback commands.
+- Show `issuerPath` when needed to identify the import source.
+
+## Output Style
+
+- For dependency chains, use a tree or arrow notation.
+- For module details, use a table or key-value list.
+- For explanations, use concise, plain language.
+- Avoid listing all packages or assets when the finding is empty.

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.