diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a256863a..18edccbc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -54,11 +54,12 @@ jobs:
       - uses: actions/checkout@v4
       - run: bash .github/scripts/check-host-boundary.sh
 
-  # Lints, at deny. `cargo fmt --check` above has always guarded the shape of the
-  # code and nothing has guarded its content, which is how ~200 clippy findings
-  # accumulated unnoticed — including two the compiler could not see: a
-  # `let _ =` hiding a unit-returning call, and a parameter used only inside a
-  # `#[cfg(windows)]` block.
+  # clippy and rustdoc, both at deny. `cargo fmt --check` above has always
+  # guarded the shape of the code and nothing has guarded its content, which is
+  # how ~200 clippy findings and 16 rustdoc warnings accumulated unnoticed —
+  # including two the compiler could not see: a `let _ =` hiding a
+  # unit-returning call, and a parameter used only inside a `#[cfg(windows)]`
+  # block.
   #
   # Linux only, and deliberately. Lint *coverage* is per-platform (a
   # `#[cfg(windows)]` body is not even parsed here), but the failures that
@@ -77,8 +78,8 @@ jobs:
   # required checks are `rustfmt` and the three `build & test (<target>)` names,
   # and making this one required on the day it lands would wedge every open PR
   # on a check it has never run.
-  clippy:
-    name: clippy
+  lint:
+    name: lint
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
@@ -97,6 +98,20 @@ jobs:
 
       - run: cargo clippy --locked --workspace --all-targets -- -D warnings
 
+      # Broken doc links accumulated for the same reason the clippy findings
+      # did: nothing read them. Four links pointed at items that no longer
+      # existed, two of them describing a type ramp that had been deleted, so
+      # the prose around them was stale too.
+      #
+      # `--document-private-items` because that is how these docs are actually
+      # read — every crate here is `publish = false`, so a private item is not
+      # an implementation detail hidden from the reader, it is most of what
+      # there is to read.
+      - name: rustdoc
+        env:
+          RUSTDOCFLAGS: -D warnings
+        run: cargo doc --locked --workspace --no-deps --document-private-items
+
   build:
     name: build & test (${{ matrix.target }})
     strategy:
diff --git a/crates/tty7-cli/src/stdio.rs b/crates/tty7-cli/src/stdio.rs
index d7313025..51d6f2e2 100644
--- a/crates/tty7-cli/src/stdio.rs
+++ b/crates/tty7-cli/src/stdio.rs
@@ -18,7 +18,7 @@
 //!   [`out`] is the stand-in that recognizes the hang-up and leaves quietly.
 //!
 //! Which is why every stdout write in this binary goes through [`out`] or
-//! [`line`]: the `print!` family has no way to express "the reader left".
+//! [`line()`]: the `print!` family has no way to express "the reader left".
 
 use std::io::Write as _;
 
diff --git a/crates/tty7-core/src/lib.rs b/crates/tty7-core/src/lib.rs
index 3b96b2be..ee058423 100644
--- a/crates/tty7-core/src/lib.rs
+++ b/crates/tty7-core/src/lib.rs
@@ -1,3 +1,16 @@
+//! The framework-free half of tty7: wire protocol, session daemon, PTY, the
+//! native SSH engine, and the domain model the headless `tty7-server` shares
+//! with the GUI.
+
+// A `pub` item here documenting how it relates to a private one — that
+// `file_open_mode` is what `sanitize` fills in, that `restart_daemon` sends
+// `TERMINATE_RUNNING_COMMAND` — is the useful half of these doc comments, and
+// following the link is how a reader checks the claim. The lint exists to stop
+// a *published* crate shipping docs whose links dead-end for anyone outside it;
+// this crate is `publish = false`, and the only docs anyone builds for it come
+// from `--document-private-items`, where every one of these targets is present.
+#![allow(rustdoc::private_intra_doc_links)]
+
 pub mod client;
 pub mod core;
 pub mod daemon;
diff --git a/src/terminal/link_probe.rs b/src/terminal/link_probe.rs
index ab7d893a..f436d2ad 100644
--- a/src/terminal/link_probe.rs
+++ b/src/terminal/link_probe.rs
@@ -6,7 +6,7 @@
 //! machine cannot: the answer costs a round trip, and the click that wanted it
 //! is long gone by the time it lands. So a remote pane keeps this cache
 //! instead. A lookup either finds a recorded answer or reports
-//! [`Probe::Unknown`](super::search::Probe::Unknown) and remembers the path as
+//! [`Probe::Unknown`] and remembers the path as
 //! wanted; the view then asks the host once for everything wanted and files
 //! the replies here, so the *next* hover — a mouse-move away — is a hit.
 //!
diff --git a/src/ui/right_panel.rs b/src/ui/right_panel.rs
index 2ae44ca1..52a061db 100644
--- a/src/ui/right_panel.rs
+++ b/src/ui/right_panel.rs
@@ -1373,8 +1373,8 @@ pub(crate) const BADGE_W: f32 = 14.;
 ///
 /// Mono and SEMIBOLD so `M`, `A`, `D` and `U` all read as the same kind of
 /// mark at a glance, and centred in a cell wide enough for the widest of them
-/// at [`PANEL_TEXT_META`] — that is what makes a column of them line up
-/// instead of drifting with the glyph widths.
+/// at [`META_MONO`] — that is what makes a column of them line up instead of
+/// drifting with the glyph widths.
 pub(crate) fn git_badge(letter: &str, color: gpui::Hsla, mono: &gpui::SharedString) -> AnyElement {
     div()
         .flex_none()
@@ -1434,12 +1434,17 @@ fn status_pip(rgb: u32, hollow: bool, hole: gpui::Hsla) -> AnyElement {
 
 /// A small filled pill around a mono token — a pid, a port number.
 ///
-/// The padding and the radius are derived from the text size: at
-/// [`PANEL_TEXT_META`] the line box is `round(10.5 × 1.618) = 17px`, so 1.5px
-/// of vertical padding makes the pill 20px tall — one pixel more than the 19px
-/// line of [`PANEL_TEXT`] beside it, which is what sets the height of a ports
-/// row. Horizontal padding of 5px is about half an em of breathing room on
-/// each side, and radius 4 is a fifth of the pill's height.
+/// The text is [`META_MONO`], a step below the [`TEXT_MONO`] it sits beside in
+/// a ports row, so the pill reads as an annotation on that line rather than as
+/// a second thing to read. Vertical padding is deliberately small — the pill
+/// has to end up about the height of the line next to it, and a chip taller
+/// than its row is what makes a list of ports look ragged.
+///
+/// The padding and radius are in pixels while the text is in rems, so the two
+/// stop being derived from each other once the interface font scale leaves
+/// 100%: the text grows and the padding does not. That is the same trap
+/// [`PIP_SIZE`] below is written in rems to avoid, and this chip has not been
+/// through it yet.
 pub(crate) fn info_chip(
     text: &str,
     bg: gpui::Hsla,
diff --git a/src/ui/scm/actions.rs b/src/ui/scm/actions.rs
index 40f11df1..d2956f92 100644
--- a/src/ui/scm/actions.rs
+++ b/src/ui/scm/actions.rs
@@ -102,7 +102,8 @@ impl Tty7App {
         self.scm_op_then(repo, op, None, window, cx);
     }
 
-    /// [`scm_op`], with something to run once this operation has succeeded.
+    /// [`Self::scm_op`], with something to run once this operation has
+    /// succeeded.
     /// Cancelling the confirmation drops the follow-up along with the op.
     pub(crate) fn scm_op_then(
         &mut self,