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/examples/frame_budget.rs

@@ -1,6 +1,6 @@
 //! What a frame actually costs — the measurement FR-DSP-2 is waiting on.
 //!
-//! `docs/display-and-extension.md` §2 argues that tiled computation predates
+//! `docs/dev/display-and-extension.md` §2 argues that tiled computation predates
 //! the fused-shader design and may not need to exist: the composer folds every
 //! active operation into **one dispatch over a viewport-sized target**, so the
 //! problem tiles were invented to solve may already be solved. That argument
@@ -28,7 +28,7 @@
 //! the per-frame CPU half is dominated by shader-source assembly, which is
 //! string formatting and is several times slower unoptimised.
 //!
-//! The committed numbers live in `docs/frame-budget.md`. Rerun this and diff
+//! The committed numbers live in `docs/dev/frame-budget.md`. Rerun this and diff
 //! that file; a regression should be a diff rather than somebody's memory.
 //!
 //! # Why the 99th percentile and not the mean

core/dr-gpu/examples/segment.rs

@@ -1,6 +1,6 @@
 //! Segment an image and write the granularity ladder as false-coloured PPMs.
 //!
-//! The whole point of S15 step 2 (docs/segmentation.md §11): look at the
+//! The whole point of S15 step 2 (docs/dev/segmentation.md §11): look at the
 //! ladder and decide whether clicking through it would land on the things a
 //! person means. No amount of design settles that — the pictures do.
 //!

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,

core/dr-gpu/tests/frame_budget.rs

@@ -2,11 +2,11 @@
 //!
 //! FR-DSP-3 says a slider updates the visible region within one frame budget at
 //! proxy resolution. Until this file existed nothing checked it, which made it
-//! a wish — `docs/display-and-extension.md` §3 is blunt about that, and §7 is
+//! a wish — `docs/dev/display-and-extension.md` §3 is blunt about that, and §7 is
 //! blunt about what tagging an unchecked requirement does to the coverage
 //! figure.
 //!
-//! The measurements this guards are in [`docs/frame-budget.md`], produced by
+//! The measurements this guards are in [`docs/dev/frame-budget.md`], produced by
 //! `examples/frame_budget.rs`. This file is the part of them that has to keep
 //! being true: it renders the **whole point-operation chain** through the real
 //! `render_detailed` for a hundred frames, moving a slider between each, and
@@ -17,7 +17,7 @@
 //! **The neighbourhood stage is deliberately not in the asserted chain.** It is
 //! over the budget today — clarity alone is 34 ms at 4K, because its kernel is
 //! a fraction of the frame and reaches a 52-pixel radius there — and
-//! `docs/frame-budget.md` records that, names the fix (a base computed at
+//! `docs/dev/frame-budget.md` records that, names the fix (a base computed at
 //! reduced resolution) and does not pretend otherwise. Asserting a budget the
 //! code does not meet would produce a red suite that everyone learns to ignore;
 //! asserting it on a chain that quietly excluded the expensive stage *without
@@ -81,7 +81,7 @@ const SOURCE: (u32, u32) = (6000, 4000);
 /// The viewport the budget is asserted at: a 16:10 desktop display.
 ///
 /// Not 4K, and the reason is worth stating. At 4K the fused chain still passes
-/// with room to spare (4.5 ms of GPU; see `docs/frame-budget.md`), but a test
+/// with room to spare (4.5 ms of GPU; see `docs/dev/frame-budget.md`), but a test
 /// that renders 8.3 M pixels a hundred times twice over is four seconds of
 /// suite time to re-establish a conclusion 4.1 M pixels already establishes.
 const VIEWPORT: (u32, u32) = (2560, 1600);
@@ -166,7 +166,7 @@ impl Run {
             judged <= BUDGET_MS,
             "{case} at {}x{}: p99 of {FRAMES} frames was {judged:.2} ms, over the \
              {BUDGET_MS:.0} ms budget (cpu {:.2} ms, gpu {:.2} ms, total {:.2} ms). \
-             FR-DSP-3 is what this violates; docs/frame-budget.md holds the \
+             FR-DSP-3 is what this violates; docs/dev/frame-budget.md holds the \
              numbers it used to be.",
             viewport.0,
             viewport.1,

core/dr-gpu/tests/local_contrast.rs

@@ -326,7 +326,7 @@ fn a_proxy_and_an_export_agree_about_the_effect() {
 
 #[test]
 fn crossing_the_reduction_threshold_does_not_change_the_picture() {
-    // TRACES: FR-DSP-3 — `docs/technical-debt.md` TD-4, held in pixels.
+    // TRACES: FR-DSP-3 — `docs/dev/technical-debt.md` TD-4, held in pixels.
     //
     // Clarity's base is computed on a reduced grid, and how reduced depends on
     // the viewport: `LocalContrast::reduction` steps 4 -> 2 -> 1 as sigma

core/dr-gpu/tests/zoom_resolution.rs

@@ -10,7 +10,7 @@
 //! code path — the zoom is the full-resolution path — which is why the
 //! requirement has been satisfied for some time without anyone tagging it.
 //!
-//! `docs/display-and-extension.md` §7 is the reason this file exists rather
+//! `docs/dev/display-and-extension.md` §7 is the reason this file exists rather
 //! than a tag on `framing.rs`: a requirement counts as covered when a `TRACES`
 //! comment names it, and nothing checks that the code under the tag does the
 //! thing. `FR-DEV-8` is tagged against plumbing a future operation would use.