[DOCS] Add details about regenerating CLI schema (#3516)

Author: lcawl

AGENTS.md

@@ -30,6 +30,14 @@ dotnet format                                   # auto-fix C# formatting
 dotnet test tests/Elastic.Markdown.Tests/       # single test project
 ```
 
+**CLI changes:** after editing `src/tooling/docs-builder/Commands/`, regenerate `docs/cli-schema.json`:
+
+```bash
+dotnet run --project src/tooling/docs-builder -- __schema > docs/cli-schema.json
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md#cli-reference-maintenance) for supplemental CLI docs under `docs/cli/`.
+
 ### TypeScript frontend
 
 ```bash

CONTRIBUTING.md

@@ -44,6 +44,18 @@ Markdown files are refreshed automatically through livereload
 
 Code or layout changes will relaunch the server automatically
 
+## CLI reference maintenance
+
+When you add or change CLI options in `src/tooling/docs-builder/Commands/`, regenerate the checked-in schema so CI and the published CLI reference stay in sync:
+
+```bash
+dotnet run --project src/tooling/docs-builder -- __schema > docs/cli-schema.json
+```
+
+Commit the updated `docs/cli-schema.json` with your code changes. CI compares the schema (ignoring the `version` field) and fails if it has drifted.
+
+The schema drives auto-generated parameter tables and usage synopses on CLI reference pages. For behavior, workflows, and examples that the schema cannot express, also update supplemental files under `docs/cli/` (see [Writing supplemental content](docs/cli/cli-supplemental-docs.md)).
+
 # Release Process
 
 This section outlines the process for releasing a new version of this project.

docs/cli/cli-reference-how-to.md

@@ -28,6 +28,16 @@ my-tool export-schema > docs/cli-schema.json
 
 Commit that file. It is the source of truth for the generated reference section.
 
+:::{note}
+**Maintaining docs-builder itself:** after changing CLI options in `src/tooling/docs-builder/Commands/`, regenerate this repository's schema with:
+
+```bash
+dotnet run --project src/tooling/docs-builder -- __schema > docs/cli-schema.json
+```
+
+Commit the updated file with your code changes. See [CONTRIBUTING.md](https://github.com/elastic/docs-builder/blob/main/CONTRIBUTING.md#cli-reference-maintenance) for the full workflow, including when to update supplemental files under `docs/cli/`.
+:::
+
 :::{tip}
 Add a CI step that regenerates the schema and fails if the checked-in copy has drifted: