feat(cli-docs): supplemental content system for generated CLI reference pages (#3271)

* feat(cli-docs): structured supplemental docs, cli-modifiers directive, and assembler/changelog content

Adds four generator improvements and restores hand-authored content for the
assembler and changelog namespaces.

Generator changes:
- New `:::{cli-modifiers}` directive renders a pill row (destructive,
  requires-confirmation, auth required, idempotent, scope, streaming,
  long-running) between the usage block and description on generated pages
- `CliSupplementalDoc` parser splits supplemental files into typed sections:
  `## Description` overrides the intro; `## Options` / `## Arguments` override
  per-parameter text (unknown keys are a build error); any other `##` heading
  appends as post-content after the generated parameter table
- `__argh_root` and other `ReservedMetaCommands` tokens are stripped from
  generated usage lines
- Schema `notes` field is no longer rendered (use supplemental post-content instead)
- Behaviour-flag params (dryRun, confirmationSkip, output) get a quick-reference
  block above Arguments/Options
- Stack-overflow fix: expose `Collector` as `protected` on `MarkdownFile` so CLI
  file subclasses can emit diagnostics without storing `BuildContext` as a record field

Supplemental content:
- Assembler namespace and all sub-commands (assemble, build, clone, serve, index,
  bloom-filter create/lookup, config init, content-source match/validate,
  deploy apply/plan/update-redirects, navigation validate/validate-link-reference)
- Changelog commands: add, bundle-amend, evaluate-pr, gh-release, init, remove, render

Docs:
- cli-reference-how-to step 3 replaced with a link to the new supplemental-docs page
- New `cli-supplemental-docs.md` documents file naming, heading rules, and
  `## Options` / `## Arguments` override syntax

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

* fix: import ordering and broken relative links in supplemental docs

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

* fix: namespace option overrides and fenced code block languages

- Thread OptionOverrides and emitError through NamespacePage so namespace
  supplemental ## Options are applied and typos are caught at build time
- Add text language to directory tree fenced blocks in cli-supplemental-docs.md

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

* fix: output formats always rendered and role-scoped override validation

- Output formats block no longer skipped when command has no modifier pills
- Option/argument override validation now checks against the correct parameter
  role subset so a flag name in ## Arguments (or vice-versa) is caught

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: Mpdreamz

docs/_docset.yml

@@ -167,6 +167,8 @@ toc:
       - file: installation.md
       - file: shell-autocompletion.md
       - file: cli-reference-how-to.md
+        children:
+          - file: cli-supplemental-docs.md
   - folder: mcp
     children:
       - file: index.md

docs/cli/assembler/bloom-filter/cmd-create.md

@@ -0,0 +1,3 @@
+Generates a bloom filter that gets embedded into the `docs-builder` binary.
+
+This bloom filter is used to determine whether a document's `mapped_page` frontmatter field exists in the [legacy-url-mappings](../../../configure/site/legacy-url-mappings.md) project. The result controls how the document history selector is populated.

docs/cli/assembler/bloom-filter/cmd-lookup.md

@@ -0,0 +1 @@
+Test command to assert whether an old V2 URL matches the bloom filter embedded in the `docs-builder` binary.

docs/cli/assembler/cmd-build.md

@@ -0,0 +1,10 @@
+## Description
+
+:::{note}
+This command requires that you've previously run `docs-builder assembler clone` to clone the documentation sets.
+If you cloned using a certain `--environment` you must also use that same `--environment` when building.
+:::
+
+Builds all the documentation sets and assembles them into a complete documentation site ready to be deployed.
+
+It uses [the site configuration files](../../configure/site/index.md) to direct how the documentation sets should be assembled.

docs/cli/assembler/cmd-clone.md

@@ -0,0 +1,3 @@
+Clones all repositories listed in the assembler configuration. Defaults to `$(pwd)/.artifacts/checkouts/{content_source}`.
+
+The `content_source` is taken from the `--environment` option as configured in `assembly.yaml`.

docs/cli/assembler/config/cmd-init.md

@@ -0,0 +1,11 @@
+Sources the configuration from [the `config` folder on the `main` branch of `docs-builder`](https://github.com/elastic/docs-builder/tree/main/config).
+
+By default, the configuration is placed in a platform-specific application support folder, which is the primary location for CI environments:
+
+* **macOS:** `~/Library/Application Support/docs-builder`
+* **Linux:** `~/.config/docs-builder`
+* **Windows:** `%APPDATA%\docs-builder`
+
+Use the `--local` flag to save the configuration in the current working directory instead. This is the recommended approach when building a local workspace for testing.
+
+See [using a local workspace for assembler builds](../../assemble.md#using-a-local-workspace) for more information.

docs/cli/assembler/content-source/cmd-match.md

@@ -0,0 +1,15 @@
+## Description
+
+Checks whether a repository at a specific branch or tag should be included in the next build. Emits the following `$GITHUB_OUTPUT` variables:
+
+* `content-source-match` — whether the branch is a configured content source.
+* `content-source-next` — whether the branch is the next content source.
+* `content-source-current` — whether the branch is the current content source.
+* `content-source-speculative` — whether the branch is a speculative content source.
+
+## Speculative builds
+
+If branches follow semantic versioning and a branch is cut that is greater than the current version, it is considered a speculative build.
+`docs-builder`'s shared workflow triggers even if the branch is not yet specified as a content source in `assembler.yml`.
+
+This allows a branch's `links.json` to be published to the Links Service ahead of time, before the branch is officially configured as a content source.

docs/cli/assembler/deploy/cmd-apply.md

@@ -0,0 +1 @@
+Applies an incremental synchronization plan created by [`docs-builder assembler deploy plan`](./plan.md).

docs/cli/assembler/deploy/cmd-plan.md

@@ -0,0 +1 @@
+Creates an incremental synchronization plan by comparing the remote `--s3-bucket-name` with the local output of the build.

docs/cli/assembler/index.md

@@ -0,0 +1,10 @@
+Assembler builds bring together all isolated documentation set builds and turn them into the overall documentation that gets published.
+
+The quickest way to run an assembler build locally is:
+
+```bash
+docs-builder assembler config init --local
+docs-builder assemble --serve
+```
+
+This fetches the current configuration from the `main` branch of `docs-builder`, clones all content repositories, builds the unified site, and serves it at `http://localhost:4000`.