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/lib/api-exception.ts

@@ -1,6 +1,6 @@
 /**
- * Defines the exception that carries an HTTP error from any layer up to the
- * error middleware.
+ * Lets any layer fail a request with an HTTP status, which the error middleware
+ * turns into the response.
  *
  * @module
  */

api/lib/canonical-url.ts

@@ -1,9 +1,10 @@
 /**
- * Reduces a URL to a key shared by every link to the same page or video.
- * `dump-service` stores it in `dumps.url_canonical` when a
- * dump is posted or edited, and `GET /api/dumps/by-url` matches on it
- * to warn the create form of a repost. The key is never fetched or shown, so it
- * may be lossy: it forces `https`, drops `www.`, tracking parameters and
+ * Spots reposts and links to known dumps, by reducing a URL to a key shared by
+ * every link to the same page or video. `dump-service` stores it in
+ * `dumps.url_canonical` when a dump is posted or edited, `GET
+ * /api/dumps/by-url` matches on it to warn the create form of a repost, and
+ * backlink-service compares links by it. The key is never fetched or shown, so
+ * it may be lossy: it forces `https`, drops `www.`, tracking parameters and
  * timestamps.
  *
  * Migration 0013 backfilled existing rows with a frozen copy of these rules.

api/lib/pagination.ts

@@ -1,7 +1,7 @@
 /**
- * Reads the page a list route's query string asks for, and cuts the rows a
- * service fetched into that page. The routes send the page as
- * `PaginatedData`.
+ * Pages every list route the same way. It reads the page a list route's query
+ * string asks for, and cuts the rows a service fetched into that page, which
+ * the routes send as `PaginatedData`.
  *
  * @module
  */