docs(readme): restore the badge set, add a banner, and bring back the two lost sections

[lusoris]

Summary

The rc1 documentation pass (3cd0f0a, 2026-09-08) cut the README from 22 badges to four and dropped two sections with it. What was left gave no signal for the Lint, Security, FFmpeg, Go and Rust lanes, named no toolchain or platform version, showed no OpenSSF Scorecard, and carried a github/v/release badge that renders empty — the repository has tags but no GitHub releases.

This restores the set, in the house style of the other CordanaLLM repositories: a banner, a centred header, and badges grouped CI → quality → languages → platforms → project.

Every badge was verified before it landed

No badge here is written from memory.

Check	Result
Workflow files behind the seven CI badges	all seven exist on master
All 25 badge image URLs	HTTP 200
Every local link in the file	resolves (four backend links corrected to their real overview.md / index.md paths)
OpenSSF Scorecard	live, 8.6, dated today

Versions come from the tree, not from recollection: Go 1.27 (go.mod), Rust edition 2024 (bindings/rust/vmafx-sys/Cargo.toml), Python 3.14 (pyproject.toml), C23 and C++23 (the meson standards), CUDA 13.3.1 / ROCm 10.0.0 / FFmpeg n9.0.1 (build-config.env), SVE2 confirmed present (15 files). The Release badge becomes a tag badge, so it shows v3.0.0 instead of nothing.

Sections

Why VMAFx and Backends at a glance come back as tables — what the fork adds over upstream, and which backend each flag selects — and the quickstart gains the raw-YUV and GPU-backend invocations. The licence and governance sections are carried over verbatim.

docs/assets/vmafx-readme-banner.svg is new: hand-written SVG (no binary asset), the two converging traces being the reference-versus-distorted comparison the tool exists to measure.

Verification

Check	Result
mkdocs build --strict	exit 0
markdownlint	passes
praetorctl audit	passes, baseline 1411 → 1411

The five markdownlint rules a centred header needs (MD013 MD023 MD033 MD036 MD041) are disabled at the top of the file with a comment saying why — the same directive style docs/adr/0000-template.md already uses. Prose still wraps at 80.

Type

• docs — documentation

Checklist

• Commits follow Conventional Commits.
• Pre-push hooks pass.
• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.
• docs/state.md: no state delta: documentation only; no bug in the tracked set opens or closes.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: trivial. The verification is the table above.
• Decision matrix — no alternatives: only-one-way fix. Badges either point at something that resolves or they do not.
• AGENTS.md invariant note — no rebase-sensitive invariants: the README and its SVG asset.
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/added/readme-badges-and-banner.md.
• Rebase note — no rebase impact: fork-local files an upstream sync never touches.

Reproducer

# every badge URL resolves
grep -oE '!\[[^]]*\]\((https://[^)]+)\)' README.md | sed -E 's/.*\((https[^)]+)\)/\1/' |
  sort -u | while read -r u; do printf '%s %s\n' "$(curl -sS -o /dev/null -w '%{http_code}' -L "$u")" "$u"; done

# every local link resolves
grep -oE '\]\(([a-zA-Z0-9][^):]*\.(md|txt|toml|mod|env|svg))\)' README.md |
  sed -E 's/^\]\(//; s/\)$//' | sort -u | while read -r f; do [ -e "$f" ] || echo "MISSING $f"; done

mkdocs build --strict

[Copilot]

Copilot review overview

🟡 Changes recommended

The changelog is out of sync, and README claims and examples require correction.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 2

Open (3)

• Remove manual changelog entry and regenerate from fragment · New
• Replace bit-exact claim with feature-specific parity tolerance · New
• Qualify backend coverage claim for GPU-supported extractors · New

What changed in this PR

Restores the README’s badges, banner, and documentation sections while updating changelog metadata and the standards-gate pin.

Changes:

• Restores badges, banner, backend overview, and quickstart examples.
• Adds the changelog fragment and rendered entry.
• Updates the Praetor pin and audit baseline timestamp.

Review findings:

• CHANGELOG.md — critical (2 votes): regenerate the Unreleased block from the fragment.
• README.md — moderate (3 votes): qualify backend coverage.
• README.md — moderate (2 votes): correct the bit-exactness claim.
• README.md — nit (1 vote): correct the upstream/fork comparison.
• README.md — nit (1 vote): use an explicit GPU extractor or model example.

File	Description
README.md	Restored badges, banner, documentation sections, and examples
docs/​assets/​vmafx-readme-banner.svg	Added README banner artwork
CHANGELOG.md	Added rendered changelog entry
changelog.d/​added/​readme-badges-and-banner.md	Added changelog fragment
.standards-baseline.json	Refreshed audit timestamp
.github/​workflows/​standards-gate.yml	Updated Praetor engine pin

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.