docs: sort the top-level directories into five sections by what the reader wants

Every docs directory moves under 1-getting-started, 2-handbook,
4-implementation or 5-project; the options reference (section 3) comes from
the website and has no directory here. trust-boundary stays whole under the
handbook for now. web-ui, swarm and tools split between handbook and
implementation, and the command-line references move to
2-handbook/reference. Links, path references in code and nix, and the docs
index follow the moves; no page content changes.

hive-c0re/src/workers/agent_sockets.rs

@@ -6,7 +6,7 @@
 //!
 //! Full mechanism — per-agent subdir bind-mount, `hyperhive-socket-bound`
 //! marker gate, gateway UDS upstream, 10s poll loop:
-//! `docs/networking/gateway.md::Per-agent unix-socket upstream`.
+//! `docs/4-implementation/networking/gateway.md::Per-agent unix-socket upstream`.
 
 use std::collections::BTreeMap;
 use std::path::{Path, PathBuf};

hive-c0re/src/workers/auto_update.rs

@@ -21,7 +21,7 @@
 //!    never while a rebuild of the agent is queued or running, so a closure
 //!    that fails to deploy does not restart its agent every interval.
 //!
-//! See `docs/scheduler/coordinator.md::Boot reconcile`.
+//! See `docs/4-implementation/scheduler/coordinator.md::Boot reconcile`.
 
 use std::collections::HashMap;
 use std::path::Path;

hive-c0re/src/workers/crash_watch.rs

@@ -4,7 +4,7 @@
 //! that line directly; see the module doc on [`emit_crash_transitions`].
 //! Login-state transitions (`needs_login`/`logged_in`) publish onto
 //! `swarm_notices` instead. The `RECENT_TRANSIENT_GRACE` window:
-//! `docs/agent-lifecycle/config-changes.md::System messages`.
+//! `docs/2-handbook/agent-lifecycle/config-changes.md::System messages`.
 
 use std::collections::HashSet;
 use std::sync::Arc;
@@ -150,7 +150,7 @@ fn emit_crash_transitions(coord: &Coordinator, prev: &HashSet<String>, current:
         // (`hh-container-crashed` in `nix/host-modules/swarm-grafana.nix`)
         // matches this exact message against the log store and pages the
         // operator directly — no agent (and no per-hive warning)
-        // in the loop. See `docs/scheduler/observability.md`.
+        // in the loop. See `docs/4-implementation/scheduler/observability.md`.
         tracing::warn!(agent = %stopped, "container crash detected");
     }
 }