eslint-plugin-stylelint-2 1.0.9 → 1.0.10

package/docs/rules/getting-started.md

@@ -1,130 +1,17 @@
 ---
-title: Getting Started
-description: Enable eslint-plugin-stylelint-2 quickly in Flat Config.
+title: Rules Getting Started (Legacy Route)
+description: This legacy route has moved to the Guides getting started page.
+unlisted: true
 ---
 
-# Getting Started
+# Rules Getting Started (Legacy Route)
 
-Install the plugin and Stylelint:
+This page has moved.
 
-```bash
-npm install --save-dev eslint-plugin-stylelint-2 eslint stylelint
-```
+Use the current guide entry:
 
-Then enable the recommended preset:
+- [Guides → Getting Started](./guides/getting-started.md)
 
-```ts
-import stylelint2 from "eslint-plugin-stylelint-2";
+If you need bridge behavior details after setup, continue with:
 
-export default [
-    ...stylelint2.configs.recommended,
-];
-```
-
-## What `recommended` includes
-
-`recommended` returns an array of flat config entries, not a single object.
-
-It currently adds:
-
-1. a CSS-targeted config that enables `stylelint-2/stylelint`
-2. a config-file-targeted config that enables the Stylelint config authoring rules
-
-## Stylelint bridge only
-
-If you only want the Stylelint bridge for stylesheet files:
-
-```ts
-import stylelint2 from "eslint-plugin-stylelint-2";
-
-export default [
-    stylelint2.configs.stylelintOnly,
-];
-```
-
-## Stylelint config files only
-
-If you only want the config-authoring rules and no stylesheet bridge:
-
-```ts
-import stylelint2 from "eslint-plugin-stylelint-2";
-
-export default [
-    stylelint2.configs.configuration,
-];
-```
-
-Legacy aliases remain supported:
-
-- `stylelint2.configs.stylesheets` → `stylelint2.configs.stylelintOnly`
-- `stylelint2.configs.configs` → `stylelint2.configs.configuration`
-
-That preset currently enables:
-
-- `stylelint-2/disallow-stylelint-allow-empty-input`
-- `stylelint-2/disallow-stylelint-configuration-comment`
-- `stylelint-2/disallow-stylelint-custom-syntax`
-- `stylelint-2/disallow-stylelint-default-severity`
-- `stylelint-2/disallow-stylelint-duplicate-extends`
-- `stylelint-2/disallow-stylelint-duplicate-plugins`
-- `stylelint-2/disallow-stylelint-duplicate-rule-option-values`
-- `stylelint-2/disallow-stylelint-empty-rules-object`
-- `stylelint-2/disallow-stylelint-ignore-disables`
-- `stylelint-2/disallow-stylelint-ignore-files`
-- `stylelint-2/disallow-stylelint-null-rule-config`
-- `stylelint-2/disallow-stylelint-overrides-runtime-options`
-- `stylelint-2/disallow-stylelint-processors`
-- `stylelint-2/disallow-stylelint-relative-extends-paths`
-- `stylelint-2/disallow-stylelint-relative-plugin-paths`
-- `stylelint-2/prefer-stylelint-cache`
-- `stylelint-2/prefer-stylelint-define-config`
-- `stylelint-2/prefer-stylelint-extends-array`
-- `stylelint-2/prefer-stylelint-fix`
-- `stylelint-2/prefer-stylelint-formatter`
-- `stylelint-2/prefer-stylelint-plugins-array`
-- `stylelint-2/prefer-stylelint-report-descriptionless-disables`
-- `stylelint-2/prefer-stylelint-report-invalid-scope-disables`
-- `stylelint-2/prefer-stylelint-report-needless-disables`
-- `stylelint-2/prefer-stylelint-report-unscoped-disables`
-- `stylelint-2/require-stylelint-custom-syntax-in-overrides`
-- `stylelint-2/require-stylelint-config-file-naming-convention`
-- `stylelint-2/require-stylelint-extends-packages-installed`
-- `stylelint-2/require-stylelint-overrides-configuration`
-- `stylelint-2/require-stylelint-overrides-files-array`
-- `stylelint-2/require-stylelint-overrides-files`
-- `stylelint-2/require-stylelint-plugins-packages-installed`
-- `stylelint-2/require-stylelint-report-disables`
-- `stylelint-2/require-stylelint-rules-object`
-- `stylelint-2/sort-stylelint-extends`
-- `stylelint-2/sort-stylelint-plugins`
-- `stylelint-2/sort-stylelint-rule-keys`
-
-## Adding Stylelint options
-
-Pass rule options when you need a custom syntax or an explicit config file:
-
-```ts
-import stylelint2 from "eslint-plugin-stylelint-2";
-
-export default [
-    {
-        ...stylelint2.configs.stylelintOnly,
-        rules: {
-            "stylelint-2/stylelint": [
-                "error",
-                {
-                    configFile: "./stylelint.config.mjs",
-                    customSyntax: "postcss-scss",
-                    ignoreDisables: true,
-                },
-            ],
-        },
-    },
-];
-```
-
-## When to use ESLint + Stylelint together
-
-Use this plugin when you want ESLint to be the single command that reports and fixes both JavaScript/TypeScript issues and stylesheet issues.
-
-If your team already runs Stylelint separately and is happy with that split, this plugin may be unnecessary overhead.
+- [Stylelint Bridge Guide](./guides/stylelint-bridge.md)

