diff --git a/frontend/packages/dashboard/src/swarm.js b/frontend/packages/dashboard/src/swarm.js
index 2b4a9478..9de7a244 100644
--- a/frontend/packages/dashboard/src/swarm.js
+++ b/frontend/packages/dashboard/src/swarm.js
@@ -1,7 +1,7 @@
 // SW4RM (containers) domain — extracted from tabs.js.
 // Agent topology, container-row rendering, selection bar, and all
 // live-update apply handlers for container-state, transient, and
-// job-queue-rollup ops. See docs/web-ui.md::Container row for the
+// job-queue-rollup ops. See docs/web-ui/dashboard.md::Container row for the
 // rendering contract.
 
 import {
@@ -41,7 +41,7 @@ const containerRowCache = new Map();
 // by agent name -> Map<transient_kind, since_unix>: an agent can hold
 // several pills at once (every *running* node naming the agent lights
 // one now, not just a curated "worth surfacing" subset — see
-// docs/web-ui.md::Container row), keyed the same way the backend's
+// docs/web-ui/dashboard.md::Container row), keyed the same way the backend's
 // own tombstone map is, `(agent, label)`, so a clear only removes the
 // specific pill it names rather than guessing. `since_unix` is
 // wall-clock so the elapsed-seconds badge ticks without polling.
@@ -342,7 +342,7 @@ function buildContainerLi(c, node, opts) {
   // Agent icon: 5em square wrapper with an absolutely-positioned
   // <img> + fire-and-forget load with /favicon.svg fallback. The
   // wrapper doubles as the selection toggle (click / keyboard).
-  // See docs/web-ui.md::Container row for the layout + load-strategy
+  // See docs/web-ui/dashboard.md::Container row for the layout + load-strategy
   // rationale.
   const iconImg = el('img', { class: 'container-icon-img', alt: '' });
   const icon = el('div', {
@@ -494,7 +494,7 @@ function buildContainerLi(c, node, opts) {
   // dashboard-state fetch above.
   if (pending.length) {
     // One badge per pill — an agent can carry several transients at
-    // once now (see docs/web-ui.md::Container row), each rendered
+    // once now (see docs/web-ui/dashboard.md::Container row), each rendered
     // independently rather than collapsed into one label.
     for (const label of pending) {
       head.append(el('span', { class: 'pending-state' },
@@ -619,7 +619,7 @@ export function renderContainers(s) {
   // TCP fallback — the gateway proxies the prefix to the per-agent
   // harness (unix-domain via `agent-sockets.json`, or a computed TCP
   // loopback port while the socket marker is absent). See
-  // `docs/web-ui.md::Container row` + `docs/gateway.md::Vhost map`.
+  // `docs/web-ui/dashboard.md::Container row` + `docs/gateway.md::Vhost map`.
   const gatewayLinks = !!(s && s.gateway_enabled);
   // Forge public URL: state.forge_public_url (set by the NixOS module
   // from services.hyperhive.forge.publicUrl) or null — never guessed
@@ -646,7 +646,7 @@ export function renderContainers(s) {
     // full stop (mara, on review: "remove the per agent pending stuff -
     // only show what is running"; rendered one badge per pill — mara,
     // earlier: "show all running nodes that name the agent"). See
-    // docs/web-ui.md::Container row.
+    // docs/web-ui/dashboard.md::Container row.
     const transientKindsMap = transientsState.get(c.name);
     // Sorted for stable badge order across renders — Map iteration
     // order is insertion order, which shifts as pills clear/re-add.
diff --git a/frontend/packages/shared/src/terminal/terminal.css b/frontend/packages/shared/src/terminal/terminal.css
index 32e03010..c35f5e12 100644
--- a/frontend/packages/shared/src/terminal/terminal.css
+++ b/frontend/packages/shared/src/terminal/terminal.css
@@ -13,7 +13,7 @@
 
    No `.term-input` here — composers are a separate concern, owned by
    each page's own CSS. Row taxonomy + layout contract documented in
-   `docs/web-ui.md::Shared terminal pane` and
+   `docs/web-ui/shape.md::Shared terminal pane` and
    `docs/terminal-rendering.md`. */
 
 .terminal-wrap {
diff --git a/frontend/packages/shared/src/terminal/terminal.js b/frontend/packages/shared/src/terminal/terminal.js
index f65b270c..90b3d8e3 100644
--- a/frontend/packages/shared/src/terminal/terminal.js
+++ b/frontend/packages/shared/src/terminal/terminal.js
@@ -46,7 +46,7 @@ export function create(opts) {
   // operator-driven wheel/drag stay in sync.
   let stickToBottom = true;
   // Scroll-handler gate during in-flight snap animations — see
-  // docs/web-ui.md::Shared terminal pane (Mid-animation scroll-event
+  // docs/web-ui/shape.md::Shared terminal pane (Mid-animation scroll-event
   // guard) for the eased-through-not-near-bottom rationale.
   let smoothScrollingUntil = 0;
   // rAF id for the current snap animation. Cancelled when a new
@@ -60,7 +60,7 @@ export function create(opts) {
   // Snap the log to the bottom with a brief eased animation. Cancels
   // any in-flight frame loop so back-to-back snaps coalesce; falls
   // back to instant scroll during `currentNoAnim` backfill replay
-  // or under SCROLL_SNAP_PX. See docs/web-ui.md::Shared terminal pane.
+  // or under SCROLL_SNAP_PX. See docs/web-ui/shape.md::Shared terminal pane.
   function snapToBottom(immediate) {
     stickToBottom = true;
     if (scrollAnimRaf) {
@@ -147,7 +147,7 @@ export function create(opts) {
   });
   // Post-append mutation snap — catches renderer mutations that land
   // after `api.row` returns (badges, multi-line bodies, tool
-  // panes). See docs/web-ui.md::Shared terminal pane (Post-append
+  // panes). See docs/web-ui/shape.md::Shared terminal pane (Post-append
   // MutationObserver) for why the pre-append `afterAppend` hop
   // alone isn't enough.
   const mo = new MutationObserver(() => {
@@ -156,7 +156,7 @@ export function create(opts) {
   mo.observe(log, { childList: true, subtree: true, characterData: true });
 
   // Pre-append nearBottom snapshot drives the initial snap decision —
-  // see docs/web-ui.md::Shared terminal pane (Post-append
+  // see docs/web-ui/shape.md::Shared terminal pane (Post-append
   // MutationObserver) for why we need both this and the MO.
   function afterAppend(wasNearBottom) {
     if (currentNoAnim || wasNearBottom) {
@@ -407,7 +407,7 @@ export function create(opts) {
     // Optional streamFactory(url) → EventSource-shaped facade. Lets
     // the dashboard hand the factory a SharedWorker-backed source so
     // open hyperhive tabs share one upstream — see
-    // docs/web-ui.md::Shared terminal pane (Backfill + SSE). Default
+    // docs/web-ui/shape.md::Shared terminal pane (Backfill + SSE). Default
     // falls back to `new EventSource(url)`.
     const es = opts.streamFactory
       ? opts.streamFactory(opts.streamUrl)
diff --git a/hive-c0re/src/agent_config/topology.rs b/hive-c0re/src/agent_config/topology.rs
index 87e2f349..96b15dbb 100644
--- a/hive-c0re/src/agent_config/topology.rs
+++ b/hive-c0re/src/agent_config/topology.rs
@@ -9,7 +9,7 @@
 //! `lifecycle::set_nspawn_flags` for the consumer.
 //!
 //! Format, rationale, read/reconcile/inject/surface flow, and target
-//! enforcement semantics: `docs/agent-lifecycle/agent-hierarchy.md::Current state`.
+//! enforcement semantics: `docs/agent-lifecycle/agent-hierarchy.md::Where the tree lives`.
 //! `<parent>` sentinel resolution (delivered by [`resolve_recipient`]):
 //! `docs/process/conventions.md::Recipient sentinels`.
 //!
@@ -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-lifecycle/agent-hierarchy.md::Current state` has the rationale.
+/// `docs/agent-lifecycle/agent-hierarchy.md::Reparenting` has the rationale.
 pub fn apply_set_parent(
     topo: &BTreeMap<String, Option<String>>,
     child: &str,
diff --git a/hive-c0re/src/container_view.rs b/hive-c0re/src/container_view.rs
index b189b93a..e5aebd02 100644
--- a/hive-c0re/src/container_view.rs
+++ b/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-lifecycle/agent-hierarchy.md::Current state`.
+    /// in the tree. See `docs/agent-lifecycle/agent-hierarchy.md::Where the tree lives`.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub parent: Option<String>,
     /// The Claude model the agent's harness is currently using, read from
diff --git a/hive-c0re/src/migrate.rs b/hive-c0re/src/migrate.rs
index dd50202c..92cb46a4 100644
--- a/hive-c0re/src/migrate.rs
+++ b/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/agent-lifecycle/approvals.md::Migration from the pre-tag`.
+//! details: `docs/agent-lifecycle/approvals.md::Startup migrations (older hosts)`.
 
 use std::path::Path;
 use std::sync::Arc;
diff --git a/hive-host-sock/src/lib.rs b/hive-host-sock/src/lib.rs
index 9be11f44..62a5bc99 100644
--- a/hive-host-sock/src/lib.rs
+++ b/hive-host-sock/src/lib.rs
@@ -234,7 +234,7 @@ pub enum HostRequest {
     /// Move an agent in the topology tree. `new_parent = None`
     /// promotes the agent to root, `Some(name)` sets a new parent.
     /// Validation rules + bind-mount caveat documented in
-    /// `docs/agent-lifecycle/agent-hierarchy.md::Current state`.
+    /// `docs/agent-lifecycle/agent-hierarchy.md::Reparenting`.
     SetParent {
         child: Ident,
         new_parent: Option<Ident>,
diff --git a/hive-sh4re/src/manager.rs b/hive-sh4re/src/manager.rs
index c46d6529..9323f2da 100644
--- a/hive-sh4re/src/manager.rs
+++ b/hive-sh4re/src/manager.rs
@@ -60,7 +60,7 @@ pub fn trusted_sender(s: &str) -> Ident {
 /// Out-of-band events the host-side daemon pushes to the manager's inbox.
 /// Serialised as JSON in `Message::body` (sender = `SYSTEM_SENDER`).
 /// Per-variant triggers + the optional `sha`/`tag` semantics live in
-/// `docs/agent-lifecycle/approvals.md::Helper events to the manager`.
+/// `docs/agent-lifecycle/approvals.md::Helper events to the submitting agent`.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(tag = "event", rename_all = "snake_case")]
 pub enum HelperEvent {