From 6b40338d962c31bd12d14385eff9bc4db6008b57 Mon Sep 17 00:00:00 2001
From: Redzwan Mutalib <254799830+redzwanmutalib@users.noreply.github.com>
Date: Wed, 12 Aug 2026 20:56:28 +0100
Subject: [PATCH] docs: document CI parity checks in the README

---
 README.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/README.md b/README.md
index 36a2235b..001bdf6b 100644
--- a/README.md
+++ b/README.md
@@ -840,6 +840,28 @@ uv run pytest tests/test_extract.py -q # one module
 uv run pytest tests/ -q -k "python"    # filter by name
 ```
 
+### CI parity checks
+
+The authoritative CI commands live in [`.github/workflows/`](.github/workflows/).
+For local CI-style verification, use Python 3.10 or 3.12 and run:
+
+```bash
+uv sync --all-extras --frozen
+uv run --frozen pytest tests/ -q --tb=short
+uv run --frozen python -m tools.skillgen --check
+uv run --frozen python -m tools.skillgen --audit-coverage
+uv run --frozen python -m tools.skillgen --schema-singleton
+uv run --frozen python -m tools.skillgen --monolith-roundtrip
+uv run --frozen python -m tools.skillgen --always-on-roundtrip
+uv run --frozen graphify --help
+uv run --frozen graphify install
+```
+
+Ruff is useful as an additional local check (`uv run --frozen ruff check .`),
+but is not currently a blocking CI job. Pyright is also local/advisory unless it
+is added to CI later. The Bandit and pip-audit CI steps currently use
+`continue-on-error`, so their findings are advisory rather than blocking.
+
 > macOS note: the test suite includes both `sample.f90` and `sample.F90` fixtures. These collide on case-insensitive HFS+ / APFS file systems. Run on Linux or in a Docker container if you need to test both Fortran variants simultaneously.
 
 ### Git workflow