diff --git a/meshterm/context.py b/meshterm/context.py
index 8a396d4..a177cb6 100644
--- a/meshterm/context.py
+++ b/meshterm/context.py
@@ -229,12 +229,12 @@ class AppContext:
 
     @property
     def active_transport(self) -> str | None:
-        """The transport of the current/selected connection: ``"serial"``, ``"ble"``, ``"tcp"``,
-        or ``None``.
+        """Which transport the current or selected connection uses.
 
-        ``None`` for the simulator. For a real device it reflects the open connection when
-        one exists, otherwise the transport implied by the pending selection (an explicit
-        ``--tcp`` selects TCP, ``--ble`` selects BLE), defaulting to serial.
+        One of ``"serial"``, ``"ble"``, ``"tcp"``, or ``None`` for the simulator. For a
+        real device it reflects the open connection when one exists, otherwise the
+        transport implied by the pending selection (an explicit ``--tcp`` selects TCP,
+        ``--ble`` selects BLE), defaulting to serial.
         """
         if self.mock:
             return None
diff --git a/meshterm/core/courier_store.py b/meshterm/core/courier_store.py
index 977b0e7..743d873 100644
--- a/meshterm/core/courier_store.py
+++ b/meshterm/core/courier_store.py
@@ -168,8 +168,10 @@ class CourierStore:
     # --- attempt bookkeeping -----------------------------------------------------------
 
     def note_attempt(self, ident: int, *, when: datetime | None = None) -> None:
-        """Record that a delivery attempt is being made (written *before* the send,
-        so a crash mid-transmission can never spend the retry budget twice).
+        """Record that a delivery attempt is being made.
+
+        Written *before* the send, so a crash mid-transmission can never spend the
+        retry budget twice.
         """
         message = self.get(ident)
         if message is not None:
diff --git a/meshterm/core/device_store.py b/meshterm/core/device_store.py
index 3eada0c..baf0993 100644
--- a/meshterm/core/device_store.py
+++ b/meshterm/core/device_store.py
@@ -76,8 +76,9 @@ class RememberedDevice:
 
     @property
     def target(self) -> str:
-        """The connection target: ``host:port`` for TCP, the BLE address for Bluetooth, else
-        the serial port.
+        """Where this device is reached.
+
+        ``host:port`` for TCP, the BLE address for Bluetooth, else the serial port.
         """
         if self.is_tcp:
             return f"{self.host}:{self.tcp_port}"
diff --git a/meshterm/core/discovery.py b/meshterm/core/discovery.py
index 617be40..7b1c73b 100644
--- a/meshterm/core/discovery.py
+++ b/meshterm/core/discovery.py
@@ -137,8 +137,10 @@ class DiscoveredDevice:
 
     @property
     def target(self) -> str:
-        """The identifier a connection opens on: the network ``host:port`` for TCP, the BLE
-        address for Bluetooth, else the serial port.
+        """The identifier a connection opens on.
+
+        The network ``host:port`` for TCP, the BLE address for Bluetooth, else the
+        serial port.
         """
         if self.is_tcp:
             return f"{self.host}:{self.tcp_port}"
diff --git a/meshterm/services/path_probe.py b/meshterm/services/path_probe.py
index 8aba0a8..3f35db3 100644
--- a/meshterm/services/path_probe.py
+++ b/meshterm/services/path_probe.py
@@ -52,8 +52,10 @@ class ProbeOutcome:
 
     @property
     def sort_key(self) -> tuple:
-        """Ranking key, best-first under ascending sort: reliability, then bottleneck
-        SNR, then RTT — the same priority order the TX optimizer applies.
+        """A ranking key that sorts the best path first.
+
+        Reliability, then bottleneck SNR, then RTT — the same priority order the TX
+        optimizer applies.
         """
         snr = self.stats.median_min_snr
         rtt = self.stats.median_rtt_ms
diff --git a/meshterm/tools/chat.py b/meshterm/tools/chat.py
index 0ddf683..a27af24 100644
--- a/meshterm/tools/chat.py
+++ b/meshterm/tools/chat.py
@@ -781,8 +781,10 @@ def _preview_text(last: ChatMessage, key_of: NameKeyResolver) -> Text:
 
 
 def _append_body(text: Text, body: str, key_of: NameKeyResolver) -> None:
-    """Append ``body`` to ``text``, muted, with each ``@[Name]`` mention drawn in the
-    mentioned node's key-derived hue (muted when the name resolves to no known node).
+    """Append ``body`` to ``text``, muted, lighting up the names it mentions.
+
+    Each ``@[Name]`` is drawn in that node's key-derived hue, or left muted when the
+    name resolves to no node we know.
     """
     pos = 0
     for match in _MENTION.finditer(body):
diff --git a/meshterm/ui/message_paths_screen.py b/meshterm/ui/message_paths_screen.py
index adce057..70a31af 100644
--- a/meshterm/ui/message_paths_screen.py
+++ b/meshterm/ui/message_paths_screen.py
@@ -222,8 +222,10 @@ class MessagePathsScreen(Screen):
             self.resolve(None)
 
     def cursor_line(self) -> int | None:
