From a6f1106ff4dc22d8e9795a8a0ea0c62331ed2ed3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Simon=20B=C3=A4rlocher?= <s.baerlocher@sbaerlocher.ch>
Date: Thu, 18 Jun 2026 20:10:07 +0200
Subject: [PATCH] docs(workflows): document ci-ansible-molecule.yml in the
 workflow reference

The molecule reusable was listed in the AGENTS.md CI table but had no
entry in workflows/README.md. Add usage, inputs, jobs and the
driver: docker|qemu selector.
---
 .github/workflows/README.md | 42 +++++++++++++++++++++++++++++++++++++
 CHANGELOG.md                |  8 +++++++
 2 files changed, 50 insertions(+)

diff --git a/.github/workflows/README.md b/.github/workflows/README.md
index 98e2287..3c87bd8 100644
--- a/.github/workflows/README.md
+++ b/.github/workflows/README.md
@@ -72,6 +72,48 @@ jobs:
 
 ---
 
+#### `ci-ansible-molecule.yml`
+
+Runs Molecule scenarios for a collection's roles. The `driver` input selects the
+backend: `docker` (default, fast containers) or `qemu` (full VMs via
+`molecule-qemu`, for roles that need a real kernel and init system — k3s,
+container engines, agents that must run as a stable `systemd` service). The
+`qemu` driver works on the standard `ubuntu-latest` runner (it exposes
+`/dev/kvm`); a larger/paid runner is not required.
+
+**Usage:**
+
+```yaml
+jobs:
+  molecule:
+    uses: arillso/.github/.github/workflows/ci-ansible-molecule.yml@main
+    with:
+      collection_name: container
+      driver: qemu
+      scenarios_root: roles/k3s/molecule
+      scenarios: '["default"]'
+      concurrency-suffix: molecule-k3s
+```
+
+**Inputs:**
+
+- `collection_namespace` (optional): Collection namespace (default: `arillso`)
+- `collection_name` (required): Collection name
+- `driver` (optional): `docker` (default) or `qemu`
+- `python_version` (optional): Python version (default: `3.12`)
+- `scenarios` (optional): JSON array of scenario names; auto-discovered from `scenarios_root` when empty
+- `scenarios_root` (optional): Path to the scenarios directory (default: `extensions/molecule`)
+- `runs_on` (optional): Runner label (default: `ubuntu-latest`)
+- `cancel-in-progress` (optional): Cancel in-progress runs in the same group (default: `true`)
+- `concurrency-suffix` (optional): Suffix appended to the concurrency group; set per role to run several scenarios in parallel from one caller
+
+**Jobs:**
+
+- discover (build the scenario matrix)
+- molecule (one matrix leg per scenario; installs QEMU/KVM when `driver: qemu`)
+
+---
+
 ### Go & Actions
 
 #### `ci-go-action.yml`
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0090952..e4ec99f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,14 @@ This is a rolling release - changes are deployed continuously to `main`.
 
 ---
 
+## 2026-06-18
+
+### Added
+
+- **workflows/README.md**: Document `ci-ansible-molecule.yml` (usage, inputs,
+  jobs, the `driver: docker|qemu` selector) — it was listed in the AGENTS.md
+  CI table but missing from the workflow reference.
+
 ## 2026-06-17
 
 ### Added