dev-booster 1.17.2 → 1.18.1

package/template/.devbooster/boosters/stack-refresh.md

@@ -60,6 +60,7 @@ Purpose:
 - run the correct `outdated` commands for the detected package manager and scope
 - run the correct audit/security commands when relevant
 - classify findings into safe, risky, and human-review categories
+- consult the knowledge base only for findings that match a concrete known pattern, following the finding-driven and read-only rules below
 - update the artifact with the detailed findings
 
 Stage 1 requires explicit user approval after Stage 0.
@@ -176,6 +177,25 @@ Load only after the user has approved update execution and validation is actuall
 - Do NOT load validation/test assets during Stage 0 mapping.
 - If evidence is missing, stay with the Stage 0 fixed base load only.
 
+### Knowledge Base Consultation — Finding-Driven and Read-Only
+Do not consult `.devbooster/hub/knowledge/` during Stage 0 mapping. Consult it only after Stage 1 identifies a concrete outdated package, security finding, runtime mismatch, configuration warning, compatibility issue, or migration surface.
+
+Do NOT read the entire knowledge base.
+
+For each relevant finding:
+1. Read `.devbooster/hub/knowledge/index.md`.
+2. Locate the matching article and section from the index.
+3. Read only that section using `read_file` with `start_line` and `end_line`.
+4. Read the official source linked by the article or section before recommending an update, migration path, or deferral.
+5. Reconcile the local pattern and official guidance with the actual package versions, package manager, lockfile, workspace topology, runtime, configuration, and dependency graph.
+
+The knowledge base is read-only. Never create, modify, append to, or otherwise maintain files in `.devbooster/hub/knowledge/` during Stack Refresh.
+
+### Knowledge Base Decision Traceability
+When a knowledge-base section materially informs an upgrade classification, migration path, deferral, or recommendation, record a complete `Knowledge Base Decision Trace` in the execution artifact: project convention observed, article and section consulted, official source, decision, rationale, and validation or follow-up.
+
+Keep chat concise: state the project convention, whether it was preserved or changed, and that the conclusion was validated against project context and official guidance. Do not dump article names, section names, or URLs unless the user asks. Never claim that the knowledge base or an official source was consulted unless the relevant local section and source were actually read during the current Stack Refresh.
+
 ## 4. PRE-FLIGHT DISCIPLINE
 Start working immediately on activation.
 

package/template/.devbooster/boosters/testing.md

@@ -52,6 +52,18 @@ Rules:
 - Prefer adding one relevant skill/persona at a time.
 - Keep the user inside the same booster mode while expanding context.
 
+## 0.3 KNOWLEDGE BASE CONSULTATION — CONDITIONAL AND READ-ONLY
+Consult `.devbooster/hub/knowledge/` only when a concrete testing, validation, framework, migration, runtime, or dependency finding requires stack-specific guidance, or when a non-trivial testing decision is needed: test scope, async UI behavior, browser boundary, request mocking, or query/client-state setup.
+
+Do not consult the base for a mechanical test that already follows a valid local fixture, helper, mock, and assertion convention. Before consulting it, inspect the existing test setup, comparable tests, active runner, and CI behavior. Do NOT read the entire knowledge base. Read `index.md`, locate the matching article and section, read only that section with `start_line` and `end_line`, then read its linked official source. Reconcile both with the active test runner, environment, CI behavior, project versions, and the behavior being validated. Preserve a valid project convention unless the developer requests a change or evidence shows it is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+The knowledge base is read-only. Never create, modify, append to, or otherwise maintain files in `.devbooster/hub/knowledge/` during testing work.
+
+### Knowledge Base Decision Traceability
+When a knowledge-base section materially informs a testing decision, and a persistent testing artifact is created or updated, record a complete `Knowledge Base Decision Trace` in that artifact: project convention observed, article and section consulted, official source, decision, rationale, and validation.
+
+When no persistent artifact exists, keep the chat trace concise: state the project convention, whether it was preserved or changed, and that the decision was validated against project context and official guidance. Do not dump article names, section names, or URLs unless the user asks. Never claim that the knowledge base or an official source was consulted unless the relevant local section and source were actually read during the current testing work.
+
 ## 1. ALLOWED INVENTORY
 - `.devbooster/hub/personas/agent_test-engineer.md`
 - `.devbooster/hub/personas/agent_qa-automation-engineer.md`

