Publish the Cucumber scenarios to GitHub Pages

[ctgnz]

Publish the Cucumber run to GitHub Pages, so the scenarios that specify this library are readable without cloning it.

The README calls the scenarios the specification. Right now that is only true for someone who checks the repo out, which is the wrong audience - anyone arriving from Maven Central has the jar and the javadoc and no way to see the worked examples.

What foxglove does

The standard Actions-to-Pages deployment, which transfers directly:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  report:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      # ... build the report into a directory ...
      - uses: actions/upload-pages-artifact@v3
        with:
          path: target/cucumber
      - id: deployment
        uses: actions/deploy-pages@v5

On push to master rather than on every pull request, matching foxglove's reasoning there: a report is something to look at after a merge, and a regression in it should be visible rather than blocking.

What this repo needs that foxglove already has

A Cucumber HTML report. Not currently configured at all - no cucumber.plugin, no junit-platform.properties. Cucumber's own html plugin writes a self-contained page, which suits Pages:

@ConfigurationParameter(key = PLUGIN_PROPERTY_NAME, value = "html:target/cucumber/index.html")

Pages enabled on the repository. GET /repos/ctgnz/yaml-flock/pages currently 404s, where foxglove reports build_type: workflow. This needs switching on with GitHub Actions as the source before any workflow can deploy, and it is a repository settings change rather than something a commit can do.

The design question: a test report is not a specification

Cucumber's HTML output is a run report - pass/fail counts, collapsible steps, timings. It is useful and nearly free, but it reads as "a test suite passed" rather than "here is how the library behaves", and the docstrings carrying the expected documents are a click deep.

Worth noting foxglove does not publish a raw report either; its dashboard is purpose-built (ConformanceReport.write()). So "a la foxglove" could reasonably mean either the publishing mechanism or the curated page.

Three options, cheapest first:

1. The raw Cucumber report. Minutes of work. Looks like CI output.
2. The report, behind a thin landing page that says what the library is and frames the report as the specification, with the README's own framing. Still small.
3. A generated specification document built from the feature files - scenario titles as headings, docstrings as examples. Reads properly, and is the only option that produces something worth linking from the README. Needs a small generator.

Suggest 2 now and 3 only if the published page turns out to be something worth sending people to.

Sequencing

After 1.0.0. This does not gate the artifact, and two consumers are currently blocked on the release - hallux on the version switch, and ctgnz/jmsfx#156 on a red CI that only a published 1.0.0 turns green. A documentation site can follow immediately afterwards.

[ctgnz]

Agreed: after the release.

Split of work settled (2026-10-01): CTG sets up GitHub Pages and the default workflow, which covers the two prerequisites a commit cannot do — enabling Pages with GitHub Actions as the source, since GET /repos/ctgnz/yaml-flock/pages currently 404s. I pick it up from there: the Cucumber HTML plugin, the report content, and whatever landing page we settle on.

So the design question above is still open and is the part worth deciding before I start — a raw Cucumber run report, the report behind a thin landing page, or a generated specification document built from the feature files.