Write down the fragment contract

[ctgnz]

Closes #99.

#71, #78, #79 and #80 settled how the fragments are structured, and two of those rules now fail the build. None of it was written anywhere a person would look.

docs/fragments.md

The contract in one repo-level copy — it applies to every icon library, so it does not belong inside one library's resources:

• the shared canvas and the bounding octagon, and why that is a rule rather than a measurement;
• the content root each family uses, in a table;
• the free canvas template/example shape, and why the template is optional (areas have at least three user-placed control points, so there is no fixed geometry to draw; Space Debris are whole symbols);
• what each GraphicType means for an element's extent, and why FREE_CANVAS is the reason FragmentMeasurer exists;
• what the normaliser strips, and what its SvgFingerprint check guarantees;
• what the two bound checks enforce and how to fix a failure;
• the steps for changing a fragment — including that SvgFingerprint cannot guard a structural move, which is the thing most likely to catch someone out.

Three things moved rather than being written twice

The README gains the composition detail it stopped short of — the octagon, and the FREE_CANVAS exception — and a pointer to the contract. It stays a front page; the contract is a page down.

svg/README.md keeps its naming section, which is accurate and is the mapping from a SIDC to a filename, and loses the inherited DISA framing around it: the title joint-military-symbology-xml, MIL-STD-2525, a zip file and an image-conversion utility that are not in this repository. It now says where the files came from, that jmsfx is the canonical fork, and points at the contract.

That link is absolute, because hallux carries a copy of this file and a relative link would resolve nowhere from there.

FragmentShapeChecker's failure message pointed at svg/README.md, which is no longer where the shape is described. Verified by breaking a fragment on purpose:

1 of 577 free canvas fragment is off the expected shape:
    25150100: a group called content; no <g id="main">

See docs/fragments.md for the shape they should hold.

mvn verify green, Spotless clean.

🤖 Generated with Claude Code