From 728b436d0f3a4ddba342a096b91363edd4f69cb1 Mon Sep 17 00:00:00 2001
From: Daniel Samson <12231216+daniel-samson@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:49:12 +0100
Subject: [PATCH] docs: the storage rationale lives with the architecture it
 justifies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

storage-stack-discussion.md was misplaced at the docs root — that level is
for track plans; this is the file-system domain's design record. Moved to
file-system-development/storage-design-rationale.md, renamed to say what it
is, cross-references updated.
---
 .../storage-architecture.md                   |  2 +-
 .../storage-design-rationale.md}              | 20 +++++++++++--------
 2 files changed, 13 insertions(+), 9 deletions(-)
 rename docs/{storage-stack-discussion.md => file-system-development/storage-design-rationale.md} (93%)

diff --git a/docs/file-system-development/storage-architecture.md b/docs/file-system-development/storage-architecture.md
index 5d22a75..6ad30bf 100644
--- a/docs/file-system-development/storage-architecture.md
+++ b/docs/file-system-development/storage-architecture.md
@@ -1,7 +1,7 @@
 # The storage architecture: layers, boundaries, responsibilities
 
 > **Status:** the layered model below is the settled design
-> ([storage-stack-discussion.md](../storage-stack-discussion.md) records how it
+> ([storage-design-rationale.md](storage-design-rationale.md) records how it
 > was reached and what the surveyed systems taught). The data path — vfs
 > protocol, kernel mount routing, the FAT service, the block protocol,
 > usb-storage — is **built**. The volume manager, the driver's range
diff --git a/docs/storage-stack-discussion.md b/docs/file-system-development/storage-design-rationale.md
similarity index 93%
rename from docs/storage-stack-discussion.md
rename to docs/file-system-development/storage-design-rationale.md
index ed4856b..aaae7f9 100644
--- a/docs/storage-stack-discussion.md
+++ b/docs/file-system-development/storage-design-rationale.md
@@ -1,12 +1,16 @@
-# The storage stack: block, volumes, filesystems — a discussion
+# The storage design rationale: why the stack is shaped this way
 
-*2026-08-09. Design discussion, not a plan. The questions, verbatim: should the
-block protocol be separate from the VFS? how do channels work with these block
-devices? how should we wire up different filesystems? Grounded in a survey of how
-Minix 3, QNX Neutrino, Fuchsia, Redox, Plan 9, and Linux each answered the same
-questions, and in exactly where our own seams sit today. The layering rule this
-discussion serves: drivers are the lowest level (hardware only); VFS and the
-filesystems are higher layers; the protocol layer routes between them.*
+*2026-08-09. The design record behind
+[storage-architecture.md](storage-architecture.md): the survey, the
+trade-offs, and the decisions with their reasons — kept so future changes
+argue against the evidence rather than rediscovering it. The questions that
+drove it, verbatim: should the block protocol be separate from the VFS? how
+do channels work with these block devices? how should we wire up different
+filesystems? Grounded in how Minix 3, QNX Neutrino, Fuchsia, Redox, Plan 9,
+and Linux each answered the same questions, and in exactly where our own
+seams sat. The layering rule it serves: drivers are the lowest level
+(hardware only); VFS and the filesystems are higher layers; the protocol
+layer routes between them.*
 
 ## What the survey says, compressed