Put the developer docs under docs/dev and index the folder for users first

docs/ had 26 developer documents flat beside the manual, and the two
audiences are very differently sized: most readers want the manual and
the gesture reference, a few want the register, the designs and the
measurements. The manual and gestures.md stay at the top; everything for
someone changing the code moves to docs/dev/, and the two documents that
name their own successors — the v0.1 milestone and the UI-refinement plan
— go to docs/dev/archive/ rather than being deleted, since both are still
cited. docs/README.md is the index, users first.

Every reference follows: code comments, Cargo manifests, the workflows,
the pre-commit hook, the bench and traceability tools (which locate the
repo root by docs/dev/requirements.md now), packaging, the Docker READMEs,
CLAUDE.md, CONTRIBUTING.md and the README. The matrix links one level
deeper and is regenerated. Links out of the moved documents into the tree
gain a level; a link checker over every Markdown file finds none broken.

tools/bench/Cargo.toml

@@ -13,7 +13,7 @@ license.workspace = true
 # into a job that has no adapter to use them with, and adding `dr-ui` would
 # pull Slint. The GPU half of the suite is `dr-gpu`'s own frame-budget test,
 # which already exists and already skips itself where there is no device — see
-# `docs/benchmarks.md`.
+# `docs/dev/benchmarks.md`.
 [dependencies]
 dr-types.workspace = true
 dr-catalog.workspace = true

tools/bench/src/baseline.rs

@@ -1,6 +1,6 @@
 //! The committed numbers, and what counts as a regression against them.
 //!
-//! `docs/frame-budget.md` commits its measurements by hand and says why: *"a
+//! `docs/dev/frame-budget.md` commits its measurements by hand and says why: *"a
 //! regression should be a diff rather than somebody's memory."* This is the
 //! same idea in a form a program can read, because §8 asks for more than a
 //! record — *"a regression beyond stated tolerance fails the build"*.
@@ -80,7 +80,7 @@ pub struct Metric {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Baseline {
     /// Prose for whoever opens the JSON first. Kept in the file rather than
-    /// only in `docs/benchmarks.md`, because the person who finds this in a
+    /// only in `docs/dev/benchmarks.md`, because the person who finds this in a
     /// failing CI log is not reading the docs directory at that moment.
     #[serde(rename = "_readme")]
     pub readme: Vec<String>,
@@ -173,15 +173,15 @@ impl Baseline {
 
     /// Where the committed baseline lives, found the way `tools/traceability`
     /// finds the repo root: by walking up from this crate's manifest until
-    /// `docs/requirements.md` appears.
+    /// `docs/dev/requirements.md` appears.
     pub fn default_path() -> Result<PathBuf> {
         let mut dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
-        while !dir.join("docs/requirements.md").exists() {
+        while !dir.join("docs/dev/requirements.md").exists() {
             if !dir.pop() {
                 anyhow::bail!("could not locate the repo root above this crate");
             }
         }
-        Ok(dir.join("docs/bench-baseline.json"))
+        Ok(dir.join("docs/dev/bench-baseline.json"))
     }
 }
 

tools/bench/src/exporting.rs

@@ -16,7 +16,7 @@
 //!
 //! That is a deliberate refusal rather than an oversight. `CONTRIBUTING.md`
 //! asks that a requirement be closed by a test that would fail if the
-//! behaviour were removed, and `docs/code-health.md` CH-4 records what the
+//! behaviour were removed, and `docs/dev/code-health.md` CH-4 records what the
 //! coverage figure looks like when tags are hung on plumbing instead. A tag
 //! here would say the export budget is checked; the GPU half of it would still
 //! be unchecked.
@@ -26,7 +26,7 @@
 //! It is a **one-sided** gate, and that is worth having. The encode half is a
 //! lower bound on the whole: if resizing, sharpening and encoding 24 MP alone
 //! take longer than two seconds, NFR-P7 is violated no matter how fast the
-//! render is. So the budget in `docs/bench-baseline.json` is the requirement's
+//! render is. So the budget in `docs/dev/bench-baseline.json` is the requirement's
 //! own 2000 ms, and exceeding it fails the build honestly. Coming in under it
 //! proves nothing about the requirement, and the report says so rather than
 //! printing a tick.
@@ -64,7 +64,7 @@ const RUNS: usize = 5;
 
 /// A row of the export table.
 pub struct EncodeRun {
-    /// The name this row carries in `docs/bench-baseline.json`.
+    /// The name this row carries in `docs/dev/bench-baseline.json`.
     pub key: &'static str,
     pub label: &'static str,
     pub width: u32,

tools/bench/src/fixture.rs

@@ -1,6 +1,6 @@
 //! The synthetic 50k catalog, and the handful of real files it points at.
 //!
-//! `docs/requirements.md` §8 asks for "an automated benchmark suite against a
+//! `docs/dev/requirements.md` §8 asks for "an automated benchmark suite against a
 //! synthetic 50k catalog". The hard part of that sentence is *50k*: a real
 //! library of that size is several terabytes and cannot live in a repository,
 //! in a CI cache, or on a laptop that also has to compile the thing.

tools/bench/src/main.rs

@@ -1,4 +1,4 @@
-//! The benchmark suite `docs/requirements.md` §8 has been promising.
+//! The benchmark suite `docs/dev/requirements.md` §8 has been promising.
 //!
 //! §8 says performance is verified by *"an automated benchmark suite against a
 //! synthetic 50k catalog, run per-commit … A regression beyond stated
@@ -191,17 +191,17 @@ enum Mode {
 fn print_help() {
     println!(
         "\
-dr-bench — DarkRoom's performance suite (docs/requirements.md §8)
+dr-bench — DarkRoom's performance suite (docs/dev/requirements.md §8)
 
   run       measure and print, judging nothing
   check     measure, print, and exit 1 on a violated budget or a regression
-  record    measure and rewrite docs/bench-baseline.json from the result
+  record    measure and rewrite docs/dev/bench-baseline.json from the result
 
 Flags:
   --reference        this machine is the reference desktop, so machine-sensitive
                      budgets are asserted rather than reported
   --fixture <dir>    where the synthetic 50k catalog lives (or $DR_BENCH_DIR)
-  --baseline <file>  the committed numbers (default docs/bench-baseline.json)
+  --baseline <file>  the committed numbers (default docs/dev/bench-baseline.json)
   --lanes <n>        sweep lanes for the thumbnail row (default: CPU threads)
   --thumbnails <n>   images in the thumbnail row (default 1200)
 
@@ -307,8 +307,8 @@ fn measure_and_report(
     }
     println!();
     println!(
-        "  {} gate(s) failed. docs/benchmarks.md says what each metric measures and\n  \
-         docs/bench-baseline.json holds the numbers these used to be.",
+        "  {} gate(s) failed. docs/dev/benchmarks.md says what each metric measures and\n  \
+         docs/dev/bench-baseline.json holds the numbers these used to be.",
         failures.len()
     );
     Ok(mode != Mode::Gate)
@@ -453,7 +453,7 @@ fn print_verdict(
     machine: &str,
     comparable_fixture: bool,
 ) -> Vec<String> {
-    println!("Against docs/bench-baseline.json");
+    println!("Against docs/dev/bench-baseline.json");
     match (&base.recorded_on, cx.same_machine) {
         (None, _) => println!(
             "  No baseline has been recorded yet. Budgets are still gated; drift is not.\n  \