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/model/auth.ts

@@ -1,6 +1,7 @@
 /**
- * Types the payloads of session and password reset tokens, and guards them.
- * `lib/jwt.ts` signs the tokens and runs the guards when it verifies one.
+ * Checks what a verified token says before it is trusted. It types the payloads
+ * of session and password reset tokens, and `lib/jwt.ts` runs their guards when
+ * it verifies one.
  *
  * @module
  */

api/model/category.ts

@@ -1,6 +1,6 @@
 /**
- * Types the rows the category service reads from `categories`, and turns them
- * into the {@link Category} the category routes send.
+ * Turns the rows the category service reads from `categories` into the {@link
+ * Category} the category routes send.
  *
  * @module
  */

api/model/chat.ts

@@ -1,5 +1,5 @@
 /**
- * Maps the rows of `chat_messages` to the {@link ChatMessage} the API sends.
+ * Turns the rows of `chat_messages` into the {@link ChatMessage} the API sends.
  * Only `services/chat-service.ts` uses it, on the rows of its one query.
  *
  * @module

api/model/comment.ts

@@ -1,6 +1,6 @@
 /**
- * Types the rows the comment service reads from `comments`, and turns them into
- * the {@link Comment} the comment routes send.
+ * Turns the rows the comment service reads from `comments` into the {@link
+ * Comment} the comment routes send.
  *
  * @module
  */

api/model/dump.ts

@@ -1,7 +1,8 @@
 /**
- * Maps the `dumps` table to the API's {@link Dump}. Every service that reads
- * dumps selects them with the column lists here, checks each row with
- * {@link isDumpRow} and converts it with {@link dumpRowToApi}.
+ * Turns the rows of `dumps` into the API's {@link Dump} the same way for every
+ * service that reads dumps: each selects them with the column lists here,
+ * checks each row with {@link isDumpRow} and converts it with {@link
+ * dumpRowToApi}.
  *
  * @module
  */

api/model/follow.ts

@@ -1,6 +1,6 @@
 /**
- * Types and guards the rows of `follows`, which `follow-service.ts` reads to
- * answer what a user follows.
+ * Checks the rows `follow-service.ts` reads from `follows` to answer what a
+ * user follows.
  *
  * @module
  */

api/model/invite.ts

@@ -1,6 +1,6 @@
 /**
- * Types and guards the rows of `invites`, which `invite-service.ts` reads to
- * check an invite before sign-up.
+ * Checks the rows `invite-service.ts` reads from `invites` to vet an invite
+ * before sign-up.
  *
  * @module
  */

api/model/notification.ts

@@ -1,6 +1,6 @@
 /**
- * Types and guards the rows of `notifications`, and converts them to the
- * {@link Notification} that `GET /api/notifications` answers.
+ * Turns the rows of `notifications`, once checked, into the {@link
+ * Notification} that `GET /api/notifications` answers.
  *
  * @module
  */

api/model/password-reset.ts

@@ -1,6 +1,6 @@
 /**
- * Types and guards the rows of `password_reset_tokens`, which
- * `password-reset-service.ts` reads to make each reset link work once.
+ * Checks the rows `password-reset-service.ts` reads from
+ * `password_reset_tokens` to make each reset link work once.
  *
  * @module
  */

api/model/playlist.ts

@@ -1,6 +1,6 @@
 /**
- * Types the rows the playlist and follow services read from `playlists`, and
- * turns them into the {@link Playlist} the API sends.
+ * Turns the rows the playlist and follow services read from `playlists` into
+ * the {@link Playlist} the API sends.
  *
  * @module
  */

api/model/rows.ts

@@ -1,7 +1,6 @@
 /**
- * Checks the rows of a list query, for the services. Every service answers a
- * row that doesn't have its table's shape with a 500 rather than leaving it
- * out, so that damage shows instead of making items silently vanish.
+ * Makes a damaged row fail its query with a 500 rather than silently vanish
+ * from a list. Every service checks the rows of its list queries with it.
  *
  * @module
  */

api/model/user.ts

@@ -1,7 +1,7 @@
 /**
- * Types and guards the rows of `users`, and converts them to the {@link User}
- * that `user-service.ts` returns. A route turns a `User` into what it may send
- * with {@link toPublicUser} or {@link toSelfUser}.
+ * Turns the rows of `users`, once checked, into the {@link User} that
+ * `user-service.ts` returns. A route turns a `User` into what it may send with
+ * {@link toPublicUser} or {@link toSelfUser}.
  *
  * @module
  */