dev-booster 1.18.0 → 1.18.1

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

@@ -0,0 +1,137 @@
+# 🚚 Migration Guides
+
+> **Purpose:** Migration guides for specific libraries with breaking changes observed in real projects
+> **Primary official sources:** [react-to-print repository](https://github.com/MatthewHerbst/react-to-print) · [React documentation](https://react.dev/) · [Radix UI documentation](https://www.radix-ui.com/) · [shadcn/ui documentation](https://ui.shadcn.com/docs)
+
+## 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.
+
+---
+
+## Index
+
+1. [react-to-print v2 → v3](#react-to-print-v2--v3)
+2. [Formik + React 19 — HTML Form Types](#formik--react-19)
+3. [Radix UI — Meta-package vs Individual Packages](#radix-ui-meta-package)
+4. [shadcn/ui — Missing Dependencies](#shadcn-ui-missing-dependencies)
+
+---
+
+## react-to-print v2 → v3
+
+### Problem
+The `useReactToPrint` API changed significantly from v2 to v3. The `content` option was renamed to `contentRef` and now receives a ref object rather than a callback.
+
+### Code (symptom)
+```tsx
+// BEFORE (v2)
+useReactToPrint({ content: () => ref.current })
+
+// AFTER (v3)
+useReactToPrint({ contentRef: ref })
+```
+
+### Expected type error
+```
+'content' does not exist in type 'UseReactToPrintOptions'
+```
+
+### Fix
+```tsx
+const contentRef = useRef<HTMLDivElement>(null)
+const print = useReactToPrint({ contentRef })
+
+// Attach contentRef to the element to print, then call print from the print trigger.
+```
+
+### Scope
+The documented v3 breaking change is the rename and type change from `content` to `contentRef`. Review the v3 migration notes for its other breaking changes.
+
+---
+
+## Formik + React 19
+
+### Problem
+React 19 form type errors can result from misaligned `react`, `react-dom`, and `@types/react` versions, including duplicate React type packages. Do not assume that a Formik version alone is the cause.
+
+### Type error
+```
+Type '{ children: Element; }' is missing the following properties from type
+'Pick<DetailedHTMLProps<FormHTMLAttributes<HTMLFormElement>, ...>':
+placeholder, onPointerEnterCapture, onPointerLeaveCapture
+```
+
+### Check first
+1. Align the installed `react`, `react-dom`, `@types/react`, and `@types/react-dom` versions.
+2. Inspect the lockfile and dependency tree for duplicate or incompatible React type packages.
+3. Re-run type checking before changing form markup.
+
+### Native form fallback
+Use a native `<form>` only when type alignment does not resolve the issue, and preserve the semantics provided by Formik's `<Form>`:
+
+```tsx
+<form
+  onReset={formik.handleReset}
+  onSubmit={formik.handleSubmit}
+  {...formProps}
+>
+  {children}
+</form>
+```
+
+Preserve any required forwarded props and refs. `noValidate` is a standard HTML form attribute and can be passed directly when needed.
+
+---
+
+## Radix UI Meta-package
+
+### Problem
+A component can import either the unified `radix-ui` package or an individual `@radix-ui/react-*` package. The required installation depends on the actual import specifier in the component source.
+
+### Symptom
+```
+Cannot find module 'radix-ui'
+```
+
+### Choose the matching package
+```bash
+# Source imports from "radix-ui"
+yarn add radix-ui
+
+# Source imports from "@radix-ui/react-dialog"
+yarn add @radix-ui/react-dialog
+```
+
+### Migration
+For existing shadcn/ui components that use individual Radix imports, use the documented Radix migration to rewrite imports before removing individual packages. Do not add the unified package solely because another component uses a different import style.
+
+---
+
+## shadcn/ui — Missing Dependencies
+
+### Problem
+The standard shadcn CLI installs the dependencies required by the component it adds. Manually copied components, custom registries, or incomplete installs may still reference packages that are absent.
+
+### Component-specific patterns
+- `class-variance-authority` — only when the component calls `cva()`
+- `tailwind-merge` — only when the project utility imports it
+- `lucide-react` — only when the component imports Lucide icons
+- `tailwindcss-animate` — legacy Tailwind v3 animation plugin
+- `tw-animate-css` — Tailwind v4 animation package
+
+### Fix
+Inspect the component imports and registry metadata, then install only the missing direct dependency. For animations, match the package to the Tailwind version:
+
+```bash
+# Tailwind v3
+yarn add -D tailwindcss-animate
+
+# Tailwind v4
+yarn add -D tw-animate-css
+```
+
+### Missing dependency symptom
+```
+Cannot find module 'class-variance-authority'
+```

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

@@ -0,0 +1,121 @@
+# Monorepo Patterns
+
+> **Purpose:** Keep workspace packages, dependency resolution, shared configuration, and task execution reproducible in JavaScript/TypeScript monorepos.
+> **Primary official sources:** [npm workspaces](https://docs.npmjs.com/cli/v11/using-npm/workspaces) · [Yarn workspaces](https://yarnpkg.com/features/workspaces) · [pnpm workspaces](https://pnpm.io/workspaces) · [Turborepo documentation](https://turborepo.com/docs) · [Nx documentation](https://nx.dev/)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing abstractions, configuration, lockfile, workspace layout, 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. [Workspace Package Boundaries](#workspace-package-boundaries)
+2. [Declared Dependencies and Phantom Dependencies](#declared-dependencies-and-phantom-dependencies)
+3. [Shared Configuration Resolution](#shared-configuration-resolution)
+4. [Task Runner Cache Hygiene](#task-runner-cache-hygiene)
+5. [Workspace-Aware Commands](#workspace-aware-commands)
+6. [Lockfile and Root Toolchain Consistency](#lockfile-and-root-toolchain-consistency)
+
+---
+
+## Workspace Package Boundaries
+
+### Symptom
+A package imports source files from another package's internals, builds only by accident, or cannot be independently published, tested, or consumed.
+
+### Verify first
+Check each workspace's `package.json`: `name`, `private`, `exports` (when published), build output, and declared dependencies. Verify that consumers import the package's public name rather than a relative path into its source tree. Workspace discovery is manager-specific; see [npm workspaces](https://docs.npmjs.com/cli/v11/using-npm/workspaces), [Yarn workspaces](https://yarnpkg.com/features/workspaces), and [pnpm workspaces](https://pnpm.io/workspaces).
+
+### Fix
+- Give each independently consumed unit an explicit package boundary and public API.
+- Import internal packages by package name, not by relative paths that bypass packaging and export rules.
+- Mark packages not intended for publication as `private`.
+- Keep generated output, package entry points, and export maps consistent with the files produced by the package build.
+
+---
+
+## Declared Dependencies and Phantom Dependencies
+
+### Symptom
+A package builds locally but fails in isolation, after a clean install, or when consumed outside the repository.
+
+### Problem
+The package imports a dependency that is only available because another workspace or a hoisted install placed it nearby. This is a phantom dependency.
+
+### Fix
+- Declare every runtime, build-time, and type dependency in the package that directly imports it, using the appropriate dependency section.
+- Declare internal workspace relationships explicitly and use the package manager's supported workspace protocol where applicable.
+- Do not rely on hoisting layout, transitive dependencies, or root-level tooling to make an import resolve.
+
+### Verify first
+Install from a clean checkout and test/build the affected workspace directly. For publishable packages, validate the packed artifact in a clean temporary consumer. pnpm explains why workspace linking and protocol use are explicit in [workspace settings](https://pnpm.io/workspaces#workspace-protocol-workspace).
+
+---
+
+## Shared Configuration Resolution
+
+### Symptom
+A linter, TypeScript compiler, test runner, or bundler behaves differently when launched from the root versus a workspace.
+
+### Verify first
+Determine which config file is found, the current working directory, and whether plugins/presets resolve from the root, the workspace, or the config package. Check the tool's own configuration-resolution documentation before moving files or adding duplicate dependencies.
+
+### Fix
+- Make shared configuration a versioned workspace package or a clearly owned root configuration, according to the consuming tool's resolution model.
+- Reference shared config through supported package/config mechanisms rather than brittle relative paths when the tool supports it.
+- Put plugins and parsers where the resolver expects them; do not depend on incidental hoisting.
+- Run configuration-sensitive commands from the same scope in local development and CI.
+
+For TypeScript project structure and references, use the [TypeScript project references handbook](https://www.typescriptlang.org/docs/handbook/project-references.html).
+
+---
+
+## Task Runner Cache Hygiene
+
+### Symptom
+A cached task returns stale output, misses a required rebuild after configuration changes, or appears successful without producing expected artifacts.
+
+### Verify first
+For the affected task, list its declared inputs, environment variables, dependency tasks, outputs, working directory, and cache mode. Turborepo documents task inputs/outputs and caching in [Turborepo caching](https://turborepo.com/docs/crafting-your-repository/caching); Nx documents inputs and task caching in [Nx cache inputs](https://nx.dev/concepts/how-caching-works#inputs).
+
+### Fix
+- Declare outputs precisely so restored cache artifacts match what downstream tasks consume.
+- Include relevant source, lockfile, configuration, generated-schema, and environment inputs in the cache definition.
+- Exclude secrets from cache keys and outputs; use non-secret version markers when configuration must affect caching.
+- Make task dependencies explicit rather than relying on execution order or existing files.
+- Clear or bypass cache only to diagnose incorrect cache inputs; repair the task definition before re-enabling it.
+
+---
+
+## Workspace-Aware Commands
+
+### Symptom
+A command runs in every package, runs only at the root, resolves the wrong binary, or changes dependencies in an unintended workspace.
+
+### Verify first
+Use the package manager's workspace-listing capability and confirm the target package name. Review the exact command's workspace flags rather than assuming equivalent syntax across managers. npm provides [workspace command guidance](https://docs.npmjs.com/cli/v11/using-npm/workspaces#running-commands-in-the-context-of-workspaces).
+
+### Fix
+- Prefer explicit workspace/package selectors for focused install, run, test, and build commands.
+- Use recursive/all-workspace execution only when the task is designed to be independent or ordered by declared dependencies.
+- Keep root scripts as orchestration entry points and package scripts as package-local behavior.
+- In CI, log the selected workspace and command to make scope errors visible.
+
+---
+
+## Lockfile and Root Toolchain Consistency
+
+### Problem
+Different packages or CI jobs use different package-manager versions, lockfile policies, Node versions, or root tool versions, producing incompatible dependency trees and task results.
+
+### Fix
+- Maintain a single root lockfile and use the repository's declared package manager everywhere.
+- Pin or otherwise declare the package-manager version with the repository-supported mechanism; Corepack recognizes `packageManager` metadata. See [Node.js Corepack](https://nodejs.org/docs/latest/api/corepack.html).
+- Align Node selection across local development, CI, and containers with the root `engines` policy.
+- Put monorepo-wide task-runner and shared-tool configuration under clear root ownership.
+- Validate CI with a non-mutating install mode, then execute workspace-aware checks from a clean checkout.
+
+### Verify first
+Confirm that a clean clone has one expected lockfile, uses the intended manager/runtime, and completes a focused package build followed by the repository's dependency-aware build. Any lockfile modification during validation is a reproducibility failure to investigate, not a change to commit automatically.

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

@@ -0,0 +1,185 @@
+# NestJS Patterns
+
+> **Purpose:** Practical patterns for dependable NestJS application boundaries.
+> **Primary official sources:** [Nest modules](https://docs.nestjs.com/modules) · [Nest providers](https://docs.nestjs.com/providers) · [Nest validation](https://docs.nestjs.com/techniques/validation) · [Nest authentication](https://docs.nestjs.com/security/authentication) · [Nest exception filters](https://docs.nestjs.com/exception-filters) · [Nest configuration](https://docs.nestjs.com/techniques/configuration)
+
+## 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. [Module and Provider Visibility](#module-and-provider-visibility)
+2. [Circular Dependencies and forwardRef](#circular-dependencies-and-forwardref)
+3. [Validation Pipes and DTO Transformation](#validation-pipes-and-dto-transformation)
+4. [Authentication Guards and Execution Context](#authentication-guards-and-execution-context)
+5. [Global Exception Filters and Error Contracts](#global-exception-filters-and-error-contracts)
+6. [Configuration and Environment Validation](#configuration-and-environment-validation)
+7. [Request-Scoped Provider Caveats](#request-scoped-provider-caveats)
+
+---
+
+## Module and Provider Visibility
+
+### Symptom
+Nest cannot resolve a dependency even though a provider exists elsewhere, or a feature accidentally depends on an implementation that should be private.
+
+### Verify first
+- Read the consuming module's `imports`, the providing module's `providers`, and its `exports`.
+- Confirm injection tokens match exactly, especially for custom providers and interfaces (which do not exist at runtime).
+- Check whether the module was registered in the application graph rather than merely imported by a TypeScript file.
+
+### Fix
+- Keep a provider private by default. Export only the provider token or service intended as the module's public API.
+- Import the module that exports the provider; adding the provider directly to a second module creates a separate instance and may hide the ownership problem.
+- Use explicit tokens for abstractions and bind them in one composition location.
+
+### Verify
+- Bootstrap a test module using the same imports as the production consumer.
+- Confirm stateful providers have the intended instance lifetime.
+
+*Sources: [Nest modules](https://docs.nestjs.com/modules), [Nest custom providers](https://docs.nestjs.com/fundamentals/custom-providers).*
+
+---
+
+## Circular Dependencies and forwardRef
+
+### Problem
+Two providers or modules require each other, leading to unresolved dependencies, undefined imports, or tightly coupled business behavior.
+
+### Verify first
+- Distinguish a Nest dependency cycle from a TypeScript import cycle; inspect the dependency direction and runtime tokens.
+- Identify whether the services are coordinating two responsibilities that should be extracted behind a third service, event, or interface.
+
+### Fix
+- Prefer removing the cycle by extracting the shared orchestration or introducing a narrower dependency direction.
+- Use `forwardRef(() => Dependency)` only when the cycle is intentional, limited, and understood. Apply it at the matching module/provider injection point.
+- Do not rely on constructor order between circular providers; Nest documents that instantiation order is indeterminate.
+
+### Verify
+- Bootstrap the affected module and exercise both paths through the cycle.
+- Check that unit tests can replace each side independently; difficult substitution is a sign that the boundary remains too coupled.
+
+*Source: [Nest circular dependency fundamentals](https://docs.nestjs.com/fundamentals/circular-dependency).*
+
+---
+
+## Validation Pipes and DTO Transformation
+
+### Symptom
+Requests accept unexpected fields, route/query values retain string types, nested objects are not validated, or validation behavior differs between endpoints.
+
+### Verify first
+- Identify the transport and source: body, query, params, headers, or a message payload.
+- Confirm the runtime DTO is a concrete class with `class-validator` decorators; TypeScript types/interfaces alone cannot be reflected for validation.
+- Test representative invalid input, unknown fields, nested DTOs, and coercion edge cases such as empty strings and dates.
+
+### Fix
+- Apply a global `ValidationPipe` only after choosing an API policy for `whitelist`, `forbidNonWhitelisted`, and transformation.
+- Use DTO classes for input contracts. For nested values, provide type metadata such as `@Type(() => ChildDto)` where required by `class-transformer`.
+- Enable `transform` when handlers need converted primitive route/query values, but declare expected types and test coercion. Transformation is not a substitute for semantic validation.
+- Keep validation rules at the boundary; preserve domain-specific invariants in application/domain logic as well.
+
+### Verify
+- Add end-to-end tests asserting the status code and error body for malformed input.
+- Confirm successful inputs arrive at the handler with the expected runtime types.
+
+*Sources: [Nest validation](https://docs.nestjs.com/techniques/validation), [class-validator](https://github.com/typestack/class-validator), [class-transformer](https://github.com/typestack/class-transformer).*
+
+---
+
+## Authentication Guards and Execution Context
+
+### Problem
+Authentication works for one transport but is bypassed or reads the wrong request object for another; authorization logic becomes duplicated across controllers.
+
+### Verify first
+- Identify the active transport and context: HTTP, GraphQL, WebSocket, or RPC. `ExecutionContext` exposes different arguments for each.
+- Separate authentication (establishing identity) from authorization (deciding access).
+- Define which routes are public and how metadata inheritance at controller and handler levels should work.
+
+### Fix
+- Put identity extraction and verification in a guard or strategy appropriate to the transport.
+- Use `ExecutionContext` APIs rather than assuming `switchToHttp().getRequest()` is valid everywhere.
+- Express authorization requirements as explicit metadata and enforce them in a guard. Keep resource-level checks close to the use case when they require loading the resource.
+- Attach only the normalized identity/claims needed downstream; do not treat unverified decoded token data as authenticated identity.
+
+### Verify
+- Test absent, malformed, expired, and valid credentials plus forbidden-but-authenticated access.
+- Exercise every supported transport and both controller- and method-level metadata paths.
+
+*Sources: [Nest guards](https://docs.nestjs.com/guards), [Nest execution context](https://docs.nestjs.com/fundamentals/execution-context), [Nest authorization](https://docs.nestjs.com/security/authorization).*
+
+---
+
+## Global Exception Filters and Error Contracts
+
+### Symptom
+Clients receive inconsistent error bodies, internal details leak, or exceptions from different layers map to arbitrary status codes.
+
+### Verify first
+- Define the public error contract: status, stable machine-readable code, safe message, field errors where applicable, and correlation/request identifier policy.
+- Identify adapter behavior and existing global filters/interceptors. A filter that writes an HTTP response is transport-specific.
+- Classify expected domain/application errors separately from programming errors and infrastructure failures.
+
+### Fix
+- Use Nest's built-in HTTP exceptions for straightforward transport errors.
+- Add a global filter to translate known application errors into one documented public contract, log unexpected errors with safe context, and avoid exposing stack traces or secrets.
+- Preserve the original cause for observability when wrapping errors, but do not return it to clients.
+- Avoid catching every exception inside controllers; doing so fragments error policy and can hide defects.
+
+### Verify
+- Test validation, not-found, forbidden, conflict, and unexpected-error responses.
+- Ensure production responses do not contain stack traces, tokens, database errors, or internal file paths.
+
+*Sources: [Nest exception filters](https://docs.nestjs.com/exception-filters), [Nest validation errors](https://docs.nestjs.com/techniques/validation#disable-detailed-errors).*
+
+---
+
+## Configuration and Environment Validation
+
+### Problem
+The application starts with missing or malformed configuration, discovers it only under traffic, or reads environment variables throughout business code.
+
+### Verify first
+- Inventory required settings, optional settings with defaults, secret sources, and environment-specific constraints.
+- Confirm how configuration is loaded in each runtime; `.env` files are not automatically a production secret-management strategy.
+- Decide which invalid settings must fail startup versus which can be disabled safely.
+
+### Fix
+- Centralize configuration with `@nestjs/config` and expose typed, focused configuration access to consumers.
+- Validate required environment values during startup with a schema or custom validation function. Validate format and range, not only presence.
+- Keep secrets out of logs, errors, repository files, and client-side configuration.
+- Prefer injecting configuration over reading `process.env` across arbitrary services, which makes tests and runtime behavior harder to control.
+
+### Verify
+- Start the application with missing, malformed, and valid configurations.
+- Confirm failures identify the setting safely without printing its secret value.
+
+*Source: [Nest configuration](https://docs.nestjs.com/techniques/configuration).*
+
+---
+
+## Request-Scoped Provider Caveats
+
+### Problem
+A request-scoped dependency unexpectedly increases latency/memory use, causes broad scope propagation, or behaves inconsistently in non-HTTP code.
+
+### Verify first
+- Confirm that mutable per-request state cannot instead be passed as an explicit argument or carried by a transport context.
+- Inspect the dependency tree: a request-scoped provider can make dependent providers request-scoped.
+- Measure the allocation and latency impact under expected concurrency, and identify whether the code also runs in jobs, events, or WebSockets.
+
+### Fix
+- Keep services singleton-scoped by default; make dependencies request-scoped only for a concrete per-request lifecycle requirement.
+- Pass request-specific values explicitly when practical. This preserves singleton reuse and makes behavior easier to test.
+- For non-singleton scenarios, use Nest's documented context/request-provider mechanisms rather than assuming an HTTP request exists.
+- Do not use request scope as a substitute for authorization isolation or transaction management.
+
+### Verify
+- Load-test the affected route and check instance lifecycle behavior.
+- Exercise background and non-HTTP invocation paths if the provider is shared with them.
+
+*Sources: [Nest injection scopes](https://docs.nestjs.com/fundamentals/injection-scopes), [Nest request lifecycle](https://docs.nestjs.com/faq/request-lifecycle).*

package/template/.devbooster/hub/knowledge/nextjs-pitfalls.md

@@ -0,0 +1,226 @@
+# ▲ Next.js Pitfalls
+
+> **Purpose:** Common pitfalls and issues in Next.js 16+ projects
+> **Primary official sources:** [Next.js TypeScript configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/typescript) · [Next.js 16 upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-16) · [Next.js Image configuration](https://nextjs.org/docs/app/api-reference/components/image#configuration-options)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, router and rendering model, 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. [Framework-level Masking — ignoreBuildErrors](#framework-level-masking)
+2. [Legacy Build-time Lint Masking — Next.js 15 and Earlier](#legacy-build-time-lint-masking)
+3. [Broken Lint Script After a Next.js 16 Upgrade](#broken-lint-script-after-a-nextjs-16-upgrade)
+4. [Invalid next.config Properties](#invalid-nextconfig-properties)
+5. [TSConfig Changes Triggered by Next.js](#tsconfig-changes-triggered-by-nextjs)
+6. [New Lint Findings After an Upgrade](#new-lint-findings-after-an-upgrade)
+7. [Warnings Need Triage](#warnings-need-triage)
+8. [Choose Server and Client Boundaries Deliberately](#choose-server-and-client-boundaries-deliberately)
+9. [Use Route Loading and Error Boundaries Before Rebuilding Them](#use-route-loading-and-error-boundaries-before-rebuilding-them)
+10. [Avoid Hydration Mismatches by Preserving Initial Output](#avoid-hydration-mismatches-by-preserving-initial-output)
+
+---
+
+## Framework-level Masking
+
+### Problem
+The `typescript.ignoreBuildErrors: true` option in `next.config.*` skips Next.js's built-in TypeScript type-checking step during production builds. It does not run the check and suppress its errors, so it can allow type errors to reach deployment.
+
+*Source: [Next.js TypeScript configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/typescript)*
+
+> The official Next.js documentation warns: "If disabled, be sure you are running type checks as part of your build or deploy process, otherwise this can be very dangerous."
+
+### Code (symptom)
+```js
+// next.config.js — bypasses Next.js type checking
+typescript: { ignoreBuildErrors: true }
+```
+
+### Fix
+Remove the flag; `false` is the default:
+```js
+module.exports = {
+  typescript: {
+    ignoreBuildErrors: false,
+  },
+}
+```
+
+If a project temporarily keeps the flag, run an explicit type check such as `tsc --noEmit` in CI or the deployment pipeline.
+
+---
+
+## Legacy Build-time Lint Masking
+
+**Evidence:** Field-validated in a real audit.
+
+### Applicability
+Next.js 15 and earlier. The `eslint.ignoreDuringBuilds` option was supported in these versions and allowed production builds to complete with ESLint errors.
+
+*Source: [Next.js 15 ESLint configuration](https://nextjs.org/docs/15/app/api-reference/config/next-config-js/eslint)*
+
+### Code (symptom)
+```js
+module.exports = {
+  eslint: {
+    ignoreDuringBuilds: true,
+  },
+}
+```
+
+### Why it matters
+This setting bypasses Next.js's built-in build-time lint failure. It may have been introduced as a temporary deployment workaround, but it hides lint failures unless ESLint runs independently in CI or another verified workflow.
+
+### Version boundary
+Next.js 16 removed `next lint`, build-time linting, and the `eslint` key in `next.config.*`. For Next.js 16+, remove this legacy config and run ESLint directly as a separate validation command.
+
+---
+
+## Broken Lint Script After a Next.js 16 Upgrade
+
+### Problem
+Starting with Next.js 16, `next lint` is removed. `next build` no longer runs linting, and the `eslint` key in `next.config.*` is removed.
+
+Invoking the removed command can produce an error such as:
+```
+Invalid project directory provided, no such directory: .../lint
+```
+
+### Fix
+Run ESLint directly and make linting a separate CI or deployment step:
+```json
+{
+  "scripts": {
+    "lint": "eslint ."
+  }
+}
+```
+
+For flat-config setup and migration details, see [ESLint Migration](./eslint-migration.md).
+
+---
+
+## Invalid next.config Properties
+
+### Problem
+A property in an unsupported location in `next.config.*` can produce a configuration warning or be ignored. For example, `unoptimized` is not a top-level Next.js config option.
+
+### Code (symptom)
+```js
+// Invalid location
+module.exports = { unoptimized: true }
+
+// Valid location
+module.exports = { images: { unoptimized: true } }
+```
+
+### Fix
+Use the documented `images.unoptimized` option:
+```js
+module.exports = {
+  images: {
+    unoptimized: true,
+  },
+}
+```
+
+---
+
+## TSConfig Changes Triggered by Next.js
+
+### Problem
+When TypeScript is added to a project, `next dev` and `next build` can create or update `tsconfig.json` with recommended settings and generated-type includes.
+
+### Handling
+- Review the complete `tsconfig.json` diff and identify why each change was made.
+- Keep required generated-type includes, such as `.next/types/**/*.ts`, when the project uses Next.js route-aware types.
+- Validate compiler-option changes, including `moduleResolution`, against the project's Next.js and TypeScript versions before accepting or reverting them.
+- Commit intentional configuration changes so they are visible in review.
+
+---
+
+## New Lint Findings After an Upgrade
+
+### Problem
+After migrating to ESLint flat config or updating Next.js, ESLint, or plugins, new rules or changed analysis can reveal existing issues or introduce upgrade-specific incompatibilities.
+
+### Common examples
+- A callback referenced before declaration
+- Non-deterministic logic during render, such as `Math.random()` in a component body
+- An unused import that was previously not reported
+
+### Handling
+1. Analyze each finding individually.
+2. Classify it as a pre-existing issue now detected, a configuration change, or an upgrade regression.
+3. Apply a specific fix or document a narrowly justified exception.
+
+---
+
+## Warnings Need Triage
+
+### Problem
+A successful build can still emit warnings about configuration, deprecations, or behavior that affects production.
+
+### Checklist
+After a framework upgrade:
+1. Run `next build` and capture the full output.
+2. Review warnings as well as errors.
+3. Determine the source, impact, and owner of each warning.
+4. Fix the warning or document an accepted disposition according to the project's release policy.
+
+### Rule of thumb
+**A passing build with warnings requires triage; warnings are neither automatically deploy-blocking nor automatically acceptable.**
+
+---
+
+## Choose Server and Client Boundaries Deliberately
+
+### Decision
+In the App Router, components are Server Components by default. Add `'use client'` only when the component or one of its direct responsibilities requires client-side capabilities such as state, Effects, browser APIs, or event handlers.
+
+### Verify first
+- Identify the active router; do not apply App Router guidance to a Pages Router project.
+- Keep the client boundary as narrow as the existing architecture permits.
+- Inspect existing component boundaries and shared providers before moving a component to the client.
+- Pass serializable props across the Server-to-Client boundary.
+
+Do not convert a server-rendered subtree to a Client Component merely to solve a small interactive concern. Extract the interactive leaf when that preserves the project’s established composition pattern.
+
+*Sources: [Next.js — Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components) · [Next.js — use client](https://nextjs.org/docs/app/api-reference/directives/use-client)*
+
+---
+
+## Use Route Loading and Error Boundaries Before Rebuilding Them
+
+### Decision
+For App Router route segments, inspect existing `loading.*`, `error.*`, and shared layout conventions before adding component-local loading or error state. These files define framework-native boundaries for the segment and its descendants.
+
+### Verify first
+- Confirm whether the loading state is route-level, component-level, or owned by an existing client query abstraction.
+- Preserve existing fallback, retry, error-reporting, and accessibility conventions.
+- Do not use `loading.*` as a substitute for errors in a client-side mutation or interaction; use the project’s local feedback pattern there.
+- Confirm the required error boundary shape for the installed Next version before creating one.
+
+Use the smallest boundary that gives the intended user experience. A project may intentionally prefer a shared route skeleton or a local component state; preserve either approach when valid.
+
+*Sources: [Next.js — Loading UI and Streaming](https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming) · [Next.js — Error Handling](https://nextjs.org/docs/app/building-your-application/routing/error-handling)*
+
+---
+
+## Avoid Hydration Mismatches by Preserving Initial Output
+
+### Symptom
+The server-rendered HTML differs from the first client render, producing a hydration warning, discarded markup, or visible flicker.
+
+### Verify first
+Look for browser-only values (`window`, storage, viewport), time, randomness, locale, and data that changes between the server and first client render. Confirm whether the component is intended to render consistently on both sides.
+
+### Fix
+Render the same initial output on server and client, then read browser-only state after mount when necessary. For an intentionally client-only widget, isolate it behind the project’s established client boundary rather than scattering hydration suppressions.
+
+Do not use `suppressHydrationWarning` as a general fix; it is a narrow escape hatch and does not reconcile the underlying output.
+
+*Source: [Next.js — React Hydration Error](https://nextjs.org/docs/messages/react-hydration-error)*