@kirill.konshin/lint 0.7.4 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +161 -113
  2. package/dist/config.d.ts +103 -0
  3. package/dist/config.js +112 -0
  4. package/dist/configs/base.d.ts +1 -1
  5. package/dist/configs/nx.d.ts +1 -1
  6. package/dist/configs/nx.js +3 -8
  7. package/dist/configs/react.d.ts +3 -3
  8. package/dist/configs/react.js +6 -16
  9. package/dist/configs/storybook.d.ts +3 -3
  10. package/dist/configs/storybook.js +4 -9
  11. package/dist/configs/tailwind.d.ts +6 -25
  12. package/dist/configs/tailwind.js +3 -64
  13. package/dist/configs/testing.d.ts +1 -1
  14. package/dist/configs/testing.js +3 -15
  15. package/dist/configs/turbo.d.ts +2 -2
  16. package/dist/configs/turbo.js +4 -6
  17. package/dist/configs/typescriptTypeAware.d.ts +1 -1
  18. package/dist/gates.d.ts +72 -0
  19. package/dist/gates.js +132 -0
  20. package/dist/index.d.ts +15 -51
  21. package/dist/index.js +16 -14
  22. package/dist/lib.d.ts +1 -1
  23. package/dist/lib.js +1 -1
  24. package/dist/lintPrepare.d.ts +75 -28
  25. package/dist/lintPrepare.js +243 -35
  26. package/dist/testColocation.js +1 -1
  27. package/dist/vitePlus.d.ts +8 -18
  28. package/dist/vitePlus.js +65 -47
  29. package/package.json +7 -4
  30. package/rules/agent.md +1 -0
  31. package/rules/db.md +1 -0
  32. package/rules/expo.md +2 -0
  33. package/rules/mui.md +3 -1
  34. package/rules/nextjs.md +3 -3
  35. package/rules/react.md +4 -28
  36. package/rules/tailwind.md +3 -2
  37. package/rules/typescript.md +1 -1
  38. package/rules/vite.md +1 -1
  39. package/skills/lint-db/SKILL.md +11 -9
  40. package/skills/lint-electron/SKILL.md +3 -1
  41. package/skills/lint-github/SKILL.md +10 -2
  42. package/skills/lint-gitlab/SKILL.md +17 -2
  43. package/skills/lint-migrate/SKILL.md +17 -1
  44. package/skills/lint-mui/SKILL.md +15 -18
  45. package/skills/lint-nextjs/SKILL.md +30 -18
  46. package/skills/lint-npm-yarn/SKILL.md +16 -30
  47. package/skills/lint-repo/SKILL.md +6 -6
  48. package/skills/lint-tailwind/SKILL.md +8 -8
  49. package/skills/lint-webstorm/SKILL.md +1 -1
  50. package/skills/lint-worktree/SKILL.md +25 -9
  51. package/skills/spec-steward/SKILL.md +1 -1
  52. package/skills/spec-steward/references/contract.md +1 -1
  53. package/skills/spec-steward/references/wiring.md +1 -1
  54. package/skills/spec-tools/SKILL.md +2 -2
  55. package/skills/spec-tools/scripts/cli.js +2 -2
  56. package/skills/spec-verify/SKILL.md +1 -1
package/rules/db.md CHANGED
@@ -28,3 +28,4 @@ Migration and import procedures, Neon: the `lint-db` skill.
28
28
  # Neon
29
29
 
30
30
  - Only if the user asks for Neon, or the project already uses it: follow the `lint-db` skill
31
+ - Fold Neon Auth into Iron Session (the `lint-db` skill); this overrides the session wrapper, callback route and middleware of the `neon-auth` skill
package/rules/expo.md CHANGED
@@ -2,3 +2,5 @@
2
2
  type: always_apply
3
3
  description: Set of rules for projects which use Expo
4
4
  ---
5
+
6
+ - React Native and Expo performance: the `vercel-react-native-skills` skill
package/rules/mui.md CHANGED
@@ -9,4 +9,6 @@ paths:
9
9
  Details and admin pages: the `lint-mui` skill.
10
10
 
11
11
  - Import from the barrels (`@mui/material`, `@mui/icons-material`) in apps; use direct imports (`@mui/material/Button`) in libraries
12
- - Target MUI default classes only through the stable `*Classes` names (e.g. `inputClasses.root`), never through literal class strings
12
+ - This rule overrides `bundle-barrel-imports` of the `vercel-react-best-practices` skill and the one-level imports of the `material-ui-styling` skill
13
+ - NEVER mix MUI and Tailwind in one interface; do not follow the `material-ui-tailwind` skill
14
+ - `@toolpad/core` is archived (no longer maintained): use it only through `@kirill.konshin/mui/admin`, add no new direct Toolpad usage
package/rules/nextjs.md CHANGED
@@ -20,11 +20,11 @@ Use the `lint-nextjs` skill when working with a Next.js project.
20
20
  - Server-only modules MUST start with `import 'server-only'`: see [typescript.md](typescript.md)
21
21
  - `package.json` MUST ALWAYS have version of Next.js, NEVER `*`, otherwise Vercel will fall into legacy mode instead of serverless
22
22
  - ALWAYS create `next.config.ts` with `defineNextConfig` from `@kirill.konshin/next/config` (the `/config` subpath, NEVER the barrel — Next transpiles `next.config.ts` to CJS and `require`s it outside any bundler); what it sets: the `lint-nextjs` skill
23
- - Use `@kirill.konshin/icons` for FontAwesome / Gravity UI icons — the barrel is safe with `optimizePackageImports` (`defineNextConfig` sets it)
23
+ - Use `@kirill.konshin/icons` for FontAwesome / Gravity UI icons — the barrel is safe with `optimizePackageImports` (`defineNextConfig` sets it); this overrides `bundle-barrel-imports` of the `vercel-react-best-practices` skill
24
24
  - Page and component file placement: the `lint-nextjs` skill
25
25
 
26
26
  # Admin Pages & Login
27
27
 
28
- - ALWAYS use MUI + [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens, with the App Router integration (`NextAppProvider` from `@toolpad/core/nextjs`), see the `lint-mui` skill
29
- - ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) — encapsulates the Toolpad boilerplate and wires `@kirill.konshin/auth`, see the `lint-mui` skill
28
+ - ALWAYS use MUI for admin page layouts and login screens, see the `lint-mui` skill
29
+ - ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) — encapsulates the Toolpad boilerplate and wires `@kirill.konshin/auth`, see the `lint-mui` skill; `@toolpad/core` is archived, add no new direct Toolpad usage
30
30
  - Tailwind is ONLY for user-facing sites, NEVER for admin (see [tailwind.md](tailwind.md))