package/docs/rules/guides/benchmarks.md

@@ -0,0 +1,27 @@
+---
+title: Benchmarks
+description: Benchmark strategy for eslint-plugin-stylelint-2.
+---
+
+# Benchmarks
+
+The benchmark suite in this repository focuses on meaningful real-world workflows instead of toy snippets.
+
+## Current scenarios
+
+- valid stylesheet corpus
+- invalid stylesheet corpus
+- fix-enabled stylesheet corpus
+- invalid config corpus
+
+## Goal
+
+The goal is to catch regressions in the Stylelint bridge path and the config-authoring rule path before they become editor-time annoyances.
+
+## What is benchmarked today
+
+- stylesheet reporting without fixes
+- stylesheet reporting with fixes
+- config-rule evaluation for invalid config files
+
+These are the workloads most likely to matter during normal editor and CI usage.

package/docs/rules/guides/config-authoring.md

@@ -0,0 +1,76 @@
+---
+title: Config Authoring
+description: Build predictable, maintainable stylelint config files with eslint-plugin-stylelint-2 rule enforcement.
+---
+
+# Config Authoring
+
+Bridge execution solves "how to run Stylelint from ESLint." Config authoring rules solve "how to keep Stylelint config files maintainable over time."
+
+## Why config quality rules matter
+
+In larger repositories, stylelint config drift usually appears as:
+
+- duplicated `extends` / `plugins`
+- inconsistent array ordering
+- hidden relative path assumptions
+- stale override blocks
+
+The config rule set helps keep config files deterministic and review-friendly.
+
+## Recommended baseline
+
+Start with [`recommended`](../presets/recommended.md), then strengthen incrementally.
+
+A practical progression:
+
+1. Deduplication and shape rules (`require-*`, `disallow-*` basics)
+2. Sorting rules for stable diffs
+3. Environment-specific hardening (monorepo path/package checks)
+
+## Authoring conventions that scale
+
+### 1) Keep `extends` and `plugins` explicit
+
+- Avoid implicit path behavior
+- Prefer package-based references where possible
+- Enforce package-install checks with dedicated rules
+
+### 2) Keep arrays deterministic
+
+Use sorting rules to minimize merge churn:
+
+- [`sort-stylelint-extends`](../sort-stylelint-extends.md)
+- [`sort-stylelint-plugins`](../sort-stylelint-plugins.md)
+- [`sort-stylelint-rule-keys`](../sort-stylelint-rule-keys.md)
+
+### 3) Treat overrides as policy, not exceptions
+
+Enforce consistent override structure and file targeting:
+
+- [`require-stylelint-overrides-configuration`](../require-stylelint-overrides-configuration.md)
+- [`require-stylelint-overrides-files`](../require-stylelint-overrides-files.md)
+- [`require-stylelint-overrides-files-array`](../require-stylelint-overrides-files-array.md)
+
+### 4) Prevent legacy/deprecated patterns
+
+Guard against obsolete or risky stylelint config patterns with `disallow-*` rules.
+
+## Monorepo tips
+
+- Keep `configBasedir` stable when invoking bridge rule options.
+- Avoid relative extends/plugin path assumptions between packages.
+- Validate package dependencies where stylelint config references plugins/presets.
+
+## Migration strategy for existing repos
+
+1. Enable config rules in warning mode first.
+2. Apply autofixes and sorting.
+3. Resolve remaining hard violations in batches.
+4. Promote to error once baseline debt is cleared.
+
+## Related docs
+
+- Runtime bridge behavior: [Stylelint Bridge](./stylelint-bridge.md)
+- Initial setup: [Getting Started](./getting-started.md)
+- Full policy sets: [Preset Reference](../presets/index.md)

