dev-booster 1.18.0 → 1.18.2

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.

package/template/.devbooster/hub/knowledge/index.md

@@ -0,0 +1,91 @@
+# 📚 Dev Booster — Knowledge Base
+
+> Consolidated knowledge base for Dev Booster.
+> Each article documents a problem pattern + validated solution.
+
+---
+
+## How to Use
+
+1. Identify the concrete technical decision or problem pattern (e.g., framework behavior, migration concern, ESLint rule name, error message, or symptom).
+2. Check the index below to locate the relevant article and section.
+3. Use `read_file` with `start_line`/`end_line` to read **only** the necessary local section.
+4. **Always read the official source linked by that section before choosing or applying a solution.** Use the local entry for field-validated context and the official source for current API, version, constraints, and migration guidance.
+5. Inspect the actual project: installed versions, local rules, existing abstractions, configuration, conventions, and relevant tests.
+6. Preserve a valid established project convention. Do not replace it only because another official approach is also valid; 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.
+
+### Example
+
+User reports: `TS2345: Type 'string' is not assignable to type 'number'`
+
+1. Identify the pattern → TypeScript strict error on a discriminated union or runtime type mismatch.
+2. Check the index → `typescript-patterns.md` table entry confirms it covers "null safety, discriminated UI states, runtime validation".
+3. Read the relevant section → `read_file` with `start_line`/`end_line` to get only the "null-safety" section of `typescript-patterns.md`.
+4. Read the official source → open the [TypeScript Handbook section on Narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.html) to verify current API behavior.
+5. Inspect the project → check `tsconfig.json` strict flags, existing type guards in the codebase, and whether the error is in a new area or a pre-typed module.
+6. Decide → if the project already uses a consistent pattern (e.g. Zod schemas + inferred types), preserve it. Only suggest a different approach if the current one is incompatible, unsafe, or the user explicitly requests a change.
+
+---
+
+### If Not Found in the Base
+
+Use the relevant **official source** below. Prefer primary documentation, official changelogs, and official migration guides over blog posts, search snippets, or unverified answers.
+
+| Area | Trusted sources |
+|---|---|
+| React | [React documentation](https://react.dev), [useEffect](https://react.dev/reference/react/useEffect), [useState](https://react.dev/reference/react/useState), [useMemo](https://react.dev/reference/react/useMemo), [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) |
+| React Hooks linting | [eslint-plugin-react-hooks](https://www.npmjs.com/package/eslint-plugin-react-hooks) |
+| Next.js | [Next.js documentation](https://nextjs.org/docs), [Next.js 16 upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-16), [TypeScript configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/typescript), [Image configuration](https://nextjs.org/docs/app/api-reference/components/image#configuration-options) |
+| Historical Next.js behavior | [Next.js 15 ESLint configuration](https://nextjs.org/docs/15/app/api-reference/config/next-config-js/eslint) |
+| ESLint | [ESLint configuration files](https://eslint.org/docs/latest/use/configure/configuration-files), [ESLint migration to flat config](https://eslint.org/docs/latest/use/configure/migration-guide) |
+| TypeScript | [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/), [TSConfig reference](https://www.typescriptlang.org/tsconfig/), [TypeScript release notes](https://devblogs.microsoft.com/typescript/) |
+| npm | [npm CLI documentation](https://docs.npmjs.com/cli/), [npm audit](https://docs.npmjs.com/cli/commands/npm-audit), [peer dependency settings](https://docs.npmjs.com/cli/using-npm/config#strict-peer-deps) |
+| Yarn Classic | [Yarn Classic documentation](https://classic.yarnpkg.com/en/docs/), [yarn audit](https://classic.yarnpkg.com/en/docs/cli/audit/), [yarn outdated](https://classic.yarnpkg.com/en/docs/cli/outdated/), [yarn why](https://classic.yarnpkg.com/en/docs/cli/why/) |
+| pnpm | [pnpm documentation](https://pnpm.io/), [pnpm audit](https://pnpm.io/cli/audit), [pnpm why](https://pnpm.io/cli/why), [pnpm workspaces](https://pnpm.io/workspaces) |
+| Node.js | [Node.js API documentation](https://nodejs.org/docs/latest/api/), [Node.js package guidance](https://nodejs.org/en/learn/getting-started/packages) |
+| Monorepos | [npm workspaces](https://docs.npmjs.com/cli/using-npm/workspaces), [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/), [pnpm workspaces](https://pnpm.io/workspaces), [Turborepo documentation](https://turbo.build/docs), [Nx documentation](https://nx.dev/docs) |
+| tRPC | [tRPC documentation](https://trpc.io/docs), [Context](https://trpc.io/docs/server/context), [Procedures](https://trpc.io/docs/server/procedures), [Error handling](https://trpc.io/docs/server/error-handling) |
+| TanStack Query | [TanStack Query documentation](https://tanstack.com/query/latest/docs/framework/react/overview), [Query keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys), [SSR and hydration](https://tanstack.com/query/latest/docs/framework/react/guides/ssr) |
+| Prisma + PostgreSQL | [Prisma documentation](https://www.prisma.io/docs/orm), [Prisma Migrate](https://www.prisma.io/docs/orm/prisma-migrate), [PostgreSQL documentation](https://www.postgresql.org/docs/), [PostgreSQL EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html) |
+| NestJS | [NestJS documentation](https://docs.nestjs.com/), [Modules](https://docs.nestjs.com/modules), [Validation](https://docs.nestjs.com/techniques/validation), [Exception filters](https://docs.nestjs.com/exception-filters) |
+| Vite | [Vite Guide](https://vite.dev/guide/), [Environment variables](https://vite.dev/guide/env-and-mode), [Vite config](https://vite.dev/config/) |
+| Tailwind CSS | [Tailwind documentation](https://tailwindcss.com/docs), [Tailwind v4 upgrade guide](https://tailwindcss.com/docs/upgrade-guide) |
+| Angular | [Angular documentation](https://angular.dev/overview), [Angular version compatibility](https://angular.dev/reference/versions), [Angular CLI](https://angular.dev/cli) |
+| Testing | [Vitest documentation](https://vitest.dev/guide/), [Jest documentation](https://jestjs.io/docs/getting-started), [Playwright documentation](https://playwright.dev/docs/intro) |
+| react-to-print | [Official repository](https://github.com/MatthewHerbst/react-to-print), [v3 changelog](https://github.com/MatthewHerbst/react-to-print/blob/v3.3.0/CHANGELOG.md) |
+| Formik | [Formik Form API](https://formik.org/docs/api/form) |
+| Radix UI | [Radix Primitives documentation](https://www.radix-ui.com/primitives/docs/overview/introduction) |
+| shadcn/ui | [shadcn CLI](https://ui.shadcn.com/docs/cli), [Radix migration](https://ui.shadcn.com/docs/cli#migrate-radix), [Tailwind v4 migration](https://ui.shadcn.com/docs/tailwind-v4) |
+
+For a library-specific issue, prioritize the library's official documentation, release notes, changelog, and migration guide. If the official sources do not cover the case, resolve it from the actual project context without writing to this knowledge base.
+
+---
+
+## Articles
+
+| File | Stacks | Content |
+|---|---|---|
+| [`react-patterns.md`](./react-patterns.md) | React 19, React Hooks | Effects, derived state, async UI strategy, Suspense boundaries, custom-hook extraction, state mutation |
+| [`nextjs-pitfalls.md`](./nextjs-pitfalls.md) | Next.js 16 | Build/lint changes, config schema drift, Server/Client boundaries, route loading/errors, hydration |
+| [`eslint-migration.md`](./eslint-migration.md) | ESLint 9, Flat Config | Flat config migration, masking, `resolutions`, inline suppressions |
+| [`typescript-patterns.md`](./typescript-patterns.md) | TypeScript Strict | Imports, suppressions, refs, discriminated UI states, runtime validation, null safety |
+| [`dependency-guide.md`](./dependency-guide.md) | npm/yarn/pnpm | Safe update model, dependency analysis, audit interpretation |
+| [`upgrade-fallout.md`](./upgrade-fallout.md) | Multi-stack | Upgrade fallout: scripts, config, new lint rules, validation |
+| [`migration-guides.md`](./migration-guides.md) | Libraries | `react-to-print` v3, Formik + React 19, Radix UI |
+| [`nodejs-patterns.md`](./nodejs-patterns.md) | Node.js | Runtime alignment, ESM/CJS, environment handling, async failures, script portability |
+| [`package-manager-patterns.md`](./package-manager-patterns.md) | npm, Yarn, pnpm | Lockfiles, peers, overrides, audit, workspaces, immutable installs |
+| [`monorepo-patterns.md`](./monorepo-patterns.md) | npm/Yarn/pnpm workspaces, Turbo, Nx | Package boundaries, dependency resolution, shared configs, cache hygiene |
+| [`trpc-patterns.md`](./trpc-patterns.md) | tRPC | Context/auth, input validation, errors, type integrity, router design, transport |
+| [`tanstack-patterns.md`](./tanstack-patterns.md) | TanStack Query | Query ownership, keys, invalidation, async UI states, caching, SSR hydration, cancellation, optimistic updates |
+| [`prisma-postgresql-patterns.md`](./prisma-postgresql-patterns.md) | Prisma, PostgreSQL | Generation drift, migrations, query loading, transactions, indexes, pooling |
+| [`nestjs-patterns.md`](./nestjs-patterns.md) | NestJS | Modules, DI, validation, guards, exceptions, configuration, request scope |
+| [`vite-patterns.md`](./vite-patterns.md) | Vite | Env exposure, base paths, aliases, ESM/CJS, optimizer cache, plugins, React integration |
+| [`tailwind-shadcn-patterns.md`](./tailwind-shadcn-patterns.md) | Tailwind CSS, shadcn/ui | v3/v4 migration, source scanning, tokens, dependencies, themes, design-system reuse |
+| [`testing-patterns.md`](./testing-patterns.md) | Vitest, Jest, Playwright | Environments, determinism, mocks, async UI behavior, isolation, CI parity, validation |
+| [`angular-patterns.md`](./angular-patterns.md) | Angular | Standalone APIs, DI, signals/RxJS, forms, HTTP, routing, version alignment |
+
+---
+
+## Maintenance (Dev Booster Maintainers Only)
+
+This base is manually curated. Only Dev Booster maintainers add, update, or remove content.

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.