docs: specs 009-013 — documentation restructure in response to #67

[iancooper]

Adds five documentation specifications responding to #67, which argues that the
documentation mixes Diátaxis modes and is organised around Brighter's architecture
rather than around what a reader is trying to do.

No documentation pages change in this PR — these are the specs that will govern that
work, opened early so the plan can be reviewed (and commented on by the issue author)
before writing starts.

Audit findings behind the specs

• No tutorial exists. The Overview section is a showcase (ShowMeTheCode.md, which opens by saying "It's not about how... It's not about why"), a glossary, and a philosophy piece. None gets a reader to something running.
• Transports are filed under a delivery guarantee — RabbitMQ, Kafka, SNS/SQS and Azure Service Bus live under "Guaranteed At Least Once".
• Explanatory material is scattered across five separate sections.
• "Reference" contains one page, and we ship two glossaries: BasicConcepts.md (24 terms) is a subset of Glossary.md (100).
• Pages mix modes internally — RabbitMQConfiguration.md interleaves reference, explanation, how-to, and guidance over 565 lines.
• Machine-readability: 0 of 110 pages carry page metadata; ## Configuration is a heading on 22 pages, ## Best Practices on 26; ~230 of ~1,050 C# blocks include using directives.

The specs

Spec	Scope
009 Getting Started Tutorials	Four-rung ladder: in-process command → RabbitMQ → durable Postgres Outbox → Kafka
010 Information Architecture	SUMMARY.md restructure, GitBook redirects, BasicConcepts/Glossary merge, llms.txt
011 Authoring Conventions	Page-type banners, subject-qualified headings, version markers, splitting mixed-mode pages, linter
012 Configuration Reference	Consistent option tables, verified against source by an automated checker
013 How-To Guides	Task-phrased recipes, including the PostgreSQL-for-both case from #67

Execution order is 011 → 010 → 012 → 013, with 009 in parallel throughout. Spec
numbers are identifiers, not a sequence.

Decisions

The issue recommended using Diátaxis. We apply it here as page-level discipline, not as literal top-level navigation.
A four-bucket split would shred each technology into four pages across 7 transports, 8 outboxes, 6 inboxes, 7 schedulers and 7 distributed locks. Readers navigate that material by technology, so those families stay grouped and get within-page mode discipline instead.

Front matter is ruled out. GitBook's documentation states that .gitbook.yaml, not front matter, is the supported route, and GitbookIO/gitbook#1079 reports front matter rendering literally into the page body. Spec 011 uses a visible banner below the H1 instead — which readers can actually see, and which survives the chunking that retrieval systems apply.

Also, tutorial sample code may be added to ../Brighter/samples/ via pull request, so tutorial code is compiled and kept honest by the source repository's CI. src/, tests/, ADRs, and release notes remain strictly read-only.

Closes nothing yet — #67 stays open until the work lands.

[iancooper]

Scope change: this PR now touches contents/ and tools/

The description above says "No documentation pages change in this PR." That is no longer
true, and the change is small but worth signposting rather than leaving to be found in
the file list.

contents/VersionBegin.md and contents/VersionEnd.md deleted (93cd9b7)

Both were a hack predating GitBook's support for multiple versions. Neither was
documentation: each held an H1 and a single line of body ("Beginning of Version" / "End of
Version"), nothing linked to either, and neither appeared in SUMMARY.md.

tools/linkcheck.py's NON_CONTENT set existed solely to keep these two out of the
ORPHAN check, so it goes with them. The orphan check now has no exemptions at all: every
page under contents/ must be reachable from SUMMARY.md, which means a page that is not
navigable has to be either linked or deleted rather than quietly excused. linkcheck.py is
clean before and after.

This also removes an edge case from spec 011's banner rule, which would otherwise have
needed its own notion of an exempt page — "does this file count as a page?" is exactly the
kind of ambiguity a linter should not have to carry.

The corpus is 105 pages, not 107 (3b783a3)

Spec 011's requirements and design are updated throughout, with the reconciliation recorded
in requirements.md § Measurements. The heading figures are unaffected — neither deleted
file had an ## heading, so neither contributed to the 53 colliding heading texts or the
297 instances. The expected linter output on the untouched tree is now 105 banner
errors, 256 cross-page heading errors and 34 within-page errors; those counts are
the test that the rules match the corpus, so getting them right before the sweep matters.

Spec 011 now has a task list

spec/011-authoring_conventions/tasks.md — 43 tasks across 7 phases, where the phases are
the design's own sequencing rather than an order invented for the task list. Two findings
in it postdate the approved design and are recorded at the top of the file: the page count
above, and the fact that .gitbook.yaml contains two U+200B zero-width spaces — one
immediately before structure:, so the key is literally ​structure:. Since malformed
indentation disables GitBook redirects silently rather than erroring, and redirects are
what preserve existing links through the restructure (#67), that one is worth knowing
before anyone edits the file.

Note on the numbers in the description above

Two figures in the audit list were superseded when spec 011 re-measured by script:
"0 of 110 pages carry page metadata" is 0 of 105, and "~230 of ~1,050 C# blocks include
using directives" is 133 of 796 (16%) — the earlier count included every fenced
block, not just C#-tagged ones. The direction is the same and compliance is worse than
first stated. Full tables in spec/011-authoring_conventions/requirements.md.

Still no page content has changed, and #67 stays open until the work lands.