package/docs/rules/guides/faq.md

@@ -0,0 +1,55 @@
+---
+title: FAQ
+description: Answers to common questions about bridge behavior, presets, rollout, and troubleshooting.
+---
+
+# FAQ
+
+## Do I still need the Stylelint CLI if I use this plugin?
+
+Not necessarily.
+
+If your goal is a unified lint pipeline, ESLint + `stylelint2/stylelint` is usually enough.
+Keep a dedicated Stylelint CLI job only if you need separate formatter/output contracts.
+
+## Which preset should I start with?
+
+- Start with [`stylelintOnly`](../presets/stylelint-only.md) for minimal-risk adoption.
+- Start with [`recommended`](../presets/recommended.md) if you want bridge + config quality enforcement from day one.
+
+## Why am I seeing both ESLint and Stylelint errors for similar issues?
+
+You may have overlapping policy between ESLint ecosystem rules and bridged Stylelint rules.
+Audit overlap and choose one source of truth for each policy area.
+
+## Can I use autofix safely?
+
+In most repos, yes—start by running `eslint --fix` in a branch and reviewing the diff.
+Then enforce in CI once results are stable.
+
+## How do I lint files that require custom parsers/syntaxes?
+
+Configure the [`stylelint` rule](../stylelint.md) with `customSyntax` (and related options) so Stylelint parses those files correctly.
+
+## What if some packages in a monorepo resolve config differently?
+
+Set `configBasedir` intentionally and avoid fragile relative paths in Stylelint config references.
+Use package-install validation rules to catch missing dependencies early.
+
+## Why do config authoring rules matter if my Stylelint config already works?
+
+A config can "work" while still being brittle, duplicated, or hard to review.
+Authoring rules reduce long-term churn and make diffs deterministic.
+
+## What’s the best migration order for existing repos?
+
+1. Enable one preset.
+2. Run autofix.
+3. Resolve high-value violations first.
+4. Promote warnings to errors once baseline is clean.
+
+## Where should I go next?
+
+- Setup flow: [Getting Started](./getting-started.md)
+- Bridge internals and behavior: [Stylelint Bridge](./stylelint-bridge.md)
+- Config quality conventions: [Config Authoring](./config-authoring.md)

package/docs/rules/guides/getting-started.md