package/template/.devbooster/hub/knowledge/angular-patterns.md

@@ -0,0 +1,185 @@
+# Angular Patterns for Modern Applications
+
+> **Purpose:** Provide practical defaults for modern Angular applications.
+> **Primary official sources:** [Angular Overview](https://angular.dev/overview) · [Version Compatibility](https://angular.dev/reference/versions) · [Angular CLI](https://angular.dev/cli)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing abstractions, configuration, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+Practical defaults for current Angular applications. Prefer APIs documented at [angular.dev](https://angular.dev/) and verify framework, CLI, TypeScript, and RxJS support before an upgrade.
+
+## Contents
+
+- [1. Standalone composition and providers](#1-standalone-composition-and-providers)
+- [2. Dependency injection scopes](#2-dependency-injection-scopes)
+- [3. Signals and RxJS boundaries](#3-signals-and-rxjs-boundaries)
+- [4. Templates and change detection](#4-templates-and-change-detection)
+- [5. Reactive forms and validation](#5-reactive-forms-and-validation)
+- [6. HTTP interceptors and errors](#6-http-interceptors-and-errors)
+- [7. Lazy routes and guards](#7-lazy-routes-and-guards)
+- [8. Version, CLI, and TypeScript alignment](#8-version-cli-and-typescript-alignment)
+
+## 1. Standalone composition and providers
+
+**Problem:** New features depend on large shared modules, making dependencies and lazy-loading boundaries unclear.
+
+**Fix:** Use standalone components, directives, and pipes. Import only the template dependencies a component needs. Register application-wide services with `bootstrapApplication` and `ApplicationConfig`; register route-specific providers on the route when their lifetime should match that route subtree.
+
+```ts
+bootstrapApplication(AppComponent, {
+  providers: [provideRouter(routes), provideHttpClient()],
+});
+
+@Component({
+  standalone: true,
+  imports: [RouterLink],
+  template: `<a routerLink="/settings">Settings</a>`,
+})
+export class NavComponent {}
+```
+
+**Verify first:** Confirm that a provider is not already registered by a library or a parent injector. Duplicate registrations can create separate service instances.
+
+Sources: [Components](https://angular.dev/guide/components), [Dependency Injection](https://angular.dev/guide/di), [Routing providers](https://angular.dev/guide/routing/define-routes).
+
+## 2. Dependency injection scopes
+
+**Symptom:** State unexpectedly resets, leaks across users of a feature, or differs between eagerly and lazily loaded views.
+
+**Fix:** Choose scope intentionally.
+
+| Need | Provider location |
+| --- | --- |
+| One instance for the application | `@Injectable({ providedIn: 'root' })` |
+| One instance per component subtree | component `providers` |
+| One instance for a route and its child routes | route `providers` |
+
+Use `inject()` in an injection context when it makes dependencies clearer; use constructor injection where it improves the class API or compatibility with existing patterns. Avoid service locators and manually constructed services—Angular must create injected services to resolve their dependencies and lifecycle correctly.
+
+Source: [Hierarchical injectors](https://angular.dev/guide/di/hierarchical-dependency-injection).
+
+## 3. Signals and RxJS boundaries
+
+**Problem:** UI state and asynchronous streams are represented interchangeably, causing duplicate subscriptions or unclear ownership.
+
+**Fix:** Use signals for synchronous state consumed by templates or derived with `computed`. Keep RxJS for event streams, cancellation, timing, multicasting, and other asynchronous composition. Convert only at a clear boundary:
+
+- Use `toSignal()` when a template or signal-based state needs an Observable value.
+- Use `toObservable()` when signal changes need an Observable pipeline.
+- Prefer the `async` pipe for Observable values used only in a template.
+
+```ts
+readonly query = signal('');
+readonly normalizedQuery = computed(() => this.query().trim().toLowerCase());
+
+readonly results = toSignal(
+  this.search.search(this.normalizedQuery()),
+  { initialValue: [] },
+);
+```
+
+**Verify first:** `toSignal()` subscribes to its source. Do not call it repeatedly for the same stream, and provide an initial value unless the `undefined` state is explicitly valid. Model loading, empty, and error states rather than treating absence as an error.
+
+Sources: [Signals](https://angular.dev/guide/signals), [RxJS interop](https://angular.dev/ecosystem/rxjs-interop).
+
+## 4. Templates and change detection
+
+**Fix:** Use built-in control flow for new templates when it improves readability. Track stable identity in repeated collections.
+
+```html
+@if (user(); as currentUser) {
+  <h1>{{ currentUser.name }}</h1>
+} @else {
+  <p>Sign in to continue.</p>
+}
+
+@for (item of items(); track item.id) {
+  <app-item [item]="item" />
+} @empty {
+  <p>No items.</p>
+}
+```
+
+Signals read in an `OnPush` component template are tracked by Angular; when they change, Angular marks the component for update. Use `ChangeDetectionStrategy.OnPush` as a performance-oriented default for components with clear input and state boundaries. Do not mutate objects or arrays in place when consumers rely on reference changes; create updated values instead.
+
+**Verify first:** If a view is stale, identify whether its state changes through a signal, an input reference, an event, or an Observable consumed with `async` before adding manual change-detection calls.
+
+Sources: [Control flow](https://angular.dev/guide/templates/control-flow), [Signals in `OnPush` components](https://angular.dev/guide/signals#reading-signals-in-onpush-components), [Skipping component subtrees](https://angular.dev/best-practices/skipping-subtrees).
+
+## 5. Reactive forms and validation
+
+**Problem:** Validation is spread through templates, values are weakly typed, or submission accepts stale/invalid data.
+
+**Fix:** Use reactive forms for non-trivial forms. Define validators with the controls, show errors after an interaction or submission attempt, and check the form state before submitting. Prefer typed controls and `NonNullableFormBuilder` when `null` is not a meaningful form value.
+
+```ts
+readonly form = this.formBuilder.nonNullable.group({
+  email: ['', [Validators.required, Validators.email]],
+  password: ['', [Validators.required, Validators.minLength(12)]],
+});
+
+submit(): void {
+  if (this.form.invalid) {
+    this.form.markAllAsTouched();
+    return;
+  }
+  this.accountService.register(this.form.getRawValue());
+}
+```
+
+For server validation, map known field errors to the relevant control with `setErrors`; keep unexpected failures as form-level or page-level errors. Async validators must complete and should avoid issuing redundant requests.
+
+Sources: [Reactive forms](https://angular.dev/guide/forms/reactive-forms), [Form validation](https://angular.dev/guide/forms/form-validation).
+
+## 6. HTTP interceptors and errors
+
+**Fix:** Configure `HttpClient` with functional interceptors. Keep interceptors narrow: add authentication or tracing headers, normalize a cross-cutting response concern, or apply a documented retry policy. Re-throw errors after any contextual handling so the caller can decide how to present recovery.
+
+```ts
+export const authInterceptor: HttpInterceptorFn = (request, next) => {
+  const token = inject(AuthService).token();
+  const authorized = token
+    ? request.clone({ setHeaders: { Authorization: `Bearer ${token}` } })
+    : request;
+
+  return next(authorized).pipe(
+    catchError((error: HttpErrorResponse) => {
+      inject(ErrorReporter).report(error);
+      return throwError(() => error);
+    }),
+  );
+};
+```
+
+Register order deliberately: request processing follows interceptor order, while responses travel back through the chain. Handle request-specific messages near the calling feature; reserve interceptors for reusable transport policy. Do not retry non-idempotent requests without an explicit server-side safety guarantee.
+
+Sources: [HTTP interceptors](https://angular.dev/guide/http/interceptors), [Making requests](https://angular.dev/guide/http/making-requests).
+
+## 7. Lazy routes and guards
+
+**Fix:** Lazy-load feature routes with `loadChildren` and standalone screens with `loadComponent`. Use functional guards for navigation policy and return a `UrlTree` or `RedirectCommand` for redirects rather than navigating imperatively from a guard.
+
+```ts
+export const routes: Routes = [
+  {
+    path: 'reports',
+    loadChildren: () => import('./reports/reports.routes').then((m) => m.REPORT_ROUTES),
+    canActivate: [() => inject(AuthService).isAuthenticated() || inject(Router).parseUrl('/login')],
+  },
+];
+```
+
+**Verify first:** Client-side guards are not authorization. Enforce access control on the server or API as well. Confirm the intended guard type: `canMatch` affects route matching, while `canActivate` controls activation after a route is selected.
+
+Sources: [Define routes](https://angular.dev/guide/routing/define-routes), [Route guards](https://angular.dev/guide/routing/route-guards), [Lazy loading](https://angular.dev/guide/ngmodules/lazy-loading).
+
+## 8. Version, CLI, and TypeScript alignment
+
+**Problem:** An Angular update fails with peer-dependency or compiler errors, or a generated project differs from repository conventions.
+
+**Verify first:** Check the official [version compatibility table](https://angular.dev/reference/versions) for the supported Node.js, TypeScript, and RxJS ranges of the target Angular version. Check the installed CLI with `ng version`; use the workspace’s package manager and lockfile rather than globally installed tooling as the source of truth.
+
+**Fix:** Upgrade Angular packages and the Angular CLI using the official [Update Guide](https://angular.dev/update-guide), selecting the current and target versions. Make the required TypeScript and Node.js changes before addressing application-level migration output. Run the repository’s build, tests, and lint commands after each upgrade step.
+
+Source: [Angular CLI](https://angular.dev/tools/cli), [Version compatibility](https://angular.dev/reference/versions), [Update Guide](https://angular.dev/update-guide).

package/template/.devbooster/hub/knowledge/dependency-guide.md

@@ -0,0 +1,175 @@
+# 📦 Dependency Guide
+
+> **Purpose:** Decision model for safe dependency updates and audit interpretation
+> **Primary official sources:** [npm CLI documentation](https://docs.npmjs.com/cli/) · [Yarn documentation](https://yarnpkg.com/) · [pnpm documentation](https://pnpm.io/)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing abstractions, configuration, lockfile, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Table of Contents
+
+1. [Safe-Update Decision Model](#safe-update-decision-model)
+2. [Eligible vs Non-Eligible — Examples](#eligible-vs-non-eligible)
+3. [Method for Analyzing Dependency Usage](#method-for-analyzing-dependency-usage)
+4. [Audit Interpretation Rules](#audit-interpretation-rules)
+5. [Package Manager Behavior](#package-manager-behavior)
+6. [Validation Hierarchy](#validation-hierarchy)
+
+---
+
+## Safe-Update Decision Model
+
+### Conditions for considering an update "safe"
+
+A dependency is eligible for a safe update **only when ALL of the following conditions are true**:
+
+1. **Same major version** — the update stays within the same major version (including a patch or minor update) and the upstream release notes do not identify an incompatible change
+2. **No coupled migration** — it is not part of a known migration family that requires source code adaptation
+3. **Role understood** — the dependency's role is known: runtime, build, types, or security
+4. **Validation path exists** — the project exposes a validation path capable of detecting obvious fallout (lint, build, typecheck)
+5. **No forced operations** — the update does not require lockfile override, `resolutions`, codemod, global rewrite, or behavior not supported by the package manager
+
+### Golden rule
+If any condition fails, the update goes to deeper analysis.
+
+---
+
+## Eligible vs Non-Eligible
+
+### Eligible (safe update)
+| Category | Example | Reason |
+|---|---|---|
+| Same-major minor | `next 16.1.x → 16.2.x` | Eligible for release-note review and validation; not inherently free of breaking behavior |
+| Coupled packages | `react + react-dom` | Update together within compatible major versions |
+| Security priority | `axios 1.x → 1.y` | Same-major security update; confirm the advisory path and release notes |
+| Bounded same-major | `@tanstack/react-query 5.x → 5.y` | Same-major update with targeted validation |
+
+### Non-Eligible (requires deep analysis)
+| Dependency | Reason |
+|---|---|
+| `tailwindcss 3 → 4` | Breaking change, config migration |
+| `Chakra UI 2 → 3` | Breaking change, component rewrite |
+| `TypeScript 5 → 7` | Two majors, high risk |
+| `ESLint 9 → 10` | Config breaking change |
+| `Zustand 4 → 5` | API breaking change |
+| `date-fns 2 → 4` | Two majors, breaking changes |
+
+---
+
+## Method for Analyzing Dependency Usage
+
+### Four layers of evidence
+
+Before recommending an update or removal, use these 4 layers:
+
+1. **Runtime import evidence**
+   - Search the code for imports/requires and API calls
+   ```bash
+   rg -n --glob '*.{js,jsx,ts,tsx,mjs,cjs}' \
+     "from ['\"]package-name['\"]|import ['\"]package-name['\"]|require\(['\"]package-name['\"]|import\(['\"]package-name['\"]" src/
+   ```
+   - Also check aliases, generated code, and configuration files; source searches alone are not conclusive.
+
+2. **Framework/config evidence**
+   - Inspect: framework config, PostCSS/Tailwind, ESLint, scripts, Docker, CI
+   - The dependency may be in use even without a direct import in source
+
+3. **Type-system evidence**
+   - Inspect `tsconfig.json`, exported types
+   - Packages that only provide types (e.g., `@types/*`) have no runtime import
+
+4. **Dependency provenance**
+   - Use `yarn why <package>` / `npm ls <package>` / `pnpm why <package>`
+   - Check whether it's a direct or transitive dependency
+
+### Result classification
+
+| Classification | Meaning | Action |
+|---|---|---|
+| **Runtime confirmed** | Direct import/call in source | Do not remove |
+| **Tooling confirmed** | Used by scripts/config/build | Do not remove without checking scripts |
+| **Indirect only** | Required by framework/chain | Check if framework still needs it |
+| **Removal candidate** | No direct or indirect evidence | Remove with validation |
+
+### Generic example
+A package like `sharp` may be listed in `package.json` but have no direct import in source — it may be used internally by the framework (e.g., Next.js uses `sharp` for image optimization). **In this case, even without a direct import, do not remove it without confirming whether the framework still uses it.**
+
+---
+
+## Audit Interpretation Rules
+
+### Rules for interpreting `npm audit` / `yarn audit`
+
+1. **Audit count ≠ business risk**
+   - A package may emit multiple advisories and paths
+   - The number of findings is not the number of independent risks
+
+2. **Root upgrade does not patch nested framework copy**
+   - Root `sharp@0.35` can coexist with `next#sharp@0.34`
+   - Root `postcss@8.5` can coexist with `next#postcss@8.4`
+   - Updating the root does not necessarily resolve the nested copy
+
+3. **Always cross-reference audit output with provenance**
+   ```bash
+   yarn why <package>
+   npm ls <package>
+   ```
+   Inspect the upstream package's `package.json` when necessary.
+
+4. **Classify risk separately**
+   - Findings in toolchain (eslint, webpack, etc.) may be **build-time risk**, not runtime
+   - Do not ignore — classify exposure and remediation separately
+
+5. **Do not add resolutions/overrides just to lower audit count**
+   - Overriding an internal framework range is a policy decision
+   - Requires compatibility validation and explicit approval
+
+---
+
+## Package Manager Behavior
+
+### Yarn Classic (1.x)
+
+| Command | Important behavior |
+|---|---|
+| `yarn outdated` | Exit code `1` when there are updates — **not an error**, it's a sign of findings |
+| `yarn audit --level moderate` | Returns a severity bitmask: info `1`, low `2`, moderate `4`, high `8`, critical `16`; `--level` filters displayed findings but does not change the exit code |
+| `yarn outdated` | Lists current, wanted, and latest versions; it does not diagnose lockfile synchronization |
+| Peer warnings | May exist even with lint/build passing (e.g., React 18 peer range in libs) |
+
+If `package.json` changes, run `yarn install` serially to update `yarn.lock`. In CI, use the project's frozen/immutable lockfile policy to detect unexpected lockfile changes.
+
+### Mandatory serialization
+**Never** run two commands that write to the lockfile in parallel:
+```bash
+# ❌ WRONG: parallel
+yarn add package-a & yarn add package-b
+
+# ✅ CORRECT: serialized
+yarn add package-a
+yarn add package-b
+```
+
+Serialize `install`, `add`, `remove`, and equivalents to avoid:
+- Lockfile races
+- Non-deterministic state
+- Loss of updates
+
+---
+
+## Validation Hierarchy
+
+### Available validation matrix
+
+| Validation | What it proves | Limitation |
+|---|---|---|
+| `lint` | Lint config works, no errors | Does not exercise runtime |
+| `build` | The configured production build pipeline (for example, bundling and framework configuration) | Type checking, route coverage, and generated output depend on the project's toolchain and settings; does not verify external APIs or UX |
+| Dedicated typecheck | Type errors (faster than build) | May not exist as a separate script |
+| Automated tests | Regression of behavior | May not exist |
+| Manual smoke test | UX and integration | Requires human execution |
+
+---

package/template/.devbooster/hub/knowledge/eslint-migration.md

@@ -0,0 +1,206 @@
+# 🧹 ESLint Migration
+
+> **Purpose:** Migration guidance and common issues for ESLint 9+ and flat config
+> **Primary official sources:** [ESLint configuration migration guide](https://eslint.org/docs/latest/use/configure/migration-guide) · [ESLint configuration files](https://eslint.org/docs/latest/use/configure/configuration-files) · [Next.js ESLint plugin](https://nextjs.org/docs/app/api-reference/config/eslint)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing abstractions, configuration, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Table of Contents
+
+1. [ESLint 9 — Flat Config by Default](#eslint-9--flat-config-by-default)
+2. [Basic JavaScript + React Hooks Config](#basic-javascript--react-hooks-config)
+3. [Configuration for Next.js](#configuration-for-nextjs)
+4. [ESLint-level Masking](#eslint-level-masking)
+5. [Inline Suppressions](#inline-suppressions)
+6. [reportUnusedDisableDirectives](#reportunuseddisabledirectives)
+7. [Resolutions Affecting the Toolchain](#resolutions-affecting-the-toolchain)
+8. [Legacy Config Mode in ESLint 9](#legacy-config-mode-in-eslint-9)
+
+---
+
+## ESLint 9 — Flat Config by Default
+
+### Status
+Flat config (`eslint.config.*`) is the default configuration format in ESLint 9. Legacy `.eslintrc.*` configuration can still be used in ESLint 9 by setting `ESLINT_USE_FLAT_CONFIG=false`, but that mode is deprecated and is removed in ESLint 10.
+
+### Supported config files
+| File | Type |
+|---|---|
+| `eslint.config.js` | ESM or CommonJS, based on `package.json` |
+| `eslint.config.mjs` | ESM |
+| `eslint.config.cjs` | CommonJS |
+| `eslint.config.ts` | TypeScript; requires `jiti` or enabled native Node.js TypeScript support |
+| `eslint.config.mts` | TypeScript ESM; requires the same TypeScript support |
+| `eslint.config.cts` | TypeScript CommonJS; requires the same TypeScript support |
+
+For Node.js, TypeScript config files require `jiti` or Node's explicitly enabled native TypeScript support. Node 22.13+ alone is not sufficient without the documented TypeScript-stripping and ESLint feature flags.
+
+### Migration checklist
+1. Create `eslint.config.*` at the project root.
+2. Use `@eslint/migrate-config` as a starting point where applicable, then review the result.
+3. Move `.eslintignore` patterns into a flat-config `ignores` object; flat config does not load `.eslintignore` automatically.
+4. For Next.js 16+, replace `next lint` with the ESLint CLI.
+5. Run `eslint .` and use `eslint --inspect-config <file>` to verify important files receive the intended rules.
+6. Update incompatible plugins or use the documented compatibility utilities where necessary.
+7. Remove `.eslintrc.*` and `.eslintignore` only after the flat configuration is verified in local development and CI.
+
+---
+
+## Basic JavaScript + React Hooks Config
+
+This example is for JavaScript and JSX only. To lint TypeScript, add a TypeScript parser/configuration such as the [official typescript-eslint flat-config setup](https://typescript-eslint.io/getting-started/); merely adding `*.ts` or `*.tsx` file patterns does not parse TypeScript.
+
+```js
+// eslint.config.js
+import { defineConfig } from "eslint/config";
+import js from "@eslint/js";
+import pluginReactHooks from "eslint-plugin-react-hooks";
+
+export default defineConfig([
+  {
+    files: ["**/*.{js,jsx,mjs,cjs}"],
+    plugins: { js },
+    extends: ["js/recommended"],
+    rules: {
+      semi: "error",
+      "no-unused-vars": "warn",
+    },
+  },
+  {
+    files: ["**/*.jsx"],
+    plugins: { "react-hooks": pluginReactHooks },
+    rules: {
+      "react-hooks/rules-of-hooks": "error",
+      "react-hooks/exhaustive-deps": "warn",
+    },
+  },
+]);
+```
+
+---
+
+## Configuration for Next.js
+
+For a TypeScript Next.js application, use the documented Next.js flat configs. Omit `nextTs` for a JavaScript-only project.
+
+```js
+// eslint.config.mjs
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+export default defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores([
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+```
+
+---
+
+## ESLint-level Masking
+
+### Problem
+Broad disables and ignore patterns can hide problems, but scoped exceptions are sometimes appropriate for generated code, fixtures, or unsupported environments.
+
+### Risky patterns
+```js
+// Broad global rule disables require a documented reason.
+const config = {
+  rules: {
+    "react-hooks/exhaustive-deps": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+  },
+};
+```
+
+### Handling
+- Prefer the narrowest rule override, file pattern, or inline suppression that addresses the specific case.
+- Keep test source linted by default; ignore only generated fixtures, vendor assets, or other verified non-source inputs.
+- Document why an exception is needed and review it when dependencies or code change.
+
+---
+
+## Inline Suppressions
+
+### Problem
+Comments that suppress ESLint or TypeScript rules need review. Some are legitimate, but each should have a narrow scope and an explanation where the reason is not obvious.
+
+### Most common patterns
+```ts
+// @ts-ignore
+// @ts-expect-error — reports an error if no longer needed
+// @ts-nocheck — disables type checking for the entire file
+// eslint-disable-next-line react-hooks/exhaustive-deps
+```
+
+### How to handle during audit
+1. Count and classify suppressions by type.
+2. Replace `@ts-ignore` with `@ts-expect-error` when an expected error must remain; fix the type when practical.
+3. Do not remove `@ts-nocheck` without reviewing the full file, especially generated code or third-party declarations.
+4. For `exhaustive-deps`, determine whether the dependency can be added safely before suppressing the rule.
+
+---
+
+## reportUnusedDisableDirectives
+
+### Problem
+Disable comments that no longer suppress a finding remain as clutter and can conceal whether an exception is still needed.
+
+*Source: [ESLint configuration files — Report Unused Disable Directives](https://eslint.org/docs/latest/use/configure/configuration-files#report-unused-disable-directives)*
+
+### Fix
+```js
+// eslint.config.js
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  {
+    linterOptions: {
+      reportUnusedDisableDirectives: "error",
+    },
+  },
+]);
+```
+
+### Why use it
+- Detects suppressions that are no longer needed.
+- Helps clean up code as rules evolve.
+- The default is `"warn"`; using `"error"` makes cleanup enforceable in CI.
+
+---
+
+## Resolutions Affecting the Toolchain
+
+### Problem
+Yarn `resolutions`, npm `overrides`, and `pnpm.overrides` can alter transitive dependencies used by development tools. A broad or incompatible override can break ESLint and related tooling.
+
+### Handling
+1. Remove overrides that are no longer needed.
+2. Document the dependency path and reason for every retained override.
+3. Inspect the dependency tree with the package manager in use:
+```bash
+npm ls ajv
+yarn why ajv
+pnpm why ajv
+```
+4. Run linting and the relevant test/build commands after changing an override.
+
+---
+
+## Legacy Config Mode in ESLint 9
+
+### Status
+In ESLint 9, `ESLINT_USE_FLAT_CONFIG=false` can temporarily enable legacy `.eslintrc.*` configuration. ESLint marks that mode as deprecated; it is not available in ESLint 10.
+
+### Guidance
+Use legacy mode only as a time-bounded compatibility measure while migrating. Verify plugin and shareable-config compatibility in the actual project, then move to flat config before upgrading to ESLint 10.