Say what the bundle is and how to serve it, from the definition that packs it [#54]

[iderex]

What was wrong

The release run packs an archive and attaches a bill of materials beside it, and
nothing tells anybody what to do with either. The only route to that today is
reading the workflow files and the generator, which is exactly what the issue
this belongs to says an operator should not have to do.

git ls-tree --name-only origin/main docs/
docs/domain-cutover.md
docs/headless.md
docs/near-miss.md
docs/parity.md
docs/roster-schema.md

Run 2026-08-16 against 8af1685.

What this does

Adds docs/serving-the-bundle.md. It says what the archive holds, what serves
it, what the host has to be told about the not-found page, what the bundle does
not reach, how to check what arrived, and what an operator is not getting. Every
claim carries the command that produced it, run against an archive packed from a
checkout by the three commands the document quotes, which are the ones
.github/workflows/package.yml runs.

Three things it states that are not readable off the output and cost time when
they are met by surprise.

A reference beginning with a slash resolves against the root of the filesystem
when a page is opened as a file, so every link inside the site goes nowhere from
a file path and the bundle has to be served rather than opened.

The canonical link, the sitemap entries and the robots line all name one host,
and they go on naming it wherever the bundle is served. That is right for a
mirror and wrong for a fork, and it cannot be edited in place without the hashes
ceasing to match.

The hash list travels inside the archive, so it answers whether the download
arrived intact and not whether it is what this repository built. What answers
the second question is packing the tag again and comparing the digest, and the
document shows two packs of one checkout agreeing byte for byte.

It also chooses a place rather than assuming one.
decisions/0003-generator-or-hand-written.md enumerates the pages the site
produces and says that a record adding a page corrects that count rather than
leaving two in the tree. An operator page is not among the eighteen and this
change adds none, so this is repository documentation beside the other five
files above rather than a page the build writes:

git show origin/main:decisions/0003-generator-or-hand-written.md | grep -A3 'The count is stated'
The count is stated because the decision turns on it, and it is the one number in
this record that a later page moves. A record that adds a page corrects the count
here rather than leaving two counts in the tree.

Run 2026-08-16 against 8af1685.

Closes

Nothing. Part of #54, and it does not meet the done-when.

Two of the three clauses need a release, and there is none:

gh release list --repo Flowfin/site --limit 5
(no output)
git ls-remote --tags origin
(no output)

Both run 2026-08-16. The clause asking that a release carry a bundle serving
correctly from a plain static server, and the clause asking that following the
page from a clean machine produce a working site, both start from a published
archive. Whether a release happens is a person's decision rather than a property
of this tree, and .github/workflows/release.yml says so on itself.

What is landed is the middle clause, which asks that the page document the
not-found mapping and the verification steps.

One further thing the document does not do, and it is a boundary rather than an
omission. Nothing points a reader at it from the notes a release carries,
because that text lives in the release run's own file and belongs with the work
that produces the release rather than with this change.

What was corrected before this branch

An earlier branch carried the same document and was refused twice, so this one
replaces it rather than being pushed over it. The pull request it was under is
closed with the reasons in its own body.

The invariant over the tree refused the pasted excerpt from the bill of
materials, because it carried the version this repository releases under and
that version is read from one file:

version-lives-in-exactly-one-file: REFUSED, 3 violation(s)
  docs/serving-the-bundle.md: line 52 writes the version 0.1.0, and internal/version/version.go is the one file it is read from

The local run before that push had said ok, and the difference is that the
file was not yet in the index when it ran, so the row over tracked text had
nothing to read. The excerpt now stops above those lines and the document says
the elision is deliberate. The gate was re-run with the file staged, which is
the run quoted below.

The commit also carried no Signed-off-by trailer. This one does, and the
history is a new branch rather than an amended one.

What was run

go run . ci
gate: 7 legs, in order: format, vet, test, build, links, sitemap, invariants
  needs-network was not asked for. Asking costs a request to the public name from whatever machine runs it, and a verdict that moves when somebody else's service does rather than when this tree changes. Ask with: go run ./harness/needs-network
  format: ok, 50 file(s)
  vet: ok
  test: ok, 24 test file(s)
  build: ok, 7 file(s)
  links: every reference that stays inside this site resolves to a file the build wrote
  sitemap: every page the build wrote is listed once, and every entry has a page behind it
  invariants: ok, 36 rule(s) decided, 1 owed and not decided
7 of 7 legs ran. None was skipped.

The needs-network harness was not asked for and is disclosed as not run. It
reaches the public name, and nothing in this change is about what answers there.

The formatter that judges prose files was run over the added file at the pinned
version rather than left to the workflow:

npx --yes "prettier@$(jq -er '.[] | select(.id == "prettier") | .version' pins.json)" \
  --check --end-of-line auto docs/serving-the-bundle.md
Checking formatting...
All matched files use Prettier code style!

The commit messages in the range were judged here as well as on the server:

go run . hygiene origin/main HEAD
hygiene: 1 non-merge commit(s) in origin/main..HEAD, origin internal
  a7d3b31690dc: subject carries its reference
1 commit(s) judged, none refused.

git diff --name-only origin/main...HEAD
docs/serving-the-bundle.md

All four runs 2026-08-16 against a7d3b31.

No test was skipped. Nothing here needed a display, a browser or elevation.

The means

Markdown in docs/, which is what the other five operator-facing and
contributor-facing documents in that directory already are, so this adds no
language, no runtime and no dependency to a tree that carries none.

It carries no rule a machine refuses, and that is the honest answer rather than
a gap being papered over. What it describes is a procedure somebody else
performs on their own host, and there is nothing in this tree for a check to
read about it. What the tree can decide is already decided by the rows quoted in
the document, and the document cites those by name rather than restating what
they refuse. Every fact it asserts about the output carries the command behind
it, which is the part of the standpoint a document can meet.

Who read it

Nobody but me. The ruleset here requires no approving review, so this is merged
by whoever opened it, and the runs above stand in place of a second reader
rather than alongside one.