Surface the playground, install from PyPI, give the page a social card

[ChelseaKR]

Three discoverability defects. All the same shape: the thing a visitor needs is real, works, and is not where they will look for it.

1. The playground is now in the lede

chelseakr.github.io/ctdl-validate runs the validator in the browser via WebAssembly. That is the strongest thing this repository has to offer someone who has not decided to install anything yet — a validator that runs on their own machine, on a payload they have not published — and it first appeared at line 42 of a 646-line README, below eight paragraphs of prose.

It is now in the first fifteen lines, one sentence, with the reason it matters (the payload stays in the tab). The fuller explanation stays where it was.

2. The documented install is the published package

The README said pip install ., which requires a clone and is not how anyone installs this. ctdl-validate has been on PyPI since 2026-08-13; verified live before changing it.

The user-facing command is now pip install ctdl-validate. The working-tree install is kept directly below it, named as what it is (what you want when main is ahead of the last tag) and pointed at CONTRIBUTING.md.

3. The playground has a card

The head declared og:title, og:description and twitter:card=summary, and no image — so every share of the playground rendered as a line of text. It now carries a 1200×630 card in the page's own dark palette (#111827 ground, the four severity colours as a rule), served from the same origin as the page.

The card says the title and the description already in the head and nothing more: no rule count, no conformance level, nothing about Credential Engine. web/a11y/audit.mjs already fails the build on any of those in the description, and it now holds the card to the same line.

twitter:card moves from summary to summary_large_image, which is what 1200×630 is for; declaring summary crops it to a square thumbnail.

The card is gated, not trusted

An og:image naming a file nothing publishes is a blank rectangle everywhere the page is shared, and nothing about the page itself looks wrong — which is the defect class this repository exists to catch. So it is checked three ways:

• .github/workflows/pages.yml copies social-card.png into the Pages artifact and fails if the head names a file the artifact does not carry.
• web/a11y/audit.mjs reads og:image, twitter:image, og:image:alt and the declared dimensions out of a real browser, alongside the head checks already there.
• tests/test_playground_catalogue.py checks, inside make verify and with no runner needed, that the address, the dimensions — read out of the PNG's own IHDR chunk, so no image library is added — and the alt text agree with the file on disk.

Verification

make verify passes: 354 tests (351 before, +3 new), coverage 95.59%, pip-audit clean. Baseline on main was green before these edits, so nothing here is inherited.

Both URLs were confirmed 200 and the PyPI package confirmed live before any edit.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pvm6FCdDXwtzA3juGxz6ba