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/routes/avatars.ts

@@ -1,7 +1,7 @@
 /**
- * Serves the avatar endpoints. The profile page uploads the avatar, and the
- * client's `Avatar` component loads it, with the user's `updatedAt` as a
- * cache-busting version.
+ * Stores and serves the users' avatars. The profile page uploads the avatar,
+ * and the client's `Avatar` component loads it, with the user's `updatedAt` as
+ * a cache-busting version.
  *
  * - `POST /api/avatars/me` — signed in. Replaces the caller's avatar (multipart
  *   `file`, at most 5 MB), sends `user_updated` to everyone, and answers the

api/routes/categories.ts

@@ -1,5 +1,6 @@
 /**
- * The category routes.
+ * Serves the categories dumps are filed under and their feeds, and changes them
+ * for those with `category:manage`.
  *
  * - `GET /api/categories` — public. Answers every category, in order.
  * - `GET /api/categories/:slug` — public. Answers one category.

api/routes/invites.ts

@@ -1,6 +1,6 @@
 /**
- * Serves the invite endpoints. Any signed-in user can invite someone, from
- * their profile page, and the invite link opens the `/register` page.
+ * Lets any signed-in user invite someone, from their profile page. The invite
+ * link opens the `/register` page.
  *
  * - `POST /api/invites` — signed in. Makes an invite and answers its token.
  * - `GET /api/invites/:token` — public. Checks that an invite still works,

api/routes/thumbnails.ts

@@ -31,8 +31,8 @@ import { authenticateMedia } from "../lib/auth.ts";
 const router: Router = new Router({ prefix: "/api/thumbnails" });
 
 /**
- * Holds whether ffmpeg runs, probed once per process: probing on every uncached
- * thumbnail request cost a process per card.
+ * Spares a process per uncached thumbnail request: whether ffmpeg runs is
+ * probed once per process, and kept here.
  */
 let ffmpegProbe: Promise<boolean> | undefined;
 
@@ -146,8 +146,8 @@ function imagePreview(srcPath: string, outPath: string): Promise<void> {
 }
 
 /**
- * Holds the generations under way, by output path. A feed full of cards asking
- * for the same new still at once then waits on a single ffmpeg run.
+ * Lets a feed full of cards asking for the same new still at once wait on a
+ * single ffmpeg run. It holds the generations under way, by output path.
  */
 const inFlight = new Map<string, Promise<void>>();