Adds CLI notes from recent team walk-throughs and discussions

.wordlist.txt

@@ -889,6 +889,7 @@ Roadmap
 RouteResponse
 RuleConditionService
 RuntimeException
+SBOM
 SBP
 SCSS
 SDK

products/tools/cli/automatic-refactoring.md

@@ -7,9 +7,15 @@ nav:
 
 # Automatic refactoring
 
-Shopware CLI includes a built-in automatic refactoring tool that helps you automatically update and clean up code in your Shopware projects and extensions.
+Shopware CLI includes a built-in automatic refactoring tool with pre-configured rules for Shopware projects. Instead of manually configuring and managing multiple linters and fixers, this tool automatically handles breaking changes and code modernization when you upgrade Shopware versions.
 
-Use this tool to modernize your codebase when upgrading to a new Shopware version or to apply best-practice changes automatically.
+Use this tool to:
+
+- Automatically fix breaking changes between Shopware versions
+- Apply Shopware-idiomatic code fixes
+- Modernize your codebase without manual linter configuration
+
+The tool uses:
 
 - [Rector](https://getrector.com/) for PHP
 - [ESLint](https://eslint.org/) for JavaScript
@@ -79,6 +85,23 @@ The CLI runs Rector and ESLint automatically. After completion, review all chang
 
 Make sure the `shopware/core` requirement in your `composer.json` file reflects the version you're targeting. Shopware CLI determines which upgrade rules to apply based on that version constraint.
 
+### Project fix options
+
+Run only specific tools:
+
+```shell
+shopware-cli project fix /path/to/your/project --only phpstan
+shopware-cli project fix /path/to/your/project --only "phpstan,eslint"
+```
+
+Allow running on non-Git repositories:
+
+```shell
+shopware-cli project fix /path/to/your/project --allow-non-git
+```
+
+By default, `project fix` requires a Git repository to safely track changes.
+
 ## After running refactoring
 
 Use Git or your diff tool to review the changes.

products/tools/cli/extension-commands/build.md

@@ -44,7 +44,7 @@ build:
 
 ## Extension as bundle
 
-If your extension is not a plugin but itself a bundle, make sure your composer type is `shopware-bundle` and that you have set a `shopware-bundle-name` in the `extra` part of the composer definition like this:
+If your extension is not a plugin but itself a bundle, make sure your Composer type is `shopware-bundle` and that you have set a `shopware-bundle-name` in the `extra` part of the composer definition like this:
 
 ```json
 {
@@ -59,61 +59,71 @@ If your extension is not a plugin but itself a bundle, make sure your composer t
 Now you can use `shopware-cli extension build <path>` to build the assets and distribute them together with your bundle.
 Also `shopware-cli project ci` detects know automatically this bundle and builds the assets for it.
 
-## Using `esbuild` for JavaScript bundling
+## Using esbuild for JavaScript bundling
 
 ::: warning
 Building with esbuild works completely standalone without the Shopware codebase. This means if you import files from Shopware, you have to copy it to your extension.
 :::
 
-Esbuild can be used for JavaScript bundling, offering a significantly faster alternative to the standard Shopware bundling process, as it eliminates the need to involve Shopware for asset building.
+An esbuild bundle can be used for JavaScript bundling, offering a significantly faster alternative to the standard Shopware bundling process, as it eliminates the need to involve Shopware for asset building.
 
 ```yaml
 # .shopware-extension.yml
 build:
-  zip:
+  package:
     assets:
       # Use esbuild for Administration
       enable_es_build_for_admin: true
       # Use esbuild for Storefront
       enable_es_build_for_storefront: true
 ```
 
+### Content-addressable assets and Vite manifest
+
+When building with esbuild, Shopware CLI emits content-hashed variants of the
+compiled JS and CSS files (e.g. `<name>-<hash>.js`) alongside files without hashes in the same directories.
+
+- **Shopware 6.7+**: The generated `.vite/manifest.json` and `.vite/entrypoints.json` reference the hashed filenames, so browser and CDN caches are invalidated automatically whenever the extension assets change. Note that an existing `.vite/manifest.json` is overwritten on each esbuild build.
+- **Shopware < 6.7**: The files without hashes are kept for backward compatibility and continue to be loaded as before.
+
+No configuration is required. This happens automatically when esbuild is enabled.
+
 ## Creating an archive
 
 To create an archive of an extension, you can use the following command:
 
 ```bash
-shopware-cli extension zip <path>
+shopware-cli extension package <path>
 ```
 
-The command copies the extension to a temporary directory, builds the assets, deletes unnecessary files and creates a zip archive of the extension. The archive is placed in the current working directory.
+The command copies the extension to a temporary directory, builds the assets, deletes unnecessary files and creates a ZIP archive of the extension. The archive is placed in the current working directory.
 
 **By default, the command picks the latest released git tag**, use the `--disable-git` flag to disable this behavior and use the current source code. Besides disabling it completely, you can also specify a specific tag or commit using `--git-commit`.
 
-### Bundling composer dependencies
+### Bundling Composer dependencies
 
-Before Shopware 6.5, bundling the composer dependencies into the zip file is required. Shopware CLI automatically runs `composer install` and removes duplicate composer dependencies to avoid conflicts.
+Before Shopware 6.5, bundling the Composer dependencies into the ZIP file is required. Shopware CLI automatically runs `composer install` and removes duplicate Composer dependencies to avoid conflicts.
 
 To disable this behavior, you can adjust the configuration:
 
 ```yaml
 # .shopware-extension.yml
 build:
-  zip:
+  package:
     composer:
       enabled: false
 ```
 
 This is automatically disabled for plugins targeting Shopware 6.5 and above and `executeComposerCommands` should be used instead.
 
-### Delete files before zipping
+### Delete files before packaging
 
-Shopware CLI deletes a lot of known files before zipping the extension. If you want to delete more files, you can adjust the configuration:
+Shopware CLI deletes a lot of known files before packaging the extension into a ZIP file. If you want to delete more files, you can adjust the configuration:
 
 ```yaml
 # .shopware-extension.yml
 build:
-  zip:
+  package:
     pack:
       excludes:
         paths:
@@ -127,7 +137,7 @@ If you bring additional NPM packages, make sure that you added only runtime depe
 ```yaml
 # .shopware-extension.yml
 build:
-  zip:
+  package:
     assets:
       npm_strict: true
 ```
@@ -136,14 +146,14 @@ This skips unnecessary `npm install` and `npm ci` commands and only installs the
 
 ### Checksums
 
-When creating an archive using `shopware-cli extension zip`, a `checksum.json` file is automatically generated. This file contains checksums for all files in the extension, which can be used to verify the integrity of the extension after installation.
+When creating an archive using `shopware-cli extension package`, a `checksum.json` file is automatically generated. This file contains checksums for all files in the extension, which can be used to verify the integrity of the extension after installation.
 
 If you want to exclude certain files or paths from the checksum calculation, you can configure this in your `.shopware-extension.yml` file:
 
 ```yaml
 # .shopware-extension.yml
 build:
-  zip:
+  package:
     checksum:
       ignore:
         - <path>
@@ -155,7 +165,7 @@ For example, to exclude the `src/Resources/config/services.php` file from checks
 ```yaml
 # .shopware-extension.yml
 build:
-  zip:
+  package:
     checksum:
       ignore:
         - src/Resources/config/services.php
@@ -165,7 +175,18 @@ To verify the checksum of installed extensions, you can use the [FroshTools](htt
 
 ### Release mode
 
-If you are building an archive for distribution, you can enable the release mode with the flag `--release`. This will remove the App secret from the `manifest.xml` and generate changelog files if enabled.
+When building an extension for distribution to the Shopware Store or installation in a Shopware instance, enable release mode with the `--release` flag:
+
+```bash
+shopware-cli extension package <path> --release
+```
+
+Release mode:
+
+- Removes secrets: Strips out sensitive data that may have been committed during development (credentials, API keys, app secrets)
+- Generates changelog: Automatically creates changelog files from Git commits (if enabled in configuration)
+
+This is important when distributing extensions because developers often commit configuration files with secrets during development that shouldn't be included in the final package.
 
 The changelog generation can be enabled with the configuration:
 
@@ -196,22 +217,22 @@ With the combination of `pattern`, `variables` and `template` we link the commit
 
 ### Overwrites
 
-Extension configuration can be overwritten during the zipping process, allowing changes to aspects such as the version and app-related settings.
+Extension configuration can be overwritten during the packaging process, allowing changes to aspects such as the version and app-related settings.
 
 Replaces the version in `composer.json` or `manifest.xml` with the given version:
 
 ```yaml
-shopware-cli extension zip --overwrite-version=1.0.0 <path>
+shopware-cli extension package --overwrite-version=1.0.0 <path>
 ```
 
 Replaces all external URLs in `manifest.xml` to that given URL:
 
 ```yaml
-shopware-cli extension zip --overwrite-app-backend-url=https://example.com <path>
+shopware-cli extension package --overwrite-app-backend-url=https://example.com <path>
 ```
 
 Replaces the App secret in `manifest.xml` with the given secret:
 
 ```yaml
-shopware-cli extension zip --overwrite-app-backend-secret=MySecret <path>
+shopware-cli extension package --overwrite-app-backend-secret=MySecret <path>
 ```

products/tools/cli/extension-commands/configuration.md

@@ -44,6 +44,10 @@ validation:
 
 When you edit that file in an editor, you will get autocompletion and hints for the available options.
 
+::: info
+To programmatically access the configuration schema, use `shopware-cli extension config-schema`. This outputs the JSON schema and is particularly useful for AI agents and automation tools that need to understand the extension configuration structure.
+:::
+
 ## Compatibility date
 
 You can define a `compatibility_date` in `.shopware-extension.yml`:

products/tools/cli/extension-commands/extract-meta-data.md

@@ -7,7 +7,7 @@ nav:
 
 # Extracting Meta Data
 
-There are helpers in Shopware CLI to extract data of an extension. This is useful in your CI/CD pipeline to get the extension version or the changelog for the automated release.
+There are helpers in Shopware CLI to extract data of an extension. This is useful in your CI/CD pipeline to get the extension version, name, or the changelog for the automated release.
 
 ## Extracting the version
 
@@ -19,6 +19,16 @@ shopware-cli extension get-version <path>
 
 The path can be absolute or relative to the current working directory. The command will output the version of the extension.
 
+## Extracting the name
+
+To extract the name of an extension, you can use the following command:
+
+```bash
+shopware-cli extension get-name <path>
+```
+
+The path can be absolute or relative to the current working directory. This is useful in CI/CD pipelines when you need to programmatically determine the extension identifier.
+
 ## Extracting the changelog
 
 To extract the changelog of an extension, you can use the following command:
@@ -30,3 +40,13 @@ shopware-cli extension get-changelog <path>
 The path can be absolute or relative to the current working directory. The command will output the changelog of the extension.
 
 It will output always the English changelog.
+
+## Configuration schema
+
+To view the JSON schema for the `.shopware-extension.yml` configuration file, you can use:
+
+```bash
+shopware-cli extension config-schema
+```
+
+This outputs the JSON schema that describes all available configuration options in `.shopware-extension.yml`. This is particularly useful for AI agents and automation tools that need to understand the extension configuration structure.

products/tools/cli/index.md

@@ -67,3 +67,9 @@ COPY --from=ghcr.io/shopware/shopware-cli:bin /shopware-cli /usr/local/bin/shopw
 </Tabs>
 
 **Binary & releases:** Prebuilt packages and archives are published at [shopware/shopware-cli · Releases](https://github.com/shopware/shopware-cli/releases).
+
+## Telemetry
+
+Shopware CLI collects limited usage telemetry to help us improve the tool and understand which features are most valuable to you. No personal data, credentials, or file contents are collected. You can opt out anytime by setting the `DO_NOT_TRACK` environment variable.
+
+See [Telemetry & Privacy](../../../resources/references/telemetry.md#shopware-cli) for full details about what data is collected and how to disable telemetry.

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

@@ -11,7 +11,7 @@ Shopware-CLI comes with some builtin auto fixers for project migrations.
 
 ## Migrate a project to Symfony Flex
 
-Prior to Shopware 6.5, Shopware didn't use Symfony Flex. This means that the project structure was different, and some configuration files were located in different places. The `shopware-cli project autofix flex` command will migrate your project to Symfony Flex and move all configuration files to the correct locations.
+Shopware 6.4 and earlier used a different project structure without Symfony Flex. When upgrading to Shopware 6.5 or later, the `shopware-cli project autofix flex` command will migrate your project from the legacy structure to Symfony Flex, moving all configuration files to the correct locations.
 
 ::: warning
 Ensure that you have a backup of your project before running this command.
@@ -25,8 +25,19 @@ The command will delete all unnecessary configuration files. It will also update
 
 ## Migrate custom/plugins extensions to Composer
 
-It's best practice to manage the store and your custom plugins via Composer. [If you want to learn more about this check out this guide](../../../../guides/hosting/installation-updates/extension-management.md). Shopware-CLI has a helper for migrating locally installed plugins to Composer through Shopware Packagist for the Shopware Store. Make sure you have a Shopware Packages Token, which can be gathered in the Shopware Account. You can find the token in the Shopware Account under "Shops" > "Licenses" > "..." of one extension and "Install via Composer.
+Instead of manually cloning extensions into `custom/plugins`, it's best practice to manage store extensions via Composer. [For more details, see this guide](../../../../guides/hosting/installation-updates/extension-management.md).
+
+Migrate locally cloned plugins to Composer-managed extensions:
 
 ```bash
 shopware-cli project autofix composer-plugins
 ```
+
+Benefits of using Composer:
+
+- Composer knows which extension versions exist and are compatible
+- Automatic dependency resolution: Composer handles version compatibility for you
+- Automatic updates: easily update extensions to new versions
+- Less manual work: no need to manually clone and manage extensions in custom directories
+
+You need a Shopware Packages Token. Get it from your Shopware Account: "Shops" > "Licenses" > "..." of one extension > "Install via Composer".

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

@@ -17,13 +17,28 @@
 shopware-cli project ci <path>
 ```
 
+One of the most-used commands in the Shopware CLI. After cloning a repository, this command prepares a complete artifact that can be deployed with all dependencies installed and assets compiled. It is widely used in PaaS and SaaS deployments.
+
 ## What does it do?
 
 - It runs `composer install` (by default, only installs the production dependencies, use `--with-dev-dependencies` to install the dev dependencies as well)
 - Looks for missing assets of extensions and only compiles the missing assets to speed up the build process
 - Deletes unnecessary files like `node_modules` and many more to save disk space
 - Deletes source code of compiled assets to save disk space
 - Merges snippets of extensions to speed up Administration
+- Generates a Software Bill of Materials (SBOM) listing all deployed dependencies
+
+## CI system configuration
+
+Specify which CI/CD platform to configure for:
+
+```bash
+shopware-cli project ci <path> --ci github
+shopware-cli project ci <path> --ci gitlab
+shopware-cli project ci <path> --ci none
+```
+
+Options: `github`, `gitlab`, `none` (default).
 
 ## Using private Composer repositories
 
@@ -100,6 +115,17 @@
 
 MJML compilation requires the `mjml` package to be installed via NPM in your build environment. The CLI uses local compilation to convert MJML templates to HTML.
 
+## Software Bill of Materials (SBOM)
+
+The `project ci` command automatically generates a Software Bill of Materials (SBOM) file containing a list of all dependencies installed in your project. This file is useful for:
+
+- **Docker images**: Container scanning tools can read SBOM files to identify dependencies and check for vulnerabilities
+- **Security scanning**: Understand exactly which packages and versions are deployed in production
+- **Compliance tracking**: Document all software components in your deployment artifact
+- **Supply chain security**: Maintain a record of what's included in each release
+
+The SBOM is included in the build artifact automatically and can be consumed by tools like Grype and other container security scanners.
+
 ## Build Hooks
 
 Build hooks let you run custom shell commands at specific stages of the CI build process. This is useful for tasks like generating configuration files, running custom build steps, or integrating with external tools.