[docs] standardise key docs, devlog catch-up for 0.5.1

[ddol]

Purpose

Documentation-only release-prep pass for 0.5.1. It fixes two problems that had been quietly compounding.

The top-level docs opened inconsistently. Some led with an ASCII banner and a one-line sentence fragment, some with a full paragraph, and nine had no <h1> at all, so their heading hierarchy started at ##. A reader arriving cold could not tell what a document was for or whether it was meant for them.

docs/DEVLOG.md had a two-month hole. The newest entry was August 10, and the one before it was June 9. Twelve working days of merged work fell into the gap, spanning 28 PRs (#509 through #551): the pre24/pre25 release train, the chart timezone fix, the LOC and coverage chart, the LiDAR PCAP tooling consolidation, the pnpm 11 and TypeScript 6 upgrade, the fully-static Linux builds, the multi-sensor capabilities redesign, and the in-binary Tailscale installer.

Changes

Opening standardisation (13 docs)

Every touched document now opens the same way: ASCII banner where one exists, then an <h1>, then a short TL;DR paragraph saying what the document is for and who should read it.

Added a missing <h1> to nine documents: ARCHITECTURE.md, CHANGELOG.md, COMMANDS.md, CONTRIBUTING.md, DEBUGGING.md, MAGIC_NUMBERS.md, TENETS.md, data/structures/MATRIX.md, and docs/VISION.md.

Added or rewrote the opening paragraph in ARCHITECTURE.md, CHANGELOG.md, CODE_OF_CONDUCT.md, COMMANDS.md, DEBUGGING.md, MAGIC_NUMBERS.md, README.md, TENETS.md, data/QUESTIONS.md, data/structures/MATRIX.md, docs/DEVLOG.md, and docs/ui/DESIGN.md. The replaced text was mostly descriptive filler that told the reader what the file was called rather than what it was for.

README.md also moved the LOC and coverage chart out of the hero position and down into the contributing section, where a codebase-composition graphic is actually relevant, with a caption that explains what the hatching means.

British English pass

Corrected spellings that had drifted American in prose: modeling, labeling, initialization, visualization, behavior, color, and apologizing.

Two Americanisms remain on purpose:

• CODE_OF_CONDUCT.md:34 keeps sexualized. It is normative Contributor Covenant text and editing it would fork the covenant.
• DEBUGGING.md:786 keeps initializing. It is verbatim sudo error output, so it has to match what the terminal actually prints.

DEVLOG catch-up

Added 12 new day entries covering every merged PR in the gap:

Date	Theme	PRs
Aug 14	Key documentation standardisation	this branch
Aug 13	Embedded Tailscale installer	#551, #550
Aug 12	Fully-static Linux builds	#513
Aug 11	Multi-sensor capabilities & serial rollout	#547, #549
Aug 2	Archived prototype references	#544, #543
Jul 30	pnpm 11, TypeScript 6 & CI repair	#536, #537, #541, #542
Jul 29	Dependency refresh	#538, #539
Jul 13	Dependency refresh	#533
Jun 24	LiDAR PCAP tooling consolidation	#531
Jun 19	Dependency cleanup	#530
Jun 11	LOC & coverage chart	#509, #529
Jun 10	Chart timezone fix & pre25 release	#527, #528

Gap-filled two existing entries and broadened their theme titles to match the added scope:

• August 10 gained [docs] recover OBB guard-stack validation notes #548 (OBB guard-stack documentation recovery), [docs] lidar plans, v0.5.2 #540 (the v0.5.2 LiDAR maths coherence plan and the 052 backlog review), and the Bump the "application" group with 2 updates across multiple ecosystems #545/Bump mermaid from 11.16.0 to 11.16.1 in /docs_html #546 dependency bumps. Retitled to macOS Developer ID signing, LiDAR maths planning & OBB doc recovery.
• June 9 gained [docs][ci] 0.5.1-pre24 changelog/devlog & Docker cache fix #523, Bump the "application" group with 3 updates across multiple ecosystems #524, [img] update release .json's #525, and [docs] graduate completed plans #526 (the pre24 release, the devlog restructure, the eight-plan graduation, and a grouped dependency bump). Retitled to Typst map editor, typstbin hardening, pre24 release & plan graduation.

Recorded unlanded branch work with {branch-name} tags, per the devlog convention: {patrickod/tailscale-acls} (the opt-in Tailscale ACL gate, #503), {codex/four-platform-build-standardisation-plan}, {claude/strange-colden-a99dc2} (four LiDAR maths-gap commits covering K1 diagonal-Q process noise, K2 Joseph-form covariance, B1 MAD-versus-sigma background spread, and M1 CLEAR MOT), and this branch.

Removed six stale {branch-name} tags whose branches have since merged: five for dd/mac/dmg-signing (#425) and one for dd/fix/security-c2-c3 (#461). Tags on {copilot/update-capabilities-check-radar-mode} (#430), {codex/plan-remaining-obb-heading-stability} (#397), {copilot/add-bumper-sticker-designs} (#403), and {dd/ci/add-swift} (#484) stay, because those PRs were closed rather than merged. Where that work was later carried forward, the landing now appears under its real date: the capabilities redesign under August 11 (#547) and the OBB notes under August 10 (#548).

Backlog

Moved the in-binary Tailscale installer entry into PR-number order under Complete and attributed it to #551, which had shipped without the reference.

Known deviation

#522 (the Typst migration) merged at 2026-06-09T08:28Z, but its bullets are split across the June 8 and June 9 entries. That looks like a UTC-attribution error and I left it alone: #523's own description says the split was deliberate, made to "reflect the actual daily cadence rather than squash-merge dates". Correcting it would undo a considered editorial decision rather than fix a mistake.

Validation

All docs gates pass against the branch:

• prettier --check on all 15 changed files: clean
• make check-mermaid: passed, 2 blocks checked
• scripts/check-relative-links.py: all relative links OK
• scripts/check-backtick-paths.py: all backtick paths OK

No code, config, build, or CI files are touched, so the Go, web, and macOS suites are unaffected.

Checklist

• Uses British English spelling/wording where applicable (two intentional exceptions documented above).
• Design is confirmed and aligns with DESIGN.md. No design change; docs/ui/DESIGN.md gained an opening paragraph only.
• Any maths/derived values are valid and up to date. No maths change.
• Version has been bumped where required. Not required; documentation only, and 0.5.1-pre29 already landed in [img] embed Tailscale installer #551.
• Documentation is up to date.
• README.md is up to date.
• docs/DEVLOG.md is up to date.

[Copilot]

Pull request overview

Documentation-only release-prep pass for 0.5.1, focused on standardising how key docs open (ASCII banner → <h1> → short purpose paragraph) and filling the missing June→August gap in docs/DEVLOG.md with the merged PR history and a small backlog bookkeeping fix.

Changes:

• Standardised openings across key top-level/hub docs by adding missing H1s and rewriting the initial “what this doc is for” paragraph.
• Added 12 missing day entries to docs/DEVLOG.md (plus updates to two existing entries) to cover the June→August merge gap.
• Moved the LOC/coverage chart in README.md to a more appropriate section and corrected docs/BACKLOG.md to include #551.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
ARCHITECTURE.md	Adds a top-level H1 and a new opening summary to orient readers.
CHANGELOG.md	Adds an H1 and a clearer “what this file is for” introduction; British English fixes.
CODE_OF_CONDUCT.md	Adds an opening paragraph and applies British English spellings (with noted exceptions).
COMMANDS.md	Adds an H1 and reframes the opening as a “map of make targets”.
CONTRIBUTING.md	Adds an H1 to fix heading hierarchy and improve consistency with other docs.
DEBUGGING.md	Adds an H1 and rewrites the opening guidance paragraph for clearer intent.
MAGIC_NUMBERS.md	Adds an H1 and rewrites the intro to explain the register’s purpose and scope.
README.md	Moves the LOC/coverage chart down into the contributing area and updates the caption text.
TENETS.md	Adds an H1 and rewrites the opening paragraph to clearly describe the project constraints.
data/QUESTIONS.md	Rewrites the introduction to better describe the purpose and graduation path to decisions.
data/structures/MATRIX.md	Adds an H1 and rewrites the intro to clarify the matrix’s purpose and legend.
docs/BACKLOG.md	Reorders/records the in-binary Tailscale installer item and attributes it to #551.
docs/DEVLOG.md	Adds a devlog introduction and fills the June→August gap with new dated entries.
docs/VISION.md	Adds a missing H1 to fix hierarchy and align with the standardised opening format.
docs/ui/DESIGN.md	Adds an opening paragraph clarifying the design language’s role across UI/report surfaces.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.