docs: split the README and state what the package adds over the alternatives - #19

Why

The README had grown to 1227 lines / 86 KB. Six What's new in vX sections and three migration
guides sat between the pitch and the API docs, so the reference material a reader actually returns
to started around line 250 and ran to the end. Separately, the READMEs explained what the library
does and never what you would otherwise use — so the first question a reader has, why not
NpgsqlRange<T>, which ships with the driver, went unanswered on both the repo page and the NuGet
page.

Docs only. No source changes, no behavioural changes, no public API surface touched.

What changed

1. Split the README into a landing page and five reference pages (2256c3f)

README is now 203 lines. The What's new sections are dropped rather than moved — CHANGELOG.md
already carries all eight of those versions in full, and duplicating release notes in the README is
what let them accumulate.

2. Added positioning to both READMEs (31c7d8e) — ## Why this exists in the root README,
## Why not NpgsqlRange<T>? on the NuGet page. Built from a survey of the current alternatives
rather than a claim of uniqueness, so a reader can check each line.

3. Sharpened the comparison after review (ac589dd) — discrete domains, FRange's partial
accessors, and value-set immutability.

The comparison, and what it deliberately does not claim

Verified against the libraries' own source and docs, not their package descriptions:

• NpgsqlRange<T> is declared in NpgsqlTypes, in Npgsql.dll — a domain model using it
  references the database driver. The struct carries no algebra at all; Contains, Overlaps,
  Union and the rest are EF Core extension methods documented "only intended for use via SQL
  translation as part of an EF Core LINQ query", and throw client-side.
• NodaTime Interval/DateInterval are real domain types the Npgsql plugin maps and
  translates — but two date/time shapes only, and DateInterval is always closed and bounded.
• FRange keeps unboundedness a runtime fact: its C# surface exposes LowerBoundValue over an
  F# DU whose Unbounded case is failwith "No bound" (FRange/CSharp.fs).
• Neither FRange nor Open.Range has a discrete domain — no step, no canonicalization — so
  [1,10) and [1,9] stay different values and integer or date adjacency cannot be decided.
• T[]/List<T> are mutable references and sequence-equal, so the domain hands out its own
  invariant on load.

Two things are stated explicitly against interest, because the sections are meant to be
falsifiable:

• Npgsql already translates the full range operator set. SQL translation is not the
  differentiator and the README says so; what is missing elsewhere is a domain type to hang it on.
• Open.Range is not accused of accepting invalid ranges. Its constructor calls
  Range.AssertIsValid, and Boundary<T>.CanRangeWith rejects equal-valued exclusive bounds, so
  even the degenerate (5,5) throws.

The survey is dated (August 2026) and invites correction by issue.

Drive-by fix

The package README — and therefore the NuGet page — claimed
Int32Range.Parse("[1,10)", null).ToString() returns [1,10). It returns [1,9]; discrete ranges
canonicalize, per
RangeParseFormatTests.Parse_DiscreteRange_HalfOpenInput_CanonicalizesToClosed.

Verification

Content moved by line-range extraction rather than retyped, then checked mechanically:

• 787 of 789 non-blank lines outside the deleted What's new block are byte-identical in their
  new home. The remainder are the two headings promoted to page titles and four lines reworded
  because the split broke their above/below references.
• A link checker over all 15 markdown files confirms every relative link and anchor resolves,
  including the ~20 cross-references rewritten here.
• The root README is not packed into any package (all four ship their own), and
  PackagingConventionTests asserts only on src/*/README.md.
• Build clean (0 warnings, warnings-as-errors). 1117 tests pass, including the live-PostgreSQL
  Testcontainers suite.

For the reviewer

• src/CodoMetis.ValueRanges/README.md is packed, so this PR changes what renders on the NuGet
  page. consumer-smoke-test.sh will pack it in both modes — that difference from main is
  intended, not a regression.
• Worth a second opinion on the comparison table specifically: it names third-party libraries, and
  every row should stay defensible.

🤖 Generated with Claude Code