docs(eslint-config): supplement README from antfu upstream

Close the gap between @antfu/eslint-config's README and ours by porting
five sections that were missing:

- Config Composer: fluent .override() / .renamePlugins() / .remove() API
  for when the plain pleaseai({...}) options aren't granular enough.
- Optional Rules — command: document eslint-plugin-command triple-slash
  codemods (/// to-function, /// keep-sorted, ...) that ship with the
  config. Marked the example with <!-- eslint-skip --> so our own lint
  doesn't try to transform it.
- Neovim integration: nvim-lspconfig, conform.nvim, none-ls, nvim-lint
  patterns for format-on-save alongside the existing VS Code section.
- Editor Specific Disables: explain isInEditor behaviour for prefer-const,
  unused-imports, test/no-only-tests and the pnpm/* rules — a common
  source of "why does it behave differently in my editor" confusion.
- Versioning Policy: Node/major refactors are breaking, rule changes are
  not. Matches the policy inherited from @antfu/eslint-config.

Also added a "Top-level function style?" FAQ entry since PleaseAI
re-enables antfu/top-level-function and users hit this every time they
write an export const arrow function.

Author: amondnet

packages/eslint-config/README.md

@@ -102,6 +102,37 @@ export default pleaseai(
 )
 ```
 
+### Config Composer
+
+The factory function `pleaseai()` returns a [`FlatConfigComposer` object from `eslint-flat-config-utils`](https://github.com/antfu/eslint-flat-config-utils#composer), so you can chain methods to compose the config even more flexibly:
+
+```js
+import pleaseai from '@pleaseai/eslint-config'
+
+export default pleaseai()
+  .prepend(
+    // some flat configs before the main config
+  )
+  // override any named config block
+  .override(
+    'antfu/stylistic/rules',
+    {
+      rules: {
+        'style/generator-star-spacing': ['error', { after: true, before: false }],
+      },
+    },
+  )
+  // rename plugin prefixes
+  .renamePlugins({
+    'old-prefix': 'new-prefix',
+    // ...
+  })
+  // remove a named config block entirely
+  .remove('antfu/stylistic')
+```
+
+This is the composable escape-hatch when the plain `pleaseai({ ... })` options are not granular enough.
+
 ### Rules Overrides
 
 Use the `overrides` option in each integration:
@@ -249,6 +280,40 @@ export default pleaseai({
 bun add -D @angular-eslint/eslint-plugin @angular-eslint/eslint-plugin-template @angular-eslint/template-parser
 ```
 
+### Optional Rules — `command`
+
+`@antfu/eslint-config` ships with [`eslint-plugin-command`](https://github.com/antfu/eslint-plugin-command), which `@pleaseai/eslint-config` inherits. It is **not** a typical lint rule — it's an on-demand micro-codemod that triggers on specific triple-slash comments.
+
+A few built-in triggers:
+
+- `/// to-function` — converts an arrow function to a `function` declaration
+- `/// to-arrow` — converts a `function` declaration to an arrow function
+- `/// to-for-each` — converts a `for`-loop to `.forEach()`
+- `/// to-for-of` — converts a `.forEach()` to a `for-of`
+- `/// keep-sorted` — sorts the next object/array/interface
+- …see the [plugin docs](https://github.com/antfu/eslint-plugin-command#built-in-commands) for the full list
+
+Place the trigger one line above the code you want to transform:
+
+<!-- eslint-skip -->
+
+```ts
+/// to-function
+const foo = async (msg: string): Promise<void> => {
+  console.log(msg)
+}
+```
+
+On the next `eslint --fix` (or auto-fix-on-save) it becomes:
+
+```ts
+async function foo(msg: string): Promise<void> {
+  console.log(msg)
+}
+```
+
+The trigger comment is one-off — it's removed along with the transformation.
+
 ### Formatters
 
 Use external formatters for files that ESLint cannot handle yet (`.css`, `.html`, etc):
@@ -339,6 +404,50 @@ Install [VS Code ESLint extension](https://marketplace.visualstudio.com/items?it
 }
 ```
 
+### Neovim
+
+A few ways to get format-on-save in Neovim:
+
+- **`nvim-lspconfig`** exposes an `EslintFixAll` command. Create an autocmd that runs it on `BufWritePre`:
+
+  ```lua
+  lspconfig.eslint.setup({
+    on_attach = function(client, bufnr)
+      vim.api.nvim_create_autocmd('BufWritePre', {
+        buffer = bufnr,
+        command = 'EslintFixAll',
+      })
+    end,
+  })
+  ```
+
+- [`conform.nvim`](https://github.com/stevearc/conform.nvim)
+- [`none-ls.nvim`](https://github.com/nvimtools/none-ls.nvim)
+- [`nvim-lint`](https://github.com/mfussenegger/nvim-lint)
+
+### Editor Specific Disables
+
+When ESLint runs inside a code editor, a handful of rules are **disabled for auto-fix** so the editor doesn't aggressively rewrite code you're still typing:
+
+- [`prefer-const`](https://eslint.org/docs/rules/prefer-const)
+- [`test/no-only-tests`](https://github.com/levibuzolic/eslint-plugin-no-only-tests)
+- [`unused-imports/no-unused-imports`](https://www.npmjs.com/package/eslint-plugin-unused-imports)
+- `pnpm/json-enforce-catalog`
+- `pnpm/json-prefer-workspace-settings`
+- `pnpm/json-valid-catalog`
+
+> Since `@antfu/eslint-config` v3.16.0 these rules are not disabled — they're made **non-fixable** in editor mode. They still report, just without a quick-fix action.
+
+Motivation: an unused import you just pasted shouldn't vanish the moment your editor auto-saves. The rules still apply when you run `eslint` in the terminal or through [Lint Staged](#lint-staged). If you prefer the uniform behaviour across editor and CLI, opt out:
+
+```js
+import pleaseai from '@pleaseai/eslint-config'
+
+export default pleaseai({
+  isInEditor: false,
+})
+```
+
 ### Lint Staged
 
 ```json
@@ -378,6 +487,25 @@ This config inherits `@antfu/eslint-config`'s plugin renaming for a consistent D
 | `style/*` | `@stylistic/*` | [@stylistic/eslint-plugin](https://github.com/eslint-stylistic/eslint-stylistic) |
 | `test/*` | `vitest/*` | [@vitest/eslint-plugin](https://github.com/vitest-dev/eslint-plugin-vitest) |
 
+## Versioning Policy
+
+`@pleaseai/eslint-config` follows [Semantic Versioning](https://semver.org/), but because it's an opinionated style preset with many moving parts, **rule changes are not treated as breaking changes**. The tables below match the policy inherited from `@antfu/eslint-config`.
+
+### Considered breaking
+
+- Node.js version requirement changes
+- Large refactors that may break downstream configs
+- Major plugin upgrades that may break existing rules
+- Changes that likely affect most codebases
+
+### Considered non-breaking
+
+- Enabling/disabling individual rules or plugins (even if stricter)
+- Changing rule options
+- Dependency version bumps
+
+If a rule tightening breaks your lint, pin to a previous minor version and open an issue so we can discuss the trade-off.
+
 ## FAQ
 
 ### Prettier?
@@ -390,6 +518,32 @@ If you need to format files that ESLint cannot handle yet (`.css`, `.html`, etc.
 
 You can opt-in to the [`formatters`](#formatters) feature to format your CSS. Note that it only does formatting, not linting. If you want proper linting support, give [`stylelint`](https://stylelint.io/) a try.
 
+### Top-level function style?
+
+PleaseAI re-enables `antfu/top-level-function` on top of `lessOpinionated: true`, so top-level functions should use a `function` declaration rather than an arrow assigned to a `const`:
+
+```ts
+// ✓ preferred
+export function greet(name: string) {
+  return `Hello, ${name}`
+}
+
+// ✗ flagged
+export const greet = (name: string) => `Hello, ${name}`
+```
+
+Arrow functions are still fine inside function bodies, as callbacks, or for inline JSX handlers — the rule only targets top-level declarations. If you disagree with this choice, override it:
+
+```ts
+import pleaseai from '@pleaseai/eslint-config'
+
+export default pleaseai({
+  rules: {
+    'antfu/top-level-function': 'off',
+  },
+})
+```
+
 ### Curly braces style?
 
 PleaseAI defaults to `lessOpinionated: true`, which enforces `curly: ['error', 'all']` — always require braces around control flow bodies: