From f059cb118c556d1f0279350507f74b8a47d5a98a Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Fri, 11 Sep 2026 00:19:06 +0200 Subject: docs: remove the documents MESHBAY_DESIGN.md replaces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Twenty-four files, about 17 000 lines: the two architecture drafts, the three security reviews, eleven design notes, the roadmap, the decisions file, the v1–v4 archive, the deprecated user guide and the stale quickstart. Their content is in MESHBAY_DESIGN.md, and git history holds the originals. The reason to delete rather than keep bannered: a document that is superseded but present still gets read, and a reader cannot always tell which of two accounts of one mechanism is the live one. That was the argument for retiring the user guide rather than repairing it, and it applies to the whole set. What made this safe is the concordance. Roughly 290 comments and docstrings cite these files by section — `musicbay.md §6`, `mediacenter.md §5.5`, `draft-v6 §2.11` — and section 16 maps every one onto its replacement, so not a single comment needs editing to stay followable. It now says plainly that the files are gone and where to recover them, and it gained rows for the three reviews (their findings are section 13), and for the two guides. Four kept documents pointed into the set and were repointed first: `playlists.md` (nine references — it is a live proposal and must not dangle), `WINDOWS-PORT.md`, and CLAUDE.md's example. No dangling reference remains outside section 16. Two files were dropped from the list after checking what they hold. `HTTPS.md` is an operational runbook — Caddy, certificate renewal, DNS, troubleshooting — and MESHBAY_DESIGN.md deliberately covers no operations, so nothing would replace it; the versioned Caddyfile is the config, not the procedure. `cast-smart-tv.md` is the plan for the unbuilt DLNA phase of a feature whose first two phases ship, and section 11.4 summarises it in four lines rather than carrying the SSDP/UPnP work. There is no user guide now, and section 0.1 says so rather than leaving a reader to discover it. Suites green: 2258 passed, 4 skipped. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YVoHVCcfBqud6ZjG4db3y7 --- docs/MESHBAY_DESIGN.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) (limited to 'docs/MESHBAY_DESIGN.md') diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md index d34351b..d24d7a9 100644 --- a/docs/MESHBAY_DESIGN.md +++ b/docs/MESHBAY_DESIGN.md @@ -33,10 +33,15 @@ | `MESHBAY_NODE_PROTOCOL.md` | the MNP wire format, message by message | | `transfers-v1.md` | the transfer system's failure-mode analysis, kept because a synthesis cannot carry "every way a slot can be lost" | | `playlists.md` | the playlist design in full — decided, not built (§9.10) | -| ~~`USERGUIDE.md`~~ | **deprecated** — a large majority of it predates per-node identity, named roots and the sealed wire, and is wrong. Kept for provenance; its own banner lists what is false | -| `PACKAGING-GUIDE.md`, `QUICKSTART.md`, `HTTPS.md`, `MAIL-SERVER.md`, `windows-build.md` | installation and server operations | +| `cast-smart-tv.md` | the DLNA/UPnP device backend — designed, not built (§11.4) | +| `WINDOWS-PORT.md` | the Windows port's audit and packaging detail (§11.2) | +| `PACKAGING-GUIDE.md`, `HTTPS.md`, `MAIL-SERVER.md`, `windows-build.md` | installation and server operations | | `CLAUDE.md` | project conventions and the engineering lessons that govern how changes are made | -| `old-draft.md` | historical archive of drafts v1–v4. Nothing there is authoritative | + +**There is no user guide.** The one that existed described the system before +per-node identity, named roots and the sealed wire, and was retired rather than +repaired — a document a reader cannot tell the sound parts of is worse than none. +Writing a new one starts here. ### 0.2 Reference labels @@ -2597,7 +2602,11 @@ account recovery, and the Windows port through packaging. ## 16. Concordance Code comments, tests and older documents cite sections of the documents this one -replaces. The mapping: +replaces. **Those documents are no longer in the tree** — they were removed on +2026-09-11, once their content was here and this table could resolve every +reference they left behind. `git log -- docs/` recovers any of them. + +Nothing needs editing to follow a reference: look the citation up here. | Cited as | Read | |---|---| @@ -2643,6 +2652,9 @@ replaces. The mapping: | `per-node-identity-v1.md` — identity keys per node | §3.2 | | `captcha.md` — registration gate | §7.7 | | `tmp-decisions.md` D1–D4 | §14.2 | +| `first-review.md`, `second-review.md`, `third-review.md` — any finding | §13, which defines every label. §13.1 is the first review, §13.3 the second, §13.4 the third | +| `USERGUIDE.md` — anything | it was wrong and is gone. §2 for the trust model, §3 for identity, §6.7 for the operator surface | +| `QUICKSTART.md` — anything | it was stale and is gone. `PACKAGING-GUIDE.md` installs; §6.7 lists the operator commands | | `devel-phases-next.md` structural decisions | §14.1 | | `cast-smart-tv.md` | §11.4 | -- cgit v1.2.3