Ships the README-linked guides in the package

[johnnyt]

Refs: sui-g45f

What

The README's relative links now resolve on GitHub, HexDocs and hex.pm alike, and the docs build is warning-free.

• package: [files: ...] in mix.exs now ships the five guides the README links to relatively: docs/architecture.md, docs/ops-embedding.md, docs/fixture-bundles.md, docs/wire-format.md, docs/telemetry.md. Each was already an extra; hex.pm renders the README from the tarball, so each link answered 404 on the package page.
• README.md: the ADR-0005 link is now the GitHub URL at the v0.10.1 tag (@version in mix.exs), where the file exists. ADRs stay unpublished; no ADR is added to extras. This was the docs build's one warning.
• CHANGELOG.md: the preamble's changelog.d/README.md link is now the GitHub URL at the v0.10.1 tag, where the file exists. ExDoc silently rewrote the relative link to the package's front page (its basename matches the README.md extra).
• test/packaging_test.exs: a new test asserts that every README relative link target is in both extras and files:. It went red on the base (README.md links docs/wire-format.md relatively, but package() files: does not ship it). A sabotage run that put the relative ADR link back went red on the extras half. It passes on this head.

No version bump (@version unchanged). No changelog fragment: changelog.d/README.md says not to write one for "documentation, ADRs, or plans".

Acceptance evidence

mix docs --warnings-as-errors at this head (no warnings; exit 0):

Generating docs...
View html docs at "doc/index.html"
View markdown docs at "doc/llms.txt"
View epub docs at "doc/StatifierUI.epub"
EXIT=0

The base (4570920) reported one warning: documentation references file "docs/adr/0005-language-neutral-trace-wire-format.md" but it does not exist. The warning set had not moved from the one the bead was written against.

Relative-link check over every published file: a Ruby script reads the seven extras and every .ex file under lib/. It strips inline code spans (the [trace](...) placeholders in the event-log docs are code, not links) and resolves every markdown link that is not http(s):, mailto: or #. It reports each target that is not an extra, and any extras that share a basename. Output at this head:

scanned 55 files (7 extras + 48 lib .ex)
relative links to non-extras: none
extras sharing a basename: none

The same script at the base listed exactly the two links fixed here:

  README.md:162 docs/adr/0005-language-neutral-trace-wire-format.md -> docs/adr/0005-language-neutral-trace-wire-format.md
  CHANGELOG.md:9 changelog.d/README.md -> changelog.d/README.md

README relative link targets against files:: the relative links at README.md lines 155, 211, 335, 392, 394, 398, 400 and 402 name five distinct files, the five guides above. Each is now in files: and in extras, and the new packaging test checks this. mix hex.build succeeds (exit 0), and the tail of its file list reads:

    mix.exs
    README.md
    LICENSE
    CHANGELOG.md
    docs/architecture.md
    docs/ops-embedding.md
    docs/fixture-bundles.md
    docs/wire-format.md
    docs/telemetry.md

Full gate, mix quality, on the committed tree, quoted whole:

Running quality checks...

✓ Format: No changes needed (309ms)
✓ Compile: dev + test compiled (warnings as errors) (328ms)

Running analysis stages in parallel...

○ Gettext: skipped (:gettext not installed)
○ Sobelow: skipped (:sobelow not installed)
✓ Dependencies: No unused dependencies (456ms)
✓ Doctor: Passed (769ms)
✓ Credo: No issues (2.0s)
✓ Tests: 1,208 of 1,208 passed, 93.5% coverage (4.0s)
⋯ Dialyzer: building PLT (this is a one-time cost)
✓ Dialyzer: No warnings (PLT built this run) (48.8s)

✓ All quality checks passed!

git diff --stat origin/main:

 CHANGELOG.md            |  2 +-
 README.md               |  2 +-
 mix.exs                 | 26 +++++++++++++++++++++-----
 test/packaging_test.exs | 37 +++++++++++++++++++++++++++++++++++++
 4 files changed, 60 insertions(+), 7 deletions(-)

Review (author's in-turn review)

I re-read the diff against the bead, its acceptance criteria and its dated notes. The ADR-0005 file and changelog.d/README.md both exist at the v0.10.1 tag (checked with git show v0.10.1:<path>), and the tag is on the remote. So both absolute URLs use the tag form, as the standard requires. The five guides in files: are exactly the five distinct relative README targets. None is new to extras, and no two extras share a basename. The mix.exs comments were updated in the same places the change touches: the docs() comment no longer says extras never need a files: entry, and the package() comment names the guides' reason and the test that holds the list. @version is unchanged, and no file under docs/adr/ is touched. The new test adds no public surface. This is tier gate: the diff changes 67 lines outside docs and fixtures, below the 300-line threshold, and touches no public function, option, callback, wire shape or record. No reviewer was dispatched.

Provenance

• The CHANGELOG.md preamble edit changes the link target only. It follows the bead's dated note, which found the silently rewritten link. The repo's commit extension says CHANGELOG.md is otherwise edited only at release; this edit touches no version section.
• The dated note suggested the main URL for changelog.d/README.md. The standard picks the tag URL when the file exists at the tag, and it does, so the tag URL is used.
• The packaging test is an engineering addition inside the bead's footprint. It guards the files: half, which the docs build cannot see.