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>

shared/api.ts

@@ -1,7 +1,8 @@
 /**
- * Defines the envelope every JSON endpoint answers with, and {@link Wire}, the
- * form a type takes once it has crossed JSON. The routes build the envelope,
- * and the frontend's API helpers unwrap it.
+ * Lets the client tell success from failure the same way for every JSON
+ * endpoint, through the envelope they all answer with. It also defines {@link
+ * Wire}, the form a type takes once it has crossed JSON. The routes build the
+ * envelope, and the frontend's API helpers unwrap it.
  *
  * @module
  */

shared/category.ts

@@ -1,7 +1,8 @@
 /**
- * Declares the categories that dumps are filed under, and the bodies that
- * create and change them. Only admins manage categories, through the API, since
- * no page does it. The client lists them in its `CategoriesProvider`.
+ * Categories file dumps by topic, and give each topic its own feed on the
+ * index. This module types them for the server and the client, with the bodies
+ * that create and change them. Only admins manage categories, through the API,
+ * since no page does it. The client lists them in its `CategoriesProvider`.
  *
  * @module
  */

shared/chat.ts

@@ -1,6 +1,6 @@
 /**
- * Defines a message of the site-wide chat, as the server sends it to the
- * chatbox.
+ * The site-wide chat lets signed-in users talk live. This module types one of
+ * its messages, as the server sends it to the chatbox.
  *
  * @module
  */

shared/comment.ts

@@ -1,6 +1,7 @@
 /**
- * Declares the comments posted under a dump, and the bodies that post and edit
- * them. The dump page's `CommentThread` renders them as a tree, by `parentId`.
+ * Comments let users discuss a dump under it, in threads. This module types
+ * them, with the bodies that post and edit them. The dump page's
+ * `CommentThread` renders them as a tree, by `parentId`.
  *
  * @module
  */

shared/dump.ts

@@ -1,8 +1,8 @@
 /**
- * Defines the dump, the link or file a user posts, as the API sends it, with
- * its link preview and the bodies that create and edit it. The backend's
- * `dump-service.ts` produces these types and the frontend's dump pages and
- * create form consume them.
+ * A dump is what users post: a link or a file, with a title and a note. This
+ * module types it as the API sends it, with its link preview and the bodies
+ * that create and edit it. The backend's `dump-service.ts` produces these types
+ * and the frontend's dump pages and create form consume them.
  *
  * @module
  */

shared/follow.ts

@@ -1,6 +1,7 @@
 /**
- * Types what the signed-in user follows, as the client's `FollowProvider`
- * loads it to show follow buttons pressed.
+ * Following a user or a playlist puts their dumps in the index's "followed"
+ * tab. This module types what the signed-in user follows, as the client's
+ * `FollowProvider` loads it to show the Follow buttons pressed.
  *
  * @module
  */

shared/mention.ts

@@ -1,6 +1,6 @@
 /**
- * Defines what counts as an @mention, so that the server notifies the same
- * users the chat highlights and the editor suggests.
+ * Makes the server notify the same users the chat highlights and the editor
+ * suggests, by defining once what counts as an @mention.
  *
  * @module
  */

shared/notification.ts

@@ -1,7 +1,9 @@
 /**
- * Types the notifications `api/services/notification-service.ts` makes, and
- * the data each kind carries. The client's `/notifications` page lists them
- * and turns each into a sentence and a link.
+ * Notifications tell a user when someone follows them or their playlists,
+ * upvotes, comments, likes or mentions them, or posts where they follow. This
+ * module types the ones `api/services/notification-service.ts` makes, and the
+ * data each kind carries. The client's `/notifications` page lists them and
+ * turns each into a sentence and a link.
  *
  * @module
  */

shared/permissions.ts

@@ -1,7 +1,8 @@
 /**
- * Maps each role to what it may do. The server enforces the table
- * (`api/lib/permissions.ts`, `api/routes/ws.ts`) and the client reads the same
- * one to hide what a role can't do (`src/utils/auth/permissions.ts`).
+ * Keeps the server and the client agreed on what each role may do. The server
+ * enforces this table (`api/lib/permissions.ts`, `api/routes/ws.ts`) and the
+ * client reads the same one to hide what a role can't do
+ * (`src/utils/auth/permissions.ts`).
  *
  * @module
  */

shared/player.ts

@@ -1,6 +1,7 @@
 /**
- * Defines what the Bandcamp and YouTube routes return to the frontend's
- * player when it plays a Bandcamp release or a YouTube playlist.
+ * Lets the global player play a Bandcamp release with its own controls and list
+ * a YouTube playlist's tracks. This module types what the Bandcamp and YouTube
+ * routes return to it.
  *
  * @module
  */

shared/playlist.ts

@@ -1,7 +1,7 @@
 /**
- * Declares playlists, the ordered collections of dumps their owners curate, and
- * the bodies that create, edit and reorder them. The client shows them on
- * `/playlists/:playlistId`, on profiles and in search results.
+ * Playlists are ordered collections of dumps their owners curate. This module
+ * types them, with the bodies that create, edit and reorder them. The client
+ * shows them on `/playlists/:playlistId`, on profiles and in search results.
  *
  * @module
  */

shared/search.ts

@@ -1,6 +1,6 @@
 /**
- * Declares the results of the site search, which the `Search` page shows under
- * one tab per kind.
+ * The site search finds dumps, users and playlists at once. This module types
+ * its results, which the `Search` page shows under one tab per kind.
  *
  * @module
  */

shared/user.ts

@@ -1,7 +1,8 @@
 /**
- * Types users as the API sends them, their roles, and the bodies and answers
- * of the `/api/users` and `/api/invites` endpoints, for the server and the
- * client alike.
+ * A user crosses the wire in several shapes: as anyone sees them, as they see
+ * themselves, and in the bodies and answers of the `/api/users` and
+ * `/api/invites` endpoints. This module types them all, with the roles, for the
+ * server and the client alike.
  *
  * @module
  */

shared/validation.ts

@@ -1,6 +1,6 @@
 /**
- * Holds the limits on what users submit, shared so that the forms check the
- * same limits the server enforces.
+ * Makes the forms check the same limits on what users submit as the server
+ * enforces, by holding them in one place.
  *
  * @module
  */

shared/ws.ts

@@ -1,6 +1,7 @@
 /**
- * Defines the messages of the WebSocket between `WSProvider` in the client and
- * `routes/ws.ts` in the server, as JSON objects told apart by `type`.
+ * Live updates, votes, likes and the chat travel over one WebSocket between
+ * `WSProvider` in the client and `routes/ws.ts` in the server. This module
+ * types its messages, JSON objects told apart by `type`.
  *
  * The server's messages go out from `services/ws-service.ts`, and `WSProvider`
  * handles them. Their Dates arrive as strings, so the client reads them as