New doc-builder changelog remove command

docs/_docset.yml

@@ -164,8 +164,9 @@ toc:
           - file: index.md
           - file: changelog-add.md
           - file: changelog-bundle.md
-          - file: changelog-init.md
           - file: changelog-bundle-amend.md
+          - file: changelog-init.md
+          - file: changelog-remove.md
           - file: changelog-render.md
   - folder: mcp
     children:

docs/cli/release/changelog-bundle.md

@@ -47,9 +47,9 @@ These arguments apply to profile-based bundling:
 `--input-products <List<ProductInfo>?>`
 :   Filter by products in format "product target lifecycle, ..."
 :   Only one filter option can be specified: `--all`, `--input-products`, `--prs`, or `--issues`.
-:   When specified, all three parts (product, target, lifecycle) are required but can be wildcards (`*`). For example:
+:   When specified, all three parts (product, target, lifecycle) are required but can be wildcards (`*`). Multiple comma-separated values are combined with OR: a changelog is included if it matches any of the specified product/target/lifecycle combinations. For example:
 
-- `"cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"` - exact matches
+- `"cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"` — include changelogs for either cloud-serverless 2025-12-02 ga or cloud-serverless 2025-12-06 beta
 - `"cloud-serverless 2025-12-02 *"` - match cloud-serverless 2025-12-02 with any lifecycle
 - `"elasticsearch * *"` - match all elasticsearch changelogs
 - `"* 9.3.* *"` - match any product with target starting with "9.3."

docs/cli/release/changelog-remove.md

