diff --git a/hive-agent/src/login.rs b/hive-agent/src/login.rs
index 518eaad4..f2e6bdbd 100644
--- a/hive-agent/src/login.rs
+++ b/hive-agent/src/login.rs
@@ -32,7 +32,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/web-ui/agent.md)
+/// `docs/web-ui/agent.md::Per-agent endpoints`
 /// (the `/api/logout` bullet).
 ///
 /// `.credentials.json` is the actual OAuth session; `mcp-needs-auth-cache.json`
@@ -148,7 +148,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/turn-loop/README.md).
+/// `docs/turn-loop/::The loop`.
 ///
 /// # Panics
 ///
diff --git a/hive-agent/src/main.rs b/hive-agent/src/main.rs
index 9c8dbc9e..92b59d97 100644
--- a/hive-agent/src/main.rs
+++ b/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/turn-loop/README.md).
+//! `docs/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.
diff --git a/hive-agent/src/web_ui/auth.rs b/hive-agent/src/web_ui/auth.rs
index e9485ab4..ea02fb3a 100644
--- a/hive-agent/src/web_ui/auth.rs
+++ b/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/web-ui/agent.md)
+/// `docs/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 {
diff --git a/hive-agent/src/web_ui/mod.rs b/hive-agent/src/web_ui/mod.rs
index cb9d9a53..15ff79ec 100644
--- a/hive-agent/src/web_ui/mod.rs
+++ b/hive-agent/src/web_ui/mod.rs
@@ -71,8 +71,8 @@ struct 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`](../../../docs/web-ui/shape.md) and
-/// [`docs/networking/gateway.md::Per-agent unix-socket upstream`](../../../docs/networking/gateway.md).
+/// `docs/web-ui/shape.md::Listener bind` and
+/// `docs/networking/gateway.md::Per-agent unix-socket upstream`.
 ///
 /// # Errors
 ///
@@ -176,7 +176,7 @@ pub async fn serve(
 /// to ask.
 ///
 /// Marker-gating + the gateway-side consumer: see
-/// [`docs/networking/gateway.md::Per-agent unix-socket upstream`](../../../docs/networking/gateway.md).
+/// `docs/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() {
@@ -216,7 +216,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`](../../../docs/web-ui/shape.md).
+/// see `docs/web-ui/shape.md::Listener bind`.
 async fn bind_with_retry(addr: SocketAddr, label: &str) -> Result<tokio::net::TcpListener> {
     let mut delay_ms = 250u64;
     let mut attempts = 0u32;
diff --git a/hive-agent/src/web_ui/state.rs b/hive-agent/src/web_ui/state.rs
index d223cad5..77907d56 100644
--- a/hive-agent/src/web_ui/state.rs
+++ b/hive-agent/src/web_ui/state.rs
@@ -317,7 +317,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`](../../../docs/web-ui/dashboard.md) for
+/// `docs/web-ui/dashboard.md::Container row` for
 /// the resolver + how `deployed:<sha>` ships alongside.
 ///
 /// Icons are real emoji, not unicode arrow/geometric glyphs — mara:
diff --git a/hive-forge-notify/src/notify.rs b/hive-forge-notify/src/notify.rs
index bec6162a..0588a22a 100644
--- a/hive-forge-notify/src/notify.rs
+++ b/hive-forge-notify/src/notify.rs
@@ -18,12 +18,12 @@
 //! **Multi-source**: always the internal Forgejo, plus github.com when the
 //! agent has a PAT. Each source polls independently behind
 //! [`Source`]; everything below is shared. Rationale
-//! + host differences: [`docs/integrations/forge.md::Sources`](../../../docs/integrations/forge.md).
+//! + host differences: `docs/integrations/forge.md::Sources`.
 //!
 //! Activation gates, self-notification filtering, body excerpt +
 //! truncation + heading escape, wrapper formats (comment / review /
 //! new-item / state-change), meta suffix, and review-request override
-//! all live in [`docs/integrations/forge.md::Notification poller`](../../../docs/integrations/forge.md).
+//! all live in `docs/integrations/forge.md::Notification poller`.
 
 use std::collections::{HashMap, HashSet};
 use std::fmt::Write as _;