@@ -0,0 +1,89 @@
+---
+title: Getting Started
+description: Install eslint-plugin-stylelint-2, pick the right preset, and roll it out safely in CI/editor workflows.
+---
+
+# Getting Started
+
+This guide gets you from zero to a production-safe baseline quickly.
+
+## Prerequisites
+
+- ESLint with Flat Config
+- Stylelint installed in the same project
+- A stylelint config file (for example `stylelint.config.mjs`)
+
+## Step 1: Install dependencies
+
+```bash
+npm install --save-dev eslint-plugin-stylelint-2 stylelint
+```
+
+## Step 2: Start with one preset
+
+Pick one adoption mode:
+
+- **Bridge only** (just run Stylelint from ESLint): [`stylelintOnly`](../presets/stylelint-only.md)
+- **Bridge + config quality** (recommended for teams): [`recommended`](../presets/recommended.md)
+
+Example `eslint.config.mjs`:
+
+```js
+import stylelint2 from "eslint-plugin-stylelint-2";
+
+export default [
+  stylelint2.configs.recommended,
+  {
+    rules: {
+      // Optional: tune bridge behavior here.
+      "stylelint2/stylelint": "error",
+    },
+  },
+];
+```
+
+## Step 3: Run lint once and apply fixes
+
+```bash
+npx eslint . --fix
+```
+
+Review the PR diff and categorize findings:
+
+1. **Safe autofixes** (accept immediately)
+2. **Configuration cleanups** (plan staged rollout)
+3. **Actual style violations** (fix or suppress with rationale)
+
+## Step 4: Configure the bridge rule intentionally
+
+If your project needs custom syntax or special file matching, tune the [`stylelint` rule](../stylelint.md).
+
+Typical options include:
+
+- `customSyntax`
+- `configFile`
+- `configBasedir`
+- `quiet`
+- `allowEmptyInput`
+
+## Step 5: Roll out in phases
+
+Recommended rollout model:
+
+1. Enable preset + run in CI as warning-only (short period)
+2. Resolve baseline issues
+3. Switch to error-level enforcement
+4. Add stricter config-authoring rules over time
+
+## Common rollout mistakes
+
+- **Enabling `all` immediately**: high noise and slower adoption
+- **Mixing Stylelint CLI and ESLint bridge outputs in the same CI gate** without clear ownership
+- **Skipping autofix pass before triage**
+
+## Where to go next
+
+- Architecture and behavior: [Stylelint Bridge](./stylelint-bridge.md)
+- Team standards and config conventions: [Config Authoring](./config-authoring.md)
+- Preset details: [Preset Reference](../presets/index.md)
+- Common troubleshooting: [FAQ](./faq.md)

package/docs/rules/guides/intro.md

@@ -0,0 +1,71 @@
+---
+title: Overview
+description: What eslint-plugin-stylelint-2 does, how the rules docs are organized, and where to start for your use case.
+---
+
+# Overview
+
+`eslint-plugin-stylelint-2` is built for teams that want Stylelint and ESLint to cooperate cleanly.
+
+1. **Bridge Stylelint into ESLint** so style diagnostics and autofixes can flow through your existing ESLint pipeline.
+2. **Enforce maintainable Stylelint config authoring** so your Stylelint configuration stays predictable, reviewable, and automation-friendly.
+
+If you only care about bridge behavior, start with:
+
+- [`stylelint` rule](../stylelint.md)
+- [`stylelintOnly` preset](../presets/stylelint-only.md)
+
+If you also want strict configuration hygiene, start with:
+
+- [`recommended` preset](../presets/recommended.md)
+- then progressively adopt stricter config-focused rules from the main [rule catalog](../overview.md)
+
+## How this rules documentation is organized
+
+The Rules docs section is intentionally split by decision-making flow:
+
+1. **Guides** (you are here) for adoption strategy and practical setup.
+2. **Presets** for curated rule sets ([reference](../presets/index.md)).
+3. **Rule catalog** for per-rule details and examples ([catalog](../overview.md)).
+
+## Pick a path
+
+### Path A — "Just run Stylelint from ESLint"
+
+Use this if your main goal is unified lint execution in CI/editor:
+
+1. Follow [Getting Started](./getting-started.md).
+2. Enable [`stylelintOnly`](../presets/stylelint-only.md).
+3. Tune the [`stylelint` rule options](../stylelint.md) if needed.
+
+### Path B — "Also standardize config quality"
+
+Use this if you want consistent stylelint config shape across repos:
+
+1. Start with [`recommended`](../presets/recommended.md).
+2. Review [Config Authoring](./config-authoring.md).
+3. Tighten with additional rule-level policies from [Rule Catalog](../overview.md).
+
+### Path C — "Need details before enabling"
+
+If you are evaluating behavior or migration risk:
+
+- Read [Stylelint Bridge](./stylelint-bridge.md).
+- Skim [FAQ](./faq.md).
+- Validate on a small target package first.
+
+## Quick map
+
+- [Getting Started](./getting-started.md)
+- [Stylelint Bridge](./stylelint-bridge.md)
+- [Config Authoring](./config-authoring.md)
+- [FAQ](./faq.md)
+- [Presets](../presets/index.md)
+- [Rule Catalog](../overview.md)
+
+## Recommended first steps (practical)
+
+1. Enable one preset (`stylelintOnly` or `recommended`) and run lint once.
+2. Apply autofixes and inspect diff quality in a PR.
+3. Add config policy rules gradually (not all at once) to reduce noisy rollouts.
+4. Lock in conventions via CI and editor integration.

