feat(cli-docs): auto-generate CLI reference from schema JSON (#3221)

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

Author: Mpdreamz

.github/workflows/ci.yml

@@ -158,6 +158,13 @@ jobs:
       - name: Compile
         run: dotnet run --project build -c release -- compile
 
+      - name: Check CLI schema is up to date
+        if: ${{ matrix.os == 'ubuntu-latest' }}
+        run: |
+          dotnet run --project src/tooling/docs-builder -c release --no-build -- __schema > docs/cli-schema.json.tmp
+          diff docs/cli-schema.json docs/cli-schema.json.tmp || (echo "docs/cli-schema.json is out of date — run: dotnet run --project src/tooling/docs-builder -- __schema > docs/cli-schema.json" && exit 1)
+          rm docs/cli-schema.json.tmp
+
       - name: Test
         run: dotnet run --project build -c release -- unit-test
 

Directory.Packages.props

@@ -69,9 +69,9 @@
     <PackageVersion Include="FSharp.Core" Version="10.1.201" />
   </ItemGroup>
   <ItemGroup>
-    <PackageVersion Include="Nullean.Argh" Version="0.15.4" />
-    <PackageVersion Include="Nullean.Argh.Hosting" Version="0.15.4" />
-    <PackageVersion Include="Nullean.Argh.Interfaces" Version="0.15.4" />
+    <PackageVersion Include="Nullean.Argh" Version="0.16.0" />
+    <PackageVersion Include="Nullean.Argh.Hosting" Version="0.16.0" />
+    <PackageVersion Include="Nullean.Argh.Interfaces" Version="0.16.0" />
     <PackageVersion Include="Crayon" Version="2.0.69" />
     <PackageVersion Include="DotNet.Glob" Version="3.1.3" />
     <PackageVersion Include="Errata" Version="0.16.0" />
@@ -88,7 +88,7 @@
     <PackageVersion Include="Proc" Version="0.13.0" />
     <PackageVersion Include="RazorSlices" Version="0.9.5" />
     <PackageVersion Include="Samboy063.Tomlet" Version="6.0.0" />
-    <PackageVersion Include="Sep" Version="0.12.5" />
+    <PackageVersion Include="Sep" Version="0.13.0" />
     <PackageVersion Include="Slugify.Core" Version="4.0.1" />
     <PackageVersion Include="SoftCircuits.IniFileParser" Version="2.7.0" />
     <PackageVersion Include="System.IO.Abstractions" Version="22.1.1" />

docs/_docset.yml

@@ -150,6 +150,7 @@ toc:
       - file: line_breaks.md
       - file: links.md
       - file: list-sub-pages.md
+      - file: page-card.md
       - file: passthrough.md
       - file: sidebars.md
       - file: stepper.md
@@ -160,53 +161,12 @@ toc:
       - file: tabs.md
       - file: tagged_regions.md
       - file: titles.md
-  - folder: cli
+  - cli: cli-schema.json
+    folder: cli
     children:
-      - file: index.md
-      - folder: docset
-        children:
-          - file: index.md
-          - file: build.md
-          - file: diff-validate.md
-          - file: format.md
-          - file: index-command.md
-          - file: mv.md
-          - file: serve.md
-      - folder: assembler
-        children:
-          - file: index.md
-          - file: assemble.md
-          - file: assembler-bloom-filter-create.md
-          - file: assembler-bloom-filter-lookup.md
-          - file: assembler-build.md
-          - file: assembler-clone.md
-          - file: assembler-config-init.md
-          - file: assembler-content-source-match.md
-          - file: assembler-content-source-validate.md
-          - file: assembler-deploy-apply.md
-          - file: assembler-deploy-plan.md
-          - file: assembler-deploy-update-redirects.md
-          - file: assembler-index.md
-          - file: assembler-navigation-validate.md
-          - file: assembler-navigation-validate-link-reference.md
-          - file: assembler-serve.md
-      - folder: links
-        children:
-          - file: index.md
-          - file: inbound-links-validate.md
-          - file: inbound-links-validate-all.md
-          - file: inbound-links-validate-link-reference.md
-      - folder: changelog
-        children:
-          - file: index.md
-          - file: add.md
-          - file: bundle.md
-          - file: bundle-amend.md
-          - file: evaluate-pr.md
-          - file: gh-release.md
-          - file: init.md
-          - file: remove.md
-          - file: render.md
+      - file: installation.md
+      - file: shell-autocompletion.md
+      - file: cli-reference-how-to.md
   - folder: mcp
     children:
       - file: index.md

docs/_redirects.yml

@@ -1,18 +1,45 @@
 redirects:
   'migration/freeze/gh-action.md' : 'index.md'
   'migration/freeze/index.md' : 'index.md'
-  'cli/mcp.md': 'index.md'
-  'cli/release/changelog-add.md': 'cli/changelog/add.md'
-  'cli/release/changelog-evaluate-artifact.md': 'index.md'
-  'cli/release/changelog-evaluate-pr.md': 'cli/changelog/evaluate-pr.md'
-  'cli/release/changelog-bundle.md': 'cli/changelog/bundle.md'
-  'cli/release/changelog-bundle-amend.md': 'cli/changelog/bundle-amend.md'
-  'cli/release/changelog-gh-release.md': 'cli/changelog/gh-release.md'
-  'cli/release/changelog-init.md': 'cli/changelog/init.md'
-  'cli/release/changelog-prepare-artifact.md': 'index.md'
-  'cli/release/changelog-remove.md': 'cli/changelog/remove.md'
-  'cli/release/changelog-render.md': 'cli/changelog/render.md'
-  'cli/release/index.md': 'cli/changelog/index.md'
+  # CLI docs: old static pages replaced by schema-generated equivalents.
+  # Targets use physical pages so redirect validation works in authoring tests.
+  # The CLI schema-generated pages (synthetic) serve the real content in production.
+  'cli/index.md': 'cli/installation.md'
+  'cli/assembler/index.md': 'cli/installation.md'
+  'cli/changelog/add.md': 'cli/changelog/index.md'
+  'cli/changelog/bundle-amend.md': 'cli/changelog/index.md'
+  'cli/changelog/bundle.md': 'cli/changelog/index.md'
+  'cli/changelog/evaluate-pr.md': 'cli/changelog/index.md'
+  'cli/changelog/gh-release.md': 'cli/changelog/index.md'
+  'cli/changelog/init.md': 'cli/changelog/index.md'
+  'cli/changelog/remove.md': 'cli/changelog/index.md'
+  'cli/changelog/render.md': 'cli/changelog/index.md'
+  'cli/assembler/assemble.md': 'cli/installation.md'
+  'cli/assembler/assembler-bloom-filter-create.md': 'cli/installation.md'
+  'cli/assembler/assembler-bloom-filter-lookup.md': 'cli/installation.md'
+  'cli/assembler/assembler-build.md': 'cli/installation.md'
+  'cli/assembler/assembler-clone.md': 'cli/installation.md'
+  'cli/assembler/assembler-config-init.md': 'cli/installation.md'
+  'cli/assembler/assembler-content-source-match.md': 'cli/installation.md'
+  'cli/assembler/assembler-content-source-validate.md': 'cli/installation.md'
+  'cli/assembler/assembler-deploy-apply.md': 'cli/installation.md'
+  'cli/assembler/assembler-deploy-plan.md': 'cli/installation.md'
+  'cli/assembler/assembler-deploy-update-redirects.md': 'cli/installation.md'
+  'cli/assembler/assembler-index.md': 'cli/installation.md'
+  'cli/assembler/assembler-navigation-validate-link-reference.md': 'cli/installation.md'
+  'cli/assembler/assembler-navigation-validate.md': 'cli/installation.md'
+  'cli/assembler/assembler-serve.md': 'cli/installation.md'
+  'cli/docset/index.md': 'cli/installation.md'
+  'cli/docset/build.md': 'cli/installation.md'
+  'cli/docset/diff-validate.md': 'cli/installation.md'
+  'cli/docset/format.md': 'cli/installation.md'
+  'cli/docset/index-command.md': 'cli/installation.md'
+  'cli/docset/mv.md': 'cli/installation.md'
+  'cli/docset/serve.md': 'cli/installation.md'
+  'cli/links/index.md': 'cli/installation.md'
+  'cli/links/inbound-links-validate.md': 'cli/installation.md'
+  'cli/links/inbound-links-validate-all.md': 'cli/installation.md'
+  'cli/links/inbound-links-validate-link-reference.md': 'cli/installation.md'
   'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
   'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md'
   'testing/redirects/6th-page.md':
@@ -35,4 +62,4 @@ redirects:
           "yy": "bb"
   'testing/redirects/third-page.md':
     anchors:
-      'removed-anchor':
+      'removed-anchor':

docs/building-blocks/inbound-cross-links.md

@@ -16,9 +16,9 @@ Inbound cross-link validation allows you to:
 
 ## How it works
 
-A regular [build](../cli/docset/build.md) of a documentation set won't validate inbound links automatically.
+A regular [build](../cli/build.md) of a documentation set won't validate inbound links automatically.
 
-You have to use the [inbound-links validate-link-reference](../cli/links/inbound-links-validate-link-reference.md) after a build to validate all inbound links.
+You have to use the [inbound-links validate-link-reference](../cli/inbound-links/validate-link-reference.md) after a build to validate all inbound links.
 
 The reason for this is that validating all inbound links has to download all published [Link Index](link-index.md) files
 for the current [Content Source](../configure/content-sources.md).