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/services/attachment-service.ts

@@ -1,7 +1,8 @@
 /**
- * Records the images pasted into Markdown bodies, and binds each one to the
- * resource whose body links it. `routes/attachments.ts` stores and serves the
- * files; the services that save a body call {@link linkAttachments}.
+ * Ties each image pasted into a Markdown body to the dump, comment, playlist or
+ * message that links it, so the image is served only to those who may see that,
+ * and purged at startup once it is gone. `routes/attachments.ts` stores and
+ * serves the files; the services that save a body call {@link linkAttachments}.
  *
  * @module
  */

api/services/rich-content-service.ts

@@ -52,9 +52,9 @@ const RECENT_TTL_MS = 5 * 60 * 1000;
 /** How many previews are kept. The oldest written goes first. */
 const RECENT_MAX = 200;
 /**
- * Holds the previews fetched in the last few minutes, by URL. The create form
- * previews a link and then posts it, and without this the second fetch of the
- * page was the slow part of posting. Only successes are kept.
+ * Makes posting a link fast after the create form previewed it, by keeping the
+ * previews fetched in the last few minutes, by URL. Without it, the second
+ * fetch of the page was the slow part of posting. Only successes are kept.
  */
 const recent = new Map<
   string,