docs: restructure into topic subdirectories, collapse duplicated index

Per mara's go-ahead on hyperhive#3902 ("getting started is good, but
terminal rendering does not go in there i think"):

Moved 21 top-level docs/*.md files into 7 new topic subdirectories
(existing web-ui/, turn-loop/, swarm/, tools/, crates/ untouched):
  getting-started/  setup.md
  agent-lifecycle/  agent-hierarchy.md, approvals.md, persistence.md
  trust-boundary/   boundary.md, security.md
  integrations/     forge.md, matrix.md, github.md, knowledge.md
  networking/       gateway.md, network.md, snapshot-store.md
  scheduler/        jobq.md, coordinator.md, ci.md, observability.md
  process/          conventions.md, gotchas.md, pr-review-gate.md
  web-ui/           terminal-rendering.md (moved into the EXISTING dir,
                    per mara's correction to the original getting-started
                    guess -- it's UI implementation detail, not onboarding)

The physical layout now matches docs/README.md's own topical headers,
which already amounted to this taxonomy -- see the scoping comment on
the issue for the two findings that motivated this (a genuine
duplication between CLAUDE.md's old "Reading paths" list and
docs/README.md's grouped one, since drifted out of sync with each
other; and the flat layout not matching the grouping we already had).

Fixed every cross-reference this moved across the whole repo (~120
files: docs/ internal links at every depth, Rust doc comments, nix
module option docs, crate READMEs) -- verified two ways: a grep sweep
confirming zero remaining references to any old path, and a script
that resolves every markdown link in docs/**/*.md + CLAUDE.md +
README.md against the filesystem and reports anything that doesn't
exist (zero broken links).

Collapsed CLAUDE.md's "Reading paths" section (the duplicate) down to
a pointer at docs/README.md, now the single index. Rewrote
docs/README.md itself to use the new subdirectory paths and added the
one doc it was missing that CLAUDE.md's old copy had (pr-review-gate.md).