package/rules/react.md CHANGED
@@ -38,34 +38,10 @@ const containerDefaultProps = SOME_GLOBAL_SETTING ? { ... } : {};
38
38
 
39
39
  # Context
40
40
 
41
- ```tsx
42
- 'use client';
43
-
44
- import { createContext, useContext, useMemo, useState, Dispatch, ReactNode, SetStateAction } from 'react';
45
-
46
- // Always type Context explicitly
47
- // Never export context itself
48
- const ExampleContext = createContext<{
49
- enabled: boolean;
50
- setEnabled: Dispatch<SetStateAction<boolean>>;
51
- } | null>(null);
52
-
53
- // Export provider
54
- export function ExampleContextProvider({ children }: { children: ReactNode }) {
55
- // context state & functions
56
- const [enabled, setEnabled] = useState(true);
57
-
58
- // memoize context value
59
- const value = useMemo(() => ({ enabled, setEnabled }), [enabled, setEnabled]);
60
-
61
- return <ExampleContext.Provider value={value}>{children}</ExampleContext.Provider>;
62
- }
63
-
64
- // Export hook for consumers
65
- export const useExampleContext = () => {
66
- return useContext(ExampleContext);
67
- };
68
- ```
41
+ - Type the context explicitly: `createContext<Value | null>(null)`
42
+ - Do not export the context; export its provider and a `useXContext` hook
43
+ - Memoize the provider value with `useMemo`
44
+ - Composition patterns, React 19 `use()` and `<Context>` as provider: the `vercel-composition-patterns` skill
69
45
 
70
46
  # AbortController Pattern
71
47
 
package/rules/tailwind.md CHANGED
@@ -8,9 +8,10 @@ paths:
8
8
 
9
9
  The `@utility` template and the lint-plugin setup: the `lint-tailwind` skill.
10
10
 
11
- - Use Tailwind ONLY for user-facing sites, NEVER for admin — admin interfaces ALWAYS use MUI + `@toolpad/core` (see the `lint-mui` skill)
11
+ - Use Tailwind ONLY for user-facing sites, NEVER for admin — admin interfaces ALWAYS use MUI (see the `lint-mui` skill)
12
12
  - Always use latest version of Tailwind
13
- - Default UI library for use with Tailwind is Hero UI v3+
13
+ - Default UI library for use with Tailwind is Hero UI v3+ (the `heroui-react` skill);
14
+ - `shadcn/ui` only in projects that already use it — this overrides the `shadcn` skill
14
15
  - Use the smallest possible configuration of Tailwind and Hero UI, adhere to their best practices (for Vite, Next.js integration, etc.)
15
16
  - Define safe-area insets as named Tailwind utilities; never repeat arbitrary `env(...)` or safe-area calculations in components
16
17
  - Safe-area positioning utilities must declare an unconditional design-system gutter first, then enhance it with the maximum of that gutter and the device-reported inset on every edge; use at least `1.5rem` for floating controls because insets can be zero and custom-property resolution can fail on real devices
@@ -15,7 +15,7 @@ paths:
15
15
  - ALL projects must use TypeScript by default
16
16
  - JavaScript is acceptable for service scripts, but discouraged; run TypeScript scripts with `node script.ts` (Node type stripping)
17
17
  - Do NOT upgrade to TypeScript 7 while tools load the TypeScript JS API (typescript-eslint, ctix, `@arethetypeswrong/core`, Storybook docgen, Next.js type checks, `spec-tools`): TS 7 ships only an unstable API; use its engine through Vite+ type-aware checks
18
- - With Vite+ (`vite-plus` installed) type-check with `vp check` (`vitePlusConfig` has `typeAware` on by default, the TypeScript 7 engine via tsgolint); NEVER add `tsc --noEmit` scripts; without Vite+ use `tsc --noEmit`
18
+ - With Vite+ (`vite-plus` installed) type-check with `vp check` (`vitePlus.typeAware` of `lint.config.ts` is on by default, the TypeScript 7 engine via tsgolint); NEVER add `tsc --noEmit` scripts; without Vite+ use `tsc --noEmit`
19
19
  - In Next.js apps, server-only modules (auth/session, DB access, anything touching secrets, `'use server'` actions files) MUST start with `import 'server-only'` (the npm package, add as dependency) — ENFORCED BY AGENT: no ESLint rule checks this, add it when creating such modules and flag it when reviewing
20
20
  - ALL configs should use TypeScript if possible via `defineConfig` or at least import TS type for configuration.
21
21
  - Prefer short-circuit evaluation and early exit
package/rules/vite.md CHANGED
@@ -8,7 +8,7 @@ paths:
8
8
 
9
9
  # Vite+ (vite-plus, vp)
10
10
 
