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

package/dist/index.js

@@ -560,6 +560,16 @@ const TYPESCRIPT_VERSION = '6.0.3';
 const REACT_VERSION = '^19.2.6';
 const REACT_DOM_VERSION = '^19.2.6';
 const WORKSPACE_PACKAGE_VERSION = 'workspace:*';
+const RSTACK_AGENT_SKILLS_COMMIT = '61c948b42512e223bad44b83af4080eba48b2677';
+const baselineAgentSkills = [
+    'rsbuild-best-practices',
+    'rspack-best-practices',
+    'rspack-tracing',
+    'rsdoctor-analysis',
+    'rslib-best-practices',
+    'rslib-modern-package',
+    'rstest-best-practices'
+];
 const modernPackageNames = [
     '@modern-js/app-tools',
     '@modern-js/plugin-bff',
@@ -1533,7 +1543,9 @@ function createTemplateManifest(modernVersion, packageSource) {
         materialization: {
             targetRoot: 'generated-project-root',
             allowedPaths: [
+                '.agents/**',
                 '.modernjs/**',
+                'AGENTS.md',
                 'README.md',
                 'apps/**',
                 'packages/**',
@@ -1562,6 +1574,17 @@ function createTemplateManifest(modernVersion, packageSource) {
             modernPackageSpecifier: modernPackageVersion(packageSource),
             generatedWorkspacePackageSpecifier: WORKSPACE_PACKAGE_VERSION
         },
+        agentSkills: {
+            installDir: '.agents/skills',
+            source: {
+                repository: 'https://github.com/rstackjs/agent-skills',
+                commit: RSTACK_AGENT_SKILLS_COMMIT,
+                license: 'MIT',
+                licensePath: '.agents/rstackjs-agent-skills-LICENSE'
+            },
+            baseline: baselineAgentSkills,
+            lockFile: '.agents/skills-lock.json'
+        },
         validation: {
             schemaValidation: true,
             sourceValidation: [

package/package.json

@@ -21,7 +21,7 @@
   "engines": {
     "node": ">=20"
   },
-  "version": "3.2.0-ultramodern.6",
+  "version": "3.2.0-ultramodern.7",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/index.js",
   "bin": {

package/template-workspace/.agents/rstackjs-agent-skills-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RstackJS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,57 @@
+---
+name: rsbuild-best-practices
+description: Rsbuild best practices for config, CLI workflow, type checking, bundle optimization, assets, and debugging. Use when writing, reviewing, or troubleshooting Rsbuild projects.
+---
+
+# Rsbuild Best Practices
+
+Apply these rules when writing or reviewing Rsbuild projects.
+
+## Configuration
+
+- Use `rsbuild.config.ts` and `defineConfig`
+- Use `tools.rspack` or `tools.bundlerChain` only when no first-class Rsbuild option exists
+- Define explicit `source.entry` values for multi-page applications
+- In TypeScript projects, prefer `tsconfig.json` path aliases first
+
+## CLI
+
+- Use `rsbuild` for local development
+- Use `rsbuild build` for production build
+- Use `rsbuild preview` only for local production preview
+- Use `rsbuild inspect` to inspect final Rsbuild/Rspack configs
+
+## Type checking
+
+- Use `@rsbuild/plugin-type-check` for integrated dev/build type checks
+- Or run `tsc --noEmit`/`vue-tsc --noEmit` as an explicit script step
+
+## Bundle size optimization
+
+- Prefer dynamic `import()` for non-critical code paths
+- Prefer lightweight libraries where possible
+- Keep browserslist aligned with real compatibility requirements
+
+## Asset management
+
+- Import source-managed assets from project source directories, not from `public`
+- Reference `public` files by absolute URL path
+
+## Security
+
+- Do not publish `.map` files to public servers/CDNs when production source maps are enabled
+
+## Debugging
+
+- Run with `DEBUG=rsbuild` when diagnosing config resolution or plugin behavior
+- Read generated files in `dist/.rsbuild` to confirm final config, not assumed config
+
+## Profiling
+
+- Use Node CPU profiling (`--cpu-prof`) when JavaScript-side overhead is suspected
+- Use `RSPACK_PROFILE=OVERVIEW` and analyze trace output for compiler-phase bottlenecks
+
+## Documentation
+
+- For the latest (v2) docs, read http://rsbuild.rs/llms.txt
+- For Rsbuild v1 docs, read http://v1.rsbuild.rs/llms.txt

package/template-workspace/.agents/skills/rsdoctor-analysis/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: rsdoctor-analysis
+description: Use when analyzing Rspack/Webpack bundles from local `rsdoctor-data.json` and producing evidence-based optimization recommendations.
+---
+
+# Rsdoctor Analysis Assistant Skill
+
+Use the globally installed `rsdoctor-agent` CLI from `@rsdoctor/agent-cli` only after a real `rsdoctor-data.json` path exists. Keep analysis read-only unless the user explicitly asks for install/config setup.
+
+Response order (required): High-Priority Issues -> Proposed Solutions -> Optional Reference-Chain Follow-up Choices -> Next Deep-Dive Issue Categories (Not commands).
+
+## Core Workflow
+
+1. Reuse current-session results and valid `.rsdoctor-analysis-cache.json` entries before doing new work.
+2. Locate `rsdoctor-data.json` fast: user-provided path, then `dist/rsdoctor-data.json`, `output/rsdoctor-data.json`, `static/rsdoctor-data.json`, `.rsdoctor/rsdoctor-data.json`, then one bounded `rg --files` search excluding `node_modules` and `.git`. Treat `manifest.json` only as an index.
+3. If data exists, skip all plugin version/config/build generation logic. Update cache when useful.
+4. If data is missing, stop analysis: do not run `rsdoctor-agent` analysis commands, do not run the Analysis Gate, and either ask for the data path or run the Generation Gate below only when setup/generation is required.
+5. After a real data file exists, run Analysis Gate at most once before the first `rsdoctor-agent` data-fetch command: verify global `@rsdoctor/agent-cli` with `npm view @rsdoctor/agent-cli version` and `rsdoctor-agent --version`; install latest only if missing/outdated, a version-related error occurs, or the user asks to refresh.
+6. Fetch only the Default Evidence Set first; run independent fetches in parallel when possible; synthesize findings in the required response order.
+
+Performance rules: parallelize independent checks, cache only derived facts (`dataFile`, `dataFileMtime`, `pluginName`, `pluginVersion`, dependency/config/plugin modification times), and invalidate cache when paths disappear, modification times change, the user asks to refresh, or cached values fail. Speculative plugin checks must not trigger generation; use them only after confirming the data file is missing.
+
+## Generation Gate
+
+Identify `pluginName` (`@rsdoctor/rspack-plugin` or `@rsdoctor/webpack-plugin`) and determine `pluginVersion` from local files first: `package.json`, lockfile, then `node_modules/<plugin>/package.json`; use `pnpm why` / `npm ls` only as fallback.
+
+Use this exact if/else decision tree; do not merge branches:
+
+```text
+if pluginName is missing:
+  install/register the matching Rsdoctor 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 edit 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`, it is forbidden. For `< 1.5.11`, generating `rsdoctor-data.json` requires the plugin config below:
+
+```ts
+output: {
+  mode: 'brief',
+  options: {
+    type: ['json'],
+  },
+}
+```
+
+## Evidence and Command Bounds
+
+Default Evidence Set:
+
+| Summary key          | Evidence source                            | Bounds                                        |
+| -------------------- | ------------------------------------------ | --------------------------------------------- |
+| `buildCost`          | `build summary`                            | filtered fields only                          |
+| `assetsTop`          | top assets by raw/gzip size                | fixed Top-N                                   |
+| `packagesTop`        | top packages by gzip size                  | fixed Top-N; avoid full `packages list` pages |
+| `duplicatePackages`  | E1001 duplicate package summary            | first-pass summary only                       |
+| `crossChunkPackages` | E1002 cross-chunk duplication summary      | first-pass summary only                       |
+| `retainedModulesTop` | `tree-shaking retained-modules --limit 10` | filtered fields only; no `--compact`          |
+
+Scope rules:
+
+- Use `rsdoctor-agent` for bundle data access only after `rsdoctor-data.json` exists; prefer parallel independent fetches; bound output with `--filter`, pagination, and `--limit`.
+- Default analysis stays within the Default Evidence Set. For non-default analysis, choose minimal fields from [references/rsdoctor-data-types.md](references/rsdoctor-data-types.md) and patterns from [references/common-analysis-patterns.md](references/common-analysis-patterns.md).
+- Treat chain tracing, broad commands, optimization edits, splitChunks experiments, and build re-runs as opt-in follow-ups that require user confirmation.
+- For duplicate packages and tree-shaking issues, identify issues first; trace reference/import chains only after user confirmation.
+- Prefer `tree-shaking retained-modules --emitted-only --category side-effects --limit 10` with narrow `--filter` for side-effects investigations.
+- For retained emitted modules, use `tree-shaking retained-modules` with `--emitted-only`, bounded `--category`, `--sort gzipSize`, `--limit`, and narrow `--filter`; do not pass `--compact`.
+- Use `tree-shaking summary` only as fallback for missing fields or aggregate context. Treat `tree-shaking bailout-reasons` as high-volume; run it only when explicitly requested and pass target `--modules` (max 100).
+- If any command exceeds `5k` tokens, `500 KB` raw output, or a few hundred transcript lines, stop broad fetching and switch to targeted compact queries.
+
+## Output and Recovery
+
+Output format:
+
+1. Issues found in the current build and recommended fixes:
+   - Group each issue with its fix recommendation.
+   - Include concrete evidence (size/time/count/path/rule code) and priority.
+   - For duplicate packages and tree-shaking issues, include a short "continue tracing vs stop here" choice.
+2. Whether deeper analysis is still needed:
+   - List remaining issue categories only, not commands.
+
+For Top-N insights, prefer a table: `Name | Volume/Time | Count | Recommendation`.
+
+Recovery rules:
+
+- `rsdoctor-data.json` missing: do not run `rsdoctor-agent`; ask for the data path or run Generation Gate, then use the matching install reference if setup is needed.
+- Command not found: run Analysis Gate, then retry with `rsdoctor-agent`.
+- `query` reports unknown tool: run `list` and use a catalog tool name, or switch to direct `<group> <subcommand>` mode.
+- JSON read error: verify file path, JSON validity, and permissions.
+- In Codex, do not run `install`, `build`, global CLI installation, version checks, or `rsdoctor-agent...` inside sandbox. Run Rsdoctor CLI setup and data-fetch commands outside sandbox so they can access project files and dependencies normally.
+
+References: commands/options [references/command-map.md](references/command-map.md); install/config/data location [references/install-rsdoctor.md](references/install-rsdoctor.md), [references/install-rsdoctor-rspack.md](references/install-rsdoctor-rspack.md), [references/install-rsdoctor-webpack.md](references/install-rsdoctor-webpack.md), [references/install-rsdoctor-common.md](references/install-rsdoctor-common.md); raw data fields [references/rsdoctor-data-types.md](references/rsdoctor-data-types.md); common patterns [references/common-analysis-patterns.md](references/common-analysis-patterns.md).

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

@@ -0,0 +1,113 @@
+# Rsdoctor Skill Command Map
+
+Stable CLI entry:
+
+- Install and verify the global CLI first:
+  - `npm view @rsdoctor/agent-cli version`
+  - `rsdoctor-agent --version`
+  - If missing or outdated: `npm install -g @rsdoctor/agent-cli@latest`
+- Run data-fetch commands directly with `rsdoctor-agent <group> <subcommand> [options]`.
+
+Top-level command mode:
+
+- `list`
+- `query <tool-name> --data-file <path> [--input <json>]`
+
+`query` catalog (current):
+
+- `chunks_list`
+- `packages_direct_dependencies`
+- `packages_duplicates`
+- `packages_similar`
+- `build_summary`
+- `bundle_optimize`
+- `errors_list`
+- `tree_shaking_summary`
+
+Option scopes:
+
+- `--data-file <path>`:
+  - required for `query`, direct `<group> <subcommand>`, and `ai <group> <subcommand>`
+  - not required for `list`, `ai --describe`, `ai --schema`
+- `--input <json>`: optional for `query`
+- `--filter <...>`: supported by every data-fetch function; use it to return only required fields selected from `@rsdoctor/types` / [rsdoctor-data-types.md](rsdoctor-data-types.md)
+- `--compact`: add whenever possible to keep CLI JSON compact. Do not use it with `tree-shaking retained-modules`; use `--filter` and `--limit` instead.
+
+## Chunks
+
+- `chunks list` -> List all chunks. Pagination: `--page-number`, `--page-size`
+- `chunks by-id --id <n>` -> Get chunk detail by numeric id
+- `chunks large` -> Find oversized chunks. High-noise in default analysis; avoid unless the user asks for chunk deep dive.
+
+## Modules
+
+- `modules by-id --id <id>` -> Module detail by id
+- `modules by-path --path "<path>"` -> Module lookup by path
+- `modules issuer --id <id>` -> Issuer/import chain (recommended as second-pass, after user confirms chain tracing)
+- `modules exports` -> Module exports info
+- `modules side-effects` -> Non-tree-shakeable modules. Fallback only for side-effects analysis; use `--page-size 10`, narrow filters, and stop if output exceeds `5k` tokens or `500 KB`.
+
+## Packages
+
+- `packages list` -> Package list with size/duplication info. Do not read full pages in default analysis; use fixed Top-N package summaries or narrowly filtered/package-targeted queries.
+- `packages by-name --name <pkg>` -> Package lookup by name
+- `packages dependencies` -> Dependency graph. Pagination: `--page-number`, `--page-size`
+- `packages direct-dependencies` -> Direct third-party package dependencies imported by project/local packages. Tool name: `packages_direct_dependencies`
+- `packages duplicates` -> Duplicate package detection (first-pass summary before optional chain tracing)
+- `packages similar` -> Similar package detection
+
+## Assets
+
+- `assets list` -> Asset list with size info
+- `assets diff --baseline <path> --current <path>` -> Compare two builds
+- `assets media` -> Media optimization guidance
+
+## Loaders
+
+- `loaders hot-files` -> Slowest loader/file pairs. Options: `--page-number`, `--page-size`, `--min-costs`
+- `loaders directories` -> Loader times by directory. Options: `--page-number`, `--page-size`, `--min-total-costs`
+
+## Build
+
+- `build summary` -> Build summary and costs
+- `build entrypoints` -> Entrypoints
+- `build config` -> Build config snapshot
+- `build optimize` -> Bundle optimization inputs. High-noise in default analysis; avoid unless the user asks for bundle optimization deep dive or default evidence is insufficient. Options: `--step`, `--side-effects-page-number`, `--side-effects-page-size` (recommend `--side-effects-page-size 10`).
+
+## Bundle
+
+- `bundle optimize` -> Alias of `build optimize`
+
+## Errors
+
+- `errors list` -> All errors and warnings
+- `errors by-code --code <code>` -> Filter by code. For default E1001/E1002 summaries, prefer local JSON summarization.
+- `errors by-level --level <level>` -> Filter by level
+
+## Rules
+
+- `rules list` -> Rule scan results
+
+## Server
+
+- `server port` -> Current JSON data file path
+
+## Tree-Shaking
+
+- `tree-shaking summary` -> Overall tree-shaking health summary (can be very large; filter with fields from `rsdoctor-data-types`, compact where useful, and use aggregated results)
+- `tree-shaking retained-modules` -> Retained emitted modules by category for tree-shaking diagnosis. Useful options: `--emitted-only`, `--category cjs,barrel,side-effects`, `--sort gzipSize`, `--limit <n>`, and `--filter id,path,packageName,version,category,size,chunks,bailoutReason,recommendation`. Does not support `--compact`.
+- `tree-shaking bailout-reasons --modules <module-list>` -> Non-tree-shakeable modules by bailout reason for the provided modules. High-volume; only run when explicitly requested, always pass `--modules`, and include at most 100 modules per command.
+- `tree-shaking exports-analysis` -> Export-level tree-shaking opportunities
+
+`tree-shaking retained-modules` returns retained module rows with:
+
+| Field                     | Meaning                                       |
+| ------------------------- | --------------------------------------------- |
+| `id`                      | Module id                                     |
+| `path`                    | Module path                                   |
+| `packageName` / `version` | Owning package                                |
+| `category`                | `cjs`, `barrel`, `side-effects`, or `unknown` |
+| `size`                    | Source, parsed, and gzip sizes when available |
+| `chunks`                  | Chunk id/name/assets                          |
+| `bailoutReason`           | Original bailout/retention reason             |
+| `recommendation`          | Optional short recommendation                 |

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.