Edit changelog bundle docs (#3213)

Author: lcawl

config/changelog.example.yml

@@ -151,7 +151,7 @@ pivot:
 #   - Comma-separated string: "value1, value2, value3"
 #   - YAML list: [value1, value2, value3]
 #
-# For details and examples, refer to the [rules documentation](https://github.com/elastic/docs-builder/blob/main/docs/contribute/configure-changelogs.md#rules).
+# For details and examples, refer to the [rules documentation](https://github.com/elastic/docs-builder/blob/main/docs/contribute/configure-changelogs-ref.md#rules).
 rules:
   # match: any
 

docs/cli/changelog/add.md

@@ -88,6 +88,7 @@ docs-builder changelog add [options...] [-h|--help]
 :   Mutually exclusive with `--prs`, `--issues`, and `--release-version`.
 :   For a plain newline-delimited list of fully-qualified PR URLs, use `--prs` with a file path instead of `--report`.
 :   When the value is an `https://` URL, only hosts allowed by the parser (such as `github.com` and `buildkite.com`) are supported, and the CLI needs network access to fetch the report.
+
 `--release-version <string?>`
 :   Optional: GitHub release tag to use as a source of pull requests (for example, `"v9.2.0"` or `"latest"`).
 :   When specified, the command fetches the release from GitHub, parses PR references from the release notes, and creates one changelog file per PR — without creating a bundle. Only automated GitHub release notes (the default format or [Release Drafter](https://github.com/release-drafter/release-drafter) format) are supported at this time.
@@ -207,7 +208,7 @@ If a configuration file exists, the command validates its values before generati
 In each of these cases where validation fails, a changelog file is not created.
 
 If the configuration file contains `rules.create` definitions and a PR or issue has a blocking label, that PR is skipped and no changelog file is created for it.
-For more information, refer to [Rules for creation and publishing](/contribute/configure-changelogs.md#rules).
+For more information, refer to [](/contribute/create-changelogs.md#rules).
 
 ## CI auto-detection [ci-auto-detection]
 

docs/cli/changelog/bundle.md

@@ -64,7 +64,7 @@ The product, target version, and lifecycle are inferred automatically from the r
 ## Configuration
 
 The `rules.bundle` section of your `changelog.yml` applies to bundles created by this command (after changelog files are gathered from the release).
-For details, refer to [Rules for filtered bundles](/cli/changelog/bundle.md#changelog-bundle-rules).
+For details, refer to [](/contribute/configure-changelogs-ref.md#rules-bundle).
 
 ## Examples
 

docs/cli/changelog/gh-release.md

@@ -142,6 +142,16 @@ Setting `bundle.directory` and `bundle.output_directory` in `changelog.yml` is r
 
 ## Option-based examples
 
+You can remove changelogs based on their issues, pull requests, product metadata, or remove all changelogs from a folder.
+Exactly one filter option must be specified: `--all`, `--products`, `--prs`, `--issues`, `--release-version` or `--report`.
+When using a file for `--prs` or `--issues`, every line must be a fully-qualified GitHub URL.
+
+For example:
+
+```sh
+docs-builder changelog remove --products "elasticsearch 9.3.0 *" --dry-run
+```
+
 ### Remove by GitHub release [changelog-remove-release-version]
 
 You can use `--release-version` to fetch pull request references directly from GitHub release notes and use them as the removal filter.
@@ -190,97 +200,4 @@ When a `changelog.yml` configuration file defines `bundle.profiles`, you can use
 
 Profile-based commands discover the changelog configuration automatically (no `--config` flag): they look for `changelog.yml` in the current directory, then `docs/changelog.yml`. If neither file is found, the command returns an error with instructions to run `docs-builder changelog init` or to re-run from the folder where the file exists.
 
-### Profile fields
-
-The `changelog remove` command reads the same `bundle.profiles` configuration as `changelog bundle`, but only a subset of fields are relevant to removal:
-
-| Field | Used by `changelog remove`? | Notes |
-|---|---|---|
-| `products` | Yes, when filtering by product | Required when the profile argument is a version string and no `source: github_release` is set. Not needed when the filter comes from a promotion report, URL list file, or `source: github_release`. |
-| `source` | Yes | `source: github_release` fetches the PR list from the GitHub release to use as the removal filter. |
-| `repo` | Yes, with `source: github_release` | Identifies the GitHub repository to fetch the release from. |
-| `owner` | Yes, with `source: github_release` | Identifies the GitHub repository owner. |
-| `output` | No | Ignored — removal does not write any output files. |
-| `output_products` | No | Ignored. |
-| `hide_features` | No | Ignored. |
-| `rules.bundle` | No | Ignored — bundle-time product filtering is not applied during removal. |
-
-### Remove by product
-
-You can create profiles that are equivalent to the `--products` filter option, that is to say the removal will affect only changelogs with matching `products`.
-
-```yaml
-bundle:
-  profiles:
-    elasticsearch-release:
-      products: "elasticsearch {version} {lifecycle}"
-      output: "elasticsearch-{version}.yaml"
-```
-
-You can remove the matching changelogs with:
-
-```sh
-docs-builder changelog remove elasticsearch-release 9.2.0 --dry-run
-```
-
-This removes changelogs for `elasticsearch 9.2.0 ga` — the same set that `docs-builder changelog bundle elasticsearch-release 9.2.0` would include. The lifecycle is inferred from the version string: `9.2.0` → `ga`, `9.2.0-beta.1` → `beta`. Refer to [Lifecycle inference for standard profiles](/cli/changelog/bundle.md#changelog-bundle-standard-profile-lifecycle) for details.
-
-### Remove by report or URL list
-
-You can also create profiles that are equivalent to the `--prs`, `--issues`, or `--report` filter options.
-That is to say the removal will affect only changelogs with matching `prs` or `issues`.
-
-For these profile-based commands, you can pass a promotion report URL, a local `.html` file, or a URL list file as the second argument. The command removes changelogs whose `prs` field matches the PR URLs extracted from the report or file. The following commands perform the same task with and without a profile:
-
-```sh
-docs-builder changelog remove serverless-report ./promotion-report.html
-
-docs-builder changelog remove \
-  --report ./promotion-report.html
-```
-
-Alternatively, use a newline-delimited text file that lists pull request or issue URLs:
-
-```sh
-docs-builder changelog remove serverless-report ./prs.txt
-```
-
-When you want to use both a version (for `{version}` substitution in the output filename) and a report as the filter, pass both as separate arguments:
-
-```sh
-docs-builder changelog remove serverless-report 2026-02-13 ./promotion-report.html
-```
-
-### Remove by GitHub release profiles [changelog-remove-github-release-profile]
-
-To make removal by GitHub release more easily repeatable, create a profile with `source: github_release` in your changelog configuration file.
-For example:
-
-```yaml
-bundle:
-  profiles:
-    agent-gh-release:
-      source: github_release
-      repo: apm-agent-dotnet
-      owner: elastic 
-      output: "agent-{version}.yaml"
-```
-
-You can remove the matching changelogs with:
-
-```sh
-docs-builder changelog remove agent-gh-release 1.34.0
-```
-
-Use `--dry-run` to preview the files that would be deleted before committing:
-
-```sh
-docs-builder changelog remove agent-gh-release 1.34.0 --dry-run
-```
-
-:::{note}
-`source: github_release` profiles require a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API.
-The `repo` and `owner` used to identify the release follow the same precedence as bundling: profile-level `repo`/`owner` override `bundle.repo`/`bundle.owner`, which in turn override the default owner `elastic`.
-:::
-
-For the full list of profile configuration fields, go to [Profile configuration fields](/cli/changelog/bundle.md#changelog-bundle-profile-config).
+Refer to [](/contribute/bundle-changelogs.md#changelog-remove) for examples.