package/docs/rules/guides/stylelint-bridge.md

@@ -0,0 +1,79 @@
+---
+title: Stylelint Bridge
+description: Understand how eslint-plugin-stylelint-2 executes Stylelint through ESLint and what that means for diagnostics, fixes, and CI.
+---
+
+# Stylelint Bridge
+
+The bridge is powered by the [`stylelint` rule](../stylelint.md). It runs Stylelint during ESLint execution and reports results as ESLint diagnostics.
+
+## What the bridge gives you
+
+- A single lint entrypoint (`eslint`) for JS/TS + style quality
+- One diagnostics stream in editors and CI
+- Unified autofix flow (`eslint --fix`) where safe
+
+## How execution works
+
+At a high level:
+
+1. ESLint visits a supported file.
+2. `stylelint2/stylelint` invokes Stylelint with your configured options.
+3. Stylelint results are mapped to ESLint reports.
+4. Autofixable issues are offered through ESLint fixers.
+
+## What gets reported
+
+The bridge can surface:
+
+- Stylelint rule violations
+- Stylelint parsing failures
+- Invalid/unsupported Stylelint configuration details
+- Deprecation and migration warnings (depending on Stylelint behavior)
+
+## Fixing behavior
+
+Use standard ESLint workflows:
+
+```bash
+npx eslint . --fix
+```
+
+Practical advice:
+
+- Prefer `--fix` first, then triage leftovers.
+- Treat non-fixable findings as policy debt, not random noise.
+- Keep bridge options explicit so behavior is deterministic across CI/local environments.
+
+## Option tuning checklist
+
+If behavior looks inconsistent, verify:
+
+- `configFile` points to the intended Stylelint config
+- `configBasedir` is stable in monorepos
+- `customSyntax` is set for non-standard syntaxes
+- `allowEmptyInput` and `quiet` match your expectations
+
+See full option docs in [`stylelint` rule reference](../stylelint.md).
+
+## Performance tips
+
+- Scope lint targets intentionally (do not lint the whole repo blindly in every job).
+- Cache ESLint in CI where possible.
+- Start with [`stylelintOnly`](../presets/stylelint-only.md) if you need low-friction adoption.
+- Add config-authoring rules after baseline bridge stability.
+
+## When to keep Stylelint CLI separately
+
+You might still keep a dedicated Stylelint CLI job when:
+
+- You require Stylelint-specific formatter output in a separate pipeline stage.
+- You need parity with existing non-ESLint tooling contracts.
+
+If you do this, avoid duplicated failing signals in PR checks (assign one owner per policy area).
+
+## Related guides
+
+- Setup path: [Getting Started](./getting-started.md)
+- Config quality standards: [Config Authoring](./config-authoring.md)
+- Troubleshooting edge cases: [FAQ](./faq.md)

package/docs/rules/overview.md

@@ -1,99 +1,17 @@
 ---
-title: Overview
-description: Overview of eslint-plugin-stylelint-2 and its Stylelint-to-ESLint workflow.
+title: Rules Overview (Legacy Route)
+description: This legacy route has moved to the Guides overview page.
+unlisted: true
 ---
 
-# eslint-plugin-stylelint-2
+# Rules Overview (Legacy Route)
 
-`eslint-plugin-stylelint-2` lets you run Stylelint inside ESLint for CSS files and author Stylelint config files with a more predictable typed setup.
+This page has moved.
 
-The current rule set focuses on three high-value workflows:
+Use the current guide entry:
 
-- surface Stylelint diagnostics through ESLint with autofix support
-- disallow execution-only Stylelint config options that belong in the runner, not the shared config object
-- disallow shared-config severity and file-ignore options that hide lint-policy changes globally
-- standardize modern `stylelint-define-config` usage in Stylelint config modules
-- require Stylelint config files to report disable comments that lack a reason
-- require the full family of Stylelint disable-comment reporting safeguards in config files
+- [Guides → Overview](./guides/intro.md)
 
