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-agent/src/harness_state.rs

@@ -88,7 +88,7 @@ fn effort_from(configured: Option<&str>, file: Option<String>) -> (String, Sourc
 // (`hyperhive-rate-limited`, `hyperhive-needs-login`) that grew organically
 // and had no shared schema. A single JSON file is self-documenting, atomic
 // to write, and cheaper for hive-c0re to read on each sweep (one fopen vs
-// two stat calls). See `docs/agent-lifecycle/persistence.md::Harness state files`.
+// two stat calls). See `docs/2-handbook/agent-lifecycle/persistence.md::Harness state files`.
 //
 // Legacy sentinel files written by older harness builds are still honoured
 // by `read_harness_state` so in-place upgrades don't lose state (the new

hive-agent/src/identity.rs

@@ -1,7 +1,7 @@
 //! Agent identity helpers — short label + hive-qualified long name +
 //! human display names for the hive and swarm. Full env var surface +
 //! domain-vs-name distinction documented in
-//! `docs/process/conventions.md::Hive identity (label + domain + display names)`.
+//! `docs/5-project/process/conventions.md::Hive identity (label + domain + display names)`.
 
 use std::env;
 

hive-agent/src/login.rs

@@ -33,7 +33,7 @@ pub fn default_dir() -> PathBuf {
 /// exactly these to force re-login while preserving session-history files —
 /// so boot detection ([`has_session`]) and logout agree by construction.
 /// Rationale + the previous wholesale-wipe shape we replaced live in
-/// `docs/web-ui/agent.md::Per-agent endpoints`
+/// `docs/2-handbook/web-ui/agent.md::Per-agent endpoints`
 /// (the `/api/logout` bullet).
 ///
 /// `.credentials.json` is the actual OAuth session; `mcp-needs-auth-cache.json`
@@ -149,7 +149,7 @@ pub const NO_PRIOR_FAILURE: SystemTime = SystemTime::UNIX_EPOCH;
 /// `since` (keep waiting), a fresh login's mtime postdates it (resume) —
 /// including a login that lands *before* this call even starts polling,
 /// which an entry-snapshot comparison could miss entirely. Full rationale:
-/// `docs/turn-loop/::The loop`.
+/// `docs/4-implementation/turn-loop/::The loop`.
 ///
 /// # Panics
 ///

hive-agent/src/main.rs

@@ -4,7 +4,7 @@
 //! generic and testable. Sibling: `hive-agent-mcp` (the MCP server this
 //! loop points claude at).
 //! Architecture lives in
-//! `docs/turn-loop/::Harness binary shape`.
+//! `docs/4-implementation/turn-loop/::Harness binary shape`.
 //!
 //! Single bin crate: the module tree below (formerly this crate's `lib.rs`,
 //! before lib + bin were collapsed into one) plus the serve loop.
@@ -469,7 +469,7 @@ fn spawn_todo_socket(
 /// Boot — wires up the web UI, login state, stats, plugins, forge
 /// notifier, and either drops into `serve_loop` directly (`Online`) or
 /// parks on the login flow first (`NeedsLogin`). See
-/// `docs/turn-loop/README.md::Boot wiring`.
+/// `docs/4-implementation/turn-loop/README.md::Boot wiring`.
 async fn serve_main<S: Surface>(socket: &Path, poll_ms: u64) -> Result<()> {
     let port = std::env::var("HIVE_PORT")
         .ok()

hive-agent/src/otel_turn_metrics.rs

@@ -1,6 +1,6 @@
 //! Per-turn OTEL metric export for the fields Claude Code's own built-in
 //! OTEL integration cannot know about. Claude's own export already covers
-//! token usage and cost (see `docs/scheduler/observability.md`) —
+//! token usage and cost (see `docs/4-implementation/scheduler/observability.md`) —
 //! duplicating those here under different metric names would just give a
 //! collector two disagreeing series for the same number. This module emits
 //! only the harness-only concepts: wall-clock turn duration as *this harness*
@@ -326,7 +326,7 @@ fn build_provider(interval: Duration) -> anyhow::Result<SdkMeterProvider> {
     // OTLP client is required — `PeriodicReader` drives export from a
     // background thread with no Tokio reactor), and same rationale as
     // `hive-metric` for the resource (the SDK reads `OTEL_RESOURCE_ATTRIBUTES`
-    // — set container-wide, see `docs/scheduler/observability.md::Built-in resource
+    // — set container-wide, see `docs/4-implementation/scheduler/observability.md::Built-in resource
     // labels` — on its own; passing an explicit `Resource` here would need to
     // duplicate `agent`/`hive`/`swarm` this crate has no other reason to know).
     let exporter = MetricExporter::builder()

hive-agent/src/paths.rs

@@ -7,7 +7,7 @@
 //! Claude credentials live at `$HOME/.claude` (resolves to
 //! `/home/<agent-name>/.claude` because the harness service runs as a
 //! non-root unix user matching the agent label — see
-//! `docs/agent-lifecycle/persistence.md::First-boot agent-user migration`).
+//! `docs/2-handbook/agent-lifecycle/persistence.md::First-boot agent-user migration`).
 //!
 //! All three paths can be overridden via env vars (`HYPERHIVE_STATE_DIR`,
 //! `HYPERHIVE_HARNESS_DIR`, `HYPERHIVE_CLAUDE_DIR`) for dev / test scenarios.

hive-agent/src/prompt.rs

@@ -2,7 +2,7 @@
 //! HTML-comment markers gating role-specific and config-repo-specific
 //! blocks; this module assembles the final prompt (always "agent" role — there is only one
 //! role). Marker grammar + placeholder substitution rules in
-//! `docs/turn-loop/claude-invocation.md::On-boot files` (`claude-system-prompt.md`).
+//! `docs/4-implementation/turn-loop/claude-invocation.md::On-boot files` (`claude-system-prompt.md`).
 
 use std::path::{Path, PathBuf};
 use std::time::Duration;
@@ -22,7 +22,7 @@ const OPERATORS_TIMEOUT: Duration = Duration::from_secs(5);
 /// [`hive_sh4re::assets::prompt_template`]
 /// (`$HIVE_ASSETS_DIR/prompts/system.md`). Substitution placeholders +
 /// marker grammar documented in
-/// `docs/turn-loop/claude-invocation.md::On-boot files` (`claude-system-prompt.md`).
+/// `docs/4-implementation/turn-loop/claude-invocation.md::On-boot files` (`claude-system-prompt.md`).
 #[must_use]
 pub fn render(
     template: &str,

hive-agent/src/turn.rs

@@ -23,7 +23,7 @@ use crate::mcp_config;
 // auto-compaction and its cross-session auto-memory because hyperhive owns those
 // concerns (`/compact` on overflow, notes persistence under `/state`). How the
 // file is wired (the nix asset) + the full rationale live in
-// `docs/turn-loop/claude-invocation.md`. Unknown keys are silently ignored by
+// `docs/4-implementation/turn-loop/claude-invocation.md`. Unknown keys are silently ignored by
 // claude-code; if a key gets renamed we'll spot it because the corresponding
 // behavior will start firing mid-turn again.
 

hive-agent/src/vacuum.rs

@@ -11,7 +11,7 @@
 //! Trade-off (accepted — issue tracker "perms borked"): a misbehaving harness
 //! could skip its own cleanup, which the host-side version was meant to
 //! prevent. But a compromised harness is already inside the container trust
-//! boundary (`docs/trust-boundary/security.md`), and these are ephemeral local artifacts — so
+//! boundary (`docs/2-handbook/trust-boundary/security.md`), and these are ephemeral local artifacts — so
 //! the honest fix is to clean them up where they live.
 
 use std::path::Path;

hive-agent/src/web_ui/auth.rs

@@ -79,7 +79,7 @@ pub(super) async fn post_login_cancel(State(state): State<AppState>) -> Response
 /// The turn loop's next iteration parks into `wait_for_login` which
 /// resumes when a fresh credentials file appears via `/login/code`.
 /// Always returns 200 with a body describing what happened. See
-/// `docs/web-ui/agent.md::Per-agent endpoints`
+/// `docs/2-handbook/web-ui/agent.md::Per-agent endpoints`
 /// (the `/api/logout` bullet) for the three-step rationale +
 /// preservation invariants.
 pub(super) async fn post_logout(State(state): State<AppState>) -> Response {

hive-agent/src/web_ui/mod.rs

@@ -94,8 +94,8 @@ fn routes() -> Router<AppState> {
 ///
 /// `HIVE_WEB_SOCKET` opt-in selects unix-socket vs TCP binding; the
 /// dual-mode transition + gateway-side consumer live in
-/// `docs/web-ui/shape.md::Listener bind` and
-/// `docs/networking/gateway.md::Per-agent unix-socket upstream`.
+/// `docs/4-implementation/web-ui/shape.md::Listener bind` and
+/// `docs/4-implementation/networking/gateway.md::Per-agent unix-socket upstream`.
 ///
 /// # Errors
 ///
@@ -150,7 +150,7 @@ pub async fn serve(
     // `UnixListener` at the given path. Empty string treated as
     // unset so a stray `HIVE_WEB_SOCKET=` doesn't trap us into an
     // un-bindable empty path. Falls through to the TCP path below
-    // otherwise. See docs/networking/gateway.md::Per-agent unix-socket upstream
+    // otherwise. See docs/4-implementation/networking/gateway.md::Per-agent unix-socket upstream
     // for the gateway-side consumer.
     if let Some(socket_path) = std::env::var_os("HIVE_WEB_SOCKET")
         && !socket_path.is_empty()
@@ -181,7 +181,7 @@ pub async fn serve(
 /// to ask.
 ///
 /// Marker-gating + the gateway-side consumer: see
-/// `docs/networking/gateway.md::Per-agent unix-socket upstream`.
+/// `docs/4-implementation/networking/gateway.md::Per-agent unix-socket upstream`.
 fn bind_unix(path: &Path) -> Result<tokio::net::UnixListener> {
     use std::os::unix::fs::PermissionsExt;
     if let Some(parent) = path.parent() {
@@ -221,7 +221,7 @@ const MAX_BIND_ATTEMPTS: u32 = 12;
 /// not an unbounded wait).
 ///
 /// Retry rationale + dashboard-banner-on-real-collision:
-/// see `docs/web-ui/shape.md::Listener bind`.
+/// see `docs/4-implementation/web-ui/shape.md::Listener bind`.
 async fn bind_with_retry(addr: SocketAddr, label: &str) -> Result<tokio::net::TcpListener> {
     let mut retries = 0u32;
     let bound = (|| async { try_bind(addr) })

hive-agent/src/web_ui/state.rs

@@ -164,7 +164,7 @@ pub(super) struct StateSnapshot {
     /// Navigation links for this agent page. Also served via
     /// `DashboardState.links` (`GET /api/dashboard-state`) for the
     /// dashboard card's icon strip. Both are produced by `agent_links()`
-    /// — single source of truth. See [`docs/web-ui/dashboard.md::Container row`]
+    /// — single source of truth. See [`docs/2-handbook/web-ui/dashboard.md::Container row`]
     /// for the frontend resolver + which links appear in which conditions.
     links: Vec<AgentLink>,
     /// Public URL of the forge (e.g.
@@ -305,7 +305,7 @@ fn read_own_status() -> (Option<String>, Option<i64>) {
 /// for `External`; the frontend resolves each against its `kind`
 /// against the right base so the backend never has to guess the
 /// operator's browser host. See
-/// `docs/web-ui/dashboard.md::Container row` for
+/// `docs/2-handbook/web-ui/dashboard.md::Container row` for
 /// the resolver + how `deployed:<sha>` ships alongside.
 ///
 /// Icons are real emoji, not unicode arrow/geometric glyphs — mara: