codebyplan 1.12.0 → 1.13.0

package/templates/skills/cbp-setup-eslint/reference/base.md

@@ -0,0 +1,82 @@
+# base — TypeScript foundation (ESLint v10 flat config)
+
+The foundation every TypeScript app shares: ESLint flat config, type-checked
+`typescript-eslint` rules, security scanning, and Prettier. Maps to the CBP **`base`** DB
+preset (`tech_match.requires: ["TypeScript"]`).
+
+> **Verified 2026-05-31.** ESLint is on **v10** — flat config (`eslint.config.mjs`) is the
+> only native format (legacy `.eslintrc*` was removed). `defineConfig` from `eslint/config`
+> is the canonical wrapper for every stack below.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint` | `10.4.1` | the linter (flat config only) |
+| `@eslint/js` | `10.0.1` | `js.configs.recommended` |
+| `typescript-eslint` | `8.60.0` | unified parser + plugin + presets |
+| `eslint-config-prettier` | `10.x` | turns off formatting rules (subpath `/flat`) |
+| `eslint-plugin-security` | `^3` | OWASP-style heuristics |
+| `eslint-plugin-no-secrets` | `^2.1` | high-entropy string detection |
+| `globals` | `17.6.0` | env global definitions |
+
+```bash
+pnpm add -D eslint @eslint/js typescript-eslint eslint-config-prettier \
+  eslint-plugin-security eslint-plugin-no-secrets globals
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import { defineConfig } from "eslint/config";
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import security from "eslint-plugin-security";
+import noSecrets from "eslint-plugin-no-secrets";
+import prettier from "eslint-config-prettier/flat";
+
+export default defineConfig([
+  js.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked, // type-aware: no-floating-promises, etc.
+  security.configs.recommended,
+  { plugins: { "no-secrets": noSecrets }, rules: { "no-secrets/no-secrets": ["warn", { tolerance: 4.5 }] } },
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,                 // current type-info mechanism
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  { rules: { "security/detect-object-injection": "off" } }, // famously noisy
+  prettier, // MUST be last
+]);
+```
+
+## Gotchas
+
+- **`recommended` vs `recommendedTypeChecked`.** The type-checked preset is what enables the
+  genuinely valuable rules (`no-floating-promises`, `no-misused-promises`, `no-unsafe-*`) but
+  needs type info and is **much slower** — scope it to `**/*.ts`/`**/*.tsx` and disable on JS
+  config files with `tseslint.configs.disableTypeChecked`.
+- **`projectService: true`** replaces the old `project: "./tsconfig.json"`. It auto-finds the
+  nearest `tsconfig.json` per file and lints out-of-project files (like `eslint.config.mjs`)
+  without a `tsconfig.eslint.json`. Always pair it with `tsconfigRootDir: import.meta.dirname`.
+- **`tseslint.config()` is deprecated** in favour of core `defineConfig` from `eslint/config`
+  (a near-exact clone). The `tseslint.configs.*` presets are unchanged.
+- **Prettier last.** `eslint-config-prettier/flat` must come after every rule-defining config
+  so it can switch off conflicting stylistic rules.
+
+## CBP preset divergence
+
+CBP's `base` DB preset currently pins `eslint: ^9.0.0` / `typescript-eslint: ^8.0.0` and
+keeps several `@typescript-eslint/no-unsafe-*` rules at `warn`. The setup above reflects the
+**latest** (`eslint@10`); both are flat-config and interoperate. Bumping the preset to v10 is
+out of scope for the skill (no DB/preset changes) — adopt v10 per-repo when you regenerate.
+
+## Official docs
+
+- Configuration files: https://eslint.org/docs/latest/use/configure/configuration-files
+- Typed linting: https://typescript-eslint.io/getting-started/typed-linting/
+- `projectService`: https://typescript-eslint.io/blog/project-service/

package/templates/skills/cbp-setup-eslint/reference/cli.md

@@ -0,0 +1,56 @@
+# cli — Node CLI tool overrides
+
+For Node CLI packages with a `bin` (the CBP `codebyplan` package). Layers a small **override
+block** on top of [base](base.md) + [node](node.md). Maps to the CBP **`cli`** DB preset
+(`tech_match.requires_capabilities: ["cli-bin"]`).
+
+> **Verified 2026-05-31.** There is no "CLI" ESLint plugin — the convention is a scoped
+> rule-override block.
+
+## What it does
+
+A CLI legitimately (a) talks to the user via `console`, and (b) operates on user-supplied
+filesystem paths and dynamic keys — so the `eslint-plugin-security` heuristics that flag those
+produce noise, not findings. Relax them, **scoped narrowly** to the CLI surface.
+
+## Flat config (override block)
+
+```js
+// eslint.config.mjs — appended after base + node + security configs
+export default [
+  // ...base, node, security.configs.recommended, etc.
+  {
+    files: ["bin/**/*.{js,ts,mjs}", "src/cli/**/*.{js,ts}"],
+    rules: {
+      "no-console": "off", // console output IS the CLI's UI
+
+      // CLIs operate on user paths and dynamic keys by design:
+      "security/detect-non-literal-fs-filename": "off",
+      "security/detect-object-injection": "off",
+
+      // optional, if eslint-plugin-n is in use (CLIs call process.exit):
+      // "n/no-process-exit": "off",
+    },
+  },
+];
+```
+
+## Gotchas
+
+- **Scope via `files`** — do NOT disable these repo-wide; the same rules are valuable in
+  server/library code.
+- The two `security/*` lines require `eslint-plugin-security` to be installed and registered
+  (otherwise ESLint errors "rule not found"). If the project has no security plugin, only the
+  `no-console: "off"` line applies.
+
+## CBP preset divergence
+
+The CBP `cli` preset matches the rule set above exactly (`no-console`,
+`security/detect-non-literal-fs-filename`, `security/detect-object-injection` all off) and is
+capability-gated on `cli-bin`. The repo's own `packages/codebyplan-package/eslint.config.mjs`
+already applies this. No divergence — this doc just documents the convention.
+
+## Official docs
+
+- Convention (no upstream doc); rules: https://eslint.org/docs/latest/rules/no-console and
+  https://github.com/eslint-community/eslint-plugin-security

package/templates/skills/cbp-setup-eslint/reference/e2e.md

@@ -0,0 +1,68 @@
+# e2e — Playwright / WebdriverIO / Mocha test rules
+
+For end-to-end specs. Three runners appear across CBP repos: **Playwright** (web), **WebdriverIO**
+(Tauri desktop), and **Mocha** (the framework WDIO drives). Each is a **directory-scoped**
+override. Playwright maps to the CBP **`testing-e2e`** preset
+(`tech_match.requires: ["Playwright"]`); WebdriverIO + Mocha are **gap stacks — no preset**.
+
+> **Verified 2026-05-31.** Version traps: Playwright is **2.10.4** (not the 0.15.x search
+> sometimes returns); Mocha 11.x uses **`configs.recommended`** — NOT `configs.flat.recommended`.
+
+## Packages
+
+| Package | Latest | Flat key |
+| ------- | ------ | -------- |
+| `eslint-plugin-playwright` | `2.10.4` | `configs['flat/recommended']` |
+| `eslint-plugin-wdio` | `9.27.2` | `configs['flat/recommended']` |
+| `eslint-plugin-mocha` | `11.3.0` | `configs.recommended` (NOT `.flat`) |
+
+```bash
+pnpm add -D eslint-plugin-playwright   # web
+pnpm add -D eslint-plugin-wdio eslint-plugin-mocha   # Tauri / WebdriverIO desktop
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import playwright from "eslint-plugin-playwright";
+// desktop: import { configs as wdioConfigs } from "eslint-plugin-wdio";
+// desktop: import mocha from "eslint-plugin-mocha";
+
+export default [
+  // Playwright — scope to the web e2e dir
+  {
+    ...playwright.configs["flat/recommended"],
+    files: ["e2e/**", "**/*.e2e.{ts,js}"],
+    rules: { ...playwright.configs["flat/recommended"].rules, "no-console": "off" },
+  },
+
+  // WebdriverIO + Mocha (Tauri desktop) — scope to the wdio spec dir
+  // { ...wdioConfigs["flat/recommended"], files: ["test/**", "e2e/**"] },
+  // { ...mocha.configs.recommended, files: ["test/**/*.{ts,js}"] },
+];
+```
+
+## Gotchas
+
+- **Scope every e2e override via `files`** — Playwright/WDIO/Mocha rules false-positive on
+  unit tests, and Testing-Library rules false-positive on e2e specs.
+- **Mocha 11.x = `mocha.configs.recommended`** — `mocha.configs.flat.recommended` is
+  `undefined` in 11.x (it only exists on the unreleased 12.x main branch) and crashes config
+  load. Don't copy a `.flat.recommended` example.
+- **WebdriverIO**: `eslint-plugin-wdio@9` requires ESLint 9+; when `typescript-eslint` is
+  present its recommended config auto-swaps `wdio/await-expect` → `wdio/no-floating-promise`.
+- The CBP web app keeps Playwright specs in `e2e/**` with a Vitest sibling override for
+  `e2e/**/__tests__/**` — mirror that split if you co-locate unit tests under `e2e/`.
+
+## CBP preset divergence
+
+CBP's `testing-e2e` preset covers **Playwright only** (`eslint-plugin-playwright: ^2.0.0`,
+`no-console: off`). There is **no** preset for WebdriverIO or Mocha — the Tauri desktop e2e
+config is manual. The skill does not add presets for the gap runners.
+
+## Official docs
+
+- Playwright: https://github.com/mskelton/eslint-plugin-playwright
+- WebdriverIO: https://github.com/webdriverio/webdriverio/tree/main/packages/eslint-plugin-wdio
+- Mocha: https://github.com/lo1tuma/eslint-plugin-mocha

package/templates/skills/cbp-setup-eslint/reference/jest.md

@@ -0,0 +1,59 @@
+# jest — Jest test-file rules
+
+For apps that test with Jest (CBP `apps/backend` NestJS specs, `livebyplan` Expo). **Gap
+stack — no CBP DB preset** (the `testing` preset is Vitest-only). Layers a test-scoped
+override on top of [base](base.md).
+
+> **Verified 2026-05-31.** `eslint-plugin-jest` uses the **bracketed** flat-config keys
+> `configs['flat/recommended']` / `['flat/style']` (the un-prefixed keys are legacy eslintrc).
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint-plugin-jest` | `29.15.2` | Jest rules |
+
+```bash
+pnpm add -D eslint-plugin-jest
+```
+
+Peers: `eslint ^8.57 || ^9 || ^10`, `@typescript-eslint/eslint-plugin ^8`, `jest`.
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import jest from "eslint-plugin-jest";
+
+export default [
+  {
+    files: ["**/*.{test,spec}.{ts,tsx,js,jsx}", "**/__tests__/**/*.{ts,tsx,js,jsx}"],
+    ...jest.configs["flat/recommended"],
+    rules: {
+      ...jest.configs["flat/recommended"].rules,
+      ...jest.configs["flat/style"].rules, // optional stylistic rules
+      // type-aware: hand the unbound-method check to the jest-aware version
+      "@typescript-eslint/unbound-method": "off",
+      "jest/unbound-method": "error",
+    },
+  },
+];
+```
+
+## Gotchas
+
+- Keys are **`configs['flat/recommended']`** / **`['flat/style']`** (bracketed) — the
+  unprefixed `configs.recommended` is the legacy eslintrc preset.
+- **`jest/unbound-method`** extends `@typescript-eslint/unbound-method`; turn the base rule
+  off on test files and enable the jest version (needs `@typescript-eslint/parser` + type
+  info). Type-aware jest rules safely no-op when type info is absent.
+- Avoid pinning `flat/all` long-term — it enables every rule and can break on minor releases.
+
+## CBP preset divergence
+
+There is **no** CBP `testing-jest` preset. NestJS/Expo Jest specs are currently linted only by
+the base rules. Add the override above per-repo; the skill does not add a preset.
+
+## Official docs
+
+- eslint-plugin-jest: https://github.com/jest-community/eslint-plugin-jest

package/templates/skills/cbp-setup-eslint/reference/nestjs.md

@@ -0,0 +1,69 @@
+# nestjs — NestJS back-end flat config
+
+For NestJS apps (the CBP `apps/backend`). **Gap stack — no CBP DB preset.** Use this doc to
+hand-author `eslint.config.mjs`; the `base` + `node` presets cover most of it, but the
+official Nest starter has a specific shape worth matching.
+
+> **Verified 2026-05-31.** There is **no first-party NestJS ESLint plugin** — the official
+> `nest new` starter uses plain type-checked `typescript-eslint` + Prettier.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `typescript-eslint` | `8.60.0` | parser + type-checked preset |
+| `@eslint/js` | `10.0.1` | `eslint.configs.recommended` |
+| `eslint-plugin-prettier` | `^5` | `/recommended` subpath |
+| `globals` | `17.6.0` | `globals.node`, `globals.jest` |
+
+```bash
+pnpm add -D typescript-eslint @eslint/js eslint-plugin-prettier eslint-config-prettier globals
+```
+
+## Flat config (official `nest new` starter, verbatim)
+
+```js
+// @ts-check
+import eslint from "@eslint/js";
+import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  { ignores: ["eslint.config.mjs"] },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      globals: { ...globals.node, ...globals.jest },
+      sourceType: "commonjs", // "module" for an ESM Nest app
+      parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
+    },
+  },
+  {
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-floating-promises": "warn",
+      "@typescript-eslint/no-unsafe-argument": "warn",
+      "prettier/prettier": ["error", { endOfLine: "auto" }],
+    },
+  },
+);
+```
+
+## Gotchas
+
+- Nest relaxes three type-checked rules (`no-explicit-any` off; `no-floating-promises` and
+  `no-unsafe-argument` to `warn`) because its DI/decorator patterns trip them. Keep these.
+- `{ ignores: ["eslint.config.mjs"] }` keeps type-aware linting off the config file itself.
+- `sourceType: "commonjs"` matches Nest's default CJS build — flip to `"module"` for ESM.
+- The starter still uses `tseslint.config(...)`; you may swap it for `defineConfig` from
+  `eslint/config` (deprecation note in [base.md](base.md)) — the presets are identical.
+- Optional community add-on: `@darraghor/eslint-plugin-nestjs-typed` adds
+  decorator/Swagger/DTO-aware rules. Not part of the official starter.
+- Nest tests use **Jest** — add the [jest.md](jest.md) override scoped to `**/*.spec.ts`.
+
+## Official docs
+
+- Starter config: https://github.com/nestjs/typescript-starter/blob/master/eslint.config.mjs

package/templates/skills/cbp-setup-eslint/reference/nextjs.md

@@ -0,0 +1,63 @@
+# nextjs — Next.js (App Router) flat config
+
+For Next.js apps. Layers on top of [base](base.md). Maps to the CBP **`nextjs`** DB preset
+(`tech_match.requires: ["Next.js"]`, `requires_capabilities: ["jsx"]`).
+
+> **Verified 2026-05-31.** As of **Next.js 16**, `eslint-config-next` ships **native flat
+> config**, `next lint` is **removed** (run `eslint .` directly), and the `eslint` key in
+> `next.config.js` is gone. No `FlatCompat` shim is needed.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint-config-next` | `16.2.6` | bundles `@next/eslint-plugin-next` + react/react-hooks/import |
+
+```bash
+pnpm add -D eslint-config-next
+```
+
+## Flat config
+
+`eslint-config-next` exposes spreadable **array** subpath exports:
+
+```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, // base + Core-Web-Vitals rules promoted warn→error
+  ...nextTs,     // typescript-eslint rules (based on @typescript-eslint/recommended)
+  globalIgnores([".next/**", "out/**", "build/**", "next-env.d.ts"]),
+]);
+```
+
+Subpath exports:
+- `eslint-config-next` — base (Next + react + react-hooks recommended).
+- `eslint-config-next/core-web-vitals` — base + CWV rules at error (**recommended default**).
+- `eslint-config-next/typescript` — adds typescript-eslint rules; spread alongside a base.
+
+## Gotchas
+
+- **`globalIgnores([...])` is required** when you spread the config — re-assert the default
+  ignores (`.next/`, etc.) per the official docs example.
+- **Monorepo**: point the plugin at the app with `settings: { next: { rootDir: "apps/web" } }`
+  (path, glob, or array).
+- **Prettier**: add `import prettier from "eslint-config-prettier/flat"` last.
+- `next lint` removal landed in Next 16.0.0 — old `.eslintrc.json` configs should migrate to
+  `eslint.config.mjs` (a codemod exists).
+
+## CBP preset divergence
+
+CBP's `nextjs` preset pins `eslint-config-next: ^15.0.0` and registers
+`eslint-plugin-react-compiler` explicitly (see [react.md](react.md) — that plugin is now
+**superseded**). The repo's own `apps/web/eslint.config.mjs` already uses the
+`createRequire` + `eslint-config-next/core-web-vitals` + `eslint-config-next/typescript`
+pattern. Adopt the native spread form above when regenerating; presets are not changed by
+this skill.
+
+## Official docs
+
+- ESLint config: https://nextjs.org/docs/app/api-reference/config/eslint

package/templates/skills/cbp-setup-eslint/reference/node.md

@@ -0,0 +1,74 @@
+# node — Node/TypeScript service (Hono, Express, plain Node) flat config
+
+For Node back-end services and server-side packages (the CBP MCP server uses Hono; any
+`node-server` capability). Layers on [base](base.md). Maps to the CBP **`node`** DB preset
+(`tech_match.requires: ["Node.js"]`, `requires_capabilities: ["node-server"]`).
+
+> **Verified 2026-05-31.** The valuable async-safety rules (`no-floating-promises`,
+> `no-misused-promises`) are **typescript-eslint** rules that need type info — they come from
+> `recommendedTypeChecked`, not from a node plugin.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `globals` | `17.6.0` | `globals.node` |
+| `typescript-eslint` | `8.60.0` | type-aware promise rules |
+| `eslint-plugin-n` | `18.0.1` | **optional** — unsupported-Node-API / import / engines checks |
+
+```bash
+pnpm add -D globals typescript-eslint
+# optional (libraries / dual ESM-CJS packages):
+pnpm add -D eslint-plugin-n
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import { defineConfig } from "eslint/config";
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import globals from "globals";
+// optional: import n from "eslint-plugin-n";
+
+export default defineConfig([
+  js.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked, // enables the promise rules below
+  {
+    files: ["**/*.{ts,mts,cts}"],
+    languageOptions: {
+      globals: globals.node,
+      sourceType: "module", // "commonjs" for a CJS service
+      parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
+    },
+    rules: {
+      "@typescript-eslint/no-floating-promises": "error",
+      "@typescript-eslint/no-misused-promises": "error",
+    },
+  },
+  // optional eslint-plugin-n:
+  // { files: ["**/*.{ts,mts,cts}"], plugins: { n }, extends: ["n/recommended-module"] },
+]);
+```
+
+## Gotchas
+
+- **`eslint-plugin-n` is optional.** For a pure internal TS service you can skip it — its main
+  value is catching unsupported Node APIs, missing imports, and `package.json#engines` issues
+  in **libraries** and dual ESM/CJS packages. Pick the right preset: `n/recommended-module`
+  (ESM), `n/recommended-script` (CJS), `n/recommended` (mixed).
+- The promise rules **require** a type-checked config + `projectService` — they silently do
+  nothing without type info.
+- A CJS service uses `sourceType: "commonjs"`; an ESM service uses `"module"`.
+
+## CBP preset divergence
+
+CBP's `node` preset ships only the two `@typescript-eslint` promise rules at `error` (no
+`eslint-plugin-n`). The repo's MCP server / CLI configs follow this minimal shape. Add
+`eslint-plugin-n` per-repo if you publish a library; the skill does not modify the preset.
+
+## Official docs
+
+- eslint-plugin-n: https://github.com/eslint-community/eslint-plugin-n
+- no-floating-promises: https://typescript-eslint.io/rules/no-floating-promises/

