brrag 0.0.2__tar.gz

brrag-0.0.2/.github/workflows/check.yml

@@ -0,0 +1,65 @@
+name: check
+
+# Proves three things on every push:
+#   1. the committed data/mldr_road.json really is what the published calculator
+#      page says (re-extracted and diffed);
+#   2. the published artefacts have not changed (SHA-256);
+#   3. the implementation still reproduces the calculator and the workbooks.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # monthly: tells us when the upstream tables or calculator change
+    - cron: "0 6 1 * *"
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install tool dependencies
+        run: |
+          python -m pip install --quiet --upgrade pip
+          python -m pip install --quiet -r requirements-tools.txt
+
+      - name: Fetch sources (calculator page, workbook, upstream tables repo)
+        run: make fetch
+
+      - name: Re-extract the factor tables and require a clean diff
+        run: |
+          make data
+          if ! git diff --exit-code -- data/mldr_road.json; then
+            echo "::error file=data/mldr_road.json::Published tables changed since data/ was extracted"
+            exit 1
+          fi
+
+      - name: Validate (exact grid, JS oracle, standards cross-check)
+        run: make verify
+
+      - name: Reproduce the fitted curves from their parameters
+        run: make curve
+
+      - name: Check documentation links
+        run: make check-links
+
+      # The Excel add-in's portable core: table lookup, vector handling, both
+      # ad hoc table layouts, caching. Building the .xll itself needs mingw-w64
+      # and the mingw-patched xll library, so that stays a local step.
+      - name: Excel add-in — generated files up to date
+        run: |
+          python3 xll/tools/gen_tables.py --check
+          python3 xll/tools/gen_expectations.py --check
+
+      - name: Excel add-in — core test suite
+        run: make xll-test
+
+      - name: Excel add-in — sample workbook up to date
+        run: python3 xll/examples/build_sample_workbook.py --check

brrag-0.0.2/.github/workflows/release.yml

