@bleedingdev/modern-js-create 3.2.0-ultramodern.0 → 3.2.0-ultramodern.10

package/template/scripts/validate-ultramodern.mjs.handlebars

@@ -2,17 +2,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 const configPath = path.resolve(process.cwd(), 'modern.config.ts');
-const templateManifestPath = path.resolve(
-  process.cwd(),
-  '.modernjs/mv-template-manifest.json',
-);
+const templateManifestPath = path.resolve(process.cwd(), '.modernjs/mv-template-manifest.json');
 
 if (!fs.existsSync(configPath)) {
   console.error('modern.config.ts not found');
   process.exit(1);
 }
 
-const content = fs.readFileSync(configPath, 'utf8');
+const content = fs.readFileSync(configPath, 'utf-8');
 const requiredTokens = [
   'presetUltramodern(',
   'appTools()',
@@ -20,12 +17,10 @@ const requiredTokens = [
   'enableBffRequestId',
   'enableTelemetryExporters',
 ];
-const missing = requiredTokens.filter(token => !content.includes(token));
+const missing = requiredTokens.filter((token) => !content.includes(token));
 
 if (missing.length > 0) {
-  console.error(
-    `Ultramodern contract check failed. Missing tokens: ${missing.join(', ')}`,
-  );
+  console.error(`Ultramodern contract check failed. Missing tokens: ${missing.join(', ')}`);
   process.exit(1);
 }
 
@@ -34,9 +29,7 @@ if (!fs.existsSync(templateManifestPath)) {
   process.exit(1);
 }
 
-const templateManifest = JSON.parse(
-  fs.readFileSync(templateManifestPath, 'utf8'),
-);
+const templateManifest = JSON.parse(fs.readFileSync(templateManifestPath, 'utf-8'));
 const requiredDeniedPaths = [
   '.git/**',
   '.github/**',
@@ -52,8 +45,22 @@ const requiredPostMaterialization = [
   'dependency-install-with-lifecycle-deny',
   'template-manifest-retained',
 ];
+const requiredPaths = [
+  'AGENTS.md',
+  '.agents/skills-lock.json',
+  'oxlint.config.ts',
+  'oxfmt.config.ts',
+  'scripts/bootstrap-agent-skills.mjs',
+];
 const manifestErrors = [];
 
+for (const requiredPath of requiredPaths) {
+  if (!fs.existsSync(path.resolve(process.cwd(), requiredPath))) {
+    console.error(`${requiredPath} not found`);
+    process.exit(1);
+  }
+}
+
 if (templateManifest.schemaVersion !== 1) {
   manifestErrors.push('schemaVersion');
 }
@@ -65,10 +72,10 @@ if (templateManifest.source?.type !== 'builtin') {
 if (
   !Array.isArray(templateManifest.integrity?.checksums) ||
   !templateManifest.integrity.checksums.some(
-    checksum =>
+    (checksum) =>
       checksum.algorithm === 'sha256' &&
       checksum.scope === 'source-tree' &&
-      /^[0-9a-f]{64}$/.test(checksum.value),
+      /^[0-9a-f]{64}$/u.test(checksum.value),
   )
 ) {
   manifestErrors.push('integrity.checksums[source-tree]');
@@ -92,11 +99,68 @@ for (const token of requiredPostMaterialization) {
 
 if (manifestErrors.length > 0) {
   console.error(
-    `Ultramodern template manifest check failed. Invalid fields: ${manifestErrors.join(
-      ', ',
-    )}`,
+    `Ultramodern template manifest check failed. Invalid fields: ${manifestErrors.join(', ')}`,
   );
   process.exit(1);
 }
 
+const packageJson = JSON.parse(
+  fs.readFileSync(path.resolve(process.cwd(), 'package.json'), 'utf-8'),
+);
+const unresolvedTemplateMarker = String.fromCodePoint(123, 123);
+if (JSON.stringify(packageJson).includes(unresolvedTemplateMarker)) {
+  console.error('package.json contains unresolved template markers');
+  process.exit(1);
+}
+const skillsLock = JSON.parse(
+  fs.readFileSync(path.resolve(process.cwd(), '.agents/skills-lock.json'), 'utf-8'),
+);
+const requiredScripts = {
+  format: 'oxfmt .',
+  'format:check': 'oxfmt --check .',
+  lint: 'oxlint .',
+  'lint:fix': 'oxlint . --fix',
+  'skills:check': 'node ./scripts/bootstrap-agent-skills.mjs --check',
+  'skills:install': 'node ./scripts/bootstrap-agent-skills.mjs',
+};
+
+for (const [scriptName, scriptCommand] of Object.entries(requiredScripts)) {
+  if (packageJson.scripts?.[scriptName] !== scriptCommand) {
+    console.error(`Missing or invalid package script: ${scriptName}`);
+    process.exit(1);
+  }
+}
+
+if (
+  !packageJson.scripts?.typecheck?.includes('effect-tsgo') ||
+  !packageJson.scripts.typecheck.includes('get-exe-path')
+) {
+  console.error('typecheck must use effect-tsgo as the TypeScript checker');
+  process.exit(1);
+}
+
+for (const dependency of [
+  '@effect/tsgo',
+  '@typescript/native-preview',
+  'oxlint',
+  'oxfmt',
+  'ultracite',
+]) {
+  if (!packageJson.devDependencies?.[dependency]) {
+    console.error(`Missing devDependency: ${dependency}`);
+    process.exit(1);
+  }
+}
+
+const privateSource = skillsLock.sources?.find(
+  (source) => source.repository === 'https://github.com/TechsioCZ/skills',
+);
+const privateSkills = new Set(privateSource?.baseline?.map((skill) => skill.name));
+for (const skillName of ['plan-graph', 'dag', 'subagent-graph', 'helm', 'debugger-mode']) {
+  if (!privateSkills.has(skillName)) {
+    console.error(`Missing private skill allowlist entry: ${skillName}`);
+    process.exit(1);
+  }
+}
+
 console.log('Ultramodern contract check passed.');

package/template/shared/effect/api.ts.handlebars

@@ -14,5 +14,4 @@ export const bffEffectApi = HttpApi.make('BffApi').add(
       }),
     }),
   ),
-);
-{{/if}}
+);{{/if}}

