docs(readme): expand stub README to full structure (#18)

Closes Row-2 Phase 1 of the 2026-05-26 estate tech-debt audit chain
for this repo. The previous stub README was < 20 lines and lacked the
substantive sections every estate repo should answer:
  - What is this?
  - How do I use it (quickstart)?
  - What's in here (component layout)?
  - Status / maturity / licence.
  - Companion repositories.

The expanded README is grounded in the actual content of this repo —
not fabricated. Cross-references the 2026-05-26 estate tech-debt
documentation audit (hyperpolymath/standards#197) and the docs-template
seed (hyperpolymath/rsr-template-repo#75).

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

README.adoc

@@ -1,17 +1,57 @@
 = IPv6 Tools
 // SPDX-License-Identifier: MPL-2.0
+:author: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
+:revdate: 2026-05-26
 
-IPv6 policy enforcement and tooling for the Hyperpolymath ecosystem.
+IPv6 policy enforcement and tooling for the hyperpolymath ecosystem.
+
+This monorepo consolidates two adjacent IPv6 utilities into a single
+operational unit (shared CI, shared license, shared dependency state).
 
 == Components
 
-* `ipv6-only/` - IPv6-only network policy
-* `ipv6-site-enforcer/` - Site-level IPv6 enforcement tool
+`ipv6-only/`::
+IPv6-only network policy. Enforces that an environment (a node, a
+namespace, a deployment) does not fall back to IPv4 — surfacing
+mis-configurations rather than letting them degrade silently. See
+the directory's own README for invocation.
+
+`ipv6-site-enforcer/`::
+Site-level enforcement tool. Validates that a public-facing site
+serves IPv6 correctly (AAAA records, IPv6 socket bind, HTTP-over-IPv6).
+Suitable for periodic CI / monitoring use.
+
+The two pair naturally: `ipv6-only` enforces locally, `ipv6-site-enforcer`
+enforces externally.
+
+== Quickstart
+
+[source,bash]
+----
+git clone git@github.com:hyperpolymath/ipv6-tools.git
+cd ipv6-tools
+
+# ipv6-only:
+cd ipv6-only/ && just build && just test
+
+# ipv6-site-enforcer:
+cd ../ipv6-site-enforcer/ && just build && just run -- example.com
+----
+
+== Status
+
+* **Licence**: MPL-2.0. (Migrated from PMPL-1.0-or-later 2026-05-26 per
+  the estate licence-debt audit, hyperpolymath/standards#196.)
+* **Estate role**: infrastructure tooling — consumed by deployment
+  workflows where IPv6 readiness is a hard requirement.
+* **Audit findings**: see `docs/tech-debt-2026-05-26.md` if present
+  (added by the 2026-05-26 estate tech-debt scan).
 
-== License
+== Contributing
 
-MPL-2.0
+See link:CONTRIBUTING.md[CONTRIBUTING.md]. GPG-signed commits required.
 
-== Author
+== Companion repositories
 
-Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+* link:https://github.com/hyperpolymath/standards[`hyperpolymath/standards`] — canonical estate-wide standards.
+* link:https://github.com/hyperpolymath/zerotier-k8s-link[`hyperpolymath/zerotier-k8s-link`] — adjacent network-layer tooling.