@@ -0,0 +1,69 @@
+# changelog remove
+
+Remove changelog YAML files from a directory.
+
+You can remove changelogs based their issues, pull requests, or product metadata.
+Alternatively, remove all changelogs from the specified directory.
+Exactly one filter option must be specified.
+
+Before deleting anything, the command checks whether any of the matching files are referenced by unresolved bundles, to prevent silently breaking the `{changelog}` directive.
+
+For more context, go to [](/contribute/changelog.md#changelog-remove).
+
+## Usage
+
+```sh
+docs-builder  changelog remove [options...] [-h|--help]
+```
+
+## Options
+
+`--all`
+:   Remove all changelog files in the directory.
+:   Exactly one filter option must be specified: `--all`, `--products`, `--prs`, or `--issues`.
+
+`--bundles-dir <string?>`
+:   Optional: Override the directory scanned for bundles during the dependency check.
+:   When not specified, the directory is discovered automatically from config or fallback paths.
+
+`--config <string?>`
+:   Optional: Path to the changelog configuration file.
+:   Defaults to `docs/changelog.yml`.
+
+`--directory <string?>`
+:   Optional: The directory that contains the changelog YAML files.
+:   When not specified, uses `bundle.directory` from the changelog configuration if set, otherwise the current directory.
+
+`--dry-run`
+:   Print the files that would be removed and any bundle dependency conflicts, without deleting anything.
+
+`--force`
+:   Proceed with removal even when files are referenced by unresolved bundles.
+:   Emits a warning per dependency instead of blocking.
+
+`--issues <string[]?>`
+:   Filter by issue URLs or numbers (comma-separated), or a path to a newline-delimited file containing issue URLs or numbers.
+:   Can be specified multiple times.
+:   Exactly one filter option must be specified: `--all`, `--products`, `--prs`, or `--issues`.
+
+`--owner <string?>`
+:   The GitHub repository owner, which is required when pull requests or issues are specified as numbers.
+
+`--products <List<ProductInfo>?>`
+:   Filter by products in format `"product target lifecycle, ..."`
+:   Exactly one filter option must be specified: `--all`, `--products`, `--prs`, or `--issues`.
+:   All three parts (product, target, lifecycle) are required but can be wildcards (`*`). Multiple comma-separated values are combined with OR: a changelog is removed if it matches any of the specified product/target/lifecycle combinations. For example:
+
+- `"elasticsearch 9.3.0 ga"` — exact match
+- `"cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"` — remove changelogs for either cloud-serverless 2025-12-02 ga or cloud-serverless 2025-12-06 beta
+- `"elasticsearch * *"` — all elasticsearch changelogs
+- `"* 9.3.* *"` — any product with a target starting with `9.3.`
+- `"* * *"` — all changelogs (equivalent to `--all`)
+
+`--prs <string[]?>`
+:   Filter by pull request URLs or numbers (comma-separated), or a path to a newline-delimited file containing PR URLs or numbers.
+:   Can be specified multiple times.
+:   Exactly one filter option must be specified: `--all`, `--products`, `--prs`, or `--issues`.
+
+`--repo <string?>`
+:   The GitHub repository name, which is required when pull requests or issues are specified as numbers.

docs/contribute/changelog.md

@@ -490,9 +490,14 @@ You can specify only one of the following filter options:
 - `--prs`: Include changelogs for the specified pull request URLs or numbers, or a path to a newline-delimited file containing PR URLs or numbers. Go to [Filter by pull requests](#changelog-bundle-pr).
 - `--issues`: Include changelogs for the specified issue URLs or numbers, or a path to a newline-delimited file containing issue URLs or numbers. Go to [Filter by issues](#changelog-bundle-issues).
 
-By default, the output file contains only the changelog file names and checksums.
+By default, the output file contains only the changelog file names and checksums unless you set `bundle.resolve` to `true` in the changelog configuration file.
 You can optionally use the `--resolve` command option to pull all of the content from each changelog into the bundle.
 
+:::{tip}
+If you plan to use [changelog directives](#changelog-directive), it is recommended to use "resolved" bundles; otherwise you can't delete your changelogs.
+If you likewise want to regenerate your [Asciidoc or Markdown files](#render-changelogs) after deleting your changelogs, it's only possible if you have resolved bundles.
+:::
+
 When you do not specify `--directory`, the command reads changelog files from `bundle.directory` in your changelog configuration if it is set, otherwise from the current directory.
 When you do not specify `--output`, the command writes the bundle to `bundle.output_directory` from your changelog configuration (creating `changelog-bundle.yaml` in that directory) if it is set, otherwise to `changelog-bundle.yaml` in the input directory.
 
@@ -548,8 +553,6 @@ entries:
 1. By default these values match your `--input-products` (even if the changelogs have more products).
 To specify different product metadata, use the `--output-products` option.
 
-If you add the `--resolve` option, the contents of each changelog will be included in the output file.
-
 ### Filter by pull requests [changelog-bundle-pr]
 
 You can use the `--prs` option to create a bundle of the changelogs that relate to those pull requests.
@@ -590,8 +593,6 @@ entries:
     checksum: 451d60283fe5df426f023e824339f82c2900311e
 ```
 
-If you add the `--resolve` option, the contents of each changelog will be included in the output file.
-
 ### Filter by issues [changelog-bundle-issues]
 
 You can use the `--issues` option to create a bundle of changelogs that relate to those GitHub issues.
@@ -821,3 +822,35 @@ highlight: true
 ```
 
 When rendering changelogs, entries with `highlight: true` are collected from all types and rendered in a dedicated highlights section. In markdown output, this creates a separate `highlights.md` file. In asciidoc output, highlights appear as a dedicated section in the single asciidoc file.
+
+## Remove changelog files [changelog-remove]
+
+A single changelog file might be applicable to multiple releases (for example, it might be delivered in both Stack and {{serverless-short}} releases or {{ech}} and Enterprise releases on different timelines).
+After it has been included in all of the relevant bundles, it is reasonable to delete the changelog to keep your repository clean.
+
+:::{important}
+If you create docs with changelog directives, run the `docs-builder changelog bundle` command with the `--resolve` option or set `bundle.resolve` to `true` in the changelog configuration file (so that bundle files are self-contained).
+Otherwise, the build will fail if you remove changelogs that the directive requires.
+
+Likewise, the `docs-builder changelog render` command fails for "unresolved" bundles after you delete the changelogs.
+:::
+
+You can use the `docs-builder changelog remove` command to remove changelogs.
+It has the same filter options as `changelog bundle` (that is to say, you can remove changelogs based their issues or pull requests, product metadata, or folder).
+Exactly one filter option must be specified.
+
+Before deleting, the command automatically scans for bundles that still hold unresolved (`file:`) references to the matching changelog files.
+If any are found, the command reports an error for each dependency.
+This check prevents the `{changelog}` directive from failing at build time with missing file errors.
+To proceed with removal even when unresolved bundle dependencies exist, use `--force`.
+
+To preview what would be removed without deleting anything, use `--dry-run`.
+Bundle dependency conflicts are also reported in dry-run mode.
+
+For example:
+
+```sh
+docs-builder changelog remove --products "elasticsearch 9.3.0 *" --dry-run
+```
+
+For full option details, go to [](/cli/release/changelog-remove.md).

docs/syntax/changelog.md

@@ -418,6 +418,8 @@ docs/
 └── release-notes.md          # Page with :::{changelog}
 ```
 
+To override these expectations, set the `bundle.directory` and `bundle.output_directory` in the changelog configuration file.
+
 ## Version ordering
 
 Bundles are automatically sorted by **semantic version** (descending - newest first). This means:
@@ -466,6 +468,24 @@ Each bundle renders as a `## {version}` section with subsections beneath:
 
 Sections with no entries of that type are omitted from the output.
 
+## Error behavior for missing files [changelog-missing-files]
+
+Bundles created without the `--resolve` option store `file:` references (filenames and checksums) instead of embedding entry content inline.
+When the directive loads such a bundle, it looks up each referenced file to read its content.
+If a referenced file cannot be found on disk, the directive emits an error and the build fails.
+This prevents silent data loss where changelog entries would be quietly omitted from rendered release notes without any indication that something was missing.
+
+To fix this, either:
+
+- Restore the missing changelog files, or
+- Re-create the bundle with `--resolve` to embed entry content directly (making the bundle self-contained), or
+- Remove the unresolvable entry from the bundle file.
+
+:::{tip}
+In general, if you want to be able to remove changelog files after your releases, create your bundles with the `--resolve` option or set `bundle.resolve` to `true` in the changelog configuration file.
+For more command syntax details, go to [Remove changelog files](../contribute/changelog.md#changelog-remove).
+:::
+
 ## Example
 
 The following renders all changelog bundles from the default `changelog/bundles/` folder:
@@ -495,4 +515,5 @@ The `{changelog}` directive is ideal for release notes pages that should always
 - [Create and bundle changelogs](../contribute/changelog.md) — Learn how to create changelog entries and bundles
 - [`changelog add`](../cli/release/changelog-add.md) — CLI command to create changelog entries
 - [`changelog bundle`](../cli/release/changelog-bundle.md) — CLI command to bundle changelog entries
+- [`changelog remove`](../cli/release/changelog-remove.md) — CLI command to remove changelog files
 - [`changelog render`](../cli/release/changelog-render.md) — CLI command to render changelogs to markdown files

src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogBlock.cs

@@ -326,9 +326,11 @@ private void LoadAndCacheBundles()
 		var loader = new BundleLoader(Build.ReadFileSystem);
 
 		// Load bundles using the BundleLoader service
+		// Emit errors (not warnings) for missing file references so the build fails fast
+		// rather than silently omitting entries from the rendered output.
 		var loadedBundles = loader.LoadBundles(
 			BundlesFolderPath,
-			msg => this.EmitWarning(msg));
+			msg => this.EmitError(msg));
 
 		// Sort by version (descending - newest first)
 		// Supports both semver (e.g., "9.3.0") and date-based (e.g., "2025-08-05") versions