package/template/src/modern.runtime.ts.handlebars

@@ -1,9 +1,7 @@
 import { defineRuntimeConfig } from '@modern-js/runtime';
 
 export default defineRuntimeConfig({
-{{#if isTanstackRouter}}
-  router: {
+{{#if isTanstackRouter}}  router: {
     framework: 'tanstack',
-  },
-{{/if}}
+  },{{/if}}
 });

package/template/src/routes/index.css.handlebars

@@ -4,7 +4,12 @@
 body {
   padding: 0;
   margin: 0;
-  font-family: PingFang SC, Hiragino Sans GB, Microsoft YaHei, Arial, sans-serif;
+  font-family:
+    PingFang SC,
+    Hiragino Sans GB,
+    Microsoft YaHei,
+    Arial,
+    sans-serif;
   background: linear-gradient(to bottom, transparent, #fff) #eceeef;
 }
 
@@ -67,8 +72,14 @@ main {
   padding: 0.6rem 0.9rem;
   font-size: 1.05rem;
   font-family:
-    Menlo, Monaco, Lucida Console, Liberation Mono, DejaVu Sans Mono,
-    Bitstream Vera Sans Mono, Courier New, monospace;
+    Menlo,
+    Monaco,
+    Lucida Console,
+    Liberation Mono,
+    DejaVu Sans Mono,
+    Bitstream Vera Sans Mono,
+    Courier New,
+    monospace;
 }
 
 .container-box .grid {

package/template/src/routes/page.tsx.handlebars

@@ -1,20 +1,31 @@
 import { Helmet } from '@modern-js/runtime/head';
 {{#if useEffectBff}}import effectBff from '@api/effect/index';
+import { Effect } from '@modern-js/plugin-bff/effect-client';
 import { useEffect, useState } from 'react';
 {{/if}}
 import './index.css';
 
 const Index = () => {
-{{#if useEffectBff}}
-  const [effectMessage, setEffectMessage] = useState('loading...');
+{{#if useEffectBff}}  const [effectMessage, setEffectMessage] = useState('loading...');
 
   useEffect(() => {
-    effectBff.client.greetings.hello({}).then(data => {
-      setEffectMessage(data.message);
-    });
+    let mounted = true;
+    Effect.runFork(
+      Effect.promise(() => effectBff.client.greetings.hello({})).pipe(
+        Effect.tap((data) =>
+          Effect.sync(() => {
+            if (mounted) {
+              setEffectMessage(data.message);
+            }
+          }),
+        ),
+      ),
+    );
+    return () => {
+      mounted = false;
+    };
   }, []);
 {{/if}}
-
   return (
     <div className="container-box">
       <Helmet>
@@ -26,19 +37,20 @@ const Index = () => {
       </Helmet>
       <main>
         <div className="title">
-          Modern.js
+          UltraModern.js 3.0
           <img
             className="logo"
             src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/modern-js-logo.svg"
-            alt="Modern.js Logo"
+            alt="UltraModern.js Logo"
           />
           <p className="name">presetUltramodern</p>
         </div>
         <p className="description{{#if enableTailwind}} text-emerald-700 font-semibold{{/if}}">
-          This starter ships the public <code className="code">presetUltramodern(...)</code> profile. Start in
+          This starter ships the public <code className="code">presetUltramodern(...)</code>{' '}
+          profile. Start in
           <code className="code">modern.config.ts</code>, keep
-          <code className="code">pnpm run ultramodern:check</code> green, and
-          tune the generated preset only where your app needs a softer lane.
+          <code className="code">pnpm run ultramodern:check</code> green, and tune the generated
+          preset only where your app needs a softer lane.
         </p>
 {{#if useEffectBff}}
         <p className="description effect-message{{#if enableTailwind}} text-emerald-700 font-semibold{{/if}}">
@@ -47,13 +59,13 @@ const Index = () => {
 {{/if}}
         <div className="grid">
           <a
-            href="https://modernjs.dev/en/guides/get-started/ultramodern.html"
+            href="https://bleedingdev.github.io/ultramodern.js/guides/get-started/ultramodern.html"
             target="_blank"
             rel="noopener noreferrer"
             className="card"
           >
             <h2>
-              presetUltramodern Guide
+              UltraModern.js Guide
               <img
                 className="arrow-right"
                 src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/arrow-right.svg"
@@ -63,7 +75,7 @@ const Index = () => {
             <p>Review the MV-first, TanStack-ready, Effect-ready public preset.</p>
           </a>
           <a
-            href="https://modernjs.dev/en/configure/app/usage.html"
+            href="https://bleedingdev.github.io/ultramodern.js/configure/app/usage.html"
             target="_blank"
             className="card"
             rel="noreferrer"
@@ -76,10 +88,12 @@ const Index = () => {
                 alt="Tutorials"
               />
             </h2>
-            <p>Tune the generated defaults in <code className="code">modern.config.ts</code>.</p>
+            <p>
+              Tune the generated defaults in <code className="code">modern.config.ts</code>.
+            </p>
           </a>
           <a
-            href="https://github.com/web-infra-dev/modern.js/blob/main/packages/toolkit/create/template/.github/workflows/ultramodern-gates.yml.handlebars"
+            href="https://github.com/BleedingDev/ultramodern.js/blob/main-ultramodern/packages/toolkit/create/template/.github/workflows/ultramodern-gates.yml.handlebars"
             target="_blank"
             className="card"
             rel="noreferrer"
@@ -92,10 +106,13 @@ const Index = () => {
                 alt="Config"
               />
             </h2>
-            <p>The starter includes a PR workflow for <code className="code">ultramodern:check</code> and build.</p>
+            <p>
+              The starter includes a PR workflow for <code className="code">ultramodern:check</code>{' '}
+              and build.
+            </p>
           </a>
           <a
-            href="https://modernjs.dev/en/configure/app/bff/effect.html"
+            href="https://bleedingdev.github.io/ultramodern.js/configure/app/bff/effect.html"
             target="_blank"
             rel="noopener noreferrer"
             className="card"

package/template/tsconfig.json

@@ -3,13 +3,117 @@
   "compilerOptions": {
     "declaration": false,
     "jsx": "preserve",
-    "baseUrl": "./",
+    "target": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "module": "preserve",
+    "moduleResolution": "Bundler",
+    "moduleDetection": "force",
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "allowJs": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
     "paths": {
       "@/*": ["./src/*"],
       "@api/*": ["./api/*"],
       "@shared/*": ["./shared/*"]
     },
-    "rootDir": "./src"
+    "rootDir": ".",
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "diagnostics": true,
+        "includeSuggestionsInTsc": true,
+        "ignoreEffectSuggestionsInTscExitCode": false,
+        "ignoreEffectWarningsInTscExitCode": false,
+        "ignoreEffectErrorsInTscExitCode": false,
+        "skipDisabledOptimization": true,
+        "diagnosticSeverity": {
+          "anyUnknownInErrorContext": "error",
+          "classSelfMismatch": "error",
+          "duplicatePackage": "error",
+          "effectFnImplicitAny": "error",
+          "floatingEffect": "error",
+          "genericEffectServices": "error",
+          "missingEffectContext": "error",
+          "missingEffectError": "error",
+          "missingLayerContext": "error",
+          "missingReturnYieldStar": "error",
+          "missingStarInYieldEffectGen": "error",
+          "nonObjectEffectServiceType": "error",
+          "outdatedApi": "error",
+          "overriddenSchemaConstructor": "error",
+          "catchUnfailableEffect": "error",
+          "effectFnIife": "error",
+          "effectGenUsesAdapter": "error",
+          "effectInFailure": "error",
+          "effectInVoidSuccess": "error",
+          "globalErrorInEffectCatch": "error",
+          "globalErrorInEffectFailure": "error",
+          "layerMergeAllWithDependencies": "error",
+          "lazyPromiseInEffectSync": "error",
+          "leakingRequirements": "error",
+          "multipleEffectProvide": "error",
+          "returnEffectInGen": "error",
+          "runEffectInsideEffect": "error",
+          "schemaSyncInEffect": "error",
+          "scopeInLayerEffect": "error",
+          "strictEffectProvide": "error",
+          "tryCatchInEffectGen": "error",
+          "unknownInEffectCatch": "error",
+          "asyncFunction": "error",
+          "cryptoRandomUUID": "error",
+          "cryptoRandomUUIDInEffect": "error",
+          "extendsNativeError": "error",
+          "globalConsole": "error",
+          "globalConsoleInEffect": "error",
+          "globalDate": "error",
+          "globalDateInEffect": "error",
+          "globalFetch": "error",
+          "globalFetchInEffect": "error",
+          "globalRandom": "error",
+          "globalRandomInEffect": "error",
+          "globalTimers": "error",
+          "globalTimersInEffect": "error",
+          "instanceOfSchema": "error",
+          "newPromise": "error",
+          "nodeBuiltinImport": "error",
+          "preferSchemaOverJson": "error",
+          "processEnv": "error",
+          "processEnvInEffect": "error",
+          "unsafeEffectTypeAssertion": "error",
+          "catchAllToMapError": "error",
+          "deterministicKeys": "error",
+          "effectDoNotation": "error",
+          "effectFnOpportunity": "error",
+          "effectMapFlatten": "error",
+          "effectMapVoid": "error",
+          "effectSucceedWithVoid": "error",
+          "missedPipeableOpportunity": "error",
+          "missingEffectServiceDependency": "error",
+          "nestedEffectGenYield": "error",
+          "redundantSchemaTagIdentifier": "error",
+          "schemaStructWithTag": "error",
+          "schemaUnionOfLiterals": "error",
+          "serviceNotAsClass": "error",
+          "strictBooleanExpressions": "error",
+          "unnecessaryArrowBlock": "error",
+          "unnecessaryEffectGen": "error",
+          "unnecessaryFailYieldableError": "error",
+          "unnecessaryPipe": "error",
+          "unnecessaryPipeChain": "error"
+        }
+      }
+    ]
   },
   "include": ["src", "api", "shared", "config", "modern.config.ts"],
   "exclude": ["**/node_modules"]

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).