docs: say what a version mark is for, then how it works

[timzifer]

The README led with machinery — entropy streams, the perceptual hash, the threshold suite. That is why the library can be trusted, but it is not why anyone would reach for it, and a reader had to get through three sections to find out whether it solves a problem they have had.

README (286 → 100 lines)

Opens on the problem instead. 1.4.12 and 1.4.2 differ by one character in the middle of a string; a mark either looks the same or it does not. Four uses follow from that:

• the odd row in a release table, deploy dashboard or artifact list stops hiding among digits;
• a version shown where no version is shown — a favicon, a corner glyph, a splash screen — so a screenshot in a bug report names its own build;
• artifact, health page and release notes either match or they do not;
• a release people remember as a picture.

Then the two enforced properties in a line each (neighbours never confusable; family resemblance is a setting, not an accident of a hash), the three ways to use it, and a link list.

Moved to docs/

File	Content
docs/how-it-works.md	the three stages, the policy table, the distinctness suite, the output back ends, the no-dependencies rationale
docs/renderers.md	the renderer table — plus a new column saying which renderers can be read back — and the gallery
docs/service.md	the endpoint, its parameters, the per-format size ceilings and the rate limit

Gallery plumbing

The gallery markers moved with the renderer table, so -readme now points at docs/renderers.md in the workflow, the PR template and CONTRIBUTING.md. The generator writes image links relative to the file it rewrites, so the paths came out as gallery/*.png without a code change.

Regenerated twice: no image diff, second run is a no-op. go test ./cmd/blazon passes. CONTRIBUTING.md gains a step for the new table row.

🤖 Generated with Claude Code

https://claude.ai/code/session_019RJ8FUiT1YvbBz3D2PriM9