-## Installation
+For the full rules list, use:
 
-```bash
-npm install --save-dev eslint-plugin-stylelint-2 eslint stylelint
-```
-
-## Quick start
-
-```ts
-import stylelint2 from "eslint-plugin-stylelint-2";
-
-export default [
-    ...stylelint2.configs.recommended,
-];
-```
-
-`recommended` expands to two file-scoped flat config entries:
-
-- one for CSS files using ESLint's `css/css` language
-- one for Stylelint config files such as `stylelint.config.ts`
-
-## Included presets
-
-| Preset                                                            | Purpose                                                       |
-| ----------------------------------------------------------------- | ------------------------------------------------------------- |
-| [`stylelint2.configs.recommended`](./presets/recommended.md)      | Stylesheet linting plus Stylelint config authoring guidance   |
-| [`stylelint2.configs.stylelintOnly`](./presets/stylelint-only.md) | Only run the Stylelint bridge workflow for stylesheet files   |
-| [`stylelint2.configs.configuration`](./presets/configuration.md)  | Only lint Stylelint config modules, with no stylesheet bridge |
-| [`stylelint2.configs.all`](./presets/all.md)                      | Enable every preset entry currently shipped by this plugin    |
-
-Legacy aliases remain supported:
-
-- `stylelint2.configs.stylesheets` → `stylelint2.configs.stylelintOnly`
-- `stylelint2.configs.configs` → `stylelint2.configs.configuration`
-
-## Included rules
-
-- [`stylelint`](./stylelint.md)
-- [`disallow-stylelint-allow-empty-input`](./disallow-stylelint-allow-empty-input.md)
-- [`disallow-stylelint-configuration-comment`](./disallow-stylelint-configuration-comment.md)
-- [`disallow-stylelint-custom-syntax`](./disallow-stylelint-custom-syntax.md)
-- [`disallow-stylelint-default-severity`](./disallow-stylelint-default-severity.md)
-- [`disallow-stylelint-duplicate-extends`](./disallow-stylelint-duplicate-extends.md)
-- [`disallow-stylelint-duplicate-plugins`](./disallow-stylelint-duplicate-plugins.md)
-- [`disallow-stylelint-duplicate-rule-option-values`](./disallow-stylelint-duplicate-rule-option-values.md)
-- [`disallow-stylelint-empty-rules-object`](./disallow-stylelint-empty-rules-object.md)
-- [`disallow-stylelint-ignore-disables`](./disallow-stylelint-ignore-disables.md)
-- [`disallow-stylelint-ignore-files`](./disallow-stylelint-ignore-files.md)
-- [`disallow-stylelint-null-rule-config`](./disallow-stylelint-null-rule-config.md)
-- [`disallow-stylelint-overrides-runtime-options`](./disallow-stylelint-overrides-runtime-options.md)
-- [`disallow-stylelint-processors`](./disallow-stylelint-processors.md)
-- [`disallow-stylelint-relative-extends-paths`](./disallow-stylelint-relative-extends-paths.md)
-- [`disallow-stylelint-relative-plugin-paths`](./disallow-stylelint-relative-plugin-paths.md)
-- [`prefer-stylelint-cache`](./prefer-stylelint-cache.md)
-- [`prefer-stylelint-define-config`](./prefer-stylelint-define-config.md)
-- [`prefer-stylelint-extends-array`](./prefer-stylelint-extends-array.md)
-- [`prefer-stylelint-fix`](./prefer-stylelint-fix.md)
-- [`prefer-stylelint-formatter`](./prefer-stylelint-formatter.md)
-- [`prefer-stylelint-plugins-array`](./prefer-stylelint-plugins-array.md)
-- [`prefer-stylelint-report-descriptionless-disables`](./prefer-stylelint-report-descriptionless-disables.md)
-- [`prefer-stylelint-report-invalid-scope-disables`](./prefer-stylelint-report-invalid-scope-disables.md)
-- [`prefer-stylelint-report-needless-disables`](./prefer-stylelint-report-needless-disables.md)
-- [`prefer-stylelint-report-unscoped-disables`](./prefer-stylelint-report-unscoped-disables.md)
-- [`require-stylelint-custom-syntax-in-overrides`](./require-stylelint-custom-syntax-in-overrides.md)
-- [`require-stylelint-config-file-naming-convention`](./require-stylelint-config-file-naming-convention.md)
-- [`require-stylelint-extends-packages-installed`](./require-stylelint-extends-packages-installed.md)
-- [`require-stylelint-overrides-configuration`](./require-stylelint-overrides-configuration.md)
-- [`require-stylelint-overrides-files-array`](./require-stylelint-overrides-files-array.md)
-- [`require-stylelint-overrides-files`](./require-stylelint-overrides-files.md)
-- [`require-stylelint-plugins-packages-installed`](./require-stylelint-plugins-packages-installed.md)
-- [`require-stylelint-report-disables`](./require-stylelint-report-disables.md)
-- [`require-stylelint-rules-object`](./require-stylelint-rules-object.md)
-- [`sort-stylelint-extends`](./sort-stylelint-extends.md)
-- [`sort-stylelint-plugins`](./sort-stylelint-plugins.md)
-- [`sort-stylelint-rule-keys`](./sort-stylelint-rule-keys.md)
-
-## Next steps
-
-- Read [Getting Started](./getting-started.md) for copy-paste setup examples.
-- Review [Presets](./presets/index.md) to pick the right rollout path.
-- Open each rule page before enabling stricter adoption in a larger codebase.
+- [Rule Catalog](./stylelint.md)