-        """The selected row's body line. The window already keeps it inside the dialog, so
-        this only bites on a terminal too short for even the compressed head.
+        """The selected row's body line.
+
+        The window already keeps it inside the dialog, so this only bites on a terminal
+        too short for even the compressed head.
         """
         return self._cursor
 
diff --git a/meshterm/ui/node_detail_screen.py b/meshterm/ui/node_detail_screen.py
index 9ddf01d..e9ee6bb 100644
--- a/meshterm/ui/node_detail_screen.py
+++ b/meshterm/ui/node_detail_screen.py
@@ -484,8 +484,7 @@ class NodeDetailScreen(Screen):
 
     @property
     def footer_hint(self) -> str:  # type: ignore[override]
-        """Tab switch (when there are tabs to switch), move, open, whatever ``←→`` reads here,
-        Esc last.
+        """The hint line: tab switch, move, open, whatever ``←→`` reads here, Esc last.
 
         The scroll atom folds ``PgUp/PgDn`` and ``←→`` into one when both apply (a busy node's
         list is windowed *and* its highlighted route overflows) rather than stacking two atoms
@@ -581,9 +580,11 @@ class NodeDetailScreen(Screen):
         return 2 if self._tabs[self._tab_index].kind == "info" else 0
 
     def handle(self, action: str, data: str = "") -> None:
-        """Switch tab, move the cursor within a tab, commit a row, page the list, scroll
-        whichever over-wide lane the active tab owns (the highlighted route's pathline, the
-        Info tab's key), or leave.
+        """Answer one key press on the page.
+
+        Switch tab, move the cursor within a tab, commit a row, page the list, scroll
+        whichever over-wide lane the active tab owns (the highlighted route's pathline,
+        the Info tab's key), or leave.
         """
         focus = self._focusables()
         n = len(focus)
@@ -652,8 +653,9 @@ class NodeDetailScreen(Screen):
         return bool(focus) and focus[self._row_index % len(focus)][0] == "path"
 
     def cursor_line(self) -> int | None:
-        """The highlighted row's body line — the frame keeps it in view, which only matters
-        on a terminal too short for the pinned layout's minimums.
+        """The highlighted row's body line, which the frame keeps in view.
+
+        That only matters on a terminal too short for the pinned layout's minimums.
         """
         return self._cursor
 
diff --git a/meshterm/ui/packet_viewer.py b/meshterm/ui/packet_viewer.py
index 5e3699d..f5773ef 100644
--- a/meshterm/ui/packet_viewer.py
+++ b/meshterm/ui/packet_viewer.py
@@ -714,8 +714,9 @@ class PacketViewer(Screen):
         return render_lines(grid, width)
 
     def _head_rows(self, entry: PacketEntry) -> list[tuple[str, RenderableType]]:
-        """The rows above the route graph: the class headline, the common core, then a
-        packet's parsed frame.
+        """The rows above the route graph.
+
+        The class headline, the common core, then a packet's parsed frame.
         """
         rows: list[tuple[str, RenderableType]] = []
 
@@ -881,8 +882,10 @@ class PacketViewer(Screen):
         return "direct — no relays"
 
     def _packet_rows(self, entry: PacketEntry) -> list[tuple[str, RenderableType]]:
-        """A raw ``packet`` entry's addressing, parsed class/route, relay path, and — for a
-        channel frame naming a channel we hold the key for — its channel and plaintext.
+        """What a raw ``packet`` entry has to say for itself.
+
+        Its addressing, parsed class and route, and relay path — plus, for a channel
+        frame naming a channel we hold the key for, its channel and plaintext.
         """
         raw = entry.raw if isinstance(entry.raw, dict) else {}
         rows: list[tuple[str, RenderableType]] = []
diff --git a/meshterm/ui/surface.py b/meshterm/ui/surface.py
index 434f8b7..8d31a63 100644
--- a/meshterm/ui/surface.py
+++ b/meshterm/ui/surface.py
@@ -803,8 +803,10 @@ class TuiUi(Ui):
         danger: bool = False,
         destructive: bool = False,
     ) -> Any:
-        """Delegate to the session's button dialog, themed cautionary when ``danger``,
-        or in the reserved error red when ``destructive`` (irreversible data loss).
+        """Delegate to the session's button dialog, in the caution tier the caller asked for.
+
+        ``danger`` themes the frame cautionary; ``destructive`` uses the reserved error
+        red, and is only for irreversible data loss.
         """
         tier = "err" if destructive else "warn" if danger else ""
         return await self.session.button_dialog(
diff --git a/meshterm/ui/termfont.py b/meshterm/ui/termfont.py
index ad983cc..c551ddd 100644
--- a/meshterm/ui/termfont.py
+++ b/meshterm/ui/termfont.py
@@ -290,8 +290,10 @@ def _read_jsonc(path: Path) -> dict | None:
 
 
 def _profile_face(profile: object) -> str | None:
-    """A Windows Terminal profile's configured face — new ``font.face`` or legacy
-    ``fontFace`` — or ``None`` when the profile leaves it to the defaults chain.
+    """A Windows Terminal profile's configured font face.
+
+    Reads the new ``font.face`` or the legacy ``fontFace``, and answers ``None`` when
+    the profile leaves the choice to the defaults chain.
     """
     if not isinstance(profile, dict):
         return None
@@ -309,8 +311,9 @@ def _profile_face(profile: object) -> str | None:
 
 
 def _wt_settings_paths(environ: Mapping[str, str]) -> list[Path]:
-    """Candidate Windows Terminal ``settings.json`` locations (packaged, preview,
-    unpackaged), existing files only.
+    """Where Windows Terminal might keep its ``settings.json``.
+
+    The packaged, preview, and unpackaged locations — existing files only.
     """
     local = environ.get("LOCALAPPDATA")
     if not local:
@@ -367,8 +370,10 @@ def _windows_terminal_face(environ: Mapping[str, str]) -> str:
 def _vscode_settings_paths(
     environ: Mapping[str, str], start: Path | None
 ) -> list[Path]:
-    """VS Code settings files in precedence order: nearest workspace, then user
-    (stable and Insiders, per-platform locations), existing files only.
+    """VS Code's settings files, nearest first.
+
+    The closest workspace, then the user's own (stable and Insiders, in their
+    per-platform locations) — existing files only.
     """
     paths: list[Path] = []
     try:
diff --git a/meshterm/ui/tui/session.py b/meshterm/ui/tui/session.py
index 3e38957..c9c5ed5 100644
--- a/meshterm/ui/tui/session.py
+++ b/meshterm/ui/tui/session.py
@@ -1539,8 +1539,10 @@ class TuiSession:
         return bool(self._float_layers())
 
     def _emit(self, text: str, layer: str = "base") -> ANSI:
-        r"""Wrap a composed frame as prompt_toolkit :class:`ANSI`, repainting whole *rows*
-        when it holds a glyph the terminal may draw narrower than pt reserves for it.
+        r"""Wrap a composed frame as prompt_toolkit :class:`ANSI`.
+
+        A row holding a glyph the terminal may draw narrower than pt reserves for it is
+        repainted whole, rather than differentially.
 
         prompt_toolkit paints differentially: it rewrites only the cells that changed since
         the last frame, and it steps the cursor *relative* to its own width model. That is
diff --git a/meshterm/ui/walk_screen.py b/meshterm/ui/walk_screen.py
index fc33b89..62bc246 100644
--- a/meshterm/ui/walk_screen.py
+++ b/meshterm/ui/walk_screen.py
@@ -1053,9 +1053,11 @@ class WalkScreen(Screen):
 
     @staticmethod
     def _clip(label: str, room: int, cap: int = _LABEL_W) -> str:
-        """``label`` fit to ``room`` cells: whole if it fits, else ellipsized (``…`` alone
-        at one cell, nothing at zero). The cap and the room-to-edge both flow through here,
-        so a name is only ever shortened as far as it truly must be.
+        """``label`` fit to ``room`` cells.
+
+        Whole if it fits, else ellipsized (``…`` alone at one cell, nothing at zero).
+        The cap and the room-to-edge both flow through here, so a name is only ever
+        shortened as far as it truly must be.
         """
         room = min(room, cap)
         if room <= 0:
@@ -1067,8 +1069,9 @@ class WalkScreen(Screen):
     def _place_label(
         self, canvas: MapCanvas, x: int, y: int, label: str, rgb: RGB
     ) -> None:
-        """Place one marker label (right of the marker when it fits, else left),
-        retrying a row below then above on collision.
+        """Place one marker label, retrying a row below then above on collision.
+
+        It goes to the right of the marker where that fits, else to the left.
 
         The label is clamped to whichever side has more room — the cells free to the
         right of the marker, or to its left — so the selection keeps as much of its name
diff --git a/meshterm/ui/widgets.py b/meshterm/ui/widgets.py
index fe5b590..09ccd68 100644
--- a/meshterm/ui/widgets.py
+++ b/meshterm/ui/widgets.py
@@ -1171,8 +1171,10 @@ def tab_strip(labels: Sequence[str], active: int, width: int) -> Group:
         return "accent" if top_owner(junction) == active else "faint"
 
     def bot_glyph(junction: int) -> str:
-        """The bottom rule's glyph at this junction — a corner turning into/out of the
-        active tab's wall, else a flat pass-through. Always accent: see the docstring.
+        """The bottom rule's glyph at this junction.
+
+        A corner turning into or out of the active tab's wall, else a flat
+        pass-through. Always accent — see the enclosing docstring for why.
         """
         if junction == active:
             return "╯"