[david-Darkcollective]

Fixes #16. Part of #17.

What

The command-line section of the Relix programming guide, in docs/guide/command-line, laid out the way the engine's manuals are: a README.md index of chapters and pages, plus index.json as the machine-readable index.

• Hand-written pages: the command and where its script comes from; binding inputs (-i, its formats, standard input, headings, unbounded inputs, -a parameters); output formats; the catalog (discovery, the overlay, trust, relixrc); secrets and profiles; pipelines with jq, awk, find and xargs.
• One page per command (commands/*.md), generated by CommandPages from the same picocli model as --help and the man pages. Each is followed by that command's hand-written examples from docs/command-examples/. Run ./gradlew commandPages to regenerate them. Subcommands such as catalog trust are sections of their parent's page, each with its own anchor, and index.json lists those anchors.
• relix-<version>-docs.zip (./gradlew docsArchive), which the release workflow now attaches to each GitHub Release.

How it stays true

• GuideExamplesTest runs all 116 examples over a fixture ~/shop (src/test/resources/docs-fixture) and compares stdout and the exit status. An example exits 0 unless it ends ; echo "exit $?", which prints the status for the page to show.
  • A plain relix … runs in the test JVM. Anything else runs through bash, with a relix shim that treats a stage's streams as a terminal when they are the example's own (fds 8/9). A piped example therefore prints exactly what a reader would see.
  • The examples are skipped on Windows; Linux and macOS run them all.
• GuideStructureTest checks four things:
  • the command pages and index.json match the model (stale → ./gradlew commandPages);
  • every page is in the index;
  • every docs/command-examples file names a command;
  • no link to a page or heading is broken. Links into the engine's manuals are checked against the pinned engine's unpacked docs.
• Mutation probe, as the issue asks. Each of these failed the build:
  • a changed output row, a changed exit status, and a failing command shown without its status;
  • a dropped output block, a changed bash-pipeline output, and an unrun bash block;
  • a link to a missing page, a missing heading, and a missing engine page;
  • a page left out of the index, a hand-edited generated page, and a changed example not regenerated;
  • the table renderer's footer changed, and the harness made to forget an example's exit status.

The site renders this section in the programming guide at guide/command-line/ and links it from llms.txt; that is a separate PR in DarkCollective/relix. Until releases attach the archive, the site pins a commit of this repository.

Found along the way (not changed here)

• When several ${VAR}s of one declaration are missing, the engine's error names an arbitrary one, and which one changes between JVM runs. The secrets page's example has only one missing.
• In a table, catalog files and catalog ls cut paths to 30 characters, so the pages use -o tsv for them.