package/docs/rules/presets/all.md

@@ -12,6 +12,16 @@ export default [
 ];
 ```
 
+## What this preset includes
+
+- The Stylelint bridge rule (`stylelint`)
+- Configuration-authoring policy rules
+- Opinionated operational policy rules (cache/formatter/fix/default-severity/reporting preferences)
+
+## What this preset does not include
+
+- Nothing from this plugin is excluded; this is the broadest preset.
+
 ## Related preset docs
 
 - [Presets overview](./index.md)
@@ -19,7 +29,7 @@ export default [
 - [Stylelint-only preset](./stylelint-only.md)
 - [Configuration-only preset](./configuration.md)
 
-## Notable rules in this preset
+## Rules in this preset
 
 For the exhaustive generated rule matrix, see [Presets overview](./index.md).
 

package/docs/rules/presets/configs.md

@@ -16,12 +16,22 @@ export default [
 ];
 ```
 
-## Preferred docs
+## What this preset includes
+
+- Legacy alias export for this plugin's preset surface (`stylelint2.configs.configs`)
+- Same active rule set as [`recommended`](./recommended.md)
+
+## What this preset does not include
+
+- Additional rules beyond what `recommended` already enables
+- Any behavior differences from `recommended` (it is an alias)
+
+## Related preset docs
 
 - [Configuration-only preset](./configuration.md)
 - [Presets overview](./index.md)
 
-## Notable rules in this preset
+## Rules in this preset
 
 For the exhaustive generated rule matrix, see [Configuration-only preset](./configuration.md) and [Presets overview](./index.md).
 

package/docs/rules/presets/configuration.md

