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

package/template/oxlint.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "oxlint";
+import core from "ultracite/oxlint/core";
+import react from "ultracite/oxlint/react";
+
+export default defineConfig({
+  env: {
+    browser: true,
+    node: true,
+  },
+  extends: [core, react],
+  ignorePatterns: ["dist", "node_modules", ".modern", ".modernjs", "**/routeTree.gen.ts"],
+});

package/template/package.json.handlebars

@@ -6,8 +6,14 @@
     "dev": "modern dev",
     "build": "modern build",
     "serve": "modern serve",
-    "ultramodern:check": "node ./scripts/validate-ultramodern.mjs"{{#unless isSubproject}},
-    "lint": "biome check",
+    "typecheck": "node -e \"const fs = require('node:fs'); const { execFileSync, spawnSync } = require('node:child_process'); const bin = execFileSync('effect-tsgo', ['get-exe-path'], { encoding: 'utf8' }).trim(); if (process.platform !== 'win32') fs.chmodSync(bin, 0o755); const result = spawnSync(bin, ['--noEmit', '-p', 'tsconfig.json'], { stdio: 'inherit' }); process.exit(result.status ?? 1);\"",
+    "skills:install": "node ./scripts/bootstrap-agent-skills.mjs",
+    "skills:check": "node ./scripts/bootstrap-agent-skills.mjs --check",
+    "ultramodern:check": "{{#unless isSubproject}}pnpm format:check && pnpm lint && {{/unless}}pnpm typecheck{{#unless isSubproject}} && pnpm skills:check{{/unless}} && node ./scripts/validate-ultramodern.mjs"{{#unless isSubproject}},
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint . --fix",
     "prepare": "simple-git-hooks"{{/unless}}
   },
   "engines": {
@@ -15,31 +21,35 @@
   }{{#unless isSubproject}},
   "lint-staged": {
     "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}": [
-      "biome check --files-ignore-unknown=true"
+      "oxfmt --write",
+      "oxlint --fix"
     ]
   },
   "simple-git-hooks": {
     "pre-commit": "npx lint-staged"
   }{{/unless}},
   "dependencies": {
-    "@modern-js/runtime": "{{version}}"{{#if isTanstackRouter}},
-    "@modern-js/plugin-tanstack": "{{version}}",
+    "@modern-js/runtime": "{{runtimeVersion}}"{{#if isTanstackRouter}},
+    "@modern-js/plugin-tanstack": "{{pluginTanstackVersion}}",
     "@tanstack/react-router": "1.170.1"{{/if}},
     "react": "^19.2.3",
     "react-dom": "^19.2.0"
   },
   "devDependencies": {
-    "@modern-js/app-tools": "{{version}}",
-    "@modern-js/tsconfig": "{{version}}"{{#if enableBff}},
-    "@modern-js/plugin-bff": "{{version}}"{{/if}}{{#if enableTailwind}},
+    "@modern-js/app-tools": "{{appToolsVersion}}",
+    "@modern-js/tsconfig": "{{tsconfigVersion}}"{{#if enableBff}},
+    "@modern-js/plugin-bff": "{{pluginBffVersion}}"{{/if}}{{#if enableTailwind}},
     "@tailwindcss/postcss": "^4.1.18",
     "postcss": "^8.5.6",
-    "tailwindcss": "^4.1.18"{{/if}}{{#unless isSubproject}},
-    "@biomejs/biome": "1.9.4"{{/unless}},
-    "@typescript/native-preview": "7.0.0-dev.20260516.1",
+    "tailwindcss": "^4.1.18"{{/if}},
+    "@effect/tsgo": "0.7.3",
+    "@typescript/native-preview": "7.0.0-dev.20260518.1",
     "@types/node": "^20",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6"{{#unless isSubproject}},
+    "oxlint": "1.65.0",
+    "oxfmt": "0.50.0",
+    "ultracite": "7.7.0",
     "lint-staged": "~15.4.0",
     "simple-git-hooks": "^2.11.1"{{/unless}},
     "rimraf": "^6.0.1"

package/template/scripts/bootstrap-agent-skills.mjs

@@ -0,0 +1,103 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const root = process.cwd();
+const lockPath = path.join(root, '.agents/skills-lock.json');
+const checkOnly = process.argv.includes('--check');
+const force = process.argv.includes('--force');
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function run(command, args, options = {}) {
+  return execFileSync(command, args, {
+    cwd: options.cwd ?? root,
+    encoding: 'utf8',
+    stdio: options.stdio ?? ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function cloneSource(source, targetDir) {
+  const repo = source.repository.replace(/^https:\/\/github.com\//, '');
+  try {
+    run('gh', ['repo', 'clone', repo, targetDir, '--', '--depth', '1'], {
+      stdio: 'inherit',
+    });
+    return;
+  } catch {
+    run('git', ['clone', '--depth', '1', source.repository, targetDir], {
+      stdio: 'inherit',
+    });
+  }
+}
+
+function resolveSkillDir(sourceRoot, skillName) {
+  const candidates = [
+    path.join(sourceRoot, skillName),
+    path.join(sourceRoot, 'skills', skillName),
+    path.join(sourceRoot, 'skills', 'engineering', skillName),
+    path.join(sourceRoot, 'skills', 'productivity', skillName),
+  ];
+  return candidates.find(candidate =>
+    fs.existsSync(path.join(candidate, 'SKILL.md')),
+  );
+}
+
+if (!fs.existsSync(lockPath)) {
+  console.error('Missing .agents/skills-lock.json');
+  process.exit(1);
+}
+
+const lock = readJson(lockPath);
+const installDir = path.join(root, lock.installDir ?? '.agents/skills');
+const privateSources = (lock.sources ?? []).filter(
+  source => source.install === 'clone-if-authorized',
+);
+
+if (checkOnly) {
+  const missing = privateSources.flatMap(source =>
+    (source.baseline ?? [])
+      .map(skill => skill.name)
+      .filter(skillName => !fs.existsSync(path.join(installDir, skillName, 'SKILL.md'))),
+  );
+  if (missing.length > 0) {
+    console.warn(
+      `Private skills not installed: ${missing.join(', ')}. Run pnpm skills:install if you have access.`,
+    );
+  } else {
+    console.log('Agent skills are installed.');
+  }
+  process.exit(0);
+}
+
+fs.mkdirSync(installDir, { recursive: true });
+
+for (const source of privateSources) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ultramodern-skills-'));
+  try {
+    cloneSource(source, tempDir);
+    for (const skill of source.baseline ?? []) {
+      const sourceSkillDir = resolveSkillDir(tempDir, skill.name);
+      if (!sourceSkillDir) {
+        throw new Error(
+          `Skill ${skill.name} not found in ${source.repository}`,
+        );
+      }
+      const targetSkillDir = path.join(installDir, skill.name);
+      if (fs.existsSync(targetSkillDir)) {
+        if (!force) {
+          console.log(`Skipping existing ${skill.name}`);
+          continue;
+        }
+        fs.rmSync(targetSkillDir, { recursive: true, force: true });
+      }
+      fs.cpSync(sourceSkillDir, targetSkillDir, { recursive: true });
+      console.log(`Installed ${skill.name}`);
+    }
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}

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

@@ -52,8 +52,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');
 }
@@ -99,4 +113,74 @@ if (manifestErrors.length > 0) {
   process.exit(1);
 }
 
+const packageJson = JSON.parse(
+  fs.readFileSync(path.resolve(process.cwd(), 'package.json'), 'utf8'),
+);
+const unresolvedTemplateMarker = '{' + '{';
+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'),
+    'utf8',
+  ),
+);
+const requiredScripts = {
+  format: 'oxfmt .',
+  'format:check': 'oxfmt --check .',
+  lint: 'oxlint .',
+  'lint:fix': 'oxlint . --fix',
+  'skills:install': 'node ./scripts/bootstrap-agent-skills.mjs',
+  'skills:check': 'node ./scripts/bootstrap-agent-skills.mjs --check',
+};
+
+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/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).