108 — The site sidebar lists a shelf in path order, and the shelf index keeps the reading order - Headwater

🜄Headwater

How it works Compare Proof Tutorial

Decision records

79 — Criterion 5 admits naming or extending a core-serving kind, and a facet-only entry ships no templates directory under criterion 2
80 — the corpus dashboard ships free and self-hosted, with tenant isolation stated as a data-model constraint from day one
81 — The hand-authored decision register indexes a subset of the shelf, and stops asserting it supersedes the complete one
82 — The resolved taxonomy is drawn by a verb that prints Mermaid and writes no file
83 — Governs and traces_to are created by an agent, because a session proposes the line and a person types it
84 — A language rule reaches front-door prose outside the corpus root, and no other rule does
85 — A live document that rests on a draft one is reported over every relation, because a draft leaves no record to cite
86 — A reciprocal half is owed once its writer leaves its initial state
87 — No paragraph limit joins the language rule, because most paragraphs past six sentences hold one topic
88 — An engine release and a taxonomy release have disjoint tag namespaces and are cut independently
89 — A taxonomy release publishes the source at the tagged commit and never ships the vendored copy
90 — Each release states in its notes the release digest that a consumer pins
91 — The runner image of the engine release build is written in the workflow because it sets the glibc floor
92 — The citation comment of spec 5 is for an adopter's corpus, and this repository does not practice it on its own code
93 — The live account of a domain is its own kind, split on the product and process line, and it draws on the records it cites
94 — The APT repository is served from headwater.tools and signed by a subkey the owner's offline key certifies
95 — One library entry may address the keys of an entry it names in requires, and confluence holds over the dependency order
96 — Harper does not become part of the engine now, and Q41 stands
97 — A figure on a hand-built page is measured when the site is published, and the committed page carries none
98 — An engine subsystem is described by a technical design spec on a shelf of its own, and its behavior stays where it is already written
99 — A namespace does not keep two corpora apart, and no rule compares identifier schemes across two locks
100 — A counted tombstone lists a digest of each withheld identifier, and a sealed one lists nothing
101 — The new command writes no far half of a symmetric relation and no state on a supersedes target
102 — An editor integration starts headwater mcp for each query and does not embed the library
103 — An evidence relation declares which end is the evidence, and discharges declares the source
104 — An agent writes governs, traces_to and cited_in through the verb, and the review of its pull request is the acceptance
105 — Whether the embedding path becomes the silence-only fallback of routing, and what happens to the shadow collection
106 — A governing document repoints a link to a rule that moved, and a record of a moment stays as written
107 — The process shelves stay published, in a labeled section of the site that a search engine does not index
108 — The site sidebar lists a shelf in path order, and the shelf index keeps the reading order

All 108 on this shelf →

Rendered from docs/decisions/0108-the-site-sidebar-lists-a-shelf-in-path-order-and-the-shelf-index-keeps-the-reading-order.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

Context

HW-DR-0036 has the site_nav emitter list each shelf in the order by_precedence derives. That is the order a shelf index prints, so the two never disagreed.

The owner reviewed the published site on 2026-10-04 and found that the decisions sidebar read 101, then 86, then 4. Precedence follows relations and the nucleus, and it gives a reader no rule for finding a decision they already know by number.

A sidebar and a shelf index do different jobs. A shelf index is the page a reader opens to learn what to read first. A sidebar is the list a reader uses to find a document by name or number.

Decision

The site_nav emitter lists the documents of a shelf in path order. A shelf of numbered documents carries a zero-padded prefix, so path order is numeric order. A shelf with no prefix reads alphabetically by file name.

The shelf index keeps the order by_precedence derives. route keeps it too.

The generated index of a shelf stays the first entry of its group, as before.

Consequences

The decisions sidebar reads 1, 2, 3 and so on up to 108.
The specification series sidebar reads by part number, with the glossary last. The shelf index still puts the documents with the highest precedence first.
The previous and next links at the foot of a page follow the sidebar, because MkDocs builds them from the nav.
A corpus that wants the reading order in its sidebar needs a declared option. This decision adds none, because no adopter has asked for one.
The test in engine/crates/generate/tests/fixtures.rs now holds the order against the path of each document. It held the old order against by_precedence.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search