docs: publish a demo page to GitHub Pages

.github/workflows/demo.yml

@@ -0,0 +1,41 @@
+name: Demo
+
+# Publishes the demo page to GitHub Pages: the CLI collects the made-up scenario in
+# demo/scenario.py, so the page and its report.json match the released code.
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch: {}
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: extractions/setup-just@v4
+      - uses: astral-sh/setup-uv@v8.2.0
+      - run: uv python install 3.13
+      - run: uv python pin 3.13
+      - run: just install
+      - run: just demo
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

AGENTS.md

@@ -20,7 +20,9 @@ turns the range plus merge requests into rows; `_candidates.py` is pure and turn
 release could ship. `_static/` is the site `collect` copies next to `report.json`: `index.html` with vendored Alpine.js.
 Besides the translation checks in `tests/test_page.py`, it has browser smoke tests in `tests/test_browser.py`, marked
 `smoke` and run by `just test-smoke`, not `just test`; still check a page change in a browser against a report from
-the CLI tests. Tests
+the CLI tests, or against `just demo-serve`. `demo/` holds the made-up scenario behind the published demo page: the
+CLI collects it against respx routes, and `.github/workflows/demo.yml` publishes it to GitHub Pages on each release
+tag. A page change that adds a state belongs in the scenario too. Tests
 mock GitLab and Jira only with respx routes (pytest-httpx2): the `gitlab` and `jira` fixtures in `tests/conftest.py`
 declare one named static route per call of the scenario in `tests/payloads.py`. A test changes a response by re-mocking a named route; add no fakes, callbacks,
 or stubs.

README.md

@@ -32,6 +32,9 @@ issue's Web links whenever a commit or MR mentions it; a link counts only if it
 the Jira keys of every row its links point to, so a key that only a commit message inside a merge request names
 still counts for that row and for the tags that ship it.
 
+The [demo page](https://modern-python.github.io/release-scope/) is that site for a made-up shop with four
+services and six Jira issues. Choose an issue to see which tags it needs. Its GitLab and Jira links lead nowhere.
+
 ## Quickstart
 
 ```sh

demo/build.py

@@ -0,0 +1,42 @@
+import datetime as dt
+import json
+import os
+import pathlib
+import sys
+import typing
+from unittest import mock
+
+import pytest_httpx2  # noqa: F401  registers the httpcore2 mocker with respx
+import respx
+from typer.testing import CliRunner
+
+from demo import scenario
+from release_scope import ioc
+from release_scope.__main__ import MAIN_APP
+
+
+_ENV: typing.Final = {
+    "GITLAB_TOKEN": "demo",
+    "RELEASE_SCOPE_GITLAB__ENDPOINT": scenario.ENDPOINT,
+    "RELEASE_SCOPE_ENVIRONMENTS": json.dumps(scenario.ENVIRONMENTS),
+    "RELEASE_SCOPE_JIRA_ENDPOINT": scenario.JIRA_ENDPOINT,
+    "JIRA_TOKEN": "demo",
+}
+
+
+def build(output: pathlib.Path) -> None:
+    now: typing.Final = dt.datetime.now(dt.UTC).replace(minute=0, second=0, microsecond=0)
+    with (
+        mock.patch.dict(os.environ, _ENV),
+        respx.mock(using="httpcore2", assert_all_called=False) as router,
+        ioc.container,
+    ):
+        scenario.mock(router, now)
+        result: typing.Final = CliRunner().invoke(MAIN_APP, ["collect", "-g", scenario.GROUP, "-o", str(output)])
+    if result.exit_code != 0:
+        msg = f"collect exited with {result.exit_code}:\n{result.output}"
+        raise RuntimeError(msg)
+
+
+if __name__ == "__main__":
+    build(pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else "site"))