package/templates/skills/cbp-setup-eslint/reference/react-native.md

@@ -0,0 +1,60 @@
+# react-native — React Native / Expo flat config
+
+For Expo / React Native apps (the CBP `livebyplan` mobile app). **Gap stack — no CBP DB
+preset.** Use Expo's official lint config.
+
+> **Verified 2026-05-31.** `eslint-config-expo` is the official config and ships **flat config
+> by default from Expo SDK 53** onward (SDK 52 and earlier use legacy `.eslintrc`).
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint-config-expo` | `56.0.4` | Expo's flat config (`/flat` subpath) |
+
+```bash
+npx expo lint   # installs eslint + eslint-config-expo and scaffolds eslint.config.js
+```
+
+`eslint-config-expo` bundles `eslint-plugin-expo`, `eslint-plugin-react`,
+`eslint-plugin-react-hooks`, `eslint-plugin-import`, and `@typescript-eslint/*`. It does **not**
+bundle `eslint-plugin-react-native` (that's a separate optional add-on, `@5.0.0`).
+
+## Flat config
+
+Expo's template is **CommonJS `eslint.config.js`** (not `.mjs`):
+
+```js
+// eslint.config.js
+const { defineConfig } = require("eslint/config");
+const expoConfig = require("eslint-config-expo/flat");
+const eslintPluginPrettierRecommended = require("eslint-plugin-prettier/recommended");
+
+module.exports = defineConfig([
+  expoConfig,
+  eslintPluginPrettierRecommended,
+  { ignores: ["dist/*"] },
+]);
+```
+
+Minimal form (no Prettier): just `expoConfig` in the array.
+
+## Gotchas
+
+- RN platform support comes from RN global variables + platform file extensions
+  (`.android.ts`, `.ios.ts`, `.web.ts`) and `eslint-plugin-expo` — **not** from
+  `eslint-plugin-react-native`. Add `eslint-plugin-react-native@5.0.0` manually only if you
+  want RN-specific rules (`no-inline-styles`, `no-unused-styles`).
+- Run linting with `npx expo lint` (it wires the config the first time).
+- Expo apps test with **Jest** — add the [jest.md](jest.md) override.
+
+## CBP preset divergence
+
+There is **no** CBP `react-native`/`expo` DB preset, and the `react` preset `excludes`
+nothing for RN but is browser-globals oriented. Use `eslint-config-expo/flat` directly; the
+skill does not add a preset for this stack.
+
+## Official docs
+
+- Using ESLint in Expo: https://docs.expo.dev/guides/using-eslint/
+- eslint-config-expo: https://github.com/expo/expo/tree/main/packages/eslint-config-expo

package/templates/skills/cbp-setup-eslint/reference/react.md

@@ -0,0 +1,82 @@
+# react — standalone React (Vite, Tauri) flat config
+
+For React apps that are **not** Next.js (Vite SPA, Tauri desktop webview). Layers on
+[base](base.md). Maps to the CBP **`react`** DB preset
+(`tech_match.requires: ["React"]`, `excludes: ["Next.js"]`, `requires_capabilities: ["jsx"]`).
+
+> **Verified 2026-05-31.** **Do NOT install `eslint-plugin-react-compiler`** — it is
+> superseded. React Compiler v1.0 (Oct 2025) merged the compiler lint rules into
+> **`eslint-plugin-react-hooks@7`** under `configs.flat["recommended-latest"]`.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint-plugin-react` | `7.37.5` | React rules + JSX parsing (`configs.flat.*`) |
+| `eslint-plugin-react-hooks` | `7.1.1` | hooks rules **+ bundled React Compiler rules** |
+| `eslint-plugin-jsx-a11y` | `6.10.2` | accessibility (`flatConfigs.*` — note plural) |
+
+```bash
+pnpm add -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y globals
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import { defineConfig } from "eslint/config";
+import react from "eslint-plugin-react";
+import reactHooks from "eslint-plugin-react-hooks";
+import jsxA11y from "eslint-plugin-jsx-a11y";
+import globals from "globals";
+
+export default defineConfig([
+  react.configs.flat.recommended,                 // namespaced react/, enables JSX parsing
+  react.configs.flat["jsx-runtime"],              // React 17+ automatic JSX transform
+  reactHooks.configs.flat["recommended-latest"],  // hooks + React Compiler rules
+  jsxA11y.flatConfigs.strict,                      // or flatConfigs.recommended
+  {
+    files: ["**/*.{js,jsx,ts,tsx}"],
+    languageOptions: { globals: globals.browser },
+    settings: { react: { version: "detect" } },
+  },
+]);
+```
+
+## Gotchas
+
+- **`eslint-plugin-react` flat configs do not set `files` or globals** — add your own
+  `files`/`globals.browser`/`settings.react.version` object (shown above) or you'll get the
+  "React version not specified" warning and no JSX globals.
+- **`eslint-plugin-react-hooks` v7 keys** live under `configs.flat.*`:
+  `recommended` (standard hooks) vs `recommended-latest` (hooks **+ compiler** rules — use
+  this for React 19 + the compiler).
+- **`jsx-a11y` uses `flatConfigs` (plural)** — `jsxA11y.flatConfigs.strict`, a different
+  namespace from react's `configs.flat`.
+
+## Storybook (bonus)
+
+If the app uses Storybook, add `eslint-plugin-storybook@10.4.1`:
+
+```js
+import storybook from "eslint-plugin-storybook";
+// ...spread into the array:
+...storybook.configs["flat/recommended"],
+```
+
+The standalone plugin repo was archived (2025-11); it now lives in the Storybook monorepo but
+the npm name `eslint-plugin-storybook` is unchanged.
+
+## CBP preset divergence
+
+CBP's `react` preset still depends on `eslint-plugin-react-compiler: ^19.0.0` and registers
+`react-compiler/react-compiler`. The latest guidance removes that plugin and relies on
+`eslint-plugin-react-hooks@7`'s `recommended-latest`. Adopt that when regenerating; the skill
+does not modify the preset.
+
+## Official docs
+
+- eslint-plugin-react: https://github.com/jsx-eslint/eslint-plugin-react
+- react-hooks: https://react.dev/reference/eslint-plugin-react-hooks
+- React Compiler v1.0: https://react.dev/blog/2025/10/07/react-compiler-1
+- jsx-a11y: https://github.com/jsx-eslint/eslint-plugin-jsx-a11y