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.

core/dr-gpu/src/segment.rs

@@ -1,4 +1,4 @@
-//! Watershed segmentation — arm A's GPU half (S15, docs/segmentation.md).
+//! Watershed segmentation — arm A's GPU half (S15, docs/dev/segmentation.md).
 //!
 //! Runs the five passes in `shaders/watershed.wgsl` over a demosaiced image
 //! and leaves a basin label per pixel on the GPU. The hierarchy built from
@@ -20,7 +20,7 @@
 //! one AC-8 forbids is per frame in the render loop, and sharing a switch
 //! would force a build wanting local masking to unlock the other.
 //!
-//! It is still a real cost and still unfinished. F3 in docs/segmentation.md
+//! It is still a real cost and still unfinished. F3 in docs/dev/segmentation.md
 //! §12 stands: the adjacency accumulation belongs GPU-side with atomics, and
 //! until it moves there every segmentation pays a full-resolution transfer.
 //! Read the feature name as a description of a known gap rather than as
@@ -36,7 +36,7 @@ pub struct SegmentOptions {
     /// Longest proxy edge. The segmentation runs here, not at sensor
     /// resolution: a 24 MP watershed costs 12× the memory to place boundaries
     /// a person cannot see, and the boundary refinement that matters at 1:1
-    /// is a separate stage (docs/segmentation.md §4).
+    /// is a separate stage (docs/dev/segmentation.md §4).
     pub max_edge: u32,
     /// Pre-smoothing radius in proxy pixels. The caller's to raise with ISO —
     /// this is the single knob that decides whether a noisy file segments
@@ -69,7 +69,7 @@ impl Default for SegmentOptions {
             w_chroma: 0.5,
             // **Zero: the pass is off.** It is implemented, dispatched
             // correctly and measurably changes nothing — see the ignored test
-            // below and §12 of docs/segmentation.md. Until that is understood,
+            // below and §12 of docs/dev/segmentation.md. Until that is understood,
             // running it would buy 64 dispatches per segmentation and no
             // improvement, so the default declines to pay.
             plateau_iterations: 0,
@@ -486,7 +486,7 @@ impl Segmentation {
     /// a region graph of a few thousand nodes that every later interaction
     /// reads from the CPU anyway.
     ///
-    /// What it is *not* is finished. F3 in docs/segmentation.md §12 stands:
+    /// What it is *not* is finished. F3 in docs/dev/segmentation.md §12 stands:
     /// the adjacency accumulation belongs on the GPU with atomics, and until
     /// it moves there a segmentation costs one full-resolution transfer of the
     /// label and gradient buffers. That is a real cost on a phone and the
@@ -724,7 +724,7 @@ mod tests {
         px
     }
     #[test]
-    #[ignore = "the plateau pass is a measured no-op; see docs/segmentation.md §12"]
+    #[ignore = "the plateau pass is a measured no-op; see docs/dev/segmentation.md §12"]
     fn lower_completion_drains_a_plateau_instead_of_shattering_it() {
         // F1, asserted rather than eyeballed, and asserted at the level where
         // it matters.
@@ -741,7 +741,7 @@ mod tests {
         // with no exit anywhere — cannot be drained by a distance that has
         // nowhere to descend to, and collapsing it fully would need connected
         // component labelling rather than a local rule. It is not worth it:
-        // see docs/segmentation.md §12.
+        // see docs/dev/segmentation.md §12.
         let Some(ctx) = ctx() else { return };
         let (w, h) = (96u32, 96u32);
         let src = DemosaicedImage::from_rgba8(&ctx, &ramp(w, h), w, h).expect("source");

core/dr-gpu/src/shaders/watershed.wgsl

@@ -1,4 +1,4 @@
-// Watershed segmentation — the passes behind arm A of S15 (docs/segmentation.md).
+// Watershed segmentation — the passes behind arm A of S15 (docs/dev/segmentation.md).
 //
 // Seven entry points forming one chain:
 //
@@ -197,7 +197,7 @@ fn gradient(@builtin(global_invocation_id) gid: vec3<u32>) {
 // lowest-indexed neighbour, which is up and to the left. Each pixel therefore
 // walks diagonally until it falls off the plateau, and one flat region becomes
 // a fan of diagonal chains rather than one basin — visible as hatching across
-// what should be a single area (docs/segmentation.md §12, F1).
+// what should be a single area (docs/dev/segmentation.md §12, F1).
 //
 // The fix is the standard lower-completion: give each plateau pixel its
 // geodesic distance to the nearest pixel that *does* have a lower neighbour,