Classified all 22 docs/*.md files first via a haiku subagent (mara's
suggestion) on two axes -- proposed grouping and operator-vs-
implementation focus -- before finalizing the taxonomy; spot-checked
the report and found internal inconsistencies (its classification
table disagreed with its own summary section for a few files), so this
taxonomy is my original proposal + the one correction mara gave
directly, not a blind application of the subagent's table. The
operator-focus data it gathered is still useful for a follow-up
content pass (docs skewing 'mixed' rather than pure operator-facing),
not addressed in this PR -- structure only.

nix fmt clean, both pre-push lints clean.

hive-c0re/src/agent_config/topology.rs

@@ -9,9 +9,9 @@
 //! `lifecycle::set_nspawn_flags` for the consumer.
 //!
 //! Format, rationale, read/reconcile/inject/surface flow, and target
-//! enforcement semantics: `docs/agent-hierarchy.md::Current state`.
+//! enforcement semantics: `docs/agent-lifecycle/agent-hierarchy.md::Current state`.
 //! `<parent>` sentinel resolution (delivered by [`resolve_recipient`]):
-//! `docs/conventions.md::Recipient sentinels`.
+//! `docs/process/conventions.md::Recipient sentinels`.
 //!
 //! ## Graph representation
 //!
@@ -109,7 +109,7 @@ pub fn top_level_agents_in(topo: &BTreeMap<String, Option<String>>) -> Vec<Strin
 /// straight into [`crate::broker::Broker::send`] without
 /// borrow-juggling around the temporary lookup.
 ///
-/// Rules + rationale: `docs/conventions.md::Recipient sentinels`.
+/// Rules + rationale: `docs/process/conventions.md::Recipient sentinels`.
 /// Fast path: ordinary recipient names short-circuit before any
 /// disk read — only `<parent>` triggers `read()` on `topology.json`.
 #[must_use]
@@ -262,7 +262,7 @@ pub fn default_seed(agent_names: &[String]) -> BTreeMap<String, Option<String>>
 /// powers come from the privileged MCP socket, not its tree
 /// position. The cycle walk below covers "moving X under its own
 /// descendant" for the manager as much as any other agent.
-/// `docs/agent-hierarchy.md::Current state` has the rationale.
+/// `docs/agent-lifecycle/agent-hierarchy.md::Current state` has the rationale.
 pub fn apply_set_parent(
     topo: &BTreeMap<String, Option<String>>,
     child: &str,

hive-c0re/src/container_view.rs

@@ -53,7 +53,7 @@ pub struct ContainerView {
     /// indentation. Sourced from `meta/topology.json` (single source of
     /// truth, hive-c0re-owned) — NOT from per-agent agent.nix, because
     /// an agent shouldn't be able to unilaterally declare its own place
-    /// in the tree. See `docs/agent-hierarchy.md::Current state`.
+    /// in the tree. See `docs/agent-lifecycle/agent-hierarchy.md::Current state`.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub parent: Option<String>,
     /// The Claude model the agent's harness is currently using, read from

hive-c0re/src/coordinator.rs

@@ -867,7 +867,7 @@ impl Coordinator {
     /// `_or_root` resolves to the literal string `"<root>"` when the
     /// slot is `None`, keeping the wording consistent with the
     /// `<parent>` sentinel's "root → operator" routing (see
-    /// `docs/conventions.md::Recipient sentinels`). The
+    /// `docs/process/conventions.md::Recipient sentinels`). The
     /// notifications fire as ordinary broker messages with
     /// `from = hive_sh4re::manager::SYSTEM_SENDER` so the dashboard renders
     /// them under the existing system-source styling.

hive-c0re/src/dashboard/mod.rs

@@ -214,7 +214,7 @@ pub async fn serve(
             webhook_secret,
         });
     // Binds loopback-only; external access via gateway.
-    // Rationale: docs/gateway.md::Firewall posture.
+    // Rationale: docs/networking/gateway.md::Firewall posture.
     let addr = SocketAddr::from(([127, 0, 0, 1], port));
     let listener = bind_with_retry(addr).await?;
     tracing::info!(%addr, "dashboard listening");

hive-c0re/src/dashboard/state_files.rs

@@ -2,7 +2,7 @@
 //!
 //! `GET /api/state-file?path=…` serves an allow-listed file (per-agent
 //! `state/` or `shared/`) with defense-in-depth symlink + traversal checks
-//! (see `docs/security.md::State-file endpoint`); raster images are served
+//! (see `docs/trust-boundary/security.md::State-file endpoint`); raster images are served
 //! with their real content-type, everything else as truncated text.
 //! `scan_validated_paths` runs the same allow-list at broker-message ingest
 //! so dashboard events carry a pre-verified file-ref set.
@@ -19,7 +19,7 @@ use crate::paths::{AGENTS_ROOT, SHARED_ROOT};
 #[derive(Deserialize, IntoParams)]
 pub(super) struct StateFileQuery {
     /// Absolute path under an agent's `state/` dir or under `shared/`;
-    /// checked against the allow-list (`docs/security.md::State-file
+    /// checked against the allow-list (`docs/trust-boundary/security.md::State-file
     /// endpoint`).
     path: String,
 }
@@ -27,7 +27,7 @@ pub(super) struct StateFileQuery {
 /// Resolve a caller-supplied path against the allow-listed roots
 /// (`agents/<n>/state/` and `shared/`). Applies defense-in-depth
 /// symlink + traversal checks before serving. Security model and
-/// all five layers: `docs/security.md::State-file endpoint`.
+/// all five layers: `docs/trust-boundary/security.md::State-file endpoint`.
 fn resolve_state_path(
     raw: &str,
 ) -> std::result::Result<(std::path::PathBuf, std::fs::Metadata), String> {

hive-c0re/src/dashboard/state_snapshot.rs

@@ -89,7 +89,7 @@ pub(super) struct StateSnapshot {
     /// runtime-generated `agents.conf` include file — see
     /// `gateway_nginx.rs`). The `false` branch (direct
     /// `http://<hostname>:<port>/` TCP links) is retained as a defensive
-    /// fallback for the env being unset. See `docs/gateway.md::Vhost map`.
+    /// fallback for the env being unset. See `docs/networking/gateway.md::Vhost map`.
     gateway_enabled: bool,
     /// Public URL of the forge (e.g.
     /// `"https://forge.pr1ma.darkest.space"`). Sourced from the

hive-c0re/src/forge/mod.rs

@@ -2,7 +2,7 @@
 //! config-repo mirroring, meta read-access grants. Also seeds
 //! `internal/docs` — a private repo every agent gets read-only
 //! collaborator access to for operator-curated shared content.
-//! No-op when `hive-forge` isn't running. Full design: `docs/forge.md`.
+//! No-op when `hive-forge` isn't running. Full design: `docs/integrations/forge.md`.
 
 mod ci_runner;
 pub mod config_pr_poll;

hive-c0re/src/forge/users.rs

@@ -59,7 +59,7 @@ fn config_org_avatar_png_path() -> std::path::PathBuf {
     ))
 }
 /// Per-agent token scopes (broad-but-not-admin) for tokens hive-c0re
-/// mints itself on the **internal** forge. See `docs/forge.md::Token
+/// mints itself on the **internal** forge. See `docs/integrations/forge.md::Token
 /// scopes` for the per-scope rationale. Not `pub(super)` — external
 /// forges (`dashboard/extra_forges.rs`) take an operator-pasted token
 /// verbatim, so their scope is whatever the operator's remote account
@@ -70,7 +70,7 @@ const TOKEN_SCOPES: &str = "read:user,write:user,read:notification,write:notific
 /// top of `TOKEN_SCOPES` so the host daemon can drive
 /// `/api/v1/admin/*`. Site-admin membership alone isn't enough: the
 /// token's own scope gate runs before the user-permission check.
-/// See `docs/forge.md::Token scopes`.
+/// See `docs/integrations/forge.md::Token scopes`.
 const CORE_TOKEN_SCOPES: &str = "read:admin,write:admin,read:user,write:user,read:notification,write:notification,write:repository,write:issue,write:organization,write:misc";
 
 /// Pull the access token out of forgejo's success message. Format
@@ -242,7 +242,7 @@ pub(super) async fn ensure_user_email(name: &str) {
         }
         Err(e) if is_forbidden(&e) => {
             // Core token missing admin scope — see
-            // `docs/forge.md::Token scopes` migration note.
+            // `docs/integrations/forge.md::Token scopes` migration note.
             tracing::warn!(
                 %name, %email, error = %e,
                 "forge: PATCH user email forbidden — core token likely missing admin scope. \

hive-c0re/src/gateway_nginx.rs

@@ -2,7 +2,7 @@
 //! `/agent/<name>/` location blocks. Writes
 //! `/var/lib/hive-gateway/conf/agents.conf` on every topology change.
 //! UDS upstream selection, the reload trigger, and idempotency:
-//! `docs/gateway.md::Per-agent unix-socket upstream`.
+//! `docs/networking/gateway.md::Per-agent unix-socket upstream`.
 
 use anyhow::{Context, Result};
 use std::fmt::Write as _;
@@ -173,7 +173,7 @@ fn render(names: &[String], frontend_dir: Option<&str>) -> String {
 /// It stays an explicit trigger rather than a systemd path
 /// unit watching the file: the write already knows it changed something,
 /// and a watcher would turn one causal edge into a race with the writer's
-/// own rename (see `docs/gateway.md`).
+/// own rename (see `docs/networking/gateway.md`).
 ///
 /// The priv call is best-effort — a failed sync is logged but not fatal.
 /// `reload_if_pending` retries on the next `spawn_poll` tick so a

hive-c0re/src/job_queue/mod.rs

@@ -24,7 +24,7 @@
 //! The queue is runtime-only (no persistence): an empty graph on boot; desired
 //! state is re-derived by the reconcile sweep. A single scheduler task
 //! ([`scheduler::run_worker`]) drives it; concurrency comes from the build-slot
-//! capacity, not multiple workers. Design: `docs/coordinator.md::Job queue`.
+//! capacity, not multiple workers. Design: `docs/scheduler/coordinator.md::Job queue`.
 
 pub mod exec;
 pub mod model;

hive-c0re/src/job_queue/model.rs

@@ -9,7 +9,7 @@
 //! execution, build-log, cancel, and the dashboard group (a group root's
 //! subtree *is* the group). A DAG used to be a second level above it, with
 //! its own store and its own id; there is no container node any more, so a
-//! job is exactly the nodes it declared. See `docs/coordinator.md::Job queue`
+//! job is exactly the nodes it declared. See `docs/scheduler/coordinator.md::Job queue`
 //! for the full design.
 
 pub use hive_host_sock::jobs::{PermPayload, State};
@@ -206,7 +206,7 @@ pub enum NodeKind {
     ///
     /// Its children declare no resources and borrow these grants, which is what
     /// lets `Prebuild` run beside the `Signal` → `Drain` window. Why braces
-    /// exist and what they cost: `docs/coordinator.md`, _Braces_.
+    /// exist and what they cost: `docs/scheduler/coordinator.md`, _Braces_.
     AgentWindow { agent: String },
     /// Deploy phase 1 — **verify only, mutates nothing.** Drift-gate the
     /// approval's PR head, fetch it into the applied repo, and eval-verify the

hive-c0re/src/job_queue/templates.rs

@@ -8,12 +8,12 @@
 //! **The one sanctioned exception is a brace** — a pure-resource-holder root
 //! ([`NodeKind::AgentWindow`], [`NodeKind::DeployWindow`]) declaring for a
 //! coordinated subtree whose members then declare nothing. See
-//! `docs/coordinator.md`, _Braces_ — which also carries the per-operation DAG
+//! `docs/scheduler/coordinator.md`, _Braces_ — which also carries the per-operation DAG
 //! shapes, so they are not restated here.
 //!
 //! Nodes are **named, not counted** — a template holds the handle
 //! [`JobBuilder::node`] hands back, so an edge says which node it waits on. Why that
-//! removes submit-time cycle validation: `docs/coordinator.md`.
+//! removes submit-time cycle validation: `docs/scheduler/coordinator.md`.
 //!
 //! The hive-wide **power ops** (`stop` / `start` / `restart`) are NOT here:
 //! their per-agent shape depends on live running state (an async
@@ -203,7 +203,7 @@ impl<'a> RebuildRoots<'a> {
 
 /// The rebuild node subtree — three group roots (`MetaSync`, the `AgentWindow`
 /// brace, `Reconcile`). `after`, when given, is the node it chains behind. The
-/// shape itself is in `docs/coordinator.md`; the code below is the source of
+/// shape itself is in `docs/scheduler/coordinator.md`; the code below is the source of
 /// truth for it, so only the three choices a reader would otherwise undo are
 /// called out here:
 ///

hive-c0re/src/job_queue/tests.rs

@@ -579,7 +579,7 @@ fn rebuild_chain_declares_its_resources_on_the_brace() {
     // ⚠️ **The rename is a reversal, not tidying.** The old name asserted "the
     // slot follows the nix work and the lease follows the container" — each node
     // declaring what it personally needed. The brace inverts that for a
-    // coordinated subtree; see `docs/coordinator.md`, _Braces_.
+    // coordinated subtree; see `docs/scheduler/coordinator.md`, _Braces_.
     //
     // (`hive_jobq` owns slot *fairness*, pinned there by
     // `a_contended_resource_goes_to_the_oldest_waiter`. What is c0re's is

hive-c0re/src/lifecycle/host_config.rs

@@ -85,7 +85,7 @@ fn config_bind_source(name: &str) -> PathBuf {
 }
 
 /// Append bind flags for `child`'s state and config dirs into `binds`.
-/// See docs/persistence.md ("Parent access to child state") for what a
+/// See docs/agent-lifecycle/persistence.md ("Parent access to child state") for what a
 /// parent may touch and why. Creates missing host-side directories so
 /// nspawn doesn't refuse to start; missing dirs are non-fatal.
 ///
@@ -134,7 +134,7 @@ fn bind_child_agent_dirs(child: &str, binds: &mut Vec<BindMount>) {
 /// that hive-c0re owns: `PRIVATE_NETWORK` (always 1), `HOST_ADDRESS` (the
 /// bridge gateway IP) and `EXTRA_NSPAWN_FLAGS` (the runtime-dir bind). What
 /// those network vars mean and why isolation is unconditional:
-/// `docs/network.md` § *What the Rust side does*.
+/// `docs/networking/network.md` § *What the Rust side does*.
 ///
 /// ⚠️ The start script expands `$EXTRA_NSPAWN_FLAGS` unquoted into the
 /// `systemd-nspawn` command.

hive-c0re/src/lifecycle/mod.rs

@@ -94,7 +94,7 @@ pub fn agent_web_port(name: &str) -> u16 {
 ///
 /// `HIVE_NETWORK_SUBNET` carries the host-side bridge address verbatim
 /// (e.g. `10.42.0.1/24`), **not** the canonical network address — see
-/// the note in `set_nspawn_flags` + `docs/network.md`. The IP part is
+/// the note in `set_nspawn_flags` + `docs/networking/network.md`. The IP part is
 /// therefore the bridge IP itself: the host end of the bridge, the
 /// default-route target for isolated containers, and the address the
 /// hive dnsmasq resolver binds. Returns the dotted-decimal IP with the
@@ -522,7 +522,7 @@ pub async fn converge_start_preamble(
 /// activation-error shape), retry once via stop + kill + start before
 /// giving up. Used by the queue's fast-lane `Start` handler and the
 /// inline start-after-rebuild path.
-/// See `docs/coordinator.md::Cold-start fallback`.
+/// See `docs/scheduler/coordinator.md::Cold-start fallback`.
 ///
 /// Requires a [`StartableAgent`] token from [`converge_start_preamble`]
 /// to prove the preamble ran. For internal use within this module (where
@@ -701,8 +701,8 @@ pub async fn destroy(name: &str) -> Result<()> {
 /// Pre-build `system.build.toplevel` against `meta#<name>` so the
 /// subsequent `nixos-container update` finds the result cached and
 /// skips straight to the profile-swap. Store-warming only — container
-/// is untouched. See `docs/coordinator.md::Rebuild path` for why
-/// the prebuild happens before stop, and `docs/coordinator.md::Prebuild
+/// is untouched. See `docs/scheduler/coordinator.md::Rebuild path` for why
+/// the prebuild happens before stop, and `docs/scheduler/coordinator.md::Prebuild
 /// attr path` for why the explicit nixosConfigurations attr is required.
 ///
 /// `node_id` is the queue node this build belongs to, when there is one —

hive-c0re/src/main.rs

@@ -528,7 +528,7 @@ async fn cmd_serve(
     // Also retries any pending gateway nginx reload that failed on
     // the previous tick. write() is idempotent so steady-state cost
     // is one stat per agent per tick.
-    // See `docs/gateway.md::Per-agent unix-socket upstream`.
+    // See `docs/networking/gateway.md::Per-agent unix-socket upstream`.
     agent_sockets::spawn_poll();
     // MCP socket listener startup sync: one-shot sweep that re-registers any
     // running agent container whose MCP listener was lost when hive-c0re

hive-c0re/src/matrix.rs

@@ -4,7 +4,7 @@
 //! haven't flipped `services.hyperhive.deploy.matrix.enable = true` pay
 //! nothing.
 //!
-//! See `docs/matrix.md::Provisioning flow (registration token)` for
+//! See `docs/integrations/matrix.md::Provisioning flow (registration token)` for
 //! the full UIAA round-trip, token-file shape, and host/container
 //! bind-mount layout.
 
@@ -744,7 +744,7 @@ pub async fn ensure_user_for(
     tracing::info!(%name, "matrix: provisioned access token");
 
     // Kick the daemon so it picks up the new token without waiting for a
-    // full container restart — see docs/matrix.md::Provisioning flow.
+    // full container restart — see docs/integrations/matrix.md::Provisioning flow.
     if let Err(e) = crate::priv_client::restart_matrix_daemon(name).await {
         tracing::warn!(%name, error = ?e, "matrix: could not restart hive-matrix-daemon (token written; daemon will reload on next container start)");
     } else {

hive-c0re/src/meta.rs

@@ -2,7 +2,7 @@
 //! exports one `nixosConfiguration` per agent and drives the system-wide
 //! deploy audit trail. Flow (`sync_agents`, two-phase `prepare_deploy` /
 //! `finalize_deploy` / `abort_deploy`, `lock_update_hyperhive`):
-//! `docs/approvals.md::Meta flake`.
+//! `docs/agent-lifecycle/approvals.md::Meta flake`.
 
 use std::path::Path;
 
@@ -162,7 +162,7 @@ pub async fn sync_agents(hive: &HiveEnv, agents: &[AgentSpec]) -> Result<()> {
     // (`HIVE_WEB_SOCKET`); the gateway routes via this map, falling back
     // to a computed TCP loopback port (`lifecycle::agent_web_port`) only
     // while an agent's socket marker is absent. Best-effort + non-fatal.
-    // See `docs/gateway.md::Per-agent unix-socket upstream`.
+    // See `docs/networking/gateway.md::Per-agent unix-socket upstream`.
     if let Err(e) = crate::agent_sockets::write(&agent_names) {
         tracing::warn!(error = ?e, "agent_sockets::write failed (non-fatal)");
     }
@@ -249,7 +249,7 @@ pub async fn prepare_deploy(name: &str, node_id: Option<u64>) -> Result<()> {
     let input = format!("agent-{name}");
     // Re-lock the agent input against the LOCAL applied mirror, not the
     // persistent forge URL declared in the meta flake (see the `## Meta flake`
-    // note in docs/approvals.md): the deploy must build the exact reviewed
+    // note in docs/agent-lifecycle/approvals.md): the deploy must build the exact reviewed
     // config that `verify_commit` gated and `applied/<n>/main` was
     // fast-forwarded to, and it must keep working when the forge is
     // unreachable (rebuilds fire on crash-restart / meta bumps too, not just

hive-c0re/src/migrate.rs

@@ -16,7 +16,7 @@
 //!   from birth does not need re-asserting each morning.
 //!
 //! Kill-switch: `HIVE_SKIP_META_MIGRATION=1`. Full sequence and phase
-//! details: `docs/approvals.md::Migration from the pre-tag`.
+//! details: `docs/agent-lifecycle/approvals.md::Migration from the pre-tag`.
 
 use std::path::Path;
 use std::sync::Arc;

hive-c0re/src/socket_server/mod.rs

@@ -1073,7 +1073,7 @@ pub(crate) fn handle_send(
     // Resolve magic-recipient sentinels (`<parent>`) against topology.json;
     // no-op for ordinary names. Lets agents address structural roles without
     // learning the label — runtime reparenting propagates for free. See
-    // `docs/conventions.md::Recipient sentinels`.
+    // `docs/process/conventions.md::Recipient sentinels`.
     let resolved = crate::topology::resolve_recipient(agent, to);
     // Validate that the resolved recipient is a known local agent or the
     // special "operator" recipient. Without this check a typo in `to`

hive-c0re/src/stats/container_stats.rs

@@ -12,7 +12,7 @@
 //! No network: agents share the host network namespace
 //! (`privateNetwork = false`), so there is no per-container net
 //! counter to read. Per-agent network only becomes meaningful with the
-//! netns-isolation roadmap (`docs/network.md`).
+//! netns-isolation roadmap (`docs/networking/network.md`).
 //!
 //! CPU is cumulative (`usage_usec` is monotonic), so a single read is
 //! meaningless — we sample every machine's counter, sleep one short

hive-c0re/src/stores/build_logs.rs

@@ -1,7 +1,7 @@
 //! Sqlite-backed full build-log capture — stdout + stderr per
 //! `nixos-container` / `nix build` invocation, accumulated live.
 //! Schema, indices, retention, and the rationale for replacing
-//! the old ring buffer: `docs/persistence.md::/var/lib/hyperhive/db/build_logs.sqlite`.
+//! the old ring buffer: `docs/agent-lifecycle/persistence.md::/var/lib/hyperhive/db/build_logs.sqlite`.
 
 use std::path::Path;
 use std::sync::{Arc, Mutex, OnceLock};

hive-c0re/src/stores/scheduled_prompts.rs

@@ -4,13 +4,13 @@
 //! `interval_seconds` and re-arm `next_fire_at` on delivery;
 //! one-shots are reaped.
 //!
-//! Schema + retention: `docs/persistence.md::/var/lib/hyperhive/db/broker.sqlite`
+//! Schema + retention: `docs/agent-lifecycle/persistence.md::/var/lib/hyperhive/db/broker.sqlite`
 //! (the `scheduled_prompts` / `scheduled_prompt_targets` table bullets).
 //! Submit paths (operator-direct vs `ApprovalKind::SchedulePrompt`,
 //! plus why even agent-self schedules go through approval):
-//! `docs/approvals.md::Scheduled prompts (submit paths)`.
+//! `docs/agent-lifecycle/approvals.md::Scheduled prompts (submit paths)`.
 //! Catch-up clamp on resume + per-target tombstoning:
-//! `docs/approvals.md::Scheduled prompt worker (catch-up clamp)`.
+//! `docs/agent-lifecycle/approvals.md::Scheduled prompt worker (catch-up clamp)`.
 
 use std::path::Path;
 use std::sync::Mutex;

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/gateway.md::Per-agent unix-socket upstream`.
+//! `docs/networking/gateway.md::Per-agent unix-socket upstream`.
 
 use std::collections::BTreeMap;
 use std::path::{Path, PathBuf};

hive-c0re/src/workers/auto_update.rs

@@ -14,7 +14,7 @@
 //!    path are skipped — nothing changed, no nix work to do.
 //!
 //! Booting with no config change performs no meta commit — only
-//! reconciles. See `docs/coordinator.md::Boot reconcile`.
+//! reconciles. See `docs/scheduler/coordinator.md::Boot reconcile`.
 
 use std::path::Path;
 use std::sync::Arc;

hive-c0re/src/workers/crash_watch.rs

@@ -1,7 +1,7 @@
 //! Per-container crash and login-state watcher. Polls every managed
 //! container on a 10s interval. Fires `ContainerCrash`, `LoggedIn`,
 //! and `NeedsLogin` helper events. Event semantics and the
-//! `RECENT_TRANSIENT_GRACE` window: `docs/approvals.md::Helper events`.
+//! `RECENT_TRANSIENT_GRACE` window: `docs/agent-lifecycle/approvals.md::Helper events`.
 
 use std::collections::HashSet;
 use std::sync::Arc;

hive-c0re/src/workers/scheduled_prompts_worker.rs

@@ -1,7 +1,7 @@
 //! Background loop that drains due `scheduled_prompts` rows and fans
 //! the body to each active target. 5s poll cadence, shutdown-aware.
 //! Catch-up clamp, missing-target handling, and broker-error retry
-//! semantics: `docs/approvals.md::Scheduled prompt worker`.
+//! semantics: `docs/agent-lifecycle/approvals.md::Scheduled prompt worker`.
 
 use std::sync::Arc;
 use std::time::Duration;