@@ -18,19 +18,7 @@ export default [
 
 ## What this preset includes
 
-- `stylelint-2/prefer-stylelint-cache`
-- `stylelint-2/disallow-stylelint-default-severity`
-- `stylelint-2/prefer-stylelint-fix`
-- `stylelint-2/prefer-stylelint-formatter`
-- `stylelint-2/disallow-stylelint-ignore-disables`
-- `stylelint-2/disallow-stylelint-ignore-files`
-- `stylelint-2/prefer-stylelint-define-config`
-- `stylelint-2/prefer-stylelint-report-descriptionless-disables`
-- `stylelint-2/prefer-stylelint-report-invalid-scope-disables`
-- `stylelint-2/prefer-stylelint-report-needless-disables`
-- `stylelint-2/prefer-stylelint-report-unscoped-disables`
-- `stylelint-2/require-stylelint-overrides-configuration`
-- `stylelint-2/require-stylelint-overrides-files-array`
+Configuration-focused policy rules only. See the canonical rules table below for the exact preset contents.
 
 ## What this preset does not include
 
@@ -45,7 +33,7 @@ export default [
 - [Stylelint-only preset](./stylelint-only.md)
 - [All preset](./all.md)
 
-## Notable rules in this preset
+## Rules in this preset
 
 For the exhaustive generated rule matrix, see [Presets overview](./index.md).
 

package/docs/rules/presets/recommended.md

@@ -19,6 +19,16 @@ export default [
 ];
 ```
 
+## What this preset includes
+
+- The Stylelint bridge rule (`stylelint`)
+- High-signal configuration policy rules for common production usage
+
+## What this preset does not include
+
+- The full strict policy surface from [`all`](./all.md)
+- Configuration-only mode semantics from [`configuration`](./configuration.md)
+
 ## Related preset docs
 
 - [Presets overview](./index.md)
@@ -26,7 +36,7 @@ export default [
 - [Configuration-only preset](./configuration.md)
 - [All preset](./all.md)
 
-## Notable rules in this preset
+## Rules in this preset
 
 For the exhaustive generated rule matrix, see [Presets overview](./index.md).
 

package/docs/rules/presets/stylelint-only.md

@@ -18,15 +18,12 @@ export default [
 
 ## What this preset includes
 
-- `stylelint-2/stylelint`
-- stylesheet files only (`**/*.css`)
-- Stylelint edit info surfaced through `eslint --fix` when available
+- The bridge rule only: [`stylelint`](https://nick2bad4u.github.io/eslint-plugin-stylelint-2/docs/rules/stylelint)
 
 ## What this preset does not include
 
-- No Stylelint config-module rules
-- No `defineConfig()` authoring checks
-- No disable-comment reporting checks for config files
+- Configuration-authoring policy rules (`require-*`, `disallow-*`, `sort-*`)
+- Operational policy rules like `prefer-stylelint-cache` and reporting preferences
 
 ## Related preset docs
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://www.schemastore.org/package.json",
     "name": "eslint-plugin-stylelint-2",
-    "version": "1.0.9",
+    "version": "1.0.10",
     "private": false,
     "description": "ESLint plugin that runs Stylelint through ESLint and adds Stylelint-specific authoring rules.",
     "keywords": [
@@ -231,8 +231,8 @@
         "@eslint/js": "^10.0.1",
         "@eslint/json": "^1.2.0",
         "@eslint/markdown": "^8.0.1",
-        "@html-eslint/eslint-plugin": "^0.58.1",
-        "@html-eslint/parser": "^0.58.1",
+        "@html-eslint/eslint-plugin": "^0.59.0",
+        "@html-eslint/parser": "^0.59.0",
         "@microsoft/eslint-plugin-sdl": "^1.1.0",
         "@microsoft/tsdoc-config": "^0.18.1",
         "@secretlint/secretlint-rule-anthropic": "^11.5.0",
@@ -302,7 +302,7 @@
         "eslint-plugin-etc": "^2.0.3",
         "eslint-plugin-etc-misc": "^1.0.5",
         "eslint-plugin-file-progress-2": "^3.4.4",
-        "eslint-plugin-github-actions-2": "^1.0.2",
+        "eslint-plugin-github-actions-2": "^1.0.6",
         "eslint-plugin-html": "^8.1.4",
         "eslint-plugin-immutable-2": "^1.0.7",
         "eslint-plugin-import-x": "^4.16.2",
@@ -335,7 +335,7 @@
         "eslint-plugin-testing-library": "^7.16.2",
         "eslint-plugin-toml": "^1.3.1",
         "eslint-plugin-tsdoc": "^0.5.2",
-        "eslint-plugin-tsdoc-require-2": "^1.0.7",
+        "eslint-plugin-tsdoc-require-2": "^1.0.9",
         "eslint-plugin-undefined-css-classes": "^0.1.5",
         "eslint-plugin-unicorn": "^64.0.0",
         "eslint-plugin-unused-imports": "^4.4.1",
@@ -355,7 +355,7 @@
         "madge": "^8.0.0",
         "markdown-link-check": "^3.14.2",
         "npm-check-updates": "^20.0.0",
-        "npm-package-json-lint": "^10.0.0",
+        "npm-package-json-lint": "^10.2.0",
         "picocolors": "^1.1.1",
         "postcss": "^8.5.8",
         "postcss-assets": "^6.0.0",