Docs-first sweep — tighten contributor rules, enrich tech docs & clarify build scripts

[peter-lawrey]

Area	File(s)	Highlights
Contributor guidance	AGENTS.md	Added Oxford link, ASCII-7 lint tip, inline-comment example, when-to-open-PR section, mvn clean verify emphasis.
Wire docs	EventsByMethod.adoc, YAML2SpecificationCompliance.adoc	Expanded rationale, added sequence diagram, “Core components”, concrete YAML snippet, compliance overview & deviations/extensions.
House-style polish	AGENTS.md, .adoc docs	Switched smart quotes → ASCII, wrapped long lines, US→UK spelling fixes.
Build clarity	root pom.xml, module POMs	Comment blocks explaining BOM usage, plugins’ purpose, Sonar & benchmark profiles.
System properties	system.properties (root + demos/perf)	Documented every flag with default & behaviour.
Demo & perf code	numerous src/main/java/...	Added class-level Javadoc, main method docs, clarified DTO field purpose, etc. (no logic change).
Resource clean-up	common-words.txt, more-common-words.txt	Header comments, one-word-per-line rule; WordsLongConverter now skips blank/comment lines (backwards compatible).
Internal pkg info	internal/package-info.java	Rewritten to concise “not public API” notice.
Docs helper	EventsByMethod.adoc → added Mermaid sequence diagram.

No production code or public API behaviour altered apart from comment-line skip in WordsLongConverter (transparent).