@@ -0,0 +1,223 @@
+name: release
+
+# A tag starting with v is the whole release procedure. The version is not in
+# any file: setuptools-scm derives it from the tag, so `git tag v0.0.2` publishes
+# 0.0.2 and an untagged commit cannot ship by accident.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      note:
+        description: "Optional note. A dispatch builds and tests but publishes nothing (no tag)."
+        required: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build and test the distribution
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm needs the tags, so a shallow clone is not enough.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: The version must be the tag
+        id: version
+        run: |
+          set -euo pipefail
+          built=$(ls dist/*.whl | sed -E 's|^dist/brrag-([^-]+)-.*$|\1|')
+          echo "built $built"
+          echo "version=$built" >> "$GITHUB_OUTPUT"
+          if [ "${GITHUB_REF_TYPE}" = "tag" ]; then
+            tag="${GITHUB_REF_NAME#v}"
+            if [ "$built" != "$tag" ]; then
+              echo "::error::tag is $GITHUB_REF_NAME but the build is $built - bump or move the tag"
+              exit 1
+            fi
+          else
+            echo "::notice::not a tag, so nothing will be published (version $built)"
+          fi
+
+      - name: The wheel must carry its own tables
+        run: |
+          set -euo pipefail
+          python -m venv /tmp/wheeltest
+          /tmp/wheeltest/bin/pip install --quiet --disable-pip-version-check dist/*.whl
+          # Run from outside the checkout: brrag must not fall back to ../data.
+          cd /tmp
+          /tmp/wheeltest/bin/python "$GITHUB_WORKSPACE/tools/wheel_smoke.py" "${{ steps.version.outputs.version }}"
+
+      - name: Install the mingw cross-compiler
+        run: |
+          set -euo pipefail
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq --no-install-recommends g++-mingw-w64-x86-64
+
+      - name: Check out the xll framework this build is pinned to
+        run: |
+          set -euo pipefail
+          # Pinned to the commit xll/patches/xll-mingw-portability.patch applies to:
+          # a moving upstream would silently change the .xll we ship.
+          XLL_DIR="$HOME/code/xll"
+          mkdir -p "$XLL_DIR"
+          git -C "$XLL_DIR" init -q
+          git -C "$XLL_DIR" remote add origin https://github.com/xlladdins/xll
+          git -C "$XLL_DIR" fetch -q --depth 1 origin 481178bced1022f0b36b582388b79a6eabe1a11f
+          git -C "$XLL_DIR" checkout -q FETCH_HEAD
+          git -C "$XLL_DIR" rev-parse --short HEAD
+          ./xll/tools/apply-xll-patches.sh
+
+      - name: Build the add-in and audit its exports
+        run: |
+          set -euo pipefail
+          make -C xll shim
+          make -C xll xll verify
+          # The link is timestamp-free, so with THIS compiler the binary is
+          # reproducible byte for byte. Record the version, because a different
+          # mingw produces a different binary from identical sources.
+          x86_64-w64-mingw32-g++ --version | head -1
+          sha256sum xll/road_running_age_grading.xll
+          x86_64-w64-mingw32-objdump -f xll/road_running_age_grading.xll | head -3
+          strings xll/road_running_age_grading.xll | grep -c '^RRAG\.' | xargs -I{} test {} -eq 12
+
+      - name: Package the Excel bundle
+        run: |
+          set -euo pipefail
+          python -m pip install --quiet "openpyxl>=3.1"
+          # --check rebuilds it and fails if the committed copy is stale, so the
+          # asset is known to match this commit rather than merely to exist.
+          python xll/examples/build_sample_workbook.py --check
+          version="${{ steps.version.outputs.version }}"
+          mkdir -p assets
+          python - "$version" <<'PY'
+          import sys, zipfile
+          version = sys.argv[1]
+          target = f"assets/brrag-{version}-excel.zip"
+          with zipfile.ZipFile(target, "w", zipfile.ZIP_DEFLATED, compresslevel=9) as z:
+              z.write("xll/road_running_age_grading.xll", "road_running_age_grading.xll")
+              z.write("xll/examples/age-grading-sample.xlsx", "age-grading-sample.xlsx")
+          with zipfile.ZipFile(target) as z:
+              names = z.namelist()
+              for i in z.infolist():
+                  print(f"  {i.filename:32} {i.file_size:>9,} -> {i.compress_size:>8,}")
+          assert names == ["road_running_age_grading.xll", "age-grading-sample.xlsx"], names
+          PY
+          ls -l dist/ assets/
+
+      # Two artifacts on purpose: `dist` is exactly what twine may upload, and
+      # gh-action-pypi-publish rejects anything else in it (a stray .zip is read
+      # as an sdist: "Too many top-level members in sdist archive").
+      - name: Upload the distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+      - name: Upload the Excel bundle
+        uses: actions/upload-artifact@v4
+        with:
+          name: assets
+          path: assets/
+          if-no-files-found: error
+
+  github-release:
+    name: publish the GitHub release
+    needs: build
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: assets
+          path: assets
+
+      - name: Checksums
+        run: |
+          set -euo pipefail
+          # Named explicitly: `sha256sum *` would include the file being written.
+          sha256sum dist/* assets/* > SHA256SUMS
+          cat SHA256SUMS
+
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            echo "::error::a release for $GITHUB_REF_NAME already exists - bump the version instead of reusing a tag"
+            exit 1
+          fi
+          gh release create "$GITHUB_REF_NAME" dist/* assets/* SHA256SUMS \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes \
+            --verify-tag
+          gh release view "$GITHUB_REF_NAME" --json url,assets \
+            --jq '.url, (.assets[] | "  " + .name + " " + (.size|tostring) + " B")'
+
+  pypi:
+    name: publish to PyPI
+    needs: build
+    # Trusted publishing: no token, no secret - PyPI verifies this workflow's
+    # OIDC identity instead. Set the repository variable PYPI_ENABLED=true once
+    # the pending publisher exists on pypi.org; see docs/11-releasing.md.
+    if: github.ref_type == 'tag' && vars.PYPI_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/brrag
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Prove it landed
+        run: |
+          set -euo pipefail
+          version="${{ needs.build.outputs.version }}"
+          for _ in $(seq 1 12); do
+            if curl -fsS "https://pypi.org/pypi/brrag/${version}/json" >/dev/null; then
+              echo "brrag ${version} is on PyPI"
+              curl -fsS "https://pypi.org/pypi/brrag/${version}/json" \
+                | python -c 'import json,sys; d=json.load(sys.stdin); print("\n".join("  "+u["filename"] for u in d["urls"]))'
+              exit 0
+            fi
+            sleep 5
+          done
+          echo "::error::PyPI does not list brrag ${version} yet"
+          exit 1

brrag-0.0.2/.gitignore

@@ -0,0 +1,33 @@
+# virtualenvs and caches
+.venv/
+__pycache__/
+*.pyc
+
+# unzipped copies of source artefacts (regenerate with `make unpack`)
+raw/
+
+# generated documentation HTML (regenerate with `make wiki`)
+wiki/
+
+# upstream clone for the standards cross-check (regenerate with `make fetch`)
+repo/
+
+# extracted text of upstream PDFs
+notes/
+
+# editable-install metadata
+*.egg-info/
+
+# build outputs (`make dist`); releases carry them, git does not
+dist/
+build/
+
+# --- Excel add-in build artefacts (xll/) -----------------------------------
+xll/*.o
+xll/*.xll
+xll/road_running_age_grading_test
+xll_test_tmp/
+# case-fixing header symlinks, created by `make -C xll shim`
+xll/shim/
+# The generated sources ARE committed on purpose (a Windows/MSVC user must not
+# need Python): xll/src/ag_tables_generated.h and xll/test/expected.h.

brrag-0.0.2/LICENSE

@@ -0,0 +1,43 @@
+MIT License
+
+Copyright (c) 2026 Francois Botha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+SCOPE
+
+This licence covers the code in this repository: the `brrag/` package, the
+`tools/` scripts and the prose in `docs/` and `README.md`.
+
+It does NOT cover the age-grading tables or the source artefacts. Those are the
+work of others:
+
+  * age-grade factors and age standards — compiled by Alan Jones
+    (alanjones@grests.com) with single-age bests by Tom Bernhard, approved by
+    the Masters Long Distance Running Council of USA Track & Field.
+    Upstream: https://github.com/AlanLyttonJones/Age-Grade-Tables
+  * the calculator page (`page.html`) and the factors workbook
+    (`MLDRRoadFactors2025.xlsm`) — Howard Grubb,
+    https://www.howardgrubb.co.uk/athletics/
+
+They are included here unmodified, for reference and reproducibility, with
+SHA-256 hashes recorded in `data/source_sha256.txt`. Cite the upstream sources,
+not this repository, when publishing graded results.

brrag-0.0.2/Makefile

@@ -0,0 +1,89 @@
+# Age-grading docs + reference implementation.
+# `make check` is what CI (or a future table revision) should run.
+
+PY ?= $(shell [ -x .venv/bin/python ] && echo .venv/bin/python || echo python3)
+UPSTREAM := https://github.com/AlanLyttonJones/Age-Grade-Tables.git
+
+.PHONY: help all setup fetch unpack data pkgdata dist verify curve wiki check check-links xll-test sample clean
+
+help:
+	@echo "setup    create .venv and install tool dependencies"
+	@echo "fetch    download the source artefacts (calculator page, xlsm, upstream clone)"
+	@echo "unpack   unzip the xlsm (sheet XML + vbaProject.bin) into raw/"
+	@echo "data     re-extract factor tables from page.html -> data/mldr_road.json"
+	@echo "pkgdata  copy data/mldr_road.json into the package, so a wheel ships its tables"
+	@echo "dist     build the sdist and wheel into dist/"
+	@echo "verify   run checks A/B/C (exact grid, JS oracle, standards cross-check)"
+	@echo "curve    reproduce factor curves from the fitted parameters"
+	@echo "wiki     render docs/*.md -> wiki/*.html"
+	@echo "check    verify + curve + wiki link check   <-- the CI target"
+	@echo "check-links  verify every docs/ cross-page link and anchor"
+	@echo "xll-test verify the Excel add-in core (needs g++ only)"
+	@echo "sample   regenerate the sample workbook (needs openpyxl)"
+	@echo "all      fetch + unpack + data + verify + curve + wiki"
+
+all: fetch unpack data verify curve wiki
+	@echo OK
+
+setup:
+	uv venv --python 3.12 .venv
+	uv pip install --python .venv/bin/python -r requirements-tools.txt
+
+fetch:
+	@echo "-> calculator page"
+	curl -sS -o page.html https://www.howardgrubb.co.uk/athletics/mldrroad25.html
+	@echo "-> factors workbook"
+	curl -sS -o MLDRRoadFactors2025.xlsm https://www.howardgrubb.co.uk/athletics/data/MLDRRoadFactors2025.xlsm
+	@echo "-> upstream tables repository (needed by check C)"
+	test -d repo || git clone --depth 1 $(UPSTREAM) repo
+	@echo "-> verifying hashes"; sha256sum -c data/source_sha256.txt
+
+unpack:
+	rm -rf raw && mkdir -p raw && cd raw && unzip -o ../MLDRRoadFactors2025.xlsm >/dev/null
+	@echo "raw/ holds the sheet XML and xl/vbaProject.bin; dump the macros with:"
+	@echo "  .venv/bin/olevba raw/xl/vbaProject.bin"
+
+data:
+	$(PY) tools/extract_tables.py page.html data/mldr_road.json
+	$(PY) tools/sync_package_data.py
+
+pkgdata:
+	$(PY) tools/sync_package_data.py
+
+# setuptools-scm takes the version from the git tag, so this is only meaningful
+# (and only publishable) on a tagged commit.
+dist:
+	$(PY) -m build
+
+verify:
+	$(PY) tools/verify.py --all
+
+curve:
+	$(PY) tools/reproduce_curve.py
+
+wiki:
+	$(PY) tools/render_wiki.py
+
+check-links:
+	$(PY) tools/render_wiki.py --check
+
+# The add-in's portable core and test suite. Building the .xll itself needs
+# mingw-w64 and the patched xll library; see xll/README.md.
+xll-test:
+	$(MAKE) -C xll test
+
+sample:
+	$(PY) xll/examples/build_sample_workbook.py
+
+check:
+	$(PY) tools/sync_package_data.py --check && \
+	$(PY) tools/verify.py --all && \
+	$(PY) tools/reproduce_curve.py && \
+	$(PY) tools/render_wiki.py --check && \
+	$(PY) xll/tools/gen_tables.py --check && \
+	$(PY) xll/tools/gen_expectations.py --check && \
+	$(MAKE) -C xll test && \
+	$(PY) xll/examples/build_sample_workbook.py --check
+
+clean:
+	rm -rf wiki raw

brrag-0.0.2/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: brrag
+Version: 0.0.2
+Summary: BRRAG - Botha's Road Running Age Grading on the USATF MLDR 2025 tables
+Author-email: Francois Botha <igitur@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/igitur/road-running-age-grading
+Project-URL: Documentation, https://github.com/igitur/road-running-age-grading/blob/main/docs/index.md
+Project-URL: Source, https://github.com/igitur/road-running-age-grading
+Project-URL: Changelog, https://github.com/igitur/road-running-age-grading/releases
+Project-URL: Published calculator, https://www.howardgrubb.co.uk/athletics/mldrroad25.html
+Keywords: running,age-grading,usatf,mldr,road-running,athletics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# BRRAG — Botha's Road Running Age Grading
+
+Age grading on the USATF MLDR 2025 road tables. The Python package, the
+CLI and the PyPI distribution are called `brrag`; the repository keeps its
+name and URL.
+
+[![check](https://github.com/igitur/road-running-age-grading/actions/workflows/check.yml/badge.svg)](https://github.com/igitur/road-running-age-grading/actions/workflows/check.yml)
+
+Reference documentation and a verified implementation of **road-running age
+grading** on the USATF Masters Long Distance Running (MLDR) 2025 tables.
+
+You give it a sex, an age, a distance and a time. It tells you the **age-graded
+time** and the **age grade percentage** — one number that lets a 12-year-old's
+5 km and a 72-year-old's marathon be compared on the same scale.
+
+```console
+$ brrag 40:00 --age 40 --sex M --distance 10k
+factor             0.9636
+age-graded        38:32.6
+age grade           68.49%
+
+$ brrag 32:00 --age 65 --sex M --distance 10k
+factor             0.7761
+age-graded        24:50.1
+age grade          106.30%      # above 100% = better than the age standard
+```
+
+## Install
+
+```console
+$ pip install brrag
+$ brrag 40:00 --age 40 --sex M --distance 10k
+```
+
+Stdlib-only, no dependencies, and the wheel carries its own tables so it works
+offline. Versions come from the git tag; see
+[docs/11-releasing.md](docs/11-releasing.md).
+
+## Where to start
+
+| If you want to… | Read |
+| --- | --- |
+| Understand the idea and the numbers | [docs/01-concepts.md](docs/01-concepts.md) |
+| See what the 2025 tables contain | [docs/02-tables-2025.md](docs/02-tables-2025.md) |
+| **Grade a time (the algorithm)** | [docs/03-algorithm.md](docs/03-algorithm.md) |
+| Know how the tables were built | [docs/04-methodology.md](docs/04-methodology.md) |
+| Trust or audit the data | [docs/05-provenance.md](docs/05-provenance.md) |
+| Handle weird inputs | [docs/06-edge-cases.md](docs/06-edge-cases.md) |
+| Write your own implementation | [docs/07-implementation.md](docs/07-implementation.md) |
+| Check our claims | [docs/08-validation.md](docs/08-validation.md) |
+| Know the revision history / what 2026 needs | [docs/09-history.md](docs/09-history.md) |
+| **Grade a whole club in Excel** | [docs/10-excel-addin.md](docs/10-excel-addin.md) |
+| Release or publish a version | [docs/11-releasing.md](docs/11-releasing.md) |
+
+Full index: [docs/index.md](docs/index.md).
+
+## Quick use (Python)
+
+```python
+from brrag import table, format_time
+
+t = table(2025, "M")                       # or table(2025, "F")
+g = t.grade("M", 40, 40 * 60, dist_km=10)  # 40:00 for 10 km at age 40
+print(g.factor, g.percent)                 # 0.9636  68.49
+print(format_time(g.age_graded_s))         # 38:32.6
+```
+
+No dependencies outside the standard library for the library itself
+(`openpyxl` is only needed by the table-extraction and verification tools).
+
+## In Excel
+
+`xll/road_running_age_grading.xll` is a native add-in for grading a whole squad at once:
+
+```excel
+=RRAG.GRADE(B2:B181, C2:C181, D2:D181, E2:E181)     180 age grades, spilled
+=RRAG.BLOCK(B2:B181, C2:C181, D2:D181, E2:E181)     factor, standards, graded time, percent
+```
+
+Four editions are compiled in (2025/2020/2015/2010), the fifth argument selects
+one or names a custom `<name>.csv` table, and a range passed there is used as an
+ad-hoc table. Build and install: [xll/README.md](xll/README.md); design notes:
+[docs/10-excel-addin.md](docs/10-excel-addin.md).
+
+## Getting started
+
+```console
+$ git clone https://github.com/igitur/road-running-age-grading.git
+$ cd road-running-age-grading
+$ make setup          # .venv + openpyxl/oletools/pypdf
+$ make check          # the full validation suite
+```
+
+The repo ships `data/mldr_road.json`, so the library and CLI work immediately
+with nothing but Python 3.10+. `make fetch` downloads the two source artefacts
+and clones the upstream tables repository when you want checks B and C to run
+(after a fresh clone they are already present, since the artefacts are committed).
+
+## Layout
+
+```
+data/mldr_road.json        2025 (+2020/2015/2010) factors, extracted and hashed
+data/source_sha256.txt     hashes of every source artefact we read
+brrag/                   reference implementation (core.py, ui.py, cli.py)
+tools/extract_tables.py    pull factor tables out of the calculator page -> JSON
+tools/js_oracle.js         run the *published calculator's own JS* under Node
+tools/verify.py            three-way validation harness (A/B/C)
+tools/reproduce_curve.py   rebuild each factor curve from its 10 fitted parameters
+tools/render_wiki.py       docs/*.md -> wiki/*.html (no JS, no CDN)
+xll/                       native Excel add-in: columns in, age grades out
+docs/                      the documentation set (Markdown; source of truth)
+page.html                  archived copy of the calculator page we read
+MLDRRoadFactors2025.xlsm   archived copy of the official factors workbook (VBA)
+```
+
+Generated or fetched, not committed: `wiki/` (`make wiki`), `raw/` (`make unpack`),
+`repo/` and `notes/` (`make fetch` + `pypdf`).
+
+`make help` lists the tasks; `make all` re-downloads the sources, re-extracts the
+data, validates it, reproduces the curves and re-renders the wiki.
+
+## Verify it
+
+```console
+$ make check
+A. exact-event grid: 4224 lookups, 0 mismatches
+B. JS oracle: 1412 requests, 0 mismatches, worst percent delta 0.000000 pp
+C. standards file: 4224 cells, 0 mismatches, 18 known anomalies
+RESULT: PASS
+worst absolute error across the curves that match exactly: 0.0001
+links: 0 problem(s)
+```
+
+Details and what each check catches: [docs/08-validation.md](docs/08-validation.md).
+
+## Reading it as a wiki
+
+The Markdown in `docs/` is the source of truth — it versions with the data, diffs
+cleanly, and renders on GitHub. If you would rather click through it, render the
+HTML copy and serve it:
+
+```console
+$ .venv/bin/python tools/render_wiki.py      # writes wiki/*.html
+```
+
+Twelve self-contained pages, a sticky sidebar, no JavaScript, no CDN, no build
+step beyond that one command — which is why it drops straight into the existing
+Caddy static-site setup if you want it online.
+
+## Status of the tables
+
+The 2025 road tables were approved by the USATF MLDR Council on **2025-01-10**;
+the published workbooks are dated **2025-07-27**. The tables are re-fitted
+roughly every five years (2010 → 2015 → 2020 → 2025), so treat 2025 as current
+and expect a 2030 revision. Everything in this repo is pinned to the published
+2025 artefacts by SHA-256 — see [docs/05-provenance.md](docs/05-provenance.md).
+
+One caveat worth knowing up front: the *working* spreadsheets shipped in the
+upstream repo (`maleRoad2025.xlsx`, dated 2025-07-25) do **not** reproduce the
+published male 5 km / 10 km curves. The published factor workbook, the
+calculator and the `…Std2025.xlsx` standards files all agree with each other;
+the male working file is one revision behind. [docs/05-provenance.md](docs/05-provenance.md)
+has the numbers.
+
+## Licence / attribution
+
+Tables compiled by **Alan Jones** (alanjones@grests.com) with single-age bests
+by **Tom Bernhard**; approved by the USATF MLDR Council. Calculator by
+**Howard Grubb** (howardgrubb.co.uk). Upstream repository:
+<https://github.com/AlanLyttonJones/Age-Grade-Tables>. Cite the upstream tables,
+not this repo, when publishing results.