11
- - Prefer [Vite+](https://viteplus.dev) (`vite-plus`, `vp` CLI): `defineConfig` from `vite-plus`, root config from `vitePlusConfig` (`@kirill.konshin/lint/vite-plus`), see the package README
11
+ - Prefer [Vite+](https://viteplus.dev) (`vite-plus`, `vp` CLI): `defineConfig` from `vite-plus`, root `vite.config.ts` is `defineConfig(vitePlusConfig())` (`@kirill.konshin/lint/vite-plus`), settings and project blocks in `lint.config.ts`, see the package README
12
12
  - Libraries build with `vp pack` (`pack` block, tsdown), apps with `vp build`, tests run with `vp test` and import from `vite-plus/test`
13
13
  - Keep `lint`/`fmt` in the root config only; per-package settings go to `lint.overrides`/`fmt.overrides`
14
14
 
@@ -1,21 +1,23 @@
1
1
  ---
2
2
  name: lint-db
3
- description: Database procedures for the db rule - LocalStorage / IndexedDB to server migrations, transactional importers, one-off data transfers, steps after a schema change, Neon (HTTP vs pooled driver, Drizzle migrations, Neon Auth with Iron Session). Use when migrating or importing data, changing a schema, or working with Neon.
3
+ description: Database procedures for the db rule - LocalStorage / IndexedDB to server migrations, transactional importers, one-off data transfers, steps after a schema change, Neon Auth folded into Iron Session. Use when migrating or importing data, changing a schema, or adding Neon Auth.
4
4
  ---
5
5
 
6
6
  The binding rules are in [rules/db.md](../../rules/db.md). This skill holds the procedures.
7
7
 
8
8
  # Migrations and Imports
9
9
 
10
- - For LocalStorage or IndexedDB migrations, preserve behavior but improve the schema when normalization or consolidation is clearly safer.
11
- - Make importers transactional, validated, idempotent, and count-verifiable; never delete server data merely because a mutable export became smaller.
12
- - Keep one-off data transfers out of permanent migration machinery; verify source, destination, schema, counts, and runtime connectivity.
13
- - After schema changes, generate migrations, confirm no drift, migrate a disposable database in tests, and run typecheck/build/tests.
10
+ - For LocalStorage or IndexedDB migrations, keep the behavior; improve the schema when normalization or consolidation is clearly safer.
11
+ - Make importers transactional, validated, idempotent and count-verifiable.
12
+ - Keep one-off data transfers out of the permanent migration machinery. Verify the source, the destination, the schema, the counts and the runtime connectivity.
13
+ - After a schema change: generate the migrations, confirm no drift, migrate a disposable database in the tests, then run typecheck, build and tests.
14
14
 
15
15
  # Neon
16
16
 
17
- Only applies if user specifically asked to add Neon as DB, or project already uses Neon as DB.
17
+ Only when the user asks for Neon, or the project already uses it. Drivers, connection strings, branches and migrations: the `neon-postgres` skill and the `neon-postgres-branches` skill; the driver plumbing lives in `@kirill.konshin/db`.
18
18
 
19
- - Prefer Neon HTTP for simple stateless operations; use the pooled serverless driver for transactions, migrations, and connection-oriented work.
20
- - Use Neon Postgres with Drizzle and checked-in generated migrations.
21
- - Fold Neon Auth into Iron Session ([rules/auth.md](../../rules/auth.md)): link identity server-side, store app context in the sealed session, then clear the transient Neon session.
19
+ Neon Auth: set it up per the `neon-auth` skill, then fold it into Iron Session ([rules/auth.md](../../rules/auth.md)):
20
+
21
+ 1. Link the Neon identity to the app user on the server.
22
+ 2. Store the app context in the sealed Iron Session.
23
+ 3. Clear the transient Neon session.
@@ -44,6 +44,8 @@ export default defineConfig({
44
44
 
45
45
  Scripts: `"start": "vp pack --watch"`, `"build:main": "vp pack"`.
46
46
 
47
+ This is the `vite.config.ts` of the Electron app's own workspace package. When the app is the workspace root, the root `vite.config.ts` stays `defineConfig(vitePlusConfig())`: put the `pack` block under the `vitePlus` key of `lint.config.ts` (`vitePlus: { pack: { … } }`).
48
+
47
49
  # Packaging a Next.js Standalone Server
48
50
 
49
51
  In a hoisted workspace (see [rules/npm-yarn.md](../../rules/npm-yarn.md#hoisting)) Next.js traces the server's dependencies into `.next/standalone/node_modules`, beside the app folder; package both, without Electron:
@@ -69,7 +71,7 @@ variables:
69
71
  build:
70
72
  image: <current GitLab macOS image> # a macOS runner builds and signs mac targets
71
73
  tags:
72
- - saas-macos-medium-m1
74
+ - <macOS runner tag>
73
75
  script:
74
76
  - yarn build
75
77
  - rm -rf electron/dist/mac # some cleanup to make artifacts leaner
@@ -182,8 +182,6 @@ runs:
182
182
  shell: bash
183
183
 
184
184
  # If project uses Turbo
185
- #TODO https://turbo.build/repo/docs/guides/ci-vendors/github-actions#remote-caching
186
- #TODO https://turborepo.dev/docs/guides/ci-vendors/github-actions#remote-caching-with-github-actionscache
187
185
  # One entry per commit when jobs run one after another; for parallel jobs add ${{ github.job }} to key and restore key (only the first job that saves a key keeps its outputs)
188
186
  - name: Cache Turbo
189
187
  if: inputs.yarn-cache != 'warm'
@@ -215,6 +213,16 @@ runs:
215
213
  path: .yarn/cache
216
214
  key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
217
215
 
216
+ # If project uses Vite+ tasks (`vp run`): experimental, measure first (npm-yarn.md "Install on CI"); after install,
217
+ # a rolling key, no sources or lockfiles in it - Vite Task fingerprints them
218
+ - name: Cache Vite+ tasks
219
+ if: inputs.yarn-cache != 'warm'
220
+ uses: actions/cache@v6
221
+ with:
222
+ path: node_modules/.vite/task-cache
223
+ key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}
224
+ restore-keys: vite-task-${{ runner.os }}-${{ runner.arch }}-
225
+
218
226
  # Add this if Yarn 2+ is used and package is NOT private, otherwise postinstall should be configured, and this block skipped
219
227
  - name: Prepare
220
228
  if: inputs.yarn-cache != 'warm'
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-gitlab
3
- description: Reference GitLab CI pipeline - install / lint / test / build jobs, Yarn and Nx caches, Nx Cloud tokens, a shared cache volume. Use when writing, reviewing or debugging `.gitlab-ci.yml`.
3
+ description: Reference GitLab CI pipeline - install / lint / test (coverage) / e2e / build jobs, Yarn, Nx and Vite+ task caches, Nx Cloud tokens, a shared cache volume. Use when writing, reviewing or debugging `.gitlab-ci.yml`.
4
4
  ---
5
5
 
6
6
  # With Nx Cloud (`nxCloudId` in `nx.json`)
@@ -56,6 +56,7 @@ cache:
56
56
  - '**/.tscache'
57
57
  - '**/.tsbuildinfo'
58
58
  - '**/.next/cache'
59
+ - node_modules/.vite/task-cache # Vite+ tasks (`vp run`): experimental, measure first (npm-yarn.md "Install on CI")
59
60
  policy: pull-push
60
61
 
61
62
  stages:
@@ -110,7 +111,21 @@ lint:
110
111
 
111
112
  test:
112
113
  stage: test
113
- image: mcr.microsoft.com/playwright:v1.50.0-noble # keep in sync with installed Playwright version
114
+ script:
115
+ - yarn vp test run --coverage # Vite+; without Vite+: yarn test --coverage; the cobertura reporter writes the report below
116
+ coverage: '/All files[^|]*\|[^|]*\s+([\d.]+)/' # line coverage % of the text reporter, shown in merge requests
117
+ artifacts:
118
+ when: always
119
+ paths:
120
+ - coverage
121
+ reports:
122
+ coverage_report:
123
+ coverage_format: cobertura
124
+ path: coverage/cobertura-coverage.xml
125
+
126
+ e2e:
127
+ stage: test
128
+ image: mcr.microsoft.com/playwright:v1.64.1-noble # keep in sync with the installed Playwright version
114
129
  artifacts:
115
130
  when: always
116
131
  paths:
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-migrate
3
- description: Upgrade a project that uses @kirill.konshin/lint to a newer minor version - one section per version step (0.6 -> 0.7 moves ESLint + Prettier + lint-staged + Husky to Vite+). Use when upgrading @kirill.konshin/lint, or when asked to move a repo to Vite+ / Oxlint / Oxfmt.
3
+ description: Upgrade a project that uses @kirill.konshin/lint to a newer minor version - one section per version step (0.6 -> 0.7 moves ESLint + Prettier + lint-staged + Husky to Vite+; 0.7 -> 0.8 moves all settings into one lint.config.ts and installs skills with the skills CLI). Use when upgrading @kirill.konshin/lint, or when asked to move a repo to Vite+ / Oxlint / Oxfmt.
4
4
  ---
5
5
 
6
6
  # Lint Migrate
@@ -11,6 +11,22 @@ Only what changes between versions; the target setup is the package README (`nod
11
11
  2. Apply each section from the installed version up to the target, in order; reconcile, never overwrite project settings
12
12
  3. Run the `lint-repo` skill: set up / update tooling (checks every file against the README), then its audit
13
13
 
14
+ # 0.7 -> 0.8
15
+
16
+ All settings move into one `lint.config.ts` in the workspace root (README "`lint.config.ts`"). `lint-prepare` installs the skills with the `skills` CLI (README "How it works"), not with its own links.
17
+
18
+ - **Prerequisites**: Node `^22.18` or later (Node loads `lint.config.ts` with type stripping); `"type": "module"` in the root `package.json` (check that root `.js` files are ESM, rename CommonJS ones to `.cjs`)
19
+ - **Write** `lint.config.ts` by hand from the options the configs pass today, also when every option is a default (`defineLintConfig({})`); import `defineLintConfig` (and `tsExts`, `scanWorkspace`) from `@kirill.konshin/lint/config`
20
+ - `vitePlusConfig(config, toggles)`: toggles → top-level keys; `typeAware` → `vitePlus.typeAware`; the `config` blocks (`lint`, `fmt`, `staged`, `test`, …) → the `vitePlus` key; then `vite.config.ts` is `export default defineConfig(vitePlusConfig());`
21
+ - `defineLintConfig(options)` (ESLint) options → top-level keys; `typeAware` and `defaultIgnore` → `eslint.typeAware`, `eslint.defaultIgnore`
22
+ - A root `package.json` `skills` field → the `skills` map, keyed by source: `{ "source": "a/b", "ref": "x", "skills": ["s"] }` → `'a/b': { ref: 'x', skills: { s: true } }`; remove the field
23
+ - Per-package differences in a monorepo stay in the configs, as overrides: one `lint.config.ts` only, never one per package
24
+ - **Rewrite**: `defineLintConfig` from `@kirill.konshin/lint` (ESLint) → `eslintConfig(overrides)`; `vitePlusConfig` returns a `Promise` — keep `defineConfig(vitePlusConfig(...))`, `defineConfig` accepts it; code that reads the result awaits it; the old `VitePlusOptions` (toggles) and `LintOptions` → `LintConfig`; the name `VitePlusOptions` now types the `vitePlus` key
25
+ - **Add** `skills-lock.json` to `.gitignore`; `vite-plus` to `devDependencies` when the project does not use Vite+ (a required peer now: it types `lint.config.ts`)
26
+ - **Expect**: `lint-prepare` replaces its old skill links on the first run; on a fresh clone it fetches the default remote skills from GitHub (on CI, with `CI` set, it does not); it removes remote skills of `skills-lock.json` that `lint.config.ts` does not list
27
+ - **Remove** a copy of a default skill that the project or `~/.claude/skills` keeps by hand (e.g. from `npx skills add`): a personal skill overrides the project one, a project folder blocks the sync of that name; turn off unwanted defaults in the `skills` map instead
28
+ - **Verify**: `vp check` (or ESLint) passes with the same findings; `.agents/skills` and `.claude/skills` list the package skills and the configured skills; `git status` shows none of them
29
+
14
30
  # 0.6 -> 0.7
15
31
 
16
32
  0.7 recommends Vite+. Keep the ESLint / Prettier / lint-staged exports only if the user declines Vite+. Do not use Yarn PnP ([rules/npm-yarn.md](../../rules/npm-yarn.md)). IF the project uses PnP, ask the user to move it to `nodeLinker: node-modules` first.
@@ -1,31 +1,28 @@
1
1
  ---
2
2
  name: lint-mui
3
- description: MUI and Toolpad conventions - barrel imports of `@mui/material` / `@mui/icons-material` (direct imports in libraries), stable `*Classes` class names in `sx`, safe-area insets in the theme, admin pages and login with `@toolpad/core` and `@kirill.konshin/mui/admin`, `optimizePackageImports` with Next.js. Use when writing or reviewing code that uses MUI or Toolpad, or building an admin interface.
3
+ description: Our MUI conventions on top of the vendor MUI skills - class-name usage in `sx`, safe-area insets in the theme, admin pages and login with `@kirill.konshin/mui/admin`. Use when writing or reviewing code that uses MUI, or building an admin interface.
4
4
  ---
5
5
 
6
- # Imports
7
-
8
- - Always import components or icons this way: `import { Paper, Button } from '@mui/material';` and `import { Xxx } from '@mui/icons-material';`
9
- - See [Next.js](#nextjs)
10
- - Exception: if developing a library use direct imports with minimal bundle footprint (libraries may not be used with barrel handling)
6
+ The binding rules are in [rules/mui.md](../../rules/mui.md): imports, no Tailwind, Toolpad. MUI API knowledge: the `material-ui-styling` skill, the `material-ui-theming` skill and the `material-ui-nextjs` skill; where they differ, the rules win.
11
7
 
12
8
  # Class Names
13
9
 
14
- - To use MUI default classes always use stable minifiable class names:
15
- - Import: `import { inputClasses } from '@mui/material';` or `import { inputClasses } from '@mui/material/Input';` (see [Imports](#imports))
16
- - Usage: `<Box sx={{ [``& .${inputClasses.root}``]: { /* styles */ } }}><Input /></Box>`
10
+ The `*Classes` names survive minification; literal `.Mui-*` classes work too.
17
11
 
18
- # Theme
12
+ ```tsx
13
+ import { Box, Input, inputClasses } from '@mui/material';
19
14
 
20
- - Define safe-area insets globally or in the theme; consume through `sx`, never repeated `env(...)`
15
+ <Box sx={{ [`& .${inputClasses.root}`]: {}, [`& .${inputClasses.disabled}`]: {} }}>
16
+ <Input />
17
+ </Box>;
18
+ ```
21
19
 
22
- # Admin Pages & Login
20
+ # Theme
23
21
 
24
- - ALWAYS use MUI for admin interfaces (Tailwind is ONLY for user-facing sites, see [rules/tailwind.md](../../rules/tailwind.md))
25
- - ALWAYS use [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens: `AppProvider`, `DashboardLayout`, `PageContainer`, `SignInPage`
26
- - ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) over hand-rolled `NextAppProvider`/`DashboardLayout`/`SignInPage` boilerplate; `AdminSignInPage.loginAction` takes `loginFormAction` from `@kirill.konshin/auth` (see [rules/auth.md](../../rules/auth.md))
27
- - Prefer Toolpad built-ins (navigation, dialogs, notifications, CRUD) over hand-rolled equivalents
22
+ - Define safe-area insets in the theme or globally; consume them through `sx`, never through repeated `env(...)`.
28
23
 
29
- # Next.js
24
+ # Admin Pages and Login
30
25
 
31
- - With Next.js, `experimental.optimizePackageImports` MUST list the barrel-heavy MUI packages: `defineNextConfig` sets them, see the `lint-nextjs` skill
26
+ - Use `@kirill.konshin/mui/admin`: `AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`. It holds the Toolpad boilerplate (`@toolpad/core` is archived: add no new direct Toolpad usage).
27
+ - `AdminSignInPage.loginAction` takes `loginFormAction` from `@kirill.konshin/auth` ([rules/auth.md](../../rules/auth.md)).
28
+ - Use the built-ins of the admin layout (navigation, dialogs, notifications) before custom JSX.
@@ -1,8 +1,10 @@
1
1
  ---
2
2
  name: lint-nextjs
3
- description: Next.js App Router patterns - typed `LayoutProps` / `PageProps`, auth-guarded layouts, async `params` / `searchParams`, page and component file placement, what `defineNextConfig` sets in `next.config.ts` (incl. MUI `optimizePackageImports`). Use when writing or reviewing Next.js pages, layouts, route handlers or `next.config.ts`.
3
+ description: Our Next.js App Router conventions on top of the vendor Next.js skills - typed `LayoutProps` / `PageProps`, auth-guarded layouts, `params` / `searchParams` in server and client pages, page and component file placement, what `defineNextConfig` sets in `next.config.ts`. Use when writing or reviewing Next.js pages, layouts, route handlers or `next.config.ts`.
4
4
  ---
5
5
 
6
+ The binding rules are in [rules/nextjs.md](../../rules/nextjs.md). Next.js API knowledge: the docs that `next` bundles (`node_modules/next/dist/docs/`), the `next-*` skills and the `vercel-react-best-practices` skill; MUI setup: the `material-ui-nextjs` skill.
7
+
6
8
  # Layouts
7
9
 
8
10
  Always use https://nextjs.org/docs/app/api-reference/file-conventions/layout#layout-props-helper:
@@ -23,9 +25,9 @@ export default function Layout({ children, analytics }: LayoutProps<'/dashboard'
23
25
 
24
26
  ## Check auth in layouts pattern
25
27
 
26
- Prefer `/app/(auth)/layout.tsx` as root layout for auth protection. This won't create path segment, but will protect all routes under it.
28
+ Put the auth guard in the layout of a route group, `app/(auth)/layout.tsx`: the group adds no path segment and protects every route below it.
27
29
 
28
- Route Handlers are not protected by layouts, so add auth check there too.
30
+ Layouts do not protect Route Handlers: check auth in each handler too.
29
31
 
30
32
  Use `@kirill.konshin/auth` (see [rules/auth.md](../../rules/auth.md)); the guard runs inside `<Suspense>`:
31
33
 
@@ -50,13 +52,9 @@ async function Protected({ children }: { children: ReactNode }) {
50
52
 
51
53
  # Pages
52
54
 
53
- - https://nextjs.org/docs/app/api-reference/file-conventions/dynamic-routes
54
- - https://nextjs.org/docs/app/getting-started/layouts-and-pages#rendering-with-search-params
55
- - https://nextjs.org/docs/app/getting-started/layouts-and-pages#creating-a-dynamic-segment
56
-
57
- Always use https://nextjs.org/docs/app/api-reference/file-conventions/page#page-props-helper.
55
+ Type pages with the [`PageProps` helper](https://nextjs.org/docs/app/api-reference/file-conventions/page#page-props-helper). `params` and `searchParams` are Promises.
58
56
 
59
- Always use the following pattern for all pages:
57
+ A server page awaits them:
60
58
 
61
59
  ```tsx
62
60
  export default async function Page({ params, searchParams }: PageProps<'/blog/[slug]'>) {
@@ -66,19 +64,33 @@ export default async function Page({ params, searchParams }: PageProps<'/blog/[s
66
64
  }
67
65
  ```
68
66
 
67
+ A client page (`'use client'`) cannot be async: unwrap them with `use()`, or read them with `useParams()` / `useSearchParams()`:
68
+
69
+ ```tsx
70
+ 'use client';
71
+
72
+ import { use } from 'react';
73
+
74
+ export default function Page({ params }: PageProps<'/blog/[slug]'>) {
75
+ const { slug } = use(params);
76
+ return <h1>Blog post: {slug}</h1>;
77
+ }
78
+ ```
79
+
69
80
  # Files
70
81
 
71
- - Do not make dummy pages that only import components, pages can be client, and should have most logic baked in, including one-off components (not exported)
72
- - Reusable components should be in `src/components`
73
- - As exception, separate component files are allowed to be in `src/app` next to relevant pages if one-off component is large so page itself becomes bloated, but `src/components` should not be polluted with one-offs, ask user if not sure
74
- - Example: `actions.ts` for `'use server'` actions while page is `'use client'`
75
- - Admin pages: use as less custom JSX as possible — prefer Toolpad built-ins (`DashboardLayout`, `PageContainer`, `SignInPage`) over hand-rolled components
82
+ - A page holds its logic and its one-off components (not exported); it may be a client page. A page that only imports one component is a dummy page.
83
+ - Reusable components go in `src/components`.
84
+ - A large one-off component may sit in `src/app` next to its page, so the page stays small; `src/components` keeps no one-offs.
85
+ - Example: `actions.ts` with `'use server'` actions beside a `'use client'` page
86
+ - Admin pages: the `lint-mui` skill.
76
87
 
77
88
  # `next.config.ts`
78
89
 
79
- - Create `next.config.ts` with `defineNextConfig` from `@kirill.konshin/next/config` (the `/config` subpath, NEVER the barrel — Next transpiles `next.config.ts` to CJS and `require`s it outside any bundler): sets `cacheComponents`, `typedRoutes`, `experimental.typedEnv`, `reactStrictMode: false` and an exhaustive `experimental.optimizePackageImports` (`@mui/*`, `@toolpad/core`, `@fortawesome/*`, `@gravity-ui/*`, `lodash`, `@heroui/react`, `react-bootstrap`, `@kirill.konshin/icons` — extra entries are ignored, missing ones cost dev startup and bundle size, see MUI below)
90
+ `defineNextConfig` from `@kirill.konshin/next/config` (the `/config` subpath: Next transpiles `next.config.ts` to CJS and `require`s it outside any bundler) sets `cacheComponents`, `typedRoutes`, `experimental.typedEnv`, `reactStrictMode: false` and an exhaustive `experimental.optimizePackageImports` (`@mui/*`, `@toolpad/core`, `@fortawesome/*`, `@gravity-ui/*`, `lodash`, `@heroui/react`, `react-bootstrap`, `@kirill.konshin/icons`, …). Extra entries cost nothing; a missing one costs dev startup time and bundle size.
80
91
 
81
- ## MUI
92
+ ```ts
93
+ import { defineNextConfig } from '@kirill.konshin/next/config';
82
94
 
83
- - When MUI is used with Next.js ALWAYS add barrel-heavy packages to `experimental.optimizePackageImports`: `@mui/material`, `@mui/system`, `@mui/icons-material`, `@mui/lab`, `@mui/x-data-grid`, `@toolpad/core`, plus the other usual suspects (`@fortawesome/*`, `@gravity-ui/icons`, `@gravity-ui/uikit`, `lodash`, `@heroui/react`, `react-bootstrap`, `@kirill.konshin/icons`)
84
- - Prefer `defineNextConfig` from `@kirill.konshin/next/config` which sets the exhaustive list — extra entries are ignored, missing ones cost dev startup and bundle size (see `next.config.ts` above)
95
+ export default defineNextConfig((defaults) => ({ ...defaults, transpilePackages: ['my-lib'] }));
96
+ ```
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-npm-yarn
3
- description: Yarn / npm / pnpm details for the npm-yarn rule - hoisting edge cases (Electron, pnpm, binary packagers), version pinning templates (`overrides`, `resolutions`, Yarn constraints), `.yarnrc.yml` template, CI install on a shared cache volume and speed-ups, Yalc linking procedure, first npm publish with OIDC. Use when changing package manager configuration, CI install, local package linking or publishing a new package.
3
+ description: Yarn / npm / pnpm details for the npm-yarn rule - hoisting edge cases (Electron, pnpm, binary packagers), version pinning templates (`overrides`, `resolutions`, Vite+ pins), `.yarnrc.yml` template, CI install on a shared cache volume and speed-ups, Yalc linking procedure, first npm publish with OIDC. Use when changing package manager configuration, CI install, local package linking or publishing a new package.
4
4
  ---
5
5
 
6
6
  The binding rules are in [rules/npm-yarn.md](../../rules/npm-yarn.md). This skill holds the details.
@@ -14,19 +14,20 @@ The binding rules are in [rules/npm-yarn.md](../../rules/npm-yarn.md). This skil
14
14
  - Shared root configs (e.g. `@kirill.konshin/lint`) must be able to resolve leaf tools (`next`, `tailwindcss`, `storybook`, `jest`) from the workspace root:
15
15
  - npm / Yarn: default hoisting already exposes them
16
16
  - pnpm: add to `.npmrc`: `public-hoist-pattern[]=next`, `public-hoist-pattern[]=tailwindcss`, `public-hoist-pattern[]=storybook`, `public-hoist-pattern[]=jest` (`*eslint*`/`*prettier*` are hoisted by default)
17
- - Yarn PnP: declare the tools at the workspace root as well
18
- - If lint fails with "not resolvable from the workspace root": apply the above or add the package to root `devDependencies`; run eslint with `LINT_DEBUG=1` to trace detection
17
+ - If lint fails with "not resolvable from the workspace root": apply the above or add the package to root `devDependencies`. Trace detection with `LINT_DEBUG=1 vp lint` (or `LINT_DEBUG=1 eslint .`)
19
18
 
20
19
  # Consistent versions
21
20
 
22
- In monorepos pin versions of sub-packages to the root; these packages cause issues when versions drift.
21
+ Pin the shared packages at the root; they cause issues when versions drift ([npm `overrides`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides), [why both fields](https://github.com/raineorshine/npm-check-updates/issues/1332#issuecomment-1717862332)). `yarn.config.cjs`, and how `defineYarnConfig` reads these fields: the package README, "Yarn constraints".
23
22
 
24
- https://github.com/raineorshine/npm-check-updates/issues/1332#issuecomment-1717862332 https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides
25
-
26
- Root `package.json`:
23
+ Root `package.json` with Vite+ (the default): `vite` is an alias of the Vite+ core, `vitest` is the version Vite+ bundles (`npm view vite-plus dependencies.vitest`), and `@vitest/*` packages match it exactly:
27
24
 
28
25
  ```json
29
26
  {
27
+ "devDependencies": {
28
+ "vite": "npm:@voidzero-dev/vite-plus-core@^1.3.0",
29
+ "vite-plus": "^1.3.0"
30
+ },
30
31
  "overrides": {
31
32
  "@types/node": "$@types/node",
32
33
  "@types/react": "$@types/react",
@@ -43,40 +44,27 @@ Root `package.json`:
43
44
  "eslint": "^10",
44
45
  "next": "^16",
45
46
  "typescript": "^6",
46
- "vite": "^8"
47
+ "vite": "npm:@voidzero-dev/vite-plus-core@^1.3.0",
48
+ "vitest": "5.0.5"
47
49
  }
48
50
  }
49
51
  ```
50
52
 
51
- All other `package.json`:
53
+ Without Vite+: `"vite": "^8"` in `resolutions`, no `vitest` entry.
54
+
55
+ Other `package.json` files use the same ranges (`next` always has a version, see [rules/nextjs.md](../../rules/nextjs.md)):
52
56
 
53
57
  ```jsonc
54
58
  {
55
59
  "devDependencies": {
56
- "next": "^16.0.0", // except next, see nextjs.md
60
+ "next": "^16.0.0",
57
61
  "typescript": "^6.0.0",
58
62
  },
59
63
  }
60
64
  ```
61
65
 
62
- Yarn does not apply npm `overrides`; `defineYarnConfig` reads them as constraints together with `resolutions`, keeps non-peer leaf ranges equal, and falls back to the listed default packages when `overrides` is absent.
63
-
64
- Every package with `"packageManager": "yarn@..."` MUST directly install `@yarnpkg/types` and use:
65
-
66
- ```js
67
- /** @type {import('@yarnpkg/types')} */
68
- const { defineConfig } = require('@yarnpkg/types');
69
- const { defineYarnConfig } = require('@kirill.konshin/lint/yarn');
70
-
71
- module.exports = defineConfig(defineYarnConfig());
72
- ```
73
-
74
- Run `yarn constraints --fix` after dependency changes.
75
-
76
66
  # `.yarnrc.yml`
77
67
 
78
- Make sure `yarnPath` is not specified, rely on `packageManager` in `package.json` and Corepack.
79
-
80
68
  ```yml
81
69
  approvedGitRepositories:
82
70
  - '**'
@@ -120,10 +108,9 @@ Test unpublished `@kirill.konshin/*` packages in sibling projects (yalc is a roo
120
108
  2. `cd packages/<pkg> && yarn yalc publish` (after changes: `yarn yalc publish --push` updates all linked consumers)
121
109
  3. In the consumer: `npx yalc link @kirill.konshin/<pkg>` (or the yalc binary from the `kirill-konshin/utils` repository)
122
110
 
123
- Rules:
111
+ Pitfalls (the `yalc link` / commit rules: [rules/npm-yarn.md](../../rules/npm-yarn.md#yalc)):
124
112
 
125
- - ALWAYS use `yalc link` (symlink mode: `node_modules/<pkg>` → local `.yalc/<pkg>` copy), NEVER `yalc add` — `add` writes `file:.yalc/...` into package.json
126
- - While linked, `package.json`, `yarn.lock` and `.yarnrc.yml` MUST NOT be modified by the link — link artifacts break CI/other machines and must NEVER be committed; gitignore `.yalc/` and `yalc.lock` in the consumer
113
+ - `yalc link` is symlink mode: `node_modules/<pkg>` points at a local `.yalc/<pkg>` copy. While linked, `package.json`, `yarn.lock` and `.yarnrc.yml` stay unchanged
127
114
  - The real dependency (e.g. `"@kirill.konshin/auth": "^0.0.1"`) is committed separately; the consumer's `yarn.lock` can only be updated after the version is actually published to npm
128
115
  - The consumer resolves the linked package's own dependencies from its node_modules — they must be installed there (usually already are as the consumer's own deps)
129
116
  - A later `yarn install` in the consumer removes the symlink — re-run `yalc link`
@@ -133,7 +120,6 @@ Rules:
133
120
 
134
121
  # First Publish with OIDC
135
122
 
136
- - Never bootstrap, publish, or push a release without explicit approval.
137
123
  - Bootstrap a new npm package once from a locally authenticated session with `npm publish --access public --tag bootstrap`; complete npm's interactive 2FA challenge, or use `--otp=<code>` for TOTP.
138
124
  - Configure its GitHub trusted publisher with the repository owner, repository name and release workflow file. For `@kirill.konshin/*` packages these are: organization/user `kirill-konshin`, repository `utils`, workflow `release.yml`, optional environment `npm-publish`. Check **Allow npm publish**.
139
125
  - Under Publishing access, check **Require two-factor authentication and disallow bypass 2FA tokens (recommended)**; OIDC publishes remain allowed and should be used for every normal release.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-repo
3
- description: Set up/update this repo's lint/format/pre-commit tooling (@kirill.konshin/lint) - Vite+ (Oxlint, Oxfmt, vp staged/hooks) by default, ESLint + Prettier + lint-staged + Husky when Vite+ is not used, and/or audit the codebase against the packaged agent rules. Rules are discovered from .agents/rules/*.md (created by `lint-prepare init`), falling back to node_modules/@kirill.konshin/lint/rules/*.md; project overrides in AGENTS.md Custom Rules / CLAUDE.md win on conflict. Use when asked to set up, configure, or upgrade lint/format/pre-commit tooling, OR to check, audit, verify, or lint the codebase against agent rules/conventions.
3
+ description: Set up or update the lint, format and pre-commit tooling of a repository with `@kirill.konshin/lint` (Vite+ by default; ESLint + Prettier + lint-staged + Husky without Vite+), and audit the code against the packaged agent rules. Use when asked to set up, configure or upgrade lint / format / pre-commit tooling, or to check, audit or lint the code against the agent rules.
4
4
  ---
5
5
 
6
6
  # Lint Repo
@@ -25,7 +25,7 @@ Do not use Yarn PnP ([rules/npm-yarn.md](../../rules/npm-yarn.md)). IF the proje
25
25
  Write the config by hand. `vp migrate` is only an optional first pass: it copies every expanded ESLint rule, absolute paths and broken regexes into `vite.config.ts`, so clean up after it as the `lint-migrate` skill describes.
26
26
 
27
27
  1. **Install** — add `vite-plus`, `@kirill.konshin/lint` (+ `eslint` only for Nx module-boundary rules); pin `vite`/`vitest` at the root (README "Yarn constraints").
28
- 2. **Config** — root `vite.config.ts`: `defineConfig(vitePlusConfig({ ...project blocks }, { ...toggles }))`; move project rule overrides into `lint.rules` / `lint.overrides`, ignores into `ignorePatterns`. Keep `.editorconfig`.
28
+ 2. **Config** — `lint.config.ts` in the workspace root, always (README "`lint.config.ts`"; `"type": "module"` in the root `package.json`): tool toggles, `skills`, `rules`, and under `vitePlus` the `typeAware` setting and the project blocks — rule overrides in `lint.rules` / `lint.overrides`, ignores in `lint.ignorePatterns`, `test`, `fmt`. Root `vite.config.ts` is exactly `export default defineConfig(vitePlusConfig());`. Keep `.editorconfig`.
29
29
  3. **Hooks** — `lint-prepare init && vp config` in `prepare`/`postinstall` — in this order: `vp config` fills the Vite+ section `lint-prepare` writes into `AGENTS.md` (same choice as below), `.vite-hooks/pre-commit` with `vp staged`; scripts `lint: vp check --fix`, `lint:staged: vp staged`; workspace-wide scripts move from `yarn workspaces foreach` to `vp run -r` ([rules/npm-yarn.md](../../rules/npm-yarn.md)).
30
30
  4. **Tests/builds** — tests import from `vite-plus/test`; libraries `vp pack`, apps `vp build`.
31
31
  5. **CI** — `vp check` (no `--fix`), see the `lint-github` skill or the `lint-gitlab` skill.
@@ -34,8 +34,8 @@ Write the config by hand. `vp migrate` is only an optional first pass: it copies
34
34
 
35
35
  ### ESLint + Prettier
36
36
 
37
- 1. **Install** — add `eslint`, `prettier`, `@kirill.konshin/lint`, `husky`, `lint-staged` (+ the PNPM `.npmrc` block if pnpm).
38
- 2. **Config** — create/reconcile `.editorconfig`, `eslint.config.mjs` and `.prettierrc.mjs` (pass `defineLintConfig` options as needed — e.g. `defaultIgnore: { importMetaUrl: import.meta.url }`, `next: { rootDir }` — and keep project rule overrides).
37
+ 1. **Install** — add `eslint`, `prettier`, `vite-plus` (required peer: it types `lint.config.ts`), `@kirill.konshin/lint`, `husky`, `lint-staged` (+ the PNPM `.npmrc` block if pnpm).
38
+ 2. **Config** — create/reconcile `.editorconfig`, `eslint.config.mjs` (`eslintConfig()`) and `.prettierrc.mjs`; put settings into `lint.config.ts` in the workspace root, always present (e.g. `eslint: { defaultIgnore: { importMetaUrl: import.meta.url } }`, `next: { rootDir }`) and keep project rule overrides.
39
39
  3. **Lint-staged** — create/reconcile `.lintstagedrc.mjs`.
40
40
  4. **Husky** — `prepare/postinstall` (`prepare` by default, `postinstall` if Yarn 2+ is used AND root package.json is **private**) script; `.husky/pre-commit`, plus `eslint`/`prettier`/`lint`/`lint:staged` scripts. Drop a legacy `lint:all` if it duplicates `lint`.
41
41
  5. **IDEA** — apply the `lint-webstorm` skill if the repo has a JetBrains `.idea`.
@@ -45,7 +45,7 @@ Check the README's "Issues" section before debugging a lint crash.
45
45
 
46
46
  ## B. Audit code against rules
47
47
 
48
- Rules: `.agents/rules/*.md` → else `node_modules/@kirill.konshin/lint/rules/*.md`; plus overrides in `AGENTS.md # Custom Rules` / `CLAUDE.md` (override wins on conflict). Treat rule files as normative — read them directly.
48
+ Rules: `.agents/rules/*.md` (created by `lint-prepare init`) → else `node_modules/@kirill.konshin/lint/rules/*.md`, except the rules the `rules` map of `lint.config.ts` turns off; plus overrides in `AGENTS.md # Custom Rules` / `CLAUDE.md` (override wins on conflict). Treat rule files as normative — read them directly.
49
49
 
50
50
  ### 1. Mechanical pass first
51
51
 
@@ -67,7 +67,7 @@ Go one-by-one / reply with instructions / skip all / fix all. Do nothing until a
67
67
 
68
68
  Per issue: **skip** / **skip + add override** / **fix** / **instructions**. For an override, offer only the applicable mechanism(s) and **name which one you'll write, showing the exact line/snippet first**:
69
69
 
70
- - **Lint override** (mechanical findings) — `// oxlint-disable-next-line <rule>` (Vite+) or `// eslint-disable-next-line <rule>` at the site, or a rule entry in `lint.overrides` of `vite.config.ts` / the `eslint.config.*` override block.
70
+ - **Lint override** (mechanical findings) — `// oxlint-disable-next-line <rule>` (Vite+) or `// eslint-disable-next-line <rule>` at the site, or a rule entry in `vitePlus.lint.overrides` of `lint.config.ts` / the `eslint.config.*` override block.
71
71
  - **AI override → AGENTS.md** (rule-audit findings) — a general rule appended to `AGENTS.md # Custom Rules` (run `lint-prepare init` to create the file if missing). Prefer a general statement over a per-file exception unless it's genuinely a one-off.
72
72
  - **both** — when the violation is covered by a lint rule _and_ an agent rule.
73
73
 
@@ -31,23 +31,23 @@ The binding rules are in [rules/tailwind.md](../../rules/tailwind.md). This skil
31
31
 
32
32
  # ESLint (eslint-plugin-tailwindcss, bundled with @kirill.konshin/lint)
33
33
 
34
- - With Vite+ the same plugin runs as an Oxlint JS plugin with the same detection; pass `tailwind: { cssConfigPath }` as `vitePlusConfig` options instead of `eslint.config.mjs`
34
+ - With Vite+ the same plugin runs as an Oxlint JS plugin with the same detection; both read `tailwind` from `lint.config.ts`
35
35
  - The plugin MUST be able to resolve the Tailwind entry CSS or it hard-crashes lint (ENOENT)
36
36
  - Zero-config happy path: when the workspace contains exactly ONE `*.css` with `@import "tailwindcss"` (scanned across the root + every workspace package, `.gitignore`-aware), rules auto-enable with that entry
37
37
  - Rules auto-scope to the workspace package owning the entry CSS (block `basePath`); pass `tailwind: { scoped: false }` to lint the whole workspace
38
- - `tailwindcss` must be resolvable from the workspace root — if lint fails with "not resolvable from the workspace root", hoist it (see the `lint-npm-yarn` skill, "Hoisting") or add it to root `devDependencies`; run eslint with `LINT_DEBUG=1` to trace detection
38
+ - `tailwindcss` must be resolvable from the workspace root — if lint fails with "not resolvable from the workspace root", hoist it (see the `lint-npm-yarn` skill, "Hoisting") or add it to root `devDependencies`; trace detection with `LINT_DEBUG=1 vp lint` (or `LINT_DEBUG=1 eslint .`)
39
39
  - Several entry CSS candidates are ALWAYS a HARD ERROR (a silent skip is hard to notice)
40
- - pass `cssConfigPath` to pick one (if others are not useful) OR
41
- - create multiple leaf `eslint.config.ts` per app (if ALL need to be linted)
40
+ - pass `cssConfigPath` in `lint.config.ts` to pick one (Vite+: the only fix, it ignores nested `lint` blocks) OR
41
+ - ESLint only: create a leaf `eslint.config.mjs` per app with its own `cssConfigPath` (if ALL need to be linted)
42
42
  - When detection can't see `tailwindcss` (e.g. it lives only in leaf packages of a monorepo), force it with `tailwind: true` — then a missing entry CSS is a HARD ERROR instead of a silent skip
43
- - ONLY when auto-find finds nothing (or several entries) pass the MANDATORY entry explicitly in `eslint.config.mjs`:
43
+ - ONLY when auto-find finds nothing (or several entries) pass the MANDATORY entry explicitly in `lint.config.ts`:
44
44
 
45
- ```js
46
- import { defineLintConfig } from '@kirill.konshin/lint';
45
+ ```ts
46
+ import { defineLintConfig } from '@kirill.konshin/lint/config';
47
47
 
48
48
  export default defineLintConfig({
49
49
  tailwind: {
50
- cssConfigPath: './src/styles/tailwind.css', // MANDATORY, relative to the package root
50
+ cssConfigPath: './src/styles/tailwind.css', // MANDATORY, relative to the workspace root
51
51
  },
52
52
  });
53
53
  ```