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/db/migrations/0002_dump_thumbnail.ts

@@ -1,7 +1,7 @@
 /**
- * Adds `dumps.custom_thumbnail_mime`, so a poster can upload a thumbnail that
- * replaces the fetched one. It holds the uploaded image's type, and NULL means
- * the dump has none.
+ * Lets a poster upload a thumbnail that replaces the fetched one. It adds
+ * `dumps.custom_thumbnail_mime`, which holds the uploaded image's type; NULL
+ * means the dump has none.
  *
  * @module
  */

api/db/migrations/0003_dump_backlinks.ts

@@ -1,8 +1,8 @@
 /**
- * Adds `dump_backlinks`, which records the links from a dump's note or
- * comments to other dumps, so a dump page can list the dumps related to it.
- * backlink-service fills it, and the index on `dumps.url` lets it find the
- * dumps an external link was posted as.
+ * Lets a dump page list the dumps related to it. It adds `dump_backlinks`,
+ * which records the links from a dump's note or comments to other dumps and
+ * which backlink-service fills, and an index on `dumps.url` to find the dumps
+ * an external link was posted as.
  *
  * @module
  */

api/db/migrations/0004_user_roles.ts

@@ -1,6 +1,6 @@
 /**
- * Adds `users.role`, which replaces the `is_admin` flag so that moderators can
- * exist between users and admins. 0005 then drops the flag.
+ * Makes room for moderators between users and admins. It adds `users.role`,
+ * which replaces the `is_admin` flag, and 0005 then drops the flag.
  *
  * @module
  */

api/db/migrations/0009_chat_reply.ts

@@ -1,8 +1,8 @@
 /**
- * Adds `chat_messages.reply_to_id`, so a message can reply to another. It has
- * no foreign key on purpose: when the replied-to message is deleted, the id
- * stays and chat-service's join reads null, so the chat shows "deleted
- * message" where the quote was.
+ * Lets a chat message reply to another, through `chat_messages.reply_to_id`.
+ * The column has no foreign key on purpose: when the replied-to message is
+ * deleted, the id stays and chat-service's join reads null, so the chat shows
+ * "deleted message" where the quote was.
  *
  * @module
  */

api/db/migrations/0010_youtube_embed_start.ts

@@ -1,8 +1,8 @@
 /**
- * Adds the `start` parameter to the YouTube embed URLs stored before the
- * YouTube provider carried it over. `rich_content.embedUrl` is computed when a
- * dump is posted, and used to drop the source URL's `t` (`?t=1265`,
- * `?t=1h2m3s`), so those videos played from 0:00.
+ * Makes the YouTube dumps posted with a start time, before the YouTube provider
+ * kept it, start there instead of at 0:00. `rich_content.embedUrl` is computed
+ * when a dump is posted, and it used to drop the source URL's `t` (`?t=1265`,
+ * `?t=1h2m3s`); this adds the `start` parameter back to the stored embed URLs.
  *
  * It reads the time from the stored source URL and fetches nothing. It keeps
  * its own copy of the parsing, so that it migrates every database alike should

api/db/migrations/0011_split_favicon_thumbnail.ts

@@ -1,10 +1,11 @@
 /**
- * Moves site icons out of `rich_content.thumbnailUrl` into the new
- * `faviconUrl`. The metadata fetch used to fall back on the page's icon, and
- * then on a guessed `/favicon.ico`, so most thumbnails were a 16×16 icon, or a
- * 404, that the UI stretched over a 128×72 box. It now stops at real artwork,
- * and a missing `thumbnailUrl` means none, which the frontend draws a
- * placeholder for. This gives the older rows that meaning.
+ * Stops older dumps from showing a site's icon as their thumbnail. The metadata
+ * fetch used to fall back on the page's icon, and then on a guessed
+ * `/favicon.ico`, so most thumbnails were a 16×16 icon, or a 404, that the UI
+ * stretched over a 128×72 box. It now stops at real artwork, and a missing
+ * `thumbnailUrl` means none, which the frontend draws a placeholder for. This
+ * gives the older rows that meaning, by moving their icons out of
+ * `rich_content.thumbnailUrl` into the new `faviconUrl`.
  *
  * It judges the stored URL alone and fetches nothing, so it doesn't fill
  * `accentColor`. The frontend derives a hue from the hostname when it is

api/db/migrations/0013_dump_url_canonical.ts

@@ -1,6 +1,7 @@
 /**
- * Adds `dumps.url_canonical`, the key the create form's "already dumped" hint
- * looks a URL up by, and fills it for every URL dump already posted.
+ * Lets the create form warn that a link was already dumped. It adds
+ * `dumps.url_canonical`, the key the hint looks a URL up by, and fills it for
+ * every URL dump already posted.
  *
  * It fills the key from each stored URL and fetches nothing. Its helpers are a
  * copy of lib/canonical-url.ts as it stood when this shipped: importing the

api/db/migrations/0015_token_revocation.ts

@@ -1,7 +1,7 @@
 /**
- * Adds `users.tokens_valid_after`, so that changing a password ends every
- * session opened before. Tokens are stateless JWTs, so lib/auth.ts refuses a
- * token issued before that time instead.
+ * Lets a password change end every session opened before it. Tokens are
+ * stateless JWTs, so this adds `users.tokens_valid_after`, and lib/auth.ts
+ * refuses a token issued before that time.
  *
  * @module
  */

api/db/migrations/0018_attachment_resource_type.ts

@@ -1,8 +1,10 @@
 /**
- * Adds `attachments.resource_type`, the kind of thing an attachment's
- * `resource_id` names. Without it, an attachment couldn't tell whose it was:
- * one pasted into a private dump was served to anyone with its URL, and one
- * whose dump, comment or message was deleted was kept for good.
+ * Serves an attachment only to those who may see what it was pasted into, and
+ * deletes it once that is gone. It adds `attachments.resource_type`, the kind
+ * of thing an attachment's `resource_id` names. Without it, an attachment
+ * couldn't tell whose it was: one pasted into a private dump was served to
+ * anyone with its URL, and one whose dump, comment or message was deleted was
+ * kept for good.
  *
  * @module
  */