chore: adjust shopware-cli tools docs

products/tools/cli/automatic-refactoring.md

@@ -34,27 +34,28 @@ Automatic refactoring is one part of an upgrade workflow rather than a complete
 
 ## Automatic refactoring tools
 
-Without `--only`, a `fix` command invokes every registered verifier tool. The following tools currently implement changes in `Fix()`:
+By default, a `fix` command invokes every registered fixer. The following tools support fixing:
 
 | Tool          | What it fixes                                                                                | Version-aware | Implementation                                                                                          |
 | ------------- | -------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
 | `rector`      | PHP breaking changes and modernization using Shopware Rector                                 | Yes           | [`rector.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/rector.go)           |
 | `eslint`      | Auto-fixable JavaScript, TypeScript, and Vue rules for Administration and Storefront code    | Yes           | [`eslint.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/eslint.go)           |
-| `admin-twig`  | Shopware-specific Administration Twig component migrations                                   | Yes           | [`admin_twig.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/admin_twig.go)   |
 | `stylelint`   | Auto-fixable Administration and Storefront SCSS rules using bundled Stylelint configurations | No            | [`stylelint.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/stylelint.go)     |
 | `symfony-xml` | Deprecated plugin `services.xml` and `routes.xml` configuration to YAML                      | No            | [`symfony_xml.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/symfony_xml.go) |
 
-The Administration Twig migrations are implemented as individual fixers under [`internal/verifier/twiglinter/admintwiglinter`](https://github.com/shopware/shopware-cli/tree/main/internal/verifier/twiglinter/admintwiglinter). They cover deterministic migrations such as replacing removed Administration components. For migration cases that require manual changes, see the [Administration migration guide](../../../guides/upgrades-migrations/administration/index.md).
+For Administration migrations, see the [Administration migration guide](../../../guides/upgrades-migrations/administration/index.md).
 
-Other registered tools do not modify files in `fix` mode:
+Other tools support validation or formatting instead:
 
 - `php-cs-fixer` and `prettier` are used for [formatting](./formatter.md).
-- `phpstan`, `storefront-twig`, and `sw-cli` report findings during [validation](./validation.md).
+- `phpstan`, `storefront-twig`, and `builtin` report findings during [validation](./validation.md).
 
-Selecting one of these tools with `fix --only` therefore does not modify anything.
+Selecting one of these tools with `fix --only` is an error; the command lists the available fixers.
+
+`extension fix` and `project fix` print a `Fixers:` table after running. `invoked` means the fixer was called, but does not guarantee that it analyzed or changed files; `skipped` means it was not selected by `--only` or was removed by `--exclude`. The table is also printed when a fixer returns an execution error, and the command exits with a non-zero status.
 
 ::: warning
-Rector applies PHP migrations during `fix`, but its `Check()` implementation does not report findings during validation. There is no Rector preview before files are rewritten, so always review the resulting `git diff`.
+Rector applies PHP migrations during `fix`, but does not support validation. There is no Rector preview before files are rewritten, so always review the resulting `git diff`.
 :::
 
 ## Refactor an extension
@@ -93,15 +94,25 @@ Use `--only` to run one or more specific fixers:
 
 ```shell
 shopware-cli extension fix /path/to/your/extension --only rector
-shopware-cli extension fix /path/to/your/extension --only "rector,eslint,admin-twig"
+shopware-cli extension fix /path/to/your/extension --only "rector,eslint"
+```
+
+Use `--exclude` to skip fixers. It removes tools from the set selected by `--only`, or from all fixers when `--only` is omitted:
+
+```shell
+shopware-cli extension fix /path/to/your/extension --exclude eslint
+shopware-cli extension fix /path/to/your/extension --only "rector,eslint" --exclude eslint
 ```
 
+Both flags accept comma-separated names. An unknown name, an excluded fixer outside the selected set, or excluding every selected fixer is an error.
+
 Available options:
 
-| Flag              | Description                                                                   |
-| ----------------- | ----------------------------------------------------------------------------- |
-| `--only <tools>`  | Run only the specified comma-separated tools                                  |
-| `--allow-non-git` | Allow the command to run when the extension directory is not a Git repository |
+| Flag                | Description                                                                   |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `--only <tools>`    | Run only the specified comma-separated tools                                  |
+| `--exclude <tools>` | Exclude fixers from all fixers or the `--only` selection                      |
+| `--allow-non-git`   | Allow the command to run when the extension directory is not a Git repository |
 
 For `extension fix`, the extension directory itself must contain `.git`; being inside a parent Git-managed Shopware project is not sufficient. Use `--allow-non-git` when you intentionally want to fix such an extension. `project fix` checks the project root instead.
 
@@ -135,18 +146,22 @@ The project path is optional. If you omit it, Shopware CLI searches upward from
 shopware-cli project fix
 ```
 
-For projects, Shopware CLI applies the selected fixers to local extensions and configured bundles. Extensions resolved under `vendor/` are skipped. Individual fixers can have a narrower scope; for example, `symfony-xml` only converts configuration belonging to platform plugins.
+For projects, Shopware CLI applies the selected fixers to local extensions and configured bundles. Extensions resolved under `vendor/` and extensions listed in `validation.ignore_extensions` are skipped. Individual fixers can have a narrower scope; for example, `symfony-xml` only converts configuration belonging to platform plugins.
 
-Use the same `--only` and `--allow-non-git` options as `extension fix`:
+Use the same `--only`, `--exclude`, and `--allow-non-git` options as `extension fix`:
 
 ```shell
 shopware-cli project fix --only rector
-shopware-cli project fix --only "rector,eslint,admin-twig"
+shopware-cli project fix --only "rector,eslint"
+shopware-cli project fix --exclude eslint
+shopware-cli project fix --only "rector,eslint" --exclude eslint
 ```
 
+Without `--only`, exclusions apply to all registered fixers. When both flags are supplied, exclusions apply to the selected set. Unknown names, exclusions outside that set, and empty final selections fail before tool setup or file changes.
+
 ## Version-aware fixes
 
-Some fixers select rules according to the Shopware version supported by the extension or project. `rector`, `eslint`, and `admin-twig` use the minimum Shopware version resolved by the verifier configuration. Stylelint and `symfony-xml` do not select rules based on a Shopware version.
+Some fixers select rules according to the Shopware version supported by the extension or project. `rector` and `eslint` use the minimum Shopware version resolved by the verifier configuration. Stylelint and `symfony-xml` do not select rules based on a Shopware version.
 
 For a Shopware project, the version range comes from the `shopware/core` constraint in `composer.json`. For an extension, it comes from the extension's declared Shopware compatibility. Shopware CLI retrieves the available Shopware releases and selects the **lowest released version matching that constraint**.
 
@@ -177,6 +192,8 @@ The version-resolution logic is implemented in [`internal/verifier/extension.go`
 
 ## Execution and safety
 
+Use `--verbose` with either `fix` command to log source directories, selected extension names, and external tool commands and arguments.
+
 The selected tools run concurrently, and the command waits for them to finish before returning. If one tool fails, the others are not cancelled and may still write changes. A failed run can therefore leave partial modifications.
 
 The `fix` commands also:

products/tools/cli/formatter.md

@@ -12,23 +12,24 @@ Shopware CLI provides code formatting through two `format` commands:
 - `extension format` to format a single extension
 - `project format` to format extensions and configured bundles across a Shopware project
 
-The formatter covers PHP and Administration Twig files, along with files supported by Prettier such as JavaScript, TypeScript, Vue, CSS, and SCSS. PHP formatting uses the Shopware [Coding Standard](https://developer.shopware.com/docs/resources/guidelines/code/).
+The formatter covers PHP files, along with files supported by Prettier such as JavaScript, TypeScript, Vue, CSS, and SCSS. PHP formatting uses the Shopware [Coding Standard](https://developer.shopware.com/docs/resources/guidelines/code/).
 
 A `--dry-run` mode is available to check formatting without rewriting the target files. Shopware CLI propagates the formatter exit status, so a non-zero dry run can mean that formatting changes are required rather than that the formatter crashed.
 
 The Docker examples are recommended because the image already contains the required runtime dependencies. For local execution, the formatter tooling requires PHP 8.2 or later and Node.js 20 or later. Composer and npm are used when Shopware CLI initializes its local tool cache.
 
 ## Formatting tools
 
-Without `--only`, a `format` command invokes every registered verifier tool. The following tools currently implement formatting in `Format()`:
+By default, a `format` command invokes every registered formatter. The following tools support formatting:
 
 | Tool           | What it formats                                                                             | Implementation                                                                                        |
 | -------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
 | `php-cs-fixer` | PHP source files using the Shopware Coding Standard                                         | [`phpcsfixer.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/phpcsfixer.go) |
 | `prettier`     | Prettier-supported files in source directories using the Shopware CLI bundled configuration | [`prettier.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/prettier.go)     |
-| `admin-twig`   | Administration Twig templates                                                               | [`admin_twig.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/admin_twig.go) |
 
-Other registered verifier tools do not modify files in `format` mode.
+Tools without formatting support cannot be selected with `format --only`; the command reports an error and lists the available formatters.
+
+`extension format` and `project format` print a `Formatters:` table after running. `invoked` means the formatter was called, but does not guarantee that it analyzed or changed files; `skipped` means it was not selected by `--only` or was removed by `--exclude`. The table is also printed when a formatter returns an execution error, and the command exits with a non-zero status.
 
 ## Format an extension
 
@@ -70,6 +71,30 @@ shopware-cli extension format /path/to/your/extension --dry-run
 
 The extension path is required.
 
+Use `--only` to select one or more formatters:
+
+```shell
+shopware-cli extension format /path/to/your/extension --only php-cs-fixer
+shopware-cli extension format /path/to/your/extension --only "php-cs-fixer,prettier"
+```
+
+Use `--exclude` to skip formatters. It removes tools from the set selected by `--only`, or from all formatters when `--only` is omitted:
+
+```shell
+shopware-cli extension format /path/to/your/extension --exclude prettier
+shopware-cli extension format /path/to/your/extension --only "prettier,php-cs-fixer" --exclude prettier
+```
+
+Both flags accept comma-separated names. An unknown name, an excluded formatter outside the selected set, or excluding every selected formatter is an error.
+
+The following table summarizes the extension format options:
+
+| Flag                | Description                                                      |
+| ------------------- | ---------------------------------------------------------------- |
+| `--only <tools>`    | Run only the specified comma-separated formatters                |
+| `--exclude <tools>` | Exclude formatters from all formatters or the `--only` selection |
+| `--dry-run`         | Check formatting without modifying files                         |
+
 ## Format a project
 
 <Tabs>
@@ -116,10 +141,11 @@ If you omit the path, `project format` discovers the nearest Shopware project by
 
 ### Project format options
 
-| Flag             | Description                                  |
-| ---------------- | -------------------------------------------- |
-| `--dry-run`      | Check formatting without modifying files     |
-| `--only <tools>` | Run only the specified comma-separated tools |
+| Flag                | Description                                                      |
+| ------------------- | ---------------------------------------------------------------- |
+| `--dry-run`         | Check formatting without modifying files                         |
+| `--only <tools>`    | Run only the specified comma-separated formatters                |
+| `--exclude <tools>` | Exclude formatters from all formatters or the `--only` selection |
 
 The path argument is optional for `project format` but required for `extension format`.
 
@@ -129,10 +155,17 @@ Format only PHP:
 shopware-cli project format /path/to/your/project --only php-cs-fixer
 ```
 
+Use `--exclude` alone or with `--only`:
+
+```shell
+shopware-cli project format /path/to/your/project --exclude prettier
+shopware-cli project format /path/to/your/project --only "prettier,php-cs-fixer" --exclude prettier
+```
+
+Unknown names, exclusions outside the selected set, and empty final selections fail before tool setup or file changes. Use `--verbose` with either `format` command to log source directories, extension names, and external tool commands and arguments.
+
 ## Configuration
 
 PHP-CS-Fixer uses a `.php-cs-fixer.dist.php` from the target root when one is present. Otherwise, Shopware CLI uses its bundled PHP-CS-Fixer configuration.
 
 Prettier uses the configuration bundled with Shopware CLI. A project or extension `.prettierrc` is not used by the `format` commands.
-
-Administration Twig formatting uses the Shopware CLI built-in formatter and has no separate configuration file.

products/tools/cli/index.md

@@ -23,14 +23,14 @@ Shopware CLI runs on macOS, Linux, and via Docker. For workstation hardware requ
 
 ## Verifier tooling requirements
 
-The Shopware CLI binary itself does not require PHP or Node.js for every command. When you run verifier tooling directly on the host — such as `extension validate --full`, `project validate`, `extension fix`, `project fix`, or the format commands — provide:
+The Shopware CLI binary itself does not require PHP or Node.js for every command. When you run external verifier tooling directly on the host — such as `extension validate`, `extension validate --only phpstan`, `project validate`, the fix commands, or the format commands — provide:
 
 - **PHP 8.2.0** or newer
 - **Node.js 20.0.0** or newer
 - **Composer** when the CLI prepares PHP verifier dependencies or resolves project/extension dependencies
 - **npm** when the CLI prepares its JavaScript verifier dependencies
 
-Basic `extension validate` uses the built-in `sw-cli` checks and does not require a local PHP or Node.js runtime. The [Docker images](installation.md#docker-image) include the verifier runtime dependencies and are recommended for consistent validation, refactoring, and formatting environments.
+`extension validate --only builtin` uses the built-in checks and does not require a local PHP or Node.js runtime. The legacy alias `sw-cli` remains accepted. Selecting only a native Twig checker also skips external tool setup. The [Docker images](installation.md#docker-image) include the verifier runtime dependencies and are recommended for consistent validation, refactoring, and formatting environments.
 
 When you use the Docker-based development environment, run Composer and PHP tools inside the web container rather than on the host. See [Running Composer, PHP, and npm](../../../guides/development/dev-environment.md#running-composer-php-and-npm).
 

products/tools/cli/project-commands/helper-commands.md

@@ -197,7 +197,9 @@ shopware-cli project validate --no-copy
 shopware-cli project validate --local-only
 ```
 
-`--only` and `--exclude` accept comma-separated tool names.
+`--only` and `--exclude` accept comma-separated checker names. Without `--only`, exclusions apply to all checkers; when both flags are supplied, exclusions apply to the selected set. Unknown names, exclusions outside that set, and empty final selections fail before tool setup or copying. Tools without validation support, such as `prettier` or `rector`, cannot be selected.
+
+The built-in checker, `builtin`, runs metadata and structure checks for each eligible extension, applying its own validation ignores. Use `--only builtin` to run these checks alone. The legacy `sw-cli` alias is accepted with a deprecation warning. Reports include checker invocation statuses; `invoked` means the checker was called, but does not guarantee that it analyzed files or produced findings. Use `--verbose` to see source directories, extension names, and external tool commands and arguments.
 
 See [Validation](../validation.md) for the available validation tools.