v3: every doc opens with the role, then the mechanism, then the details — the docs were written bottom-up: what a thing does first ("Declares the three contexts WSProvider fills…"), details that only make sense once its purpose is known next, and the reason it exists last ("…so that a feed doesn't re-render"), so a reader had nothing to hang the first sentences on. The README's rule caused it, since a module doc "opened with what the module does"; it now opens with the module's role in the app, and the value-side phrasing of a type ("Returned to Y by X") comes once the role is said, with WSContext as the before and after. WSContext.ts is rewritten that way throughout, and so are the docs elsewhere that buried their purpose in a trailing "so that" (the migrations, og, image-proxy, public-address, useFading, useFeedCache, the drafts), opened on a generic verb that hid it ("Holds", "Declares", "Loads", "Defines", "Types": the contexts and providers, the shared types, the models, the hooks), or were label fragments ("The page of a dump…", "A row of tabs."). A function whose verb is its action ("Stores session"), a props or result type, and a protocol message ("Sent by X when Y") already say their role and are left as they are. Only comments changed, and the catalogs only move their references; deno fmt, deno lint and doc:lint are clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

api/remote/image-proxy.ts

@@ -1,8 +1,9 @@
 /**
- * Fetches and caches the remote images `GET /api/proxy-image` serves. The
- * frontend routes a thumbnail through it when the image is on plain http,
- * which an https page would block, or when loading it directly failed, often
- * to hotlink protection.
+ * Shows the thumbnails a browser can't load from their own site: those on plain
+ * http, which an https page would block, and those behind hotlink protection.
+ * It fetches and caches the images `GET /api/proxy-image` serves, which the
+ * frontend routes a thumbnail through when it is on http or when loading it
+ * directly failed.
  *
  * @module
  */

api/remote/providers/provider.ts

@@ -1,6 +1,7 @@
 /**
- * Declares what a link provider implements. `rich-content-service.ts` asks its
- * providers in turn and fetches a link's preview from the first that matches.
+ * Lets each kind of site have its own link previews. A provider implements this
+ * interface, and `rich-content-service.ts` asks its providers in turn and
+ * fetches a link's preview from the first that matches.
  *
  * @module
  */

api/remote/public-address.ts

@@ -1,8 +1,8 @@
 /**
- * Tells private addresses from public ones, so that a user-supplied URL can't
- * make the server fetch what only it can reach: loopback, the LAN, container
- * networks or the cloud metadata endpoint at 169.254.169.254. `fetch.ts` checks
- * every hop with it.
+ * Keeps a user-supplied URL from making the server fetch what only it can
+ * reach: loopback, the LAN, container networks or the cloud metadata endpoint
+ * at 169.254.169.254. It tells private addresses from public ones, and
+ * `fetch.ts` checks every hop with it.
  *
  * @module
  */

api/remote/youtube-playlist.ts

@@ -1,7 +1,7 @@
 /**
- * Resolves a YouTube playlist to its entries' titles and lengths, for
- * `GET /api/youtube/playlist`. The embed plays the list but doesn't expose
- * them, and the global player needs them to draw a tracklist.
+ * Gives the global player a tracklist for a YouTube playlist, which the embed
+ * plays but doesn't list. It resolves the playlist to its entries' titles and
+ * lengths, for `GET /api/youtube/playlist`.
  *
  * They are read from the `ytInitialData` JSON of the public playlist page,
  * whose undocumented shape changes, so both the current `lockupViewModel` rows