diff --git a/lib/src/components/wall/wall-handles.ts b/lib/src/components/wall/wall-handles.ts
index 1e75358f5..895330e57 100644
--- a/lib/src/components/wall/wall-handles.ts
+++ b/lib/src/components/wall/wall-handles.ts
@@ -6,13 +6,6 @@ import type { SaveOptions } from '../../lib/session-save';
 import type { PreparedWorkspaceTransfer } from './workspace-transfer';
 import type { DorControlRequest } from './use-dor-control';
 
-/**
- * The imperative surface a mounted `<Wall>` exposes to code outside its React
- * tree: the strip, the window-level persistence owner, and the `dor` router
- * (`docs/specs/layout.md` → "Workspaces"). Every Wall registers one, a bare Wall
- * under `DEFAULT_WORKSPACE_ID`, so exactly one handle answers a `dor` request
- * even in the single-Workspace hosts.
- */
 export interface PreparedSurfaceMove {
   meta: LeafMeta;
   surfaceRef: string;
@@ -22,6 +15,13 @@ export interface PreparedSurfaceMove {
   depart(): () => void;
 }
 
+/**
+ * The imperative surface a mounted `<Wall>` exposes to code outside its React
+ * tree: the strip, the window-level persistence owner, and the `dor` router
+ * (`docs/specs/layout.md` → "Workspaces"). Every Wall registers one, a bare Wall
+ * under `DEFAULT_WORKSPACE_ID`, so exactly one handle answers a `dor` request
+ * even in the single-Workspace hosts.
+ */
 export interface WallHandle {
   canMoveSurfaces: boolean;
   prepareSurfaceMove(id: string): PreparedSurfaceMove;
diff --git a/lib/src/lib/alert-delivery-scheduler.ts b/lib/src/lib/alert-delivery-scheduler.ts
index 590c3dfc9..d2c4af6ba 100644
--- a/lib/src/lib/alert-delivery-scheduler.ts
+++ b/lib/src/lib/alert-delivery-scheduler.ts
@@ -14,7 +14,8 @@ import { DEFAULT_ALERT_SETTINGS, type AlertSettings } from './alert-settings-mod
  * When a ring is spoken or pushed (`docs/specs/alert.md` -> Alarm settings),
  * decided in the host beside the `AlertManager`, which sees every episode from
  * its start and outlives every renderer. A push goes from here; speech needs
- * `window.speechSynthesis`, so it goes to the realm showing the Session.
+ * the renderer's audio or `window.speechSynthesis`, so it goes to the realm
+ * showing the Session.
  * Platform-free, like the manager: both hosts run it inside `createAlertHost`.
  */
 
diff --git a/lib/src/lib/alert-delivery.ts b/lib/src/lib/alert-delivery.ts
index 47f087c4d..96e624566 100644
--- a/lib/src/lib/alert-delivery.ts
+++ b/lib/src/lib/alert-delivery.ts
@@ -14,7 +14,7 @@ import { getWorkspaceSurfacesSnapshot } from './workspace-surfaces';
  * settings). The host decides when a ring is spoken or pushed, and sends the
  * push itself; the realm tells it what only the renderer knows — each
  * Session's Pane label and its Workspace's overrides — and speaks what it is
- * handed, which needs `window.speechSynthesis`.
+ * handed, which needs the renderer's audio or `window.speechSynthesis`.
  */
 
 /** How long a label change waits to be published: Claude Code animates its
diff --git a/lib/src/lib/alert-manager.ts b/lib/src/lib/alert-manager.ts
index 92c39a3f8..890ef246b 100644
--- a/lib/src/lib/alert-manager.ts
+++ b/lib/src/lib/alert-manager.ts
@@ -981,10 +981,10 @@ export class AlertManager {
    * publish a paused ring's end, re-arming if output moved it — so
    * continuing output costs one timer per quiet window rather than one per PTY
    * chunk. A timer already waiting stays: the due time only moves later, and
-   * the wake re-checks it. Mostly the detector's own settle gets there first;
-   * the timer is load-bearing after a command boundary resets the detector,
-   * which kills the settle that would have flushed, and for output that never
-   * goes quiet.
+   * the wake re-checks it. The detector's own settle fires only from busy, so
+   * the timer is what releases a deferral after output that never confirmed
+   * busy, after a command boundary resets the detector (killing the settle that
+   * would have flushed), and at the end of a pause.
    */
   private scheduleDeferredNotification(id: string, entry: AlertEntry): void {
     if (entry.deferredTimer !== null) return;
diff --git a/lib/src/remote/client/pocket-client.ts b/lib/src/remote/client/pocket-client.ts
index 1720a46ac..9e5fd3491 100644
--- a/lib/src/remote/client/pocket-client.ts
+++ b/lib/src/remote/client/pocket-client.ts
@@ -1161,7 +1161,7 @@ export class PocketClient {
 
   /**
    * Ping the relay socket while the page is visible, on the session core's
-   * visibility as keepalives run (`docs/specs/pocket-app.md`); a socket that
+   * visibility as keepalives run (`docs/specs/relay.md` → "Routing"); a socket that
    * stops answering is a drop, though no close arrived.
    */
   #startHeartbeat(ws: PocketSocket): void {
diff --git a/lib/src/stories/PhoneFrame.tsx b/lib/src/stories/PhoneFrame.tsx
index 29aa6a50e..3ae37dbef 100644
--- a/lib/src/stories/PhoneFrame.tsx
+++ b/lib/src/stories/PhoneFrame.tsx
@@ -1,10 +1,10 @@
 import type { ReactNode } from 'react';
 
 /**
- * Phone-sized frame for the Pocket auth stories (SetupOrSignin, BurrowsView),
- * sitting on the app-bg surface — matches the real app shell. Uses a faint
- * app-fg outline for definition since panel-border is transparent in many
- * themes (see docs/specs/theme.md).
+ * Phone-sized frame for the Pocket and one-time phone page stories, sitting on
+ * the app-bg surface — matches the real app shell. Uses a faint app-fg outline
+ * for definition since panel-border is transparent in many themes (see
+ * docs/specs/theme.md).
  */
 export function PhoneFrame({
   children,
diff --git a/scripts/lint-kit.mjs b/scripts/lint-kit.mjs
index 5e4d04ed7..7ffea955b 100644
--- a/scripts/lint-kit.mjs
+++ b/scripts/lint-kit.mjs
@@ -1,6 +1,6 @@
 /**
- * The plumbing `spec-lint`, `deploy-lint` and `e2e-lint` share with their
- * self-tests, and the script tests that execute shipped workflow blocks.
+ * The plumbing the repo's lints share with their self-tests, and the script
+ * tests that execute shipped workflow blocks.
  *
  * Rules and patterns stay in each lint — this is only the machinery around
  * them, factored out because the self-test contract is the part that must never
@@ -25,7 +25,6 @@ export const repoRoot = fileURLToPath(new URL('..', import.meta.url));
  * Line endings, normalized to `\n`. Patterns that span two adjacent lines see a
  * `\r` in front of every newline on a `core.autocrlf=true` checkout — which no
  * pattern spells, so every span rule would report a present control as missing.
- * Shared with the self-tests, which match and edit the same text.
  */
 export function normalizeEol(text) {
   return text.replace(/\r\n/g, '\n');
diff --git a/vscode-ext/src/burrow.ts b/vscode-ext/src/burrow.ts
index 34a1bd3e5..7793fad0a 100644
--- a/vscode-ext/src/burrow.ts
+++ b/vscode-ext/src/burrow.ts
@@ -210,9 +210,9 @@ export function notifyDirectoryChanged(): void {
  * The relay socket, preferring whatever this extension host already provides.
  *
  * `globalThis.WebSocket` only landed in Node 22, and `engines.vscode` here is
- * `^1.85.0` — VS Code 1.85 shipped Electron 25 / Node 18, and the supported
- * range spans the boundary — so on an older host there is no global to use and
- * the bundled `ws` is the only implementation. Its socket satisfies the same
+ * `^1.92.0` — VS Code 1.92 shipped Node 20.14, and the supported range spans
+ * the boundary — so on an older host there is no global to use and the bundled
+ * `ws` is the only implementation. Its socket satisfies the same
  * surface `BurrowRuntime` reads and nothing more: `send`, `close`, `readyState`,
  * `addEventListener`, with `message` events carrying `.data` and `close` events
  * carrying `.code`.
@@ -628,7 +628,8 @@ function answerIdle(burrowRequestId: string, result: unknown): void {
 /**
  * Give the Burrow its storage and start it if this installation is already
  * enrolled, or another window's one-time connection is serving. Nothing
- * contends for the socket otherwise — see the module header.
+ * contends for the socket otherwise — see `docs/specs/vscode.md` → "Burrow: a
+ * service in the extension host".
  */
 export function initBurrow(ctx: vscode.ExtensionContext): vscode.Disposable {
   context = ctx;