diff --git a/app/components/AbilitiesSelector.tsx b/app/components/AbilitiesSelector.tsx
index 041366d11..7105ea58f 100644
--- a/app/components/AbilitiesSelector.tsx
+++ b/app/components/AbilitiesSelector.tsx
@@ -176,28 +176,21 @@ function addAbility({
 	) as BuildAbilitiesTupleWithUnknown;
 
 	if (atRowIndex !== undefined && atAbilityIndex !== undefined) {
-		// Attempt to place the ability at a specific slot since we
-		// were given an atRowIndex and atAbilityIndex
 		if (canPlaceAbilityAtSlot(atRowIndex, atAbilityIndex, ability)) {
-			// Assign this ability to the slot
 			abilitiesClone[atRowIndex][atAbilityIndex] = ability.name;
 		}
 	} else {
-		// Loop through all slots and attempt to place this ability
-		// in the first empty one
+		// place in the first empty valid slot
 		for (const [rowIndex, row] of abilitiesClone.entries()) {
 			for (const [abilityIndex, oldAbility] of row.entries()) {
 				if (oldAbility !== "UNKNOWN") {
-					// Skip any filled slots in this loop until we arrive at an empty one.
 					continue;
 				}
 
 				if (!canPlaceAbilityAtSlot(rowIndex, abilityIndex, ability)) {
-					// This ability isn't valid for this slot
 					continue;
 				}
 
-				// Assign this ability to the slot
 				abilitiesClone[rowIndex][abilityIndex] = ability.name;
 
 				return abilitiesClone;
@@ -205,6 +198,5 @@ function addAbility({
 		}
 	}
 
-	// no-op if no available slots
 	return abilitiesClone;
 }
diff --git a/app/components/Ability.tsx b/app/components/Ability.tsx
index 7f997487f..7a37edfa4 100644
--- a/app/components/Ability.tsx
+++ b/app/components/Ability.tsx
@@ -47,7 +47,6 @@ export function Ability({
 
 	const readonly = typeof onClick === "undefined" || ability === "UNKNOWN"; // Force "UNKNOWN" ability icons to be readonly
 
-	// Render an ability as a button only if it is meant to be draggable (i.e., not readonly)
 	const AbilityTag = readonly ? "div" : "button";
 
 	const altText =
diff --git a/app/components/ActionButton.tsx b/app/components/ActionButton.tsx
index dbe76c341..2ab2acae1 100644
--- a/app/components/ActionButton.tsx
+++ b/app/components/ActionButton.tsx
@@ -14,16 +14,15 @@ interface ActionButtonBaseProps<
 	TSchema extends AnySchema,
 	TAction extends ActionsOf<TSchema>,
 > extends Omit<SendouButtonProps, "type" | "name" | "value" | "form"> {
-	/** Action schema of the route the button submits to. Only used for typing `action` and `fields`. */
+	/** Route's action schema, only used for typing `action` and `fields`. */
 	schema: TSchema;
-	/** `_action` to submit, narrowed to the literals of the schema. */
 	action: TAction;
-	/** Route to submit to. Defaults to the current route. */
+	/** Defaults to the current route. */
 	formAction?: string;
 	formClassName?: string;
-	/** Fetcher to submit with, e.g. to share submitting state between buttons. Defaults to own fetcher. */
+	/** e.g. to share submitting state between buttons */
 	fetcher?: FetcherWithComponents<unknown>;
-	/** When set, submits only after the user confirms via a dialog. */
+	/** submits only after the user confirms via a dialog */
 	confirm?: {
 		dialogHeading: string;
 		description?: React.ReactNode;
diff --git a/app/components/BuildCard.tsx b/app/components/BuildCard.tsx
index 124b4d598..d0bc6fec0 100644
--- a/app/components/BuildCard.tsx
+++ b/app/components/BuildCard.tsx
@@ -65,7 +65,7 @@ interface BuildProps {
 		Partial<
 			Pick<BuildGraphicOwner, "customUrl" | "discordAvatar" | "customAvatarUrl">
 		>;
-	/** Set to false when the page context already shows the owner (e.g. their own builds page) */
+	/** false when the page already shows the owner (e.g. their own builds page) */
 	showOwner?: boolean;
 	canEdit?: boolean;
 }
diff --git a/app/components/Catcher.tsx b/app/components/Catcher.tsx
index 9ad37bebe..10cead5ca 100644
--- a/app/components/Catcher.tsx
+++ b/app/components/Catcher.tsx
@@ -29,7 +29,7 @@ export function Catcher() {
 		window.scrollTo(0, 0);
 	}, []);
 
-	// refresh user data to make sure it's up to date (e.g. cookie might have been removed, let's show the prompt to log back in)
+	// refresh user data so e.g. a removed cookie shows the prompt to log back in
 	const hasRevalidated = React.useRef(false);
 	React.useEffect(() => {
 		if (!isRouteErrorResponse(error) || error.status !== 401) return;
@@ -144,10 +144,7 @@ export function Catcher() {
 	}
 }
 
-/**
- * A client side navigation to an URL matching no route never reaches the server, so the
- * redirects (normally resolved by `redirectsMiddleware`) are checked here as well.
- */
+/** Client side navigation to an unmatched URL never reaches the server, so `redirectsMiddleware`'s redirects are checked here too. */
 function PageNotFound() {
 	const location = useLocation();
 	const navigate = useNavigate();
diff --git a/app/components/Chart.tsx b/app/components/Chart.tsx
index f192b26b0..fd049159f 100644
--- a/app/components/Chart.tsx
+++ b/app/components/Chart.tsx
@@ -49,14 +49,14 @@ export default function Chart({
 	xTicksLimit?: number;
 	yTicksLimit?: number;
 	xAbilityLimit?: number;
-	/** Marks current positions on the curve, each at ability point `x` and stat value `y` (e.g. one per build being compared). */
+	/** Markers on the curve at ability point `x` / stat value `y`, e.g. one per build compared. */
 	highlight?: Array<{ x: number; y: number }>;
-	/** When true, draws dashed guide lines from the hovered point to the x- and y-axes. */
+	/** dashed guide lines from the hovered point to both axes */
 	crosshair?: boolean;
 }) {
 	const isHydrated = useHydrated();
 
-	// Ref to the Chart.js instance, allows proper cleanup between renders to prevent "Canvas is already in use" errors
+	// cleanup between renders prevents "Canvas is already in use" errors
 	const chartRef = useRef<ChartType<"line"> | null>(null);
 	const chartId = React.useId();
 	// Chart.js re-fires the external tooltip on every redraw; track the last value to skip redundant state updates
@@ -74,22 +74,19 @@ export default function Chart({
 		header: string;
 	} | null>(null);
 
-	// Format dates in the tooltip header using the user's locale
 	const { formatter: headerFormatter } = useDateTimeFormat({
 		weekday: "short",
 		day: "numeric",
 		month: "numeric",
 	});
 
-	// Format dates on the xAxis
 	const { formatter: scaleFormatter } = useDateTimeFormat({
 		day: "numeric",
 		month: "numeric",
 	});
 
-	// Get the chart colors from CSS variables
 	const colors = useThemeColors({
-		// bright "high" variants for the curve lines so they stay legible on the dark chart
+		// "high" variants for the curve lines so they stay legible on the dark chart
 		accentHigh: "--color-text-accent",
 		infoHigh: "--color-info-high",
 		secondHigh: "--color-second-high",
@@ -110,13 +107,12 @@ export default function Chart({
 		[colors.border, colors.borderHigh, colors.text],
 	);
 
-	// Make a color list to use inside ChartData for the borderColor and the external tooltip
 	const colorList = React.useMemo(
 		() => [colors.accentHigh, colors.infoHigh, colors.secondHigh],
 		[colors.accentHigh, colors.infoHigh, colors.secondHigh],
 	);
 
-	// Distinct accent/secondary pair so the highlight markers (e.g. build 1 vs build 2) stay tellable apart in both themes
+	// distinct pair so highlight markers (e.g. build 1 vs build 2) stay apart in both themes
 	const markerColors = React.useMemo(
 		() => [colors.accentLow, colors.secondLow],
 		[colors.accentLow, colors.secondLow],
@@ -169,7 +165,6 @@ export default function Chart({
 		[options, datasetColors, highlight, markerColors, colors.text],
 	);
 
-	// Draws dashed guide lines from the hovered point to the y-axis (left) and x-axis (bottom)
 	const crosshairPlugin = React.useMemo(
 		() => ({
 			id: "crosshair",
diff --git a/app/components/EmptyState.tsx b/app/components/EmptyState.tsx
index 2ed9a3a24..52beace7c 100644
--- a/app/components/EmptyState.tsx
+++ b/app/components/EmptyState.tsx
@@ -9,7 +9,7 @@ interface EmptyStateProps {
 	children: React.ReactNode;
 }
 
-/** Renders the message shown by a page or tab that has no content, with the feature's nav icon above it. */
+/** Message for a page or tab with no content, with the feature's nav icon above it. */
 export function EmptyState({ navItem, children }: EmptyStateProps) {
 	return (
 		<div className={styles.container}>
diff --git a/app/components/FormWithConfirm.tsx b/app/components/FormWithConfirm.tsx
index bc06fa3bb..cc0dbb038 100644
--- a/app/components/FormWithConfirm.tsx
+++ b/app/components/FormWithConfirm.tsx
@@ -37,17 +37,17 @@ export function FormWithConfirm({
 	)[];
 	children?: React.ReactElement<ChildProps>;
 	dialogHeading: string;
-	/** Optional explanatory text shown below the heading in the confirm dialog */
+	/** shown below the heading in the confirm dialog */
 	description?: React.ReactNode;
 	submitButtonText?: string;
 	action?: string;
 	submitButtonTestId?: string;
 	submitButtonVariant?: SendouButtonProps["variant"];
 	fetcher?: FetcherWithComponents<any>;
-	/** Controls the dialog open state. When provided, no child trigger is needed. */
+	/** controlled open state, no child trigger needed */
 	isOpen?: boolean;
 	onOpenChange?: (isOpen: boolean) => void;
-	/** Confirming runs this callback instead of submitting a form (client only action) */
+	/** runs instead of submitting a form (client only action) */
 	onConfirm?: () => void;
 }) {
 	const componentsFetcher = useFetcher();
diff --git a/app/components/GameTimeline.tsx b/app/components/GameTimeline.tsx
index 152e11217..5d4238079 100644
--- a/app/components/GameTimeline.tsx
+++ b/app/components/GameTimeline.tsx
@@ -1,11 +1,7 @@
 /**
- * A game's two scanned-timeline charts stacked on one shared time axis and
- * plot width: per-player status bands above the objective-counter chart.
- * Hovering scrubs over both — a dotted cursor line spans the charts and a
- * readout next to the cursor shows the moment's elapsed time, match clock,
- * scores, penalties, who was in control, who was splatted and who had their
- * special ready. The chart's own tooltip is turned off in favor of the
- * readout.
+ * A game's two scanned-timeline charts (player status bands above the objective-counter chart)
+ * on one shared time axis. Hovering scrubs both: a cursor line spans the charts and a readout
+ * shows the moment's state, replacing the chart's own tooltip.
  */
 import clsx from "clsx";
 import { memo, useRef, useState } from "react";
diff --git a/app/components/LocaleTime.tsx b/app/components/LocaleTime.tsx
index 67514e95b..df95f99e2 100644
--- a/app/components/LocaleTime.tsx
+++ b/app/components/LocaleTime.tsx
@@ -3,24 +3,18 @@ import { useDateTimeFormat } from "~/hooks/intl/useDateTimeFormat";
 import { databaseTimestampToDate } from "~/utils/dates";
 
 interface LocaleTimeProps {
-	/** The date to render. Accepts a `Date` or a database timestamp (number), which is converted via `databaseTimestampToDate`. */
+	/** `Date` or database timestamp */
 	date: Date | number;
-	/** Formatting options forwarded to `Intl.DateTimeFormat`. Combined with the user's locale and hour cycle preferences. */
 	options: Intl.DateTimeFormatOptions;
-	/** Optional extra class names appended to the rendered `<time>` element. */
 	className?: string;
-	/** When `true`, renders inline; otherwise the element is displayed as a block. Defaults to block. */
+	/** defaults to block */
 	inline?: boolean;
-	/** Optional test id forwarded to the rendered `<time>` element. */
 	"data-testid"?: string;
 }
 
 /**
- * Renders a `<time>` element with the given date formatted according to the user's locale preferences.
- *
- * During SSR and before the user's locale preference has loaded the formatted text is hidden
- * (via `invisible`) while still reserving one line of height to avoid layout shift on hydration.
- * The `dateTime` attribute is always set to the ISO string for machine readability and a11y.
+ * `<time>` formatted per the user's locale preferences. Before the preference has loaded (SSR)
+ * the text is `invisible` but still reserves one line of height to avoid layout shift.
  */
 export function LocaleTime({
 	date,
@@ -36,9 +30,8 @@ export function LocaleTime({
 
 	return (
 		<time
-			// Hydration warnings are suppressed because callers may pass a live "now" value (e.g. a clock)
-			// whose server and client render instants differ slightly, which would otherwise mismatch the
-			// `dateTime` attribute. For fixed dates the ISO string is deterministic, so nothing real is masked.
+			// a live "now" value (e.g. a clock) differs slightly between server and client render,
+			// which would mismatch `dateTime`; fixed dates are deterministic so nothing real is masked
 			suppressHydrationWarning
 			data-testid={testId}
 			dateTime={dateObject.toISOString()}
diff --git a/app/components/LocaleTimeRange.tsx b/app/components/LocaleTimeRange.tsx
index d94ea4d01..ba58a90db 100644
--- a/app/components/LocaleTimeRange.tsx
+++ b/app/components/LocaleTimeRange.tsx
@@ -3,27 +3,21 @@ import { useDateTimeFormat } from "~/hooks/intl/useDateTimeFormat";
 import { databaseTimestampToDate } from "~/utils/dates";
 
 interface LocaleTimeRangeProps {
-	/** Start of the range. Accepts a `Date` or a database timestamp (number), which is converted via `databaseTimestampToDate`. */
+	/** `Date` or database timestamp */
 	from: Date | number;
-	/** End of the range. Accepts a `Date` or a database timestamp (number), which is converted via `databaseTimestampToDate`. */
+	/** `Date` or database timestamp */
 	to: Date | number;
-	/** Formatting options forwarded to `Intl.DateTimeFormat`. Combined with the user's locale and hour cycle preferences. */
 	options: Intl.DateTimeFormatOptions;
-	/** Optional extra class names appended to the rendered element. */
 	className?: string;
-	/** When `true`, renders inline; otherwise the element is displayed as a block. Defaults to block. */
+	/** defaults to block */
 	inline?: boolean;
-	/** Optional test id forwarded to the rendered element. */
 	"data-testid"?: string;
 }
 
 /**
- * Renders the given date range formatted according to the user's locale preferences,
- * using `Intl.DateTimeFormat.prototype.formatRange` for locale-aware separators and
- * collapsing of shared parts (e.g. the year when both bounds share it).
- *
- * During SSR and before the user's locale preference has loaded the formatted text is hidden
- * (via `invisible`) while still reserving one line of height to avoid layout shift on hydration.
+ * Date range via `Intl.DateTimeFormat.formatRange` (locale-aware separators, shared parts
+ * collapsed). Before the locale preference has loaded (SSR) the text is `invisible` but still
+ * reserves one line of height to avoid layout shift.
  */
 export function LocaleTimeRange({
 	from,
diff --git a/app/components/NoteAvatar.tsx b/app/components/NoteAvatar.tsx
index f63c3f3af..a61ea9ef6 100644
--- a/app/components/NoteAvatar.tsx
+++ b/app/components/NoteAvatar.tsx
@@ -25,13 +25,9 @@ const SIZE_CLASS = {
 } as const;
 
 /**
- * Wraps an avatar (or any node) and overlays a sentiment badge on the bottom-left corner when
- * `sentiment` is set: POSITIVE → green check, NEGATIVE → red cross, NEUTRAL → grey dash. Renders the
- * children without a badge when `sentiment` is `null`/`undefined`. `size` scales the badge to match
- * the wrapped avatar (`xs` for tiny avatars, `sm` for small avatars, `md` for large ones).
- *
- * `onClick` makes the whole wrapper (avatar and badge) clickable. It is kept out of the tab order, so
- * only use it as a shortcut to an action that is also available elsewhere.
+ * Overlays a sentiment badge (check / cross / dash) on the bottom-left of the wrapped avatar;
+ * `size` matches the avatar. `onClick` is kept out of the tab order, so only use it as a shortcut
+ * to an action also available elsewhere.
  */
 export function NoteAvatar({
 	sentiment,
diff --git a/app/components/ObjectiveTimeline.tsx b/app/components/ObjectiveTimeline.tsx
index 4081f5c1c..d2a9c9c7a 100644
--- a/app/components/ObjectiveTimeline.tsx
+++ b/app/components/ObjectiveTimeline.tsx
@@ -1,20 +1,9 @@
 /**
- * Line chart of a game's objective-counter reads: one line per team
- * (remaining count over match time, so lines fall toward 0). Control is a
- * state rather than a count, so it gets its own lane in a gutter below the
- * zero gridline instead of sharing the count axis — a strip in the
- * controlling team's color, absent while neither team controls. The
- * zero gridline is drawn in the stronger border color to read as the
- * divider between the counts above and the lane below. Penalty is a
- * translucent band filled between score and score + penalty — its thickness
- * is the extra count the team must burn through before its score moves
- * again, so it grows when a penalty lands and shrinks as it counts down.
- * Control state and exact values stay in the shared hover tooltip.
- *
- * Series colors are the chart tokens from vars.css — the theme's text-tier
- * colors are too pastel to tell apart as marks; these are the same two hues
- * re-stepped per theme and validated for CVD separation and surface
- * contrast.
+ * Line chart of a game's objective-counter reads, one falling line per team. Control is a state,
+ * not a count, so it gets its own lane below the zero gridline (strip in the controlling team's
+ * color); penalty is a translucent band between score and score + penalty, so its thickness is
+ * the extra count to burn through. Series colors are the chart tokens from vars.css: the text-tier
+ * colors are too pastel to tell apart as marks.
  */
 
 import {
@@ -261,10 +250,7 @@ export function ObjectiveTimeline({
 	);
 }
 
-/**
- * One tick every 25 up to the top of the data and none below zero, so the
- * control gutter stays free of axis furniture.
- */
+/** One tick every 25 up to the top of the data, none below zero so the control gutter stays clean. */
 function countAxisTicks(max: number) {
 	const ticks = [];
 	for (let value = 0; value <= max; value += COUNT_TICK_STEP) {
diff --git a/app/components/Pagination.test.ts b/app/components/Pagination.test.ts
index 2c0bf695d..9e2fff7c0 100644
--- a/app/components/Pagination.test.ts
+++ b/app/components/Pagination.test.ts
@@ -87,9 +87,7 @@ describe("getPageNumbers", () => {
 	});
 
 	test("shows a bridging number instead of an ellipsis that hides a single page", () => {
-		// An ellipsis takes the same space as one page number, so replacing a
-		// lone hidden page with "..." is never an improvement (same intent as the
-		// edge "lonely jump" fix, but for windows one step inward).
+		// an ellipsis takes the same space as one page number, so hiding a lone page is never an improvement
 		// desktop window around page 5 of 10 leaves only page 2 hidden on the left
 		expect(desktopView(5, 10)).toEqual([1, 2, 3, 4, 5, 6, 7, "...", 10]);
 		// ...and only page 9 hidden on the right for page 6 of 10
diff --git a/app/components/Pagination.tsx b/app/components/Pagination.tsx
index 396856758..1770f833b 100644
--- a/app/components/Pagination.tsx
+++ b/app/components/Pagination.tsx
@@ -249,15 +249,10 @@ export function getPageNumbers(
 }
 
 /**
- * Inclusive range of inner page numbers (excluding the always-shown first and
- * last page) to render around the current page. The window is nudged inward by
- * one when the current page is the very first or last page, so the edge view
- * shows a bridging number instead of a lonely jump like "1 2 … 8".
- *
- * When exactly one page would be left between the window and the always-shown
- * first or last page, the window is widened to include it: an ellipsis takes
- * the same space as a single page number, so "1 … 3" is never better than
- * "1 2 3".
+ * Inclusive range of inner page numbers (first and last are always shown) around the current
+ * page. Nudged inward by one at the very first/last page so the edge shows a bridging number
+ * instead of "1 2 … 8", and widened when exactly one page would be hidden: an ellipsis takes the
+ * same space, so "1 … 3" is never better than "1 2 3".
  */
 function innerPageWindow(
 	currentPage: number,
diff --git a/app/components/Placeholder.tsx b/app/components/Placeholder.tsx
index d41c8da14..473681b37 100644
--- a/app/components/Placeholder.tsx
+++ b/app/components/Placeholder.tsx
@@ -1,6 +1,6 @@
 import styles from "./Placeholder.module.css";
 
-/** Renders a blank placeholder component that can be used while content is loading. Better than returning null because it keeps the footer down where it belongs. */
+/** Blank placeholder while content loads; unlike null it keeps the footer down. */
 export function Placeholder() {
 	return <div className={styles.placeholder} />;
 }
diff --git a/app/components/PlayerStatusTimeline.tsx b/app/components/PlayerStatusTimeline.tsx
index 2ac487bcf..bb6c78bc4 100644
--- a/app/components/PlayerStatusTimeline.tsx
+++ b/app/components/PlayerStatusTimeline.tsx
@@ -1,12 +1,8 @@
 /**
- * Per-player status bands over a game's scanned icon-strip reads: one row
- * per player (weapon icon as the label), a band while the player was
- * splatted and another while they held their special, both teams stacked.
- * Rendered above the ObjectiveTimeline chart on the same `t` seconds axis —
- * pass `domain` so both span the same range. Reads re-confirm an unchanged
- * state every few seconds; a longer sample gap means the HUD was not
- * observed, so bands never bridge across one (the state there is unknown,
- * not continued).
+ * Per-player splatted / special-held bands over a game's scanned icon-strip reads, rendered above
+ * the ObjectiveTimeline on the same `t` axis (pass `domain` to share the range). Reads re-confirm
+ * an unchanged state every few seconds; a longer gap means the HUD was not observed, so bands never
+ * bridge across one.
  */
 import { useTranslation } from "react-i18next";
 import type { MainWeaponId } from "~/modules/in-game-lists/types";
@@ -150,10 +146,8 @@ interface StatusSpan {
 }
 
 /**
- * Contiguous stretches where the flag held true: a span opens at its first
- * true read and closes at the read that shows false — or one second past
- * its last confirmation when the next read is too far away (or the series
- * ends) to know what happened in between.
+ * Contiguous stretches where the flag held true: opens at the first true read, closes at the read
+ * showing false, or one second past the last confirmation when the next read is too far away.
  */
 export function statusSpans(
 	sorted: readonly PlayerStatusTimelineSample[],
diff --git a/app/components/RankTable.tsx b/app/components/RankTable.tsx
index 1234c1137..86827b97f 100644
--- a/app/components/RankTable.tsx
+++ b/app/components/RankTable.tsx
@@ -1,7 +1,4 @@
-/**
- * Rows of ranked entries (rank, avatar, weapon, name, power) as rendered by the
- * leaderboards and the X Rank top search pages.
- */
+/** Rows of ranked entries (rank, avatar, weapon, name, power) for the leaderboards and X Rank top search pages. */
 
 import clsx from "clsx";
 import type * as React from "react";
diff --git a/app/components/SpDelta.tsx b/app/components/SpDelta.tsx
index 745afd4d1..f2f29eff3 100644
--- a/app/components/SpDelta.tsx
+++ b/app/components/SpDelta.tsx
@@ -1,10 +1,6 @@
 import { roundToNDecimalPlaces } from "~/utils/number";
 
-/**
- * An SP change, rendered as a colored arrow followed by the size of the change.
- * A change of exactly zero gets no arrow. Meant to be placed in a flex or grid
- * container that spaces the two apart.
- */
+/** SP change as a colored arrow (none for zero) and the size; place in a flex/grid container spacing the two. */
 export function SpDelta({ diff }: { diff: number }) {
 	const rounded = roundToNDecimalPlaces(diff);
 
diff --git a/app/components/StageBannerBox.tsx b/app/components/StageBannerBox.tsx
index 8c5e33aeb..1f4f7c54c 100644
--- a/app/components/StageBannerBox.tsx
+++ b/app/components/StageBannerBox.tsx
@@ -4,11 +4,7 @@ import type { StageId } from "~/modules/in-game-lists/types";
 import { stageBannerImageUrl } from "~/utils/urls";
 import styles from "./StageBannerBox.module.css";
 
-/**
- * Box with a stage banner image fading in from the right. The fade color
- * defaults to `--color-bg-high`; override per use with the
- * `--stage-banner-fade` CSS variable.
- */
+/** Box with a stage banner fading in from the right; fade color via `--stage-banner-fade` (default `--color-bg-high`). */
 export function StageBannerBox({
 	stageId,
 	className,
diff --git a/app/components/SubmitButton.tsx b/app/components/SubmitButton.tsx
index 39d884eac..2b45e51a8 100644
--- a/app/components/SubmitButton.tsx
+++ b/app/components/SubmitButton.tsx
@@ -4,14 +4,13 @@ import type { AnySchema } from "~/utils/schema";
 import { SendouButton, type SendouButtonProps } from "./elements/Button";
 
 type SubmitButtonProps<TSchema extends AnySchema> = SendouButtonProps & {
-	/** If the page has multiple forms you can pass in fetcher.state to differentiate when this SubmitButton should be in submitting state */
+	/** fetcher.state, to tell apart submitting state between multiple forms */
 	state?: FetcherWithComponents<any>["state"];
 	testId?: string;
 } & (
 		| {
-				/** Action schema of the route the form submits to. Only used for typing `_action`. */
+				/** Route's action schema, only used for typing `_action`. */
 				schema: TSchema;
-				/** `_action` to submit, narrowed to the literals of the schema. */
 				_action: ActionsOf<TSchema>;
 		  }
 		| { schema?: never; _action?: never }
diff --git a/app/components/UserLink.tsx b/app/components/UserLink.tsx
index 790077bc0..08032deb4 100644
--- a/app/components/UserLink.tsx
+++ b/app/components/UserLink.tsx
@@ -18,7 +18,7 @@ type UnlinkedPlayer = { name: string | null } & {
 	[K in keyof UserLinkUser]: UserLinkUser[K] | null;
 };
 
-/** Link to a user's page showing their avatar and username. Accepts also result players without an account, rendering just their name. */
+/** Avatar + username link; result players without an account render just their name. */
 export function UserLink({
 	user,
 	size = "xxs",
diff --git a/app/components/WeaponSelect.tsx b/app/components/WeaponSelect.tsx
index db9d6c276..df148c53d 100644
--- a/app/components/WeaponSelect.tsx
+++ b/app/components/WeaponSelect.tsx
@@ -45,7 +45,7 @@ interface WeaponSelectProps<
 	disabledWeaponIds?: Array<MainWeaponId>;
 	testId?: string;
 	isRequired?: boolean;
-	/** If set, selection of weapons that user sees when search input is empty allowing for quick select for e.g. previous selections */
+	/** Shown while the search input is empty, e.g. previous selections */
 	quickSelectWeaponsIds?: Array<MainWeaponId>;
 	isDisabled?: boolean;
 	placeholder?: string;
@@ -253,9 +253,8 @@ function useWeaponItems({
 	const [filterValue, setFilterValue] = React.useState("");
 	const { t } = useTranslation(["common"]);
 
-	// While closed only the selected item is needed (the trigger's value
-	// display); react-aria renders every item passed to it into a hidden
-	// collection even when the popover is closed.
+	// react-aria renders every item into a hidden collection even while closed,
+	// when only the selected item (the trigger's value) is needed
 	if (!isOpen) {
 		return {
 			items: collapseToSelectedItem(items, selectedKey),
@@ -298,7 +297,6 @@ function useWeaponItems({
 		};
 
 		return {
-			// not too sure why we need to type cast here.. was working fine before refactoring
 			items: [quickSelectCategory] as typeof items,
 			filterValue,
 			setFilterValue,
@@ -401,8 +399,7 @@ function keyify(value?: MainWeaponId | AnyWeapon | null) {
 function collapseToSelectedItem<
 	Category extends { items: Array<{ weapon: { anyWeaponId: string } }> },
 >(categories: Category[], selectedKey: string | null | undefined): Category[] {
-	// react-stately refuses to open a select whose collection is empty, so even
-	// with nothing selected the closed collection keeps one item around.
+	// react-stately refuses to open a select with an empty collection, so one item is always kept
 	const fallbackItems = () => {
 		const firstCategory = categories[0];
 		if (!firstCategory) return [];
diff --git a/app/components/elements/Button.tsx b/app/components/elements/Button.tsx
index 2e05ad35e..e706c18bf 100644
--- a/app/components/elements/Button.tsx
+++ b/app/components/elements/Button.tsx
@@ -190,10 +190,7 @@ function iconClassName(
 	});
 }
 
-/**
- * Renders the button look on a plain element, for when the interactive element
- * is elsewhere, e.g. the box inside a tab.
- */
+/** Button look on a plain element, for when the interactive element is elsewhere (e.g. the box inside a tab). */
 export function ButtonLook({
 	className,
 	children,
diff --git a/app/components/elements/Calendar.tsx b/app/components/elements/Calendar.tsx
index c99383f02..b91eddc92 100644
--- a/app/components/elements/Calendar.tsx
+++ b/app/components/elements/Calendar.tsx
@@ -17,7 +17,7 @@ import styles from "./Calendar.module.css";
 export interface SendouCalendarProps<T extends DateValue>
 	extends CalendarProps<T> {
 	className?: string;
-	/** Highlights the whole week row rather than a single day, for pickers where choosing a day means choosing the week it belongs to. */
+	/** Selecting a day selects (and highlights) its whole week. */
 	weekSelection?: boolean;
 }
 
diff --git a/app/components/elements/Dialog.tsx b/app/components/elements/Dialog.tsx
index 5f0b3042a..cd34f8fdc 100644
--- a/app/components/elements/Dialog.tsx
+++ b/app/components/elements/Dialog.tsx
@@ -19,41 +19,19 @@ interface SendouDialogProps extends ModalOverlayProps {
 	heading?: string;
 	showHeading?: boolean;
 	onClose?: () => void;
-	/** When closing the modal which URL to navigate to */
+	/** URL to navigate to on close */
 	onCloseTo?: string;
 	overlayClassName?: string;
 	"aria-label"?: string;
-	/** If true, the modal takes over the full screen with the content below hidden */
+	/** takes over the full screen, hiding the content below */
 	isFullScreen?: boolean;
-	/** If true, shows the close button even if onClose is not provided */
+	/** show the close button even without onClose */
 	showCloseButton?: boolean;
 }
 
 /**
- * This component allows you to create a dialog with a customizable trigger and content.
- * It supports both controlled and uncontrolled modes for managing the dialog's open state.
- *
- * @example
- * // Example usage with implicit isOpen
- * return (
- *   <SendouDialog
- *     heading="Dialog Title"
- *     onCloseTo={previousPageUrl()}
- *   >
- *     This is the dialog content.
- *   </SendouDialog>
- * );
- *
- * @example
- * // Example usage with a SendouButton as the trigger
- * return (
- *   <SendouDialog
- *     heading="Dialog Title"
- *     trigger={<SendouButton>Open Dialog</SendouButton>}
- *   >
- *     This is the dialog content.
- *   </SendouDialog>
- * );
+ * Dialog that is open by default without a `trigger` (or controlled via `isOpen`), or opened by
+ * the given `trigger` element.
  */
 export function SendouDialog({
 	trigger,
diff --git a/app/components/elements/Popover.tsx b/app/components/elements/Popover.tsx
index 33066662f..0f8e48ad3 100644
--- a/app/components/elements/Popover.tsx
+++ b/app/components/elements/Popover.tsx
@@ -7,19 +7,7 @@ import {
 } from "react-aria-components";
 import styles from "./Popover.module.css";
 
-/**
- * A reusable popover component that wraps around a trigger element (SendouButton or Button from React Aria Components library).
- * Supports controlled and uncontrolled open states.
- *
- * @example
- * ```tsx
- * <SendouPopover
- *   trigger={<SendouButton>Click me</SendouButton>}
- * >
- *   Popover content goes here!
- * </SendouPopover>
- * ```
- */
+/** Popover opened by `trigger` (a SendouButton or React Aria Button); controlled or uncontrolled. */
 export function SendouPopover({
 	children,
 	trigger,
@@ -48,11 +36,7 @@ export function SendouPopover({
 	);
 }
 
-/**
- * Popover anchored to a trigger rendered outside of it, with its open state
- * controlled by the caller. Prefer `SendouPopover` when the trigger can be
- * passed in.
- */
+/** Controlled popover anchored to a trigger rendered outside of it. Prefer `SendouPopover` when the trigger can be passed in. */
 export function SendouAnchoredPopover({
 	children,
 	isOpen,
diff --git a/app/components/elements/SearchSelect.tsx b/app/components/elements/SearchSelect.tsx
index c52d87dd6..5fa936ca7 100644
--- a/app/components/elements/SearchSelect.tsx
+++ b/app/components/elements/SearchSelect.tsx
@@ -56,11 +56,7 @@ interface SearchSelectProps<
 	renderItem: (item: TItem) => React.ReactElement;
 }
 
-/**
- * Presentational autocomplete select shared by the entity search components
- * (e.g. `UserSearch`, `TeamSearch`, `TournamentSearch`). Wire up data fetching
- * with `useEntitySearch` and pass its result as `search`.
- */
+/** Presentational autocomplete select for the entity searches (`UserSearch` etc.); `search` comes from `useEntitySearch`. */
 export function SearchSelect<
 	TItem extends { id: number; name: string },
 	T extends object,
@@ -131,8 +127,7 @@ function PlaceholderItem({
 }) {
 	const { t } = useTranslation(["common"]);
 
-	// for some reason the `renderEmptyState` on ListBox is not working
-	// so doing this as a workaround
+	// workaround for `renderEmptyState` on ListBox not working
 	return (
 		<ListBoxItem
 			textValue="PLACEHOLDER"
@@ -146,11 +141,7 @@ function PlaceholderItem({
 	);
 }
 
-/**
- * One result inside a `SearchSelect`'s list: an optional leading avatar or
- * logo, then the texts. `SearchSelectItemAdditionalText` renders the muted
- * second line, which is hidden while the item is shown in the trigger.
- */
+/** One `SearchSelect` result; `SearchSelectItemAdditionalText` is the muted second line, hidden in the trigger. */
 export function SearchSelectItem({
 	id,
 	textValue,
diff --git a/app/components/elements/Select.tsx b/app/components/elements/Select.tsx
index ada2cb383..919100bc0 100644
--- a/app/components/elements/Select.tsx
+++ b/app/components/elements/Select.tsx
@@ -45,9 +45,9 @@ export interface SendouSelectProps<T extends object>
 		placeholder?: string;
 	};
 	popoverClassName?: string;
-	/** Value of the search input, used for controlled components */
+	/** controlled search input value */
 	searchInputValue?: string;
-	/** Callback for when the search input value changes. When defined `items` has to be filtered on the caller side (automatic filtering in component disabled). */
+	/** When defined, the caller filters `items` (automatic filtering disabled). */
 	onSearchInputChange?: (value: string) => void;
 	clearable?: boolean;
 	filter?: AutocompleteProps<object>["filter"];
@@ -55,20 +55,7 @@ export interface SendouSelectProps<T extends object>
 	estimatedRowHeight?: number;
 }
 
-/**
- * A customizable select component with optional search functionality. Virtualizes the list of items for performance.
- *
- * @example
- * ```tsx
- * <SendouSelect items={items} search={{ placeholder: "Search for items..." }}>
- *   {({ key, ...item }) => (
- *     <SendouSelectItem key={key} {...item}>
- *       {item.name}
- *     </SendouSelectItem>
- *   )}
- * </SendouSelect>
- * ```
- */
+/** Select with optional search; virtualizes the item list. */
 export function SendouSelect<T extends object>({
 	label,
 	description,
@@ -121,9 +108,8 @@ export function SendouSelect<T extends object>({
 		</Virtualizer>
 	);
 
-	// The Autocomplete wrapper filters the collection, but its filtering drops
-	// items with a falsy key (e.g. `0`). When there is nothing to filter we skip
-	// it entirely so such items always render.
+	// the Autocomplete wrapper's filtering drops items with a falsy key (e.g. `0`),
+	// so it is skipped entirely when there is nothing to filter
 	const filterable = !!search || isControlled || !!filter;
 
 	return (
diff --git a/app/components/elements/SelectShell.tsx b/app/components/elements/SelectShell.tsx
index cb60fbdb4..25fba024e 100644
--- a/app/components/elements/SelectShell.tsx
+++ b/app/components/elements/SelectShell.tsx
@@ -1,8 +1,4 @@
-/**
- * The select look shared by `SendouSelect` and `SearchSelect`: the trigger
- * button, the popover with its search field, and the list box items' focus and
- * selection states. Both selects render their own contents inside these.
- */
+/** Select look (trigger, popover with search field, list box item states) shared by `SendouSelect` and `SearchSelect`. */
 
 import clsx from "clsx";
 import { ChevronsUpDown, Search, X } from "lucide-react";
diff --git a/app/components/elements/Tabs.tsx b/app/components/elements/Tabs.tsx
index a74b7f1a4..ed3293bf2 100644
--- a/app/components/elements/Tabs.tsx
+++ b/app/components/elements/Tabs.tsx
@@ -16,42 +16,15 @@ import { ButtonLook } from "./Button";
 import styles from "./Tabs.module.css";
 
 interface SendouTabsProps extends TabsProps {
-	/** Should there be padding above the panels. Defaults to true, pass in false if the panel content is managing its own padding. */
+	/** Padding above the panels, default true. */
 	padded?: boolean;
-	/** Hide tabs if only one tab shown? Defaults to true. */
+	/** Hide tabs if only one tab shown, default true. */
 	disappearing?: boolean;
-	/** When orientation is "vertical", switch to horizontal once the main content width drops below this many pixels. */
+	/** Vertical orientation switches to horizontal below this main content width (px). */
 	horizontalBelow?: number;
 }
 
-/**
- * Renders a set of accessible tabs using the provided props.
- *
- * This component is a wrapper around the `Tabs` component, forwarding all props.
- *
- * @param props - The properties to pass to the underlying `Tabs` component.
- * @returns The rendered tab interface.
- *
- * @url https://react-spectrum.adobe.com/react-aria/Tabs.html
- *
- * @example
- * <SendouTabs>
- *   <SendouTabList>
- *     <Tab id="shooter">Shooter</Tab>
- *     <Tab id="roller">Roller</Tab>
- *     <Tab id="charger">Charger</Tab>
- *   </SendouTabList>
- *   <SendouTabPanel id="shooter">
- *     Splattershot, Aerospray, etc.
- *   </SendouTabPanel>
- *   <SendouTabPanel id="roller">
- *     Splat Roller, Dynamo Roller, etc.
- *   </SendouTabPanel>
- *   <SendouTabPanel id="charger">
- *     Splat Charger, E-liter, etc.
- *   </SendouTabPanel>
- * </SendouTabs>
- */
+/** Wrapper around react-aria `Tabs`, see https://react-spectrum.adobe.com/react-aria/Tabs.html */
 export function SendouTabs({
 	padded = true,
 	disappearing = true,
@@ -89,7 +62,7 @@ export function SendouTabs({
 interface SendouTabProps extends TabProps {
 	icon?: React.ReactNode;
 	number?: number;
-	/** Render a warning-colored alert icon to draw attention to this tab. */
+	/** warning-colored alert icon on the tab */
 	alert?: boolean;
 	children?: React.ReactNode;
 }
@@ -117,7 +90,7 @@ export function SendouTab({
 
 interface SendouTabListProps<T extends object> extends TabListProps<T> {
 	sticky?: boolean;
-	/** Should tabs take 100% width with equal distribution? */
+	/** tabs share 100% width equally */
 	fullWidth?: boolean;
 }
 
@@ -130,8 +103,6 @@ export function SendouTabList<T extends object>({
 		<div className={clsx(styles.tabListContainer, "scrollbar")}>
 			<TabList
 				className={clsx(styles.tabList, {
-					// invisible: cantSwitchTabs && !disappearing,
-					// hidden: cantSwitchTabs && disappearing,
 					[styles.sticky]: sticky,
 					[styles.fullWidth]: fullWidth,
 				})}
diff --git a/app/components/elements/TeamSearch.tsx b/app/components/elements/TeamSearch.tsx
index 9dad8cadc..d2a9ddb7d 100644
--- a/app/components/elements/TeamSearch.tsx
+++ b/app/components/elements/TeamSearch.tsx
@@ -20,7 +20,7 @@ interface TeamSearchProps<T extends object>
 	label?: string;
 	bottomText?: string;
 	errorText?: string;
-	/** Team to preselect and display on mount (e.g. when editing a linked team). */
+	/** preselected on mount (e.g. when editing a linked team) */
 	initialTeam?: { id: number; name: string; avatarUrl?: string | null };
 	onChange?: (team: TeamSearchResult | null) => void;
 	ref?: React.Ref<HTMLButtonElement>;
diff --git a/app/components/elements/TournamentSearch.tsx b/app/components/elements/TournamentSearch.tsx
index fc12995be..dccaf234b 100644
--- a/app/components/elements/TournamentSearch.tsx
+++ b/app/components/elements/TournamentSearch.tsx
@@ -23,11 +23,7 @@ interface TournamentSearchProps<T extends object>
 	bottomText?: string;
 	errorText?: string;
 	initialTournamentId?: number;
-	/**
-	 * Restrict results to tournaments that have already started (finished/past)
-	 * instead of the default recent + upcoming window. Useful e.g. for importing
-	 * data from a previous tournament.
-	 */
+	/** Only tournaments that have already started, instead of the default recent + upcoming window. */
 	pastOnly?: boolean;
 	onChange?: (tournament: TournamentSearchItem | null) => void;
 	ref?: React.Ref<HTMLButtonElement>;
diff --git a/app/components/elements/UserSearch.tsx b/app/components/elements/UserSearch.tsx
index 66141e280..467d155ca 100644
--- a/app/components/elements/UserSearch.tsx
+++ b/app/components/elements/UserSearch.tsx
@@ -76,11 +76,7 @@ function parseUserResults(
 		.filter((user) => user.id !== initialUser?.id);
 }
 
-/**
- * Resolves the full user object for a preselected id so it can be displayed.
- * Loads at most once per field: later id changes come from the user picking a
- * result, which already carries the full user object.
- */
+/** Loads the preselected id's user once; later changes come from picked results which carry the full user. */
 function useInitialUser(initialUserId?: number) {
 	const fetcher = useFetcher<SearchLoaderData>();
 	const { load } = fetcher;
diff --git a/app/components/elements/useEntitySearch.ts b/app/components/elements/useEntitySearch.ts
index 516f88e65..f1cdc4512 100644
--- a/app/components/elements/useEntitySearch.ts
+++ b/app/components/elements/useEntitySearch.ts
@@ -12,14 +12,11 @@ export type EntitySearchItem<TItem> = TItem | EntitySearchPlaceholder;
 interface UseEntitySearchArgs<TItem extends { id: number }> {
 	/** Builds the loader URL queried (debounced) as the user types. */
 	buildUrl: (query: string) => string;
-	/**
-	 * Turns raw loader data into result items. Return `null` when the data does
-	 * not (yet) correspond to the current query so a placeholder is shown.
-	 */
+	/** Return `null` when the data does not (yet) correspond to the query, showing a placeholder. */
 	parseResults: (data: unknown, query: string) => TItem[] | null;
-	/** Already resolved item to pin to the top of the list (e.g. when editing). */
+	/** pinned to the top of the list (e.g. when editing) */
 	initialItem?: TItem;
-	/** Id to preselect on mount even before its item is resolved. */
+	/** preselected on mount even before its item is resolved */
 	initialSelectedId?: number;
 	onChange?: (item: TItem | null) => void;
 }
@@ -32,12 +29,7 @@ export interface EntitySearch<TItem extends { id: number }> {
 	onSelectionChange: (key: number) => void;
 }
 
-/**
- * Shared state + data fetching for the autocomplete search selects
- * (e.g. `UserSearch`, `TeamSearch`, `TournamentSearch`). Pair with the
- * presentational `SearchSelect` component, passing the returned value as its
- * `search` prop.
- */
+/** State + data fetching for the entity search selects (`UserSearch` etc.); pass the result as `SearchSelect`'s `search` prop. */
 export function useEntitySearch<TItem extends { id: number }>({
 	buildUrl,
 	parseResults,
diff --git a/app/components/layout/ChatSidebar.module.css b/app/components/layout/ChatSidebar.module.css
index ecd1d07fc..02f16a025 100644
--- a/app/components/layout/ChatSidebar.module.css
+++ b/app/components/layout/ChatSidebar.module.css
@@ -245,14 +245,14 @@
 	overflow: hidden;
 	padding-block-start: var(--s-2);
 
-	/* Chat section.container - fill the space */
+	/* Chat section.container */
 	& > section {
 		height: 100%;
 		display: flex;
 		flex-direction: column;
 	}
 
-	/* inputContainer wraps both messages + form - make it fill and flex */
+	/* inputContainer wrapping messages + form */
 	& > section > div {
 		flex: 1;
 		display: flex;
@@ -261,7 +261,7 @@
 		min-height: 0;
 	}
 
-	/* messages: no top padding, fill available space */
+	/* messages */
 	& [role="listbox"] {
 		padding-top: 0;
 		flex: 1;
@@ -272,7 +272,6 @@
 		padding-inline: var(--s-2);
 	}
 
-	/* form: stick to bottom */
 	& form {
 		padding: var(--s-1-5);
 		margin-top: 0;
diff --git a/app/components/layout/ChatSidebar.tsx b/app/components/layout/ChatSidebar.tsx
index cfdafbb78..60936b076 100644
--- a/app/components/layout/ChatSidebar.tsx
+++ b/app/components/layout/ChatSidebar.tsx
@@ -165,8 +165,7 @@ function RoomList({ onClose }: { onClose?: () => void }) {
 		return room ? [{ ...entry, room }] : [];
 	});
 
-	// Rooms the active route opens together collapse into a single combined list
-	// entry that opens the stacked split view.
+	// rooms the active route opens together collapse into one entry opening the stacked split view
 	const autoOpenRooms = routeRooms.filter((entry) => entry.autoOpen);
 	const combinedRooms = autoOpenRooms.length > 1 ? autoOpenRooms : [];
 	const combinedRoomIds = new Set(combinedRooms.map((entry) => entry.room.id));
@@ -449,9 +448,8 @@ function CombinedChatView({
 		</>
 	);
 
-	// Primary (match) sits on top, flush below the main header which already names
-	// it, so its sub-header is hidden. Desktop splits evenly; mobile gives the
-	// match chat the larger 3/5 share (group chat 2/5).
+	// primary (match) sits on top with its sub-header hidden, the main header already names it;
+	// desktop splits evenly, mobile gives the match chat 3/5
 	const panels = [
 		{ room: primary, grow: isMobile ? 3 : 1, showHeader: false },
 		...rooms.slice(1).map((room) => ({
diff --git a/app/components/layout/SearchResults.tsx b/app/components/layout/SearchResults.tsx
index 16e18d541..97500060a 100644
--- a/app/components/layout/SearchResults.tsx
+++ b/app/components/layout/SearchResults.tsx
@@ -1,8 +1,4 @@
-/**
- * The result list chrome shared by the global search and its weapon sub-view:
- * the list box, its items and the empty state shown while there is nothing to
- * list.
- */
+/** Result list chrome (list box, items, empty state) shared by the global search and its weapon sub-view. */
 
 import clsx from "clsx";
 import type * as React from "react";
diff --git a/app/components/layout/WeaponSearch.tsx b/app/components/layout/WeaponSearch.tsx
index 71f4fe610..379b07ecc 100644
--- a/app/components/layout/WeaponSearch.tsx
+++ b/app/components/layout/WeaponSearch.tsx
@@ -60,11 +60,7 @@ export interface SelectedWeapon {
 	paramsSlug: string;
 }
 
-/**
- * Builds the {@link SelectedWeapon} for a main weapon id: its localized name plus the English-derived
- * url slugs (the build pages slug from the weapon's canonical id, the params page slug from its base
- * id). The caller's `t` must have the `weapons` namespace available.
- */
+/** {@link SelectedWeapon} for a main weapon id: localized name plus English-derived url slugs. `t` needs the `weapons` namespace. */
 export function weaponToSelectedWeapon<Ns extends Namespace>(
 	id: MainWeaponId,
 	t: TFunction<Ns>,
diff --git a/app/components/layout/index.tsx b/app/components/layout/index.tsx
index aa09d9eaf..20fe90141 100644
--- a/app/components/layout/index.tsx
+++ b/app/components/layout/index.tsx
@@ -60,19 +60,14 @@ import { TopRightButtons } from "./TopRightButtons";
 
 const MAX_DESKTOP_FRIENDS = 4;
 
-// lazy loaded so the rarely needed auth error dialog stays out of the eager
-// bundle loaded on every page
+// lazy loaded to stay out of the eager bundle
 const AuthErrorDialog = React.lazy(() =>
 	import("./AuthErrorDialog").then((module) => ({
 		default: module.AuthErrorDialog,
 	})),
 );
 
-/** Id of the loading-bar track rendered inside the header. NProgress mounts its
- * bar into it; the track sits just below the header border, spans only the area
- * between the sidebars, and clips the bar so it never extends over a sidebar.
- * Living inside the header makes it follow the header on scroll and in
- * standalone (PWA) mode where the header grows by the safe-area inset. */
+/** Loading-bar track inside the header that NProgress mounts into; styled in common.css. */
 export const NPROGRESS_ANCHOR_ID = "nprogress-anchor";
 
 function useRelativeDayFormat() {
@@ -147,10 +142,7 @@ function useSideNavCollapsed(initialCollapsed: boolean) {
 	return [collapsed, setCollapsedAndPersist] as const;
 }
 
-/**
- * Open state of a modal that only the tablet layout has, remembering the pathname it was
- * opened on so that leaving that layout or navigating elsewhere closes it on its own.
- */
+/** Open state of a tablet-layout-only modal; leaving that layout or navigating closes it. */
 function useTabletModal(isTabletLayout: boolean) {
 	const location = useLocation();
 	const [openedOnPathname, setOpenedOnPathname] = React.useState<string | null>(
diff --git a/app/components/match-page/MatchBanner.tsx b/app/components/match-page/MatchBanner.tsx
index 4d5b7980f..778bceaec 100644
--- a/app/components/match-page/MatchBanner.tsx
+++ b/app/components/match-page/MatchBanner.tsx
@@ -215,10 +215,7 @@ function ScreenNotice({ screenLegal }: { screenLegal: boolean }) {
 	);
 }
 
-/**
- * Trigger for the small popovers hung off a banner's info row, e.g. who voted
- * for the map or which team picked it.
- */
+/** Trigger for the small popovers on a banner's info row, e.g. who voted for the map. */
 export function MatchBannerInfoBadge({
 	children,
 }: {
diff --git a/app/components/match-page/MatchBannerStartedAt.tsx b/app/components/match-page/MatchBannerStartedAt.tsx
index 20347355a..9ef007b46 100644
--- a/app/components/match-page/MatchBannerStartedAt.tsx
+++ b/app/components/match-page/MatchBannerStartedAt.tsx
@@ -13,7 +13,7 @@ const CLASS_NAME = "text-lighter font-semi-bold";
 
 interface MatchBannerStartedAtProps {
 	time: Date;
-	/** When given, the time the match ended, shown as a range together with the start time */
+	/** shown as a range together with the start time */
 	endTime?: Date | null;
 }
 
diff --git a/app/components/match-page/MatchRosterTab.tsx b/app/components/match-page/MatchRosterTab.tsx
index 51ae546a5..6c4f51816 100644
--- a/app/components/match-page/MatchRosterTab.tsx
+++ b/app/components/match-page/MatchRosterTab.tsx
@@ -37,10 +37,10 @@ interface RosterTabTeam {
 	};
 	defaultName?: string;
 	members: Array<RosterTabMember>;
-	/** Sub user ids i.e. those who are not the current active roster */
+	/** users not in the current active roster */
 	subbedOut?: Array<number>;
 	tier?: { name: TierName; isPlus: boolean };
-	/** Tournament seed of the team (tournament only). */
+	/** tournament only */
 	seed?: number | null;
 }
 
diff --git a/app/components/match-page/MatchTabs.tsx b/app/components/match-page/MatchTabs.tsx
index 4f62a8b4f..e5bae9786 100644
--- a/app/components/match-page/MatchTabs.tsx
+++ b/app/components/match-page/MatchTabs.tsx
@@ -11,7 +11,7 @@ type MatchTabsKey = (typeof TAB_KEYS)[keyof typeof TAB_KEYS];
 interface MatchTabsProps {
 	children: React.ReactNode;
 	tabs: Array<MatchTabsKey>;
-	/** Tabs that should show a warning-colored alert icon to draw attention. */
+	/** tabs showing a warning-colored alert icon */
 	alertTabs?: Array<MatchTabsKey>;
 }
 
diff --git a/app/components/match-page/MatchTimeline.tsx b/app/components/match-page/MatchTimeline.tsx
index 9507d98eb..863121200 100644
--- a/app/components/match-page/MatchTimeline.tsx
+++ b/app/components/match-page/MatchTimeline.tsx
@@ -82,17 +82,17 @@ export interface TimelineMap {
 	};
 	/** Whether the game ended in a knockout. Undefined if not collected. */
 	ko?: boolean;
-	/** Side that picked this map (counterpick / postGame map PICK). Renders a click indicator next to that side's WIN/LOSS label. */
+	/** Side that picked this map (counterpick / postGame map PICK), shown as a click indicator. */
 	pickedBy?: MatchSide;
-	/** Ingested end-of-game scoreboard rendered as an expandable stats section below the map row. */
+	/** Ingested end-of-game scoreboard, an expandable stats section below the map row. */
 	scoreboard?: {
 		/** [alpha, bravo] on the ingested 0-100 scale (100 = knockout) */
 		scores: [number | null, number | null];
 		alpha: TimelineScoreboardPlayer[];
 		bravo: TimelineScoreboardPlayer[];
-		/** Objective-counter reads ([alpha, bravo] values) charted above the stats tables. */
+		/** [alpha, bravo] objective-counter reads charted above the stats tables */
 		objective?: ObjectiveTimelineEvent[];
-		/** Per-player splat/special bands ([alpha, bravo]) charted above the objective chart. */
+		/** [alpha, bravo] per-player splat/special bands charted above the objective chart */
 		playerStatus?: PlayerStatusTimelineSample[];
 	};
 }
@@ -126,15 +126,13 @@ export interface MatchTimelineProps {
 	score?: { alpha: number; bravo: number };
 	maps: TimelineMap[];
 	spChanges?: TimelineSpChanges;
-	/** When true, render only the team + score header (no per-map rows or SP section). */
+	/** only the team + score header, no per-map rows or SP section */
 	compact?: boolean;
-	/** When true, the match is still in progress; renders a small LIVE label under the score. */
+	/** renders a LIVE label under the score */
 	isOngoing?: boolean;
 	/**
-	 * Pick/ban events keyed by the slot they precede. Length = `maps.length + 1`.
-	 * Bucket `i` renders above map row `i`; the trailing bucket renders after the
-	 * last map row (covers events made after the latest result, or the
-	 * pick/ban-only state with no maps reported yet).
+	 * Pick/ban events keyed by the slot they precede, length `maps.length + 1`. Bucket `i` renders
+	 * above map row `i`; the trailing bucket after the last row (events after the latest result).
 	 */
 	pickBanRowsBySlot?: TimelinePickBanEvent[][];
 }
@@ -375,11 +373,7 @@ interface SideScore {
 	fromObjective: boolean;
 }
 
-/**
- * A knockout's loser is reported with no score of its own, so the count it
- * took is only known from the objective counter — prefer that read over a
- * scoreless 0, and mark it as the video-sourced value it is.
- */
+/** A knockout's loser has no reported score, so prefer the objective counter read over a scoreless 0. */
 function resolveSideScore(
 	scoreboardScore?: number | null,
 	objectiveScore?: number | null,
diff --git a/app/components/match-page/SecondaryAction.tsx b/app/components/match-page/SecondaryAction.tsx
index c63195a68..d3677e7df 100644
--- a/app/components/match-page/SecondaryAction.tsx
+++ b/app/components/match-page/SecondaryAction.tsx
@@ -10,26 +10,14 @@ interface SecondaryActionProps {
 	collapsedLabel: string;
 	collapsedIcon?: React.JSX.Element;
 	expandedAriaLabel?: string;
-	/**
-	 * Always-open variant used when this is the only content in the tab (no
-	 * primary action to sit underneath). Hides the collapse toggle and drops the
-	 * striped footer styling.
-	 */
+	/** Only content in the tab: always open, no collapse toggle, no striped footer styling. */
 	standalone?: boolean;
-	/**
-	 * Forces the expanded state and hides the collapse toggle while keeping the
-	 * footer styling. Used when the expanded content is small enough that
-	 * collapsing brings no benefit.
-	 */
+	/** Always open without the collapse toggle, keeping the footer styling. */
 	alwaysOpen?: boolean;
 	children: React.ReactNode;
 }
 
-/**
- * Generic panel hosting follow-up match actions (e.g. weapon reporting, scrim
- * map list management). Defaults to a striped footer attached beneath the
- * primary action card; pass `standalone` when it is the only tab content.
- */
+/** Panel for follow-up match actions (weapon reporting etc.), a striped footer beneath the primary action card. */
 export function SecondaryAction({
 	isOpen,
 	onOpenChange,
diff --git a/app/components/match-page/WeaponReporter.tsx b/app/components/match-page/WeaponReporter.tsx
index 320db6f13..f609bbfe5 100644
--- a/app/components/match-page/WeaponReporter.tsx
+++ b/app/components/match-page/WeaponReporter.tsx
@@ -24,8 +24,7 @@ export interface WeaponReporterMap {
 }
 
 export interface WeaponReporterProps {
-	/** Only the maps the viewer took part in, so someone who was subbed out is
-	 * never asked for a weapon of a map they did not play. */
+	/** Only the maps the viewer took part in, so a subbed out player is never asked for one they did not play. */
 	maps: WeaponReporterMap[];
 	pastReported: MainWeaponId[];
 	nextMapIndex: number;
diff --git a/app/components/match-page/ingested-scoreboard.ts b/app/components/match-page/ingested-scoreboard.ts
index a58ca3f13..b18531549 100644
--- a/app/components/match-page/ingested-scoreboard.ts
+++ b/app/components/match-page/ingested-scoreboard.ts
@@ -11,10 +11,7 @@ import type { WeaponPoolWeapon } from "./WeaponPool";
 /** Ingested scoreboard rows come winning team first, 4 players per side. */
 const SCOREBOARD_PLAYERS_PER_TEAM = 4;
 
-/**
- * Maps a game's ingested scoreboard (stored winner-first) onto the
- * alpha/bravo-oriented shape the match timeline renders.
- */
+/** Maps a game's ingested scoreboard (stored winner-first) onto the alpha/bravo shape the timeline renders. */
 export function resolveTimelineScoreboard(
 	data: IngestedScoreboardData | undefined,
 	alphaIsWinner: boolean,
@@ -48,17 +45,12 @@ export function resolveTimelineScoreboard(
 }
 
 /**
- * One team's weapons for a map row: each roster member's reported weapon,
- * with the gaps filled from the map's ingested scoreboard rows that no
- * member accounts for. An ingested row without a user is only unaccounted
- * for if no roster member already reported its weapon, otherwise it is that
- * member's row and reusing it would show their weapon twice — a multiset
- * count, so two ingested rows of a weapon survive one report of it.
+ * One team's weapons for a map row: each roster member's reported weapon, gaps filled from the
+ * ingested scoreboard rows no member accounts for. A userless ingested row counts as accounted
+ * for once a member reported its weapon (multiset count), else the weapon would show twice.
  *
- * @param linkedWeapons per roster member, the weapon they reported for the map (null = none)
- * @param ingestedPlayers the map's ingested scoreboard rows (empty when none ingested)
+ * @param linkedWeapons per roster member (null = none); result is index-aligned, fills marked unverified
  * @param tournamentTeamId the team's side id in the game result (tournament team or SendouQ group id)
- * @returns index-aligned with `linkedWeapons`; ingested fills are marked unverified
  */
 export function resolveTimelineWeapons({
 	linkedWeapons,
diff --git a/app/components/match-page/useMatchWeaponReport.ts b/app/components/match-page/useMatchWeaponReport.ts
index a367438bd..8a83afc59 100644
--- a/app/components/match-page/useMatchWeaponReport.ts
+++ b/app/components/match-page/useMatchWeaponReport.ts
@@ -5,14 +5,9 @@ import { weaponReportActionSchema } from "./match-page-schemas";
 import type { WeaponReporterMap, WeaponReporterProps } from "./WeaponReporter";
 
 /**
- * Wires the `<WeaponReporter />` component to the standard
- * `REPORT_WEAPON` / `UNDO_WEAPON_REPORT` fetcher actions and to the
- * locally persisted recently-reported weapons list.
- *
- * `maps` is the maps the viewer can report a weapon for, in play order, each
- * carrying its `mapIndex` in the match's map list — a viewer who sat out a map
- * simply has no entry for it. `pastReported` is the weapons the viewer has
- * already reported, paired with the `mapIndex` they were reported for.
+ * Wires `<WeaponReporter />` to the `REPORT_WEAPON` / `UNDO_WEAPON_REPORT` actions and the
+ * locally persisted recently-reported list. `maps` are the maps the viewer can report for, in
+ * play order with their `mapIndex` in the match's map list (sat out maps have no entry).
  */
 export function useMatchWeaponReport({
 	maps,
diff --git a/app/components/match-page/utils.ts b/app/components/match-page/utils.ts
index 22531e3d5..6e822024f 100644
--- a/app/components/match-page/utils.ts
+++ b/app/components/match-page/utils.ts
@@ -16,10 +16,8 @@ export interface InferredSubstitution {
 }
 
 /**
- * Compares the rosters of two consecutive maps and pairs up any
- * players that dropped from a side with new players that joined the same side.
- * The pairs are returned in roster order, so the first player out is paired with
- * the first new player in. When the counts don't match, unpaired players are ignored.
+ * Pairs players that dropped from a side between two consecutive maps with the new players that
+ * joined it, in roster order. Unpaired players are ignored when the counts don't match.
  */
 export function inferSubstitutions(
 	previousRosters: Rosters,
@@ -59,11 +57,7 @@ const NUM_MAP = {
 	"0": ["0", "8"],
 };
 
-/**
- * Generates a deterministic 4-digit Splatoon private battle room password based on the provided seed.
- *
- * Given the same seed, this function will always return the same password.
- */
+/** Deterministic 4-digit private battle room password for the seed. */
 export function resolveRoomPass(seed: number | string) {
 	let pass = "5";
 	for (let i = 0; i < 3; i++) {
@@ -75,8 +69,7 @@ export function resolveRoomPass(seed: number | string) {
 		pass += next;
 	}
 
-	// prevent 5555 since many use it as a default pass
-	// making it a bit more common guess
+	// 5555 is a common default pass, so a more common guess
 	if (pass === "5555") return "5800";
 
 	return pass;
diff --git a/app/components/objective-timeline-utils.ts b/app/components/objective-timeline-utils.ts
index 61c6eea23..6a682a94f 100644
--- a/app/components/objective-timeline-utils.ts
+++ b/app/components/objective-timeline-utils.ts
@@ -1,10 +1,6 @@
 const PENALTY_BRIDGE_SECONDS = 6;
 
-/**
- * Width of the label gutter left of the plot area, shared by the objective
- * chart (its y-axis is forced to this width) and the player-status rows (their
- * weapon-icon column), so both plots span exactly the same x-range.
- */
+/** Label gutter left of the plot, shared by the objective chart's y-axis and the player-status weapon column so both span the same x-range. */
 export const TIMELINE_PLOT_GUTTER_PX = 36;
 
 /** The count a knockout wins at: the counter runs out and the team takes all of it. */
@@ -18,14 +14,11 @@ export interface PenaltyRead {
 }
 
 /**
- * The penalty pill is misread for a frame or two at a time: it flickers
- * between a value and null, and occasionally drops a digit ("36" read as
- * "6"). Median-filters isolated outlier values, drops one-off reads with no
- * nearby confirmation and carries the previous value across short null gaps
- * so the band renders as one steady shape instead of a picket fence.
+ * The penalty pill flickers between a value and null and occasionally drops a digit ("36" → "6").
+ * Median-filters outliers, drops one-off reads with no nearby confirmation and carries the previous
+ * value across short null gaps so the band renders as one steady shape.
  *
- * @param reads one team's penalty reads, sorted by `t` ascending
- * @returns the smoothed penalty per read, index-aligned with the input
+ * @param reads one team's reads sorted by `t` ascending; result is index-aligned
  */
 export function smoothPenalties(
 	reads: readonly PenaltyRead[],
@@ -69,15 +62,11 @@ export interface ObjectiveScoreRead {
 }
 
 /**
- * Match scores implied by each team's last readable counter read. The counter
- * counts down from 100 while match scores run the other way (100 = knockout),
- * so a read is inverted into the count the team took. Stands in where the
- * results screen reports no score of its own — a knockout's loser — but the
- * last read is only as late as the last frame the counter was seen in, so it
- * can trail the count the team ended on.
+ * Match scores (0-100, null if nothing read) implied by each team's last readable counter read,
+ * inverted since the counter counts down. Stands in where the results screen has no score (a
+ * knockout's loser), but can trail the final count since it only goes as far as the counter was last seen.
  *
- * @param reads counter reads, in any order
- * @returns per-team match score (0-100); null where nothing was read
+ * @param reads in any order
  */
 export function matchScoresFromObjective(
 	reads: readonly ObjectiveScoreRead[],
@@ -97,10 +86,7 @@ export function matchScoresFromObjective(
 	return [lastCountTaken(0), lastCountTaken(1)];
 }
 
-/**
- * Seconds into the source formatted for display: m:ss, growing an hours
- * part only when needed.
- */
+/** Seconds formatted as m:ss, with an hours part only when needed. */
 export function formatElapsed(seconds: number): string {
 	const hours = Math.floor(seconds / 3600);
 	const minutes = Math.floor((seconds % 3600) / 60);
diff --git a/app/config-helpers.ts b/app/config-helpers.ts
index 46682f611..e405cd444 100644
--- a/app/config-helpers.ts
+++ b/app/config-helpers.ts
@@ -3,11 +3,7 @@ import * as v from "valibot";
 const TRUTHY_ENV_VALUES = ["true", "1", "yes", "on", "y", "enabled"];
 const FALSY_ENV_VALUES = ["false", "0", "no", "off", "n", "disabled"];
 
-/**
- * Builds an `Error` with a readable, multi-line message describing every invalid
- * environment variable. Schemas are keyed by the literal env var name so the
- * issue path points straight at the variable a contributor needs to fix.
- */
+/** `Error` listing every invalid env var; issue paths are the literal variable names. */
 export function formatEnvErrors(
 	scope: "client" | "server",
 	issues: readonly v.BaseIssue<unknown>[],
@@ -24,15 +20,10 @@ export function formatEnvErrors(
 	);
 }
 
-/**
- * String schema that must be set to a non-empty value in production, but falls
- * back to `devFallback` outside of production so contributors can run the app
- * without configuring every integration.
- */
+/** Non-empty string in production, `devFallback` elsewhere. */
 export function requiredInProd(isProd: boolean, devFallback: string) {
-	// The production branch defaults to `""` rather than being required outright
-	// so that a missing variable reaches `minLength` and reports the same
-	// actionable message an empty one does, instead of valibot's "Invalid key".
+	// defaults to `""` so a missing variable reaches `minLength` and gets the same
+	// actionable message as an empty one, instead of valibot's "Invalid key"
 	return isProd
 		? v.pipe(
 				v.optional(v.string(), ""),
diff --git a/app/config.server.ts b/app/config.server.ts
index 6111ff2ae..7fba860c9 100644
--- a/app/config.server.ts
+++ b/app/config.server.ts
@@ -4,13 +4,8 @@ import { IS_E2E_TEST_RUN } from "./utils/e2e";
 import { superRefine, type ValidationCtx } from "./utils/schema";
 
 /**
- * Server (`process.env`) configuration. Import with
- * `import { ServerConfig } from "~/config.server"` and read values like
- * `ServerConfig.dbPath` or `ServerConfig.storage.endpoint`.
- *
- * Values are validated once when this module is first imported, surfacing a
- * single clear error for any misconfigured variable. Variables required in
- * production fall back to development defaults outside of production.
+ * Server (`process.env`) configuration, validated once on first import. Variables required in
+ * production fall back to development defaults elsewhere.
  */
 
 const isProd = process.env.NODE_ENV === "production" && !IS_E2E_TEST_RUN;
@@ -41,9 +36,8 @@ const schema = v.pipe(
 
 		PATREON_ACCESS_TOKEN: v.optional(v.string()),
 
-		// The VAPID public key (VITE_VAPID_PUBLIC_KEY) lives in `~/config` since
-		// it is client-readable; the full three-var coupling is completed by the
-		// runtime check in webPush.server.ts.
+		// the client-readable public key (VITE_VAPID_PUBLIC_KEY) lives in `~/config`;
+		// webPush.server.ts checks all three are set together
 		VAPID_PRIVATE_KEY: v.optional(v.string()),
 		VAPID_EMAIL: v.optional(v.string()),
 	}),
@@ -60,34 +54,23 @@ if (!parsed.success) {
 const values = parsed.output;
 
 export const ServerConfig = {
-	/**
-	 * Whether `NODE_ENV` is `"production"`. Note: this is `true` during e2e tests
-	 * (which run a production build), so combine it with `IS_E2E_TEST_RUN` when
-	 * you specifically need to exclude the e2e environment (as the session
-	 * cookies do).
-	 */
+	/** Also `true` during e2e tests (production build); combine with `IS_E2E_TEST_RUN` to exclude them. */
 	isProduction: values.NODE_ENV === "production",
-	/** Whether the app is running under the test runner. */
 	isTest: values.NODE_ENV === "test",
 
-	/** Path to the SQLite database file. */
 	dbPath: values.DB_PATH,
-	/** Secret used to sign session cookies. */
 	sessionSecret: values.SESSION_SECRET,
-	/** Token authorizing internal Lohi (bot/cron) requests. */
+	/** Authorizes internal Lohi (bot/cron) requests. */
 	lohiToken: values.LOHI_TOKEN,
-	/** SQL query logging level. */
 	sqlLog: values.SQL_LOG,
-	/** Whether response caching is disabled. */
 	disableCache: values.DISABLE_CACHE,
 
-	/** Discord OAuth configuration. */
 	discord: {
 		clientId: values.DISCORD_CLIENT_ID,
 		clientSecret: values.DISCORD_CLIENT_SECRET,
 	},
 
-	/** S3-compatible object storage configuration. */
+	/** S3-compatible object storage */
 	storage: {
 		endpoint: values.STORAGE_END_POINT,
 		accessKey: values.STORAGE_ACCESS_KEY,
@@ -96,18 +79,17 @@ export const ServerConfig = {
 		bucket: values.STORAGE_BUCKET,
 	},
 
-	/** Twitch integration credentials. Optional — streams are hidden when unset. */
+	/** Optional, streams are hidden when unset. */
 	twitch: {
 		clientId: values.TWITCH_CLIENT_ID,
 		clientSecret: values.TWITCH_CLIENT_SECRET,
 	},
 
-	/** Patreon integration configuration. */
 	patreon: {
 		accessToken: values.PATREON_ACCESS_TOKEN,
 	},
 
-	/** Web push (VAPID) server configuration. */
+	/** web push */
 	vapid: {
 		privateKey: values.VAPID_PRIVATE_KEY,
 		email: values.VAPID_EMAIL,
diff --git a/app/config.ts b/app/config.ts
index 86b93a883..ef9659684 100644
--- a/app/config.ts
+++ b/app/config.ts
@@ -3,16 +3,11 @@ import { envBoolean, formatEnvErrors, requiredInProd } from "./config-helpers";
 import { IS_E2E_TEST_RUN } from "./utils/e2e";
 
 /**
- * Client (`VITE_*`) configuration. Import with `import { Config } from "~/config"`
- * and read values like `Config.siteDomain` or `Config.staticAssetsUrl`.
- *
- * Values are validated once when this module is first imported, surfacing a
- * single clear error for any misconfigured variable. Variables required in
- * production fall back to development defaults outside of production.
+ * Client (`VITE_*`) configuration, validated once on first import. Variables required in
+ * production fall back to development defaults elsewhere.
  */
 
-// `import.meta.env` is undefined when Playwright bundles test code, so guard the
-// access and treat that environment as non-production (see `~/utils/e2e`).
+// `import.meta.env` is undefined when Playwright bundles test code; treat that as non-production (see `~/utils/e2e`)
 const env =
 	typeof import.meta.env !== "undefined"
 		? (import.meta.env as Record<string, string | undefined>)
@@ -42,9 +37,8 @@ const schema = v.object({
 	VITE_LEAGUE_GOOGLE_FORM_URL: v.optional(v.string()),
 	VITE_SHOW_BANNER_FOR_SEASON: v.optional(v.string()),
 
-	// The VAPID private key and email live in `~/config.server` since they are
-	// server-only; the full three-var coupling is completed by the runtime check
-	// in webPush.server.ts.
+	// the server-only private key and email live in `~/config.server`;
+	// webPush.server.ts checks all three are set together
 	VITE_VAPID_PUBLIC_KEY: v.optional(v.string()),
 });
 
@@ -55,24 +49,20 @@ if (!parsed.success) {
 const values = parsed.output;
 
 export const Config = {
-	/** Base URL of the site, e.g. `https://sendou.ink`. */
+	/** e.g. `https://sendou.ink` */
 	siteDomain: values.VITE_SITE_DOMAIN,
-	/** Filename of the default tournament logo asset. */
 	tournamentDefaultLogo: values.VITE_TOURNAMENT_DEFAULT_LOGO,
-	/** Base URL for static assets (images, sounds, svg). */
 	staticAssetsUrl: values.VITE_STATIC_ASSETS_URL,
-	/** Whether to use real seasons & league data (used when developing against the production database). */
+	/** Use real seasons & league data (when developing against the production database). */
 	prodMode: values.VITE_PROD_MODE,
-	/** Whether to show the LUTI navigation item. */
 	showLutiNavItem: values.VITE_SHOW_LUTI_NAV_ITEM,
 	fuseEnabled: values.VITE_FUSE_ENABLED,
-	/** Whether the scanner is available to everyone. While false only the admin and devs can use the scanner page and its ingest endpoint. */
+	/** While false only the admin and devs can use the scanner page and its ingest endpoint. */
 	scannerEnabled: values.VITE_SCANNER_ENABLED,
-	/** Google Form URL for league registration, if configured. */
 	leagueGoogleFormUrl: values.VITE_LEAGUE_GOOGLE_FORM_URL,
-	/** Season identifier to show the registration banner for, if any. */
+	/** Season to show the registration banner for. */
 	showBannerForSeason: values.VITE_SHOW_BANNER_FOR_SEASON,
-	/** Web push (VAPID) client configuration. */
+	/** web push */
 	vapid: {
 		publicKey: values.VITE_VAPID_PUBLIC_KEY,
 	},
diff --git a/app/db/empty-values-noop-plugin.ts b/app/db/empty-values-noop-plugin.ts
index ade5c6f96..ccf772c87 100644
--- a/app/db/empty-values-noop-plugin.ts
+++ b/app/db/empty-values-noop-plugin.ts
@@ -14,11 +14,8 @@ import {
 } from "kysely";
 
 /**
- * Makes inserting an empty array of values a no-op instead of a syntax error.
- * Kysely compiles `.values([])` into invalid SQL, so without this plugin every
- * dynamic multi-row insert would need a length check before it. The empty
- * insert is rewritten into `INSERT INTO "T" SELECT * FROM "T" WHERE 0` which
- * inserts zero rows and returns zero rows for any `returning` clause.
+ * Kysely compiles `.values([])` into invalid SQL; this rewrites it into `INSERT INTO "T" SELECT * FROM "T" WHERE 0`,
+ * inserting and returning zero rows.
  */
 export class EmptyValuesNoopPlugin implements KyselyPlugin {
 	transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
diff --git a/app/db/json-columns.ts b/app/db/json-columns.ts
index c2bec460d..a5c569365 100644
--- a/app/db/json-columns.ts
+++ b/app/db/json-columns.ts
@@ -1,9 +1,6 @@
 /**
- * Every "Table.column" whose text content is a JSON document. The node-sqlite
- * dialect parses only these columns (plus computed expression columns) when
- * reading rows; all other text columns stay plain strings even if a user typed
- * something JSON-shaped into them. Kept in sync with the JSONColumnType
- * declarations of tables.ts by json-columns.test.ts.
+ * Every "Table.column" the dialect parses as JSON; other text stays a plain string even if JSON-shaped.
+ * Kept in sync with the JSONColumnType declarations of tables.ts by json-columns.test.ts.
  */
 export const JSON_COLUMNS: ReadonlySet<string> = new Set([
 	"AllTeam.customTheme",
diff --git a/app/db/json-selections.test.ts b/app/db/json-selections.test.ts
index a7e26d6e3..99d161999 100644
--- a/app/db/json-selections.test.ts
+++ b/app/db/json-selections.test.ts
@@ -25,8 +25,7 @@ describe("computedJsonColumns", () => {
 				).as("weapons"),
 			]);
 
-		// `username` is `coalesce("User"."tournamentName", "User"."username")`, which
-		// SQLite reports the same way as the weapons subquery: as a computed column
+		// `username` is a `coalesce(...)`, reported by SQLite as a computed column like the weapons subquery
 		expect(computedJsonColumns(query.compile().query)).toEqual(
 			new Set(["weapons"]),
 		);
@@ -101,8 +100,7 @@ describe("reading rows", () => {
 			.where("User.id", "=", member.id)
 			.executeTakeFirstOrThrow();
 
-		// rendered as a bare JSX child on public tournament pages, so an object here
-		// is "Objects are not valid as a React child" for everyone viewing them
+		// rendered as a bare JSX child on public pages; an object here would crash React for every viewer
 		expect(row.username).toBe(JSON_SHAPED_TEXT);
 	});
 
diff --git a/app/db/json-selections.ts b/app/db/json-selections.ts
index 808602270..29062384d 100644
--- a/app/db/json-selections.ts
+++ b/app/db/json-selections.ts
@@ -22,8 +22,7 @@ const NO_NAMES: ReadonlySet<string> = new Set();
 export function computedJsonColumns(
 	query: RootOperationNode,
 ): ReadonlySet<string> {
-	// only select queries have computed result columns: `returning` selections keep
-	// the origin metadata of the column they write to
+	// `returning` selections keep the origin metadata of the column they write to
 	return SelectQueryNode.is(query) ? outputNames(query) : NO_NAMES;
 }
 
@@ -90,8 +89,7 @@ function outputNames(select: SelectQueryNode): ReadonlySet<string> {
 		}
 	}
 
-	// a compound select is named after its first branch, but any branch can be the
-	// one contributing the JSON document
+	// a compound select is named after its first branch, but any branch can contribute the JSON
 	for (const { expression } of select.setOperations ?? []) {
 		if (!SelectQueryNode.is(expression)) continue;
 
diff --git a/app/db/node-sqlite-dialect.ts b/app/db/node-sqlite-dialect.ts
index 873486eea..050a3d23b 100644
--- a/app/db/node-sqlite-dialect.ts
+++ b/app/db/node-sqlite-dialect.ts
@@ -22,10 +22,7 @@ import {
 	SqliteQueryCompiler,
 } from "kysely";
 
-/**
- * Query kinds whose compiled SQL is stable enough to keep a prepared statement
- * around for. Everything else (DDL, raw SQL, `begin`/`commit`) is prepared fresh.
- */
+/** Query kinds worth caching a prepared statement for; DDL, raw SQL and `begin`/`commit` are prepared fresh. */
 const CACHEABLE_QUERY_KINDS = new Set([
 	"SelectQueryNode",
 	"InsertQueryNode",
@@ -34,11 +31,7 @@ const CACHEABLE_QUERY_KINDS = new Set([
 	"MergeQueryNode",
 ]);
 
-/**
- * Leading keywords of raw statements that can not change the schema, so the
- * column lists the statement cache is holding stay valid across them. Raw DDL
- * (`create`, `alter`, `drop`, ...) is not here and clears the cache.
- */
+/** Leading keywords of raw statements that can't change the schema; any other raw statement clears the cache. */
 const SCHEMA_PRESERVING_RAW_COMMANDS = new Set([
 	"begin",
 	"commit",
@@ -62,39 +55,24 @@ const NO_JSON_OUTPUT_NAMES: ReadonlySet<string> = new Set();
 
 export interface NodeSqliteDialectConfig {
 	database: DatabaseSync;
-	/**
-	 * Keeps prepared statements around between queries, keyed by their SQL. Saves
-	 * a re-compile per query at the cost of holding onto the compiled programs.
-	 * Off by default because it assumes the schema does not change under the
-	 * connection, which is not true while migrations run.
-	 */
+	/** Caches prepared statements by SQL. Off by default since it assumes a stable schema, untrue while migrations run. */
 	cacheStatements?: boolean;
 	/**
-	 * "Table.column" names whose text content is a JSON document. When given,
-	 * result values of these columns are parsed into objects. Other text columns
-	 * are always returned verbatim, so JSON-shaped user input stays a string.
-	 * Origin metadata from `statement.columns()` sees through aliases, views,
-	 * subqueries and CTEs, so the names here are the underlying table names
-	 * (e.g. `AllTeam`, not the `Team` view).
+	 * "Table.column" names parsed as JSON; other text stays verbatim so JSON-shaped user input stays a string.
+	 * Origin metadata sees through aliases, views, subqueries and CTEs, so use underlying table names (`AllTeam`, not `Team`).
 	 */
 	jsonColumns?: ReadonlySet<string>;
 	/**
-	 * Output names of a query's computed result columns whose value is a JSON
-	 * document, which is what `jsonArrayFrom`/`jsonObjectFrom` subqueries compile
-	 * to. SQLite reports no origin for a computed expression, so only the query's
-	 * own AST tells those apart from an ordinary `coalesce(...)` over user text.
+	 * Output names of computed JSON result columns (`jsonArrayFrom`/`jsonObjectFrom` subqueries). SQLite reports no
+	 * origin for computed expressions, so only the AST tells them from a `coalesce(...)` over user text.
 	 * Called once per prepared statement. Requires {@link jsonColumns}.
 	 */
 	computedJsonColumns?: (query: RootOperationNode) => ReadonlySet<string>;
 }
 
 /**
- * Kysely dialect backed by Node's built-in `node:sqlite` module, replacing the
- * `better-sqlite3` native addon that Kysely's own `SqliteDialect` expects.
- *
- * Rows come back from `node:sqlite` as arrays rather than objects: the objects it
- * builds itself are both slower to produce and have a `null` prototype, which is
- * not what the rest of the codebase (or Kysely's own dialects) hand out.
+ * Kysely dialect over `node:sqlite` instead of the `better-sqlite3` addon. Rows are read as arrays:
+ * the objects `node:sqlite` builds are slower and have a `null` prototype.
  */
 export class NodeSqliteDialect implements Dialect {
 	readonly #config: NodeSqliteDialectConfig;
@@ -252,8 +230,7 @@ class NodeSqliteConnection implements DatabaseConnection {
 			);
 		}
 
-		// deliberately uncached: the cursor stays open across yields, so sharing the
-		// statement with another query would reset it mid-iteration
+		// uncached: the cursor stays open across yields, sharing the statement would reset it mid-iteration
 		const prepared = prepare(
 			this.#database,
 			compiledQuery.sql,
@@ -342,8 +319,7 @@ function columnMetadata(
 		columnNames: columns.map((it) => it.name),
 		jsonColumnFlags: columns.map((it) => {
 			if (!jsonColumns) return false;
-			// a null origin is a computed expression (a jsonArrayFrom subquery, but also
-			// e.g. a coalesce over user text), which only the query itself can classify
+			// null origin = computed expression (jsonArrayFrom subquery, or a coalesce over user text)
 			if (it.column === null) return jsonColumns.byOutputName.has(it.name);
 			return jsonColumns.byOrigin.has(`${it.table}.${it.column}`);
 		}),
@@ -360,8 +336,7 @@ function readRows<R>(
 
 	if (rawRows.length === 0) return [];
 
-	// `select *` widens when a migration adds a column, leaving a cached statement
-	// with a stale column list until the next read notices the mismatch
+	// `select *` widens when a migration adds a column, leaving a cached statement with a stale column list
 	if (rawRows[0].length !== prepared.columnNames.length) {
 		Object.assign(
 			prepared,
@@ -413,11 +388,7 @@ function parseJsonValue(value: string): unknown {
 	return parsed;
 }
 
-/**
- * Whether the raw document could hold a `__proto__` or `constructor` key. Skips the
- * recursive walk for the vast majority of documents; a `\u` escape can spell either
- * name in a way the substring checks would miss, so those take the walk too.
- */
+/** Could the raw document hold a `__proto__`/`constructor` key? `\u` escapes could spell either, so those walk too. */
 function mayPrototypePollute(value: string) {
 	return (
 		value.includes("__proto__") ||
diff --git a/app/db/reset.ts b/app/db/reset.ts
index 04e69ca7f..e85460a0c 100644
--- a/app/db/reset.ts
+++ b/app/db/reset.ts
@@ -3,13 +3,8 @@ import { deleteAllRows } from "~/db/wipe";
 import { markDatabaseClean } from "~/db/write-tracker";
 
 /**
- * Resets all data in the database by deleting all rows from every table,
- * except for SQLite system tables and the kysely migration bookkeeping tables
- * (`kysely_migration` and `kysely_migration_lock`).
- *
- * Tests do not call this — `app/test-setup.ts` runs it after every vitest test that
- * wrote anything, and the e2e reset fixture before every test. Call it by hand only
- * to wipe *within* a test.
+ * Deletes all rows except migration bookkeeping. `app/test-setup.ts` runs it after every writing
+ * vitest test and the e2e reset fixture before every test; call by hand only to wipe *within* a test.
  */
 export const dbReset = async () => {
 	await deleteAllRows();
diff --git a/app/db/seed/core/SplatoonFaker.ts b/app/db/seed/core/SplatoonFaker.ts
index 5e947c4a6..b7ba9b759 100644
--- a/app/db/seed/core/SplatoonFaker.ts
+++ b/app/db/seed/core/SplatoonFaker.ts
@@ -35,8 +35,7 @@ const CANONICAL_MAIN_WEAPON_IDS = mainWeaponIds.filter(
 	(id) => canonicalWeaponSplId(id) === id,
 );
 
-/** `count` main weapons distinct down to their canonical id, e.g. a weapon pool or
- * a multi-weapon build's. */
+/** `count` main weapons distinct down to their canonical id. */
 export function mainWeapons(count: number): MainWeaponId[] {
 	return faker.helpers.arrayElements(CANONICAL_MAIN_WEAPON_IDS, count);
 }
@@ -50,10 +49,7 @@ export function gear() {
 	};
 }
 
-/**
- * An in-game name with its discriminator, e.g. `Agent 4#1859`. `name` is sanitized and
- * truncated the way the real thing is, so the result always passes `inGameNameIsValid`.
- */
+/** E.g. `Agent 4#1859`; `name` is sanitized and truncated so the result always passes `inGameNameIsValid`. */
 export function inGameName(name = faker.person.firstName()): string {
 	const discriminator = faker.string.alphanumeric({
 		length: {
@@ -66,10 +62,7 @@ export function inGameName(name = faker.person.firstName()): string {
 	return `${sanitizedName(name)}#${discriminator}`;
 }
 
-/**
- * A map list of `count` maps, rotating through the ranked modes and never repeating
- * a stage, the way a real one looks. Callers add whatever `source` their domain uses.
- */
+/** `count` maps rotating through the ranked modes, never repeating a stage. Callers add their own `source`. */
 export function mapList(count: number): ModeWithStage[] {
 	const stages = faker.helpers.arrayElements(stageIds, count);
 
@@ -79,10 +72,7 @@ export function mapList(count: number): ModeWithStage[] {
 	}));
 }
 
-/**
- * The abilities of a build: a main and three subs per gear slot. All of them are
- * stackable ones, which every slot allows.
- */
+/** A main and three subs per gear slot, all stackable so every slot allows them. */
 export function buildAbilities(): BuildAbilitiesTuple {
 	return [gearAbilities(), gearAbilities(), gearAbilities()];
 }
diff --git a/app/db/seed/core/actAs.ts b/app/db/seed/core/actAs.ts
index 0cc81da71..68d2b3b32 100644
--- a/app/db/seed/core/actAs.ts
+++ b/app/db/seed/core/actAs.ts
@@ -3,11 +3,7 @@ import {
 	userAsyncLocalStorage,
 } from "~/features/auth/core/user-context.server";
 
-/**
- * Runs `fn` inside the acting-user store, so that repository functions resolving
- * the actor via `actorId()` see `userId` as the acting user. Needed because seeding
- * happens outside a request, where there is no acting user at all.
- */
+/** Runs `fn` with `userId` as the `actorId()` actor, since seeding happens outside a request. */
 export function actAs<T>(userId: number, fn: () => T): T {
 	return userAsyncLocalStorage.run(
 		{ user: { id: userId } as AuthenticatedUser },
diff --git a/app/db/seed/core/backdate.ts b/app/db/seed/core/backdate.ts
index d955559df..47344c3cd 100644
--- a/app/db/seed/core/backdate.ts
+++ b/app/db/seed/core/backdate.ts
@@ -14,11 +14,7 @@ type TimestampColumn<T extends BackdatableTable> = Extract<
 	`${string}At`
 >;
 
-/**
- * Moves a row's timestamps into the past. Every production write stamps *now*, so
- * a seed that needs rows looking old — an expired vote, a season's worth of matches
- * — has no way to ask for one.
- */
+/** Moves a row's timestamps into the past, since every production write stamps *now*. */
 export async function backdate<T extends BackdatableTable>(
 	table: T,
 	id: number,
@@ -27,7 +23,7 @@ export async function backdate<T extends BackdatableTable>(
 	const assignments: RawBuilder<unknown>[] = [];
 
 	for (const [column, date] of Object.entries(timestamps)) {
-		// so that a caller passing its own optional dates through needs no filtering
+		// callers pass their own optional dates through unfiltered
 		if (!date) continue;
 
 		assignments.push(
diff --git a/app/db/seed/core/defineFactory.ts b/app/db/seed/core/defineFactory.ts
index 1d0edc532..711390b74 100644
--- a/app/db/seed/core/defineFactory.ts
+++ b/app/db/seed/core/defineFactory.ts
@@ -42,19 +42,10 @@ export type Factory<Args, Row, Defaults, Options> = {
 const sequenceResets = new Set<() => void>();
 
 /**
- * Defines a factory: a thin wrapper around a repository write function that fills
- * arguments with a plausible default and lets the caller override any of them.
- *
- * `Args` is inferred from `insert`, so factories never restate column types. What
- * `defaults` leaves out — foreign keys above all, which a factory must not invent —
- * becomes a required argument of `create`.
- *
- * Defaults are drawn eagerly, before overrides are applied, so that which fields a
- * caller happens to override does not shift the values every later row gets.
- *
- * `applyOptions` runs after the insert and is how a factory hands back a row in a
- * later state (a concluded match, a finalized tournament). It gets there by running
- * the app's own operations, never by writing the resulting rows itself.
+ * Wraps a repository write with plausible defaults; `Args` is inferred from `insert` and whatever `defaults`
+ * leaves out (foreign keys above all) is required by `create`. Defaults are drawn eagerly, before overrides,
+ * so overriding doesn't shift later rows. `applyOptions` runs after the insert to reach later states through
+ * the app's own operations, never by writing rows itself.
  */
 export function defineFactory<
 	Args,
@@ -86,8 +77,7 @@ export function defineFactory<
 		return row;
 	};
 
-	// `create` requires everything `defaults` doesn't supply, so the merge is a
-	// complete `Args` — something the compiler can't work out from the spread
+	// the merge is a complete `Args`, which the compiler can't work out from the spread
 	const build = (overrides: Partial<Args>) =>
 		({
 			...defaults?.({ seq: ++seq }),
diff --git a/app/db/seed/core/faker.ts b/app/db/seed/core/faker.ts
index c7cb0d676..046e8fe50 100644
--- a/app/db/seed/core/faker.ts
+++ b/app/db/seed/core/faker.ts
@@ -3,10 +3,7 @@ import { base, en, Faker } from "@faker-js/faker";
 const FAKER_SEED = 5800;
 const MAX_UNIQUE_ATTEMPTS = 100;
 
-/**
- * Faker instance dedicated to seeding. Deliberately not the global singleton, so
- * that app code or a test drawing from `faker` cannot shift what the seed produces.
- */
+/** Not the global singleton, so app code or a test drawing from `faker` can't shift what the seed produces. */
 export const faker = new Faker({ locale: [en, base] });
 faker.seed(FAKER_SEED);
 
@@ -25,11 +22,7 @@ export function createSeededFaker(
 	return instance;
 }
 
-/**
- * Draws from `generate` until it produces a value that has not been drawn before,
- * for values that should look real but still be unique (e.g. a Discord name).
- * Values with a unique constraint should be derived from the factory's `seq` instead.
- */
+/** Draws from `generate` until unique (e.g. a Discord name). Unique-constrained values should derive from `seq` instead. */
 export function unique<T>(generate: () => T): T {
 	for (let attempt = 0; attempt < MAX_UNIQUE_ATTEMPTS; attempt++) {
 		const value = generate();
diff --git a/app/db/seed/core/pinUserId.ts b/app/db/seed/core/pinUserId.ts
index b838b7f22..1ff5b3d43 100644
--- a/app/db/seed/core/pinUserId.ts
+++ b/app/db/seed/core/pinUserId.ts
@@ -2,12 +2,8 @@ import { sql } from "kysely";
 import { db } from "~/db/sql";
 
 /**
- * Moves a user to a fixed id. Production permission logic keys off literal user
- * ids (`ADMIN_ID`, `STAFF_IDS`), so the users those refer to have to land on them
- * for the app to consider them an admin or staff at all.
- *
- * Throws if the id is already taken, since taking it would mean deleting somebody
- * else's rows. Create the pinned users before any other.
+ * Moves a user to a fixed id, since permission logic keys off literal ids (`ADMIN_ID`, `STAFF_IDS`).
+ * Throws if the id is taken, so create pinned users before any other.
  */
 export async function pinUserId(userId: number, pinnedId: number) {
 	if (userId === pinnedId) return pinnedId;
@@ -29,8 +25,7 @@ export async function pinUserId(userId: number, pinnedId: number) {
 		db,
 	);
 
-	// the search index is kept in sync by triggers that don't watch `id`, so its
-	// entry would keep pointing at the id the user just moved off of
+	// the search index triggers don't watch `id`, so its entry would keep pointing at the old id
 	await sql`insert into "UserSearch"("UserSearch") values ('rebuild')`.execute(
 		db,
 	);
diff --git a/app/db/seed/core/reseason.ts b/app/db/seed/core/reseason.ts
index 39793bb04..2109a390c 100644
--- a/app/db/seed/core/reseason.ts
+++ b/app/db/seed/core/reseason.ts
@@ -1,11 +1,8 @@
 import { db } from "~/db/sql";
 
 /**
- * Moves every season stamped row (skills and the aggregated stats keyed off them)
- * to the given season. Concluding a match stamps its results with the season that
- * is current then, so matches backdated into an older season still leave their
- * results in the ongoing one — a seed that needs a season looking played out and
- * over has no other way to ask for one.
+ * Moves every season stamped row (skills and aggregated stats) to `season`. Concluding stamps the current
+ * season, so backdated matches still leave their results in the ongoing one.
  */
 export async function reseason(season: number) {
 	await db.updateTable("Skill").set({ season }).execute();
diff --git a/app/db/seed/core/showcaseNames.ts b/app/db/seed/core/showcaseNames.ts
index 23d6266c1..a84894fa1 100644
--- a/app/db/seed/core/showcaseNames.ts
+++ b/app/db/seed/core/showcaseNames.ts
@@ -24,8 +24,7 @@ export const CUSTOM_NAMES = [
 	"xX_sniper_Xx",
 ];
 
-/** Kana-only in-game names — the Switch keyboard allows no kanji or emoji, so a
- * kanji display name pairs with one of these. */
+/** The Switch keyboard allows no kanji or emoji, so a kanji display name pairs with one of these. */
 const KANA_NAMES = [
 	"スプラちゃん",
 	"いかタコどん",
diff --git a/app/db/seed/dev/availability.ts b/app/db/seed/dev/availability.ts
index 39f84342b..944e1e77b 100644
--- a/app/db/seed/dev/availability.ts
+++ b/app/db/seed/dev/availability.ts
@@ -53,11 +53,8 @@ const EVENINGS: WeekSchedule = [
 ];
 
 /**
- * Availability of the admin's team, their friends and a stranger, for this week
- * and the next. Every state the schedule surfaces can be in is on the admin's
- * team: a filled week, a week submitted as unavailable, a week nobody reported,
- * ranges crossing midnight, day notes, and ranges a tournament or a booked scrim
- * takes back.
+ * The admin's team, friends and a stranger, this week and next. The admin's team covers every state: a filled
+ * week, one submitted as unavailable, one nobody reported, midnight-crossing ranges, day notes, commitments.
  */
 export async function seedAvailability({
 	users,
@@ -76,16 +73,14 @@ export async function seedAvailability({
 	const [, multiRangeId, crossMidnightId, unavailableId, weekendId] =
 		teams.allianceRogue.playerUserIds;
 
-	// the tournament and the scrim the admin's team is committed to, with room
-	// around them so that the commitment visibly takes availability back
+	// with room around them so the commitment visibly takes availability back
 	const commitments = [
 		{
 			userId: users.adminId,
 			startsAt: scrims.accepted.startsAt - HOUR,
 			endsAt: scrims.accepted.startsAt + 2 * HOUR,
 		},
-		// registration availability of the reg open tournament: fully available,
-		// available from an hour in, and not available at all
+		// reg open tournament: fully available, available from an hour in, not available at all
 		{
 			userId: users.adminId,
 			startsAt: tournaments.regOpen.startsAt - HOUR,
@@ -104,8 +99,7 @@ export async function seedAvailability({
 	];
 
 	const schedules: Array<SeededSchedule> = [
-		// N-ZAP reports nothing at all, so that they are the one the Monday
-		// reminder routine has something to say to
+		// N-ZAP reports nothing, so the Monday reminder routine has someone to nudge
 		{
 			userId: users.adminId,
 			timezone: "Europe/Helsinki",
@@ -169,8 +163,7 @@ export async function seedAvailability({
 		{
 			userId: teams.allianceRogue.subUserId,
 			timezone: "Europe/Helsinki",
-			// Wednesday ends exactly at midnight, the shape the drag editor
-			// produces when a bar is pulled to the 00:00 tick
+			// Wednesday ends exactly at midnight, as the drag editor produces at the 00:00 tick
 			weekly: [[], [["18:00", "22:00"]], [["18:00", "00:00"]], [], [], [], []],
 			fillsNextWeek: true,
 		},
@@ -188,8 +181,7 @@ export async function seedAvailability({
 			],
 			fillsNextWeek: true,
 		},
-		// the last of the admin's friends reports nothing, so the friends page has
-		// a row with no schedule to sort below the ones that have one
+		// the last friend reports nothing, giving the friends page a schedule-less row to sort last
 		...misc.adminFriendIds.slice(0, -1).map((userId, index) => ({
 			userId,
 			timezone: "Europe/Helsinki",
diff --git a/app/db/seed/dev/highlights.ts b/app/db/seed/dev/highlights.ts
index 1663e342b..a4c349ff7 100644
--- a/app/db/seed/dev/highlights.ts
+++ b/app/db/seed/dev/highlights.ts
@@ -3,14 +3,10 @@ import type { SeededCalendarEvents } from "./calendar";
 import type { SeededTournaments } from "./tournaments";
 import type { SeededUsers } from "./users";
 
-/** Calendar event results N-ZAP highlights, few enough that the highlights view of
- * his results page is a page shorter than the full one. */
+/** Few enough that the highlights view of N-ZAP's results page is a page shorter than the full one. */
 const NZAP_CALENDAR_HIGHLIGHT_COUNT = 6;
 
-/**
- * Highlights some of N-ZAP's results, so that his profile has a highlighted results
- * widget and his results page opens on the highlights view.
- */
+/** Gives N-ZAP a highlighted results widget and a results page opening on the highlights view. */
 export async function seedResultHighlights({
 	users,
 	calendarEvents,
diff --git a/app/db/seed/dev/misc.ts b/app/db/seed/dev/misc.ts
index a53c7cf7e..f1616e166 100644
--- a/app/db/seed/dev/misc.ts
+++ b/app/db/seed/dev/misc.ts
@@ -29,7 +29,7 @@ const ADMIN_FRIEND_COUNT = 3;
 const STREAM_COUNT = 20;
 
 export type SeededMisc = {
-	/** The admin's friends, who are none of them their teammate. */
+	/** None of them a teammate. */
 	adminFriendIds: number[];
 };
 
diff --git a/app/db/seed/dev/sendouq.ts b/app/db/seed/dev/sendouq.ts
index 6b175d40e..8bdb59168 100644
--- a/app/db/seed/dev/sendouq.ts
+++ b/app/db/seed/dev/sendouq.ts
@@ -14,8 +14,7 @@ const SQUAD_COUNT = 8;
 const LOOKING_GROUP_COUNT = 10;
 const REPORTED_MAP_COUNT = 4;
 
-/** N-ZAP's unconfirmed match, on an id worth remembering. Every other match is
- * created before it, so the squad matches make up the difference. */
+/** N-ZAP's unconfirmed match id; every other match is created before it, squad matches making up the difference. */
 const NZAP_MATCH_ID = 500;
 const SQUAD_MATCH_COUNT =
 	NZAP_MATCH_ID - 1 - RECENT_MATCH_COUNT - OLDER_MATCH_COUNT;
@@ -60,9 +59,7 @@ export async function seedSendouQ(
 	return { recentMatchIds };
 }
 
-/** A match N-ZAP's team has reported but the other has not confirmed, so it is the
- * other team's to report and N-ZAP's group is free to queue again. His side is
- * Alliance Rogue's lineup, so the match is one of a team against a pickup group. */
+/** Reported by N-ZAP's side (Alliance Rogue vs. a pickup), unconfirmed, so his group is free to queue again. */
 async function seedNzapReportedMatch(users: SeededUsers, teams: SeededTeams) {
 	const opponentIds = users.crowdIds.slice(-88, -84);
 
@@ -81,9 +78,7 @@ async function seedNzapReportedMatch(users: SeededUsers, teams: SeededTeams) {
 	);
 }
 
-/** One canceled match of each form the cancel reports take, so that the staff-only
- * views have every one of them to show: the two teams pointing at the same player,
- * at different ones, and a match staff canceled without either team's account of it. */
+/** Every cancel report form for the staff views: both teams naming the same player, different ones, and a staff cancel. */
 async function seedNzapCanceledMatches(users: SeededUsers, teams: SeededTeams) {
 	const [nzapId, ...teammateIds] = allianceRogueLineup(teams);
 	const opponentIds = users.crowdIds.slice(-104, -88);
@@ -187,8 +182,7 @@ function allianceRogueLineup(teams: SeededTeams) {
 	return allianceRogue.memberUserIds;
 }
 
-/** Fixed team lineups playing together repeatedly, so their identifier skills reach
- * the match count the team leaderboard requires. */
+/** Fixed lineups playing repeatedly so their identifier skills reach the team leaderboard's match count. */
 async function seedSquadMatches(teams: SeededTeams) {
 	const squads = teams.squads.slice(0, SQUAD_COUNT);
 
diff --git a/app/db/seed/dev/teams.ts b/app/db/seed/dev/teams.ts
index 627e9de6d..26476e0d8 100644
--- a/app/db/seed/dev/teams.ts
+++ b/app/db/seed/dev/teams.ts
@@ -83,8 +83,7 @@ export async function seedTeams(users: SeededUsers): Promise<SeededTeams> {
 		}
 	}
 
-	// showcase users double as members of a secondary team; disjoint chunks so
-	// nobody exceeds the two-team limit
+	// showcase users double as secondary team members; disjoint chunks keep everyone within the two-team limit
 	for (let i = 0; i < SECONDARY_TEAM_COUNT; i++) {
 		const memberUserIds = users.showcaseIds.slice(i * 4, i * 4 + 4);
 
diff --git a/app/db/seed/dev/tournaments.ts b/app/db/seed/dev/tournaments.ts
index 89ce9c1d4..02112034e 100644
--- a/app/db/seed/dev/tournaments.ts
+++ b/app/db/seed/dev/tournaments.ts
@@ -21,8 +21,7 @@ import type { SeededTeams } from "./teams";
 import type { SeededTrophies } from "./trophies";
 import type { SeededUsers } from "./users";
 
-/** Series the played-out tournaments of the past are named off. The four the seed
- * puts in a state worth opening are named off a series of their own. */
+/** Series the past tournaments are named off; the four in a state worth opening have series of their own. */
 const TOURNAMENT_NAME_STEMS = [
 	{ name: "PICNIC", avatarFileName: "picnic.png" },
 	{ name: "The Depths", avatarFileName: "the-depths.png" },
@@ -32,8 +31,7 @@ const TOURNAMENT_NAME_STEMS = [
 const HISTORICAL_COUNT = 5;
 /** Showcase users seeded into every played tournament, so their results paginate. */
 const CORE_PLAYER_COUNT = 8;
-/** Share of a tournament's teams that register as one of the site's teams, the rest
- * being pickups put together for the tournament. */
+/** Share of teams registering as one of the site's teams, the rest being pickups. */
 const REGISTERED_TEAM_SHARE = 0.4;
 /** Solo players looking for a team in a tournament whose registration has closed. */
 const SUB_COUNT = 7;
@@ -175,10 +173,10 @@ type Ctx = {
 	rosters: ReturnType<typeof rosterBuilder>;
 };
 
-/** #1 double elim, TO maps — reg open and a couple of days out, so it has both
- * registered teams (some of them still short of a full roster) and LFG teams.
- * The admin registers with Alliance Rogue on a roster whose availability mixes
- * every state the registration page's panel can show. */
+/**
+ * #1 double elim, TO maps — reg open, a couple of days out: registered teams (some short of a full roster)
+ * and LFG teams. The admin's Alliance Rogue roster mixes every availability state the panel can show.
+ */
 async function seedInTheZone({
 	users,
 	organizations,
@@ -202,9 +200,8 @@ async function seedInTheZone({
 		trophyId: trophies.ids[0],
 	});
 
-	// availability panel states, in roster order: the admin and multiRange are
-	// fully available, weekend is free only from an hour in, unavailable
-	// submitted an empty week and the captain (N-ZAP) reports nothing at all
+	// in roster order: admin and multiRange fully available, weekend free from an hour in, unavailable
+	// submitted an empty week, the captain (N-ZAP) reports nothing
 	const [, multiRangeId, , unavailableId, weekendId] =
 		teams.allianceRogue.playerUserIds;
 	const allianceRogueRoster: Roster = {
@@ -247,9 +244,7 @@ async function seedInTheZone({
 	};
 }
 
-/** #2 double elim with an underground bracket, AUTO_SZ, ranked — bracket started,
- * not a single set reported yet. N-ZAP is seeded past the byes of the first round,
- * so he has a match of his own going on. */
+/** #2 double elim + underground, AUTO_SZ, ranked — started, nothing reported. N-ZAP is seeded past the byes so he has a match going. */
 async function seedPaddlingPool({ users, rosters }: Ctx) {
 	const tournament = await TournamentFactory.create({
 		name: nameFor("Paddling Pool"),
@@ -306,8 +301,7 @@ async function seedLowInk({ users, rosters }: Ctx) {
 	await TournamentFactory.playOut(tournament.id, 0);
 }
 
-/** #4 round robin → SE, TO maps — everybody checked in, first bracket not started.
- * The one upcoming tournament N-ZAP is not registered in, so it is his saved one. */
+/** #4 round robin → SE, TO maps — everybody checked in, not started. N-ZAP isn't registered, so it is his saved one. */
 async function seedSwimOrSink({ users, rosters }: Ctx) {
 	const tournament = await TournamentFactory.create({
 		name: nameFor("Swim or Sink"),
@@ -377,8 +371,7 @@ async function seedHistoricalTournaments({
 			{ tier: ((i % 3) + 1) as TournamentTierNumber },
 		);
 
-		// on the top seed of the first one, so that a win of his is finalized, and
-		// further down another, so his result list is not all first places
+		// top seed of the first (a finalized win), further down in another so his results aren't all firsts
 		const nzapRosterIdx = i === 0 ? 0 : i === 2 ? 5 : null;
 
 		const teamRosters = rosters.take({
@@ -408,8 +401,7 @@ async function seedHistoricalTournaments({
 	return nzapTeamIds;
 }
 
-/** Every edition of a series shares the one logo image of it, an image row not being
- * allowed the url of another. */
+/** Editions of a series share one logo image, an image row not being allowed the url of another. */
 async function seriesLogoImgId(
 	imgIds: Map<string, number>,
 	stem: (typeof TOURNAMENT_NAME_STEMS)[number],
@@ -427,9 +419,7 @@ async function seriesLogoImgId(
 	return image.id;
 }
 
-/** Solo players looking to sub in a tournament whose registration has closed, the
- * admin among them so that the state of having posted is one of the two profiles'.
- * Drawn from the tail of the crowd, which no tournament roster reaches. */
+/** Subs for a closed-registration tournament, the admin among them. Drawn from the tail of the crowd no roster reaches. */
 async function seedSubs(tournamentId: number, users: SeededUsers) {
 	const userIds = [
 		users.adminId,
@@ -451,8 +441,7 @@ async function seedTournamentExtras(tournamentId: number, users: SeededUsers) {
 		await TournamentStreamerFactory.create({ tournamentId, twitchAccount });
 	}
 
-	// N-ZAP used to be the demo LFG poster, but he registers with Alliance
-	// Rogue now — a player cannot both be on a team and look for one
+	// not N-ZAP: he registers with Alliance Rogue and a player can't both be on a team and look for one
 	const lfgUserIds = users.showcaseIds.slice(90, 96);
 
 	const lfgTeamIds: number[] = [];
@@ -507,12 +496,10 @@ function rosterBuilder(users: SeededUsers, teams: SeededTeams) {
 	];
 
 	return {
-		/** Rosters for one tournament: some of the site's teams registering as
-		 * themselves, core players spread over the rest, and the remaining seats drawn
-		 * without replacement within the tournament. A `pinned` user is added to a
-		 * roster of their own as its owner, and kept out of everybody else's. A
-		 * `preset` roster takes the first team slots exactly as given, its members
-		 * kept out of every other roster. */
+		/**
+		 * Some site teams register as themselves, core players spread over the rest, remaining seats drawn without
+		 * replacement. A `pinned` user owns a roster of their own; a `preset` roster takes the first slots as given.
+		 */
 		take({
 			teamCount,
 			teamSize,
@@ -551,8 +538,7 @@ function rosterBuilder(users: SeededUsers, teams: SeededTeams) {
 			const shuffled = faker.helpers.shuffle(pool.filter(isFree));
 			const freeCorePlayers = corePlayers.filter(isFree);
 
-			// the teams of the site take the first team slots a preset or a pin
-			// does not want
+			// site teams take the first slots a preset or a pin does not want
 			const pinnedIdxs = new Set(pinned.map((pin) => pin.teamIdx));
 			const registeringIdxs = Array.from({ length: teamCount }, (_, i) => i)
 				.filter((i) => !pinnedIdxs.has(i) && i >= preset.length)
diff --git a/app/db/seed/dev/trophies.ts b/app/db/seed/dev/trophies.ts
index 36a46424d..a2f6ff806 100644
--- a/app/db/seed/dev/trophies.ts
+++ b/app/db/seed/dev/trophies.ts
@@ -44,11 +44,7 @@ export async function seedTrophies({
 	return { ids };
 }
 
-/**
- * Creates the trophies awarded off something other than a tournament win and hands
- * them to everybody eligible, as the nightly sync does. Runs last of the seed: who
- * is eligible follows from the patrons and X Rank placements seeded before it.
- */
+/** Non-tournament trophies handed to everybody eligible like the nightly sync. Runs last: eligibility follows from patrons and X Rank placements. */
 export async function seedSpecialTrophies() {
 	const models = TrophyFactory.MODELS;
 
diff --git a/app/db/seed/dev/users.ts b/app/db/seed/dev/users.ts
index be9a04955..a544203a8 100644
--- a/app/db/seed/dev/users.ts
+++ b/app/db/seed/dev/users.ts
@@ -242,8 +242,7 @@ async function seedShowcaseUsers() {
 	return { ids, artistIds, favoriteBadgeUserIds };
 }
 
-/** Widget profile of the one seeded supporter: both slots filled, and every widget
- * whose content other modules seed onto N-ZAP. */
+/** The one seeded supporter's widgets: both slots filled, every widget other modules seed content for. */
 function nzapWidgets(): NonNullable<
 	Parameters<typeof UserFactory.create>[1]
 >["widgets"] {
diff --git a/app/db/seed/factories/ApiTokenFactory.ts b/app/db/seed/factories/ApiTokenFactory.ts
index c4499b630..42cee33bc 100644
--- a/app/db/seed/factories/ApiTokenFactory.ts
+++ b/app/db/seed/factories/ApiTokenFactory.ts
@@ -7,11 +7,7 @@ type InsertArgs = {
 	type: ApiTokenType;
 };
 
-/**
- * Creates API tokens. `userId` is whose token it is — note that having one and being
- * allowed to use it are separate things, the permission coming from the user's roles.
- * The token itself is the repository's own.
- */
+/** Having a token and being allowed to use it are separate things: the permission comes from the user's roles. */
 export const { create } = defineFactory({
 	defaults: () => ({ type: "read" as const }),
 	insert: ({ userId, type }: InsertArgs) =>
diff --git a/app/db/seed/factories/ArtFactory.ts b/app/db/seed/factories/ArtFactory.ts
index 9504cd46e..fdcbe2eb5 100644
--- a/app/db/seed/factories/ArtFactory.ts
+++ b/app/db/seed/factories/ArtFactory.ts
@@ -7,12 +7,7 @@ type InsertArgs = Parameters<typeof ArtRepository.insert>[0] & {
 	authorId: number;
 };
 
-/**
- * Creates art.
- *
- * Validated by default, as art uploaded by a patron is, so that the listings
- * reading through the validated-images view can see it.
- */
+/** Validated by default (as a patron's upload is) so listings reading the validated-images view see it. */
 export const { create, createMany } = defineFactory({
 	defaults: ({ seq }) => ({
 		url: `art-${seq}.png`,
diff --git a/app/db/seed/factories/AvailabilityWeekFactory.ts b/app/db/seed/factories/AvailabilityWeekFactory.ts
index ce032c492..ec9efa54c 100644
--- a/app/db/seed/factories/AvailabilityWeekFactory.ts
+++ b/app/db/seed/factories/AvailabilityWeekFactory.ts
@@ -7,11 +7,7 @@ type InsertArgs = Parameters<typeof AvailabilityRepository.upsertOwnWeek>[0] & {
 	userId: number;
 };
 
-/**
- * Creates the availability one user reported for one week. Slots and day notes
- * are absolute, so a range crossing midnight is given as one slot like any other.
- * A week with no slots is the "unavailable all week" a user submits.
- */
+/** Slots are absolute (a range crossing midnight is one slot). No slots = "unavailable all week". */
 export const { create } = defineFactory({
 	defaults: () => ({
 		timezone: "Europe/Helsinki",
diff --git a/app/db/seed/factories/BuildFactory.ts b/app/db/seed/factories/BuildFactory.ts
index 8ca68aa6c..64760f238 100644
--- a/app/db/seed/factories/BuildFactory.ts
+++ b/app/db/seed/factories/BuildFactory.ts
@@ -4,17 +4,13 @@ import { defineFactory } from "../core/defineFactory";
 import { faker } from "../core/faker";
 import * as SplatoonFaker from "../core/SplatoonFaker";
 
-/**
- * Creates builds. `ownerId` is whose build it is. The ability and weapon rows every
- * build listing is read through are what the repository derives from `abilities` and
- * `weaponSplIds`; a multi-weapon build is `weaponSplIds` with more than one entry.
- */
 const NO_GEAR = {
 	headGearSplId: null,
 	clothesGearSplId: null,
 	shoesGearSplId: null,
 };
 
+/** The repository derives the ability and weapon rows from `abilities` and `weaponSplIds` (several = multi-weapon build). */
 export const { create, createMany } = defineFactory({
 	defaults: () => ({
 		title: faker.lorem.words(3),
diff --git a/app/db/seed/factories/CalendarEventFactory.ts b/app/db/seed/factories/CalendarEventFactory.ts
index 1323aef17..66093a133 100644
--- a/app/db/seed/factories/CalendarEventFactory.ts
+++ b/app/db/seed/factories/CalendarEventFactory.ts
@@ -14,10 +14,7 @@ type InsertArgs = Omit<
 	"isFullTournament" | "bracketProgression" | "mapPickingStyle"
 >;
 
-/**
- * What every calendar event is defaulted to, tournaments included — a tournament is
- * a calendar event with one attached, see `TournamentFactory`.
- */
+/** Defaults of every calendar event, tournaments (see `TournamentFactory`) included. */
 export const eventDefaults = () => ({
 	name: faker.company.name(),
 	description: faker.number.float(1) < 0.4 ? faker.lorem.paragraph() : null,
diff --git a/app/db/seed/factories/CalendarEventResultFactory.ts b/app/db/seed/factories/CalendarEventResultFactory.ts
index 27690acab..1aaf657b5 100644
--- a/app/db/seed/factories/CalendarEventResultFactory.ts
+++ b/app/db/seed/factories/CalendarEventResultFactory.ts
@@ -2,13 +2,7 @@ import * as CalendarRepository from "~/features/calendar/CalendarRepository.serv
 import { defineFactory } from "../core/defineFactory";
 import { faker } from "../core/faker";
 
-/**
- * Creates reported results for a non-tournament calendar event, the way the event's
- * organizer reports them. `results` decides the placements and who played.
- *
- * Returns the result teams as they were created, so that a caller can pick one of
- * them (a result to highlight, say) by who played on it.
- */
+/** Results of a non-tournament event as the organizer reports them. Returns the result teams as created. */
 export const { create } = defineFactory({
 	defaults: () => ({
 		participantCount: faker.number.int({ min: 10, max: 250 }),
diff --git a/app/db/seed/factories/FriendRequestFactory.ts b/app/db/seed/factories/FriendRequestFactory.ts
index 31445a332..ba6af3b8e 100644
--- a/app/db/seed/factories/FriendRequestFactory.ts
+++ b/app/db/seed/factories/FriendRequestFactory.ts
@@ -1,10 +1,7 @@
 import * as FriendRepository from "~/features/friends/FriendRepository.server";
 import { defineFactory } from "../core/defineFactory";
 
-/**
- * Creates pending friend requests: `senderId` has asked `receiverId` to be friends.
- * A request that was accepted is a friendship instead, see `FriendshipFactory`.
- */
+/** Pending requests from `senderId` to `receiverId`. An accepted one is a friendship, see `FriendshipFactory`. */
 export const { create, createMany } = defineFactory({
 	defaults: () => ({}),
 	insert: FriendRepository.insertFriendRequest,
diff --git a/app/db/seed/factories/FriendshipFactory.ts b/app/db/seed/factories/FriendshipFactory.ts
index d1a85b47a..f7c703975 100644
--- a/app/db/seed/factories/FriendshipFactory.ts
+++ b/app/db/seed/factories/FriendshipFactory.ts
@@ -6,11 +6,7 @@ type InsertArgs = Omit<
 	"friendRequestId"
 >;
 
-/**
- * Creates friendships between `userOneId` and `userTwoId`, in the order production
- * makes them: the request one sent the other is created first and consumed by the
- * friendship. Which of the two is stored as the first user is the repository's own.
- */
+/** Like production: a request is created first and consumed by the friendship. Stored order is the repository's own. */
 export const { create } = defineFactory({
 	defaults: () => ({}),
 	insert: async ({ userOneId, userTwoId }: InsertArgs) => {
diff --git a/app/db/seed/factories/GroupMatchContinueVoteFactory.ts b/app/db/seed/factories/GroupMatchContinueVoteFactory.ts
index 371292c7d..45366c325 100644
--- a/app/db/seed/factories/GroupMatchContinueVoteFactory.ts
+++ b/app/db/seed/factories/GroupMatchContinueVoteFactory.ts
@@ -9,12 +9,7 @@ type InsertArgs = Parameters<
 	userId: number;
 };
 
-/**
- * Creates the votes a SendouQ group casts on carrying on with the same teammates
- * after a match. A vote against clears the group's votes in favour, since those
- * were for carrying on at a size the group no longer has — the repository's own
- * doing, which is why the votes go through it in the order they were cast.
- */
+/** Votes on carrying on after a match. A vote against clears the votes in favour, so they go through the repository in cast order. */
 export const { create } = defineFactory({
 	defaults: () => ({ isContinuing: true }),
 	insert: ({ userId, ...args }: InsertArgs) =>
diff --git a/app/db/seed/factories/ImageFactory.ts b/app/db/seed/factories/ImageFactory.ts
index 3d1114014..2e84800eb 100644
--- a/app/db/seed/factories/ImageFactory.ts
+++ b/app/db/seed/factories/ImageFactory.ts
@@ -10,14 +10,8 @@ type Options = {
 };
 
 /**
- * Creates user submitted images, unvalidated as the repository function makes them.
- * An image on its own is an orphan — the queries counting images for approval only
- * see it once something (a calendar event avatar, a team logo) points at it.
- *
- * The url is one of the numbered logos seeded to the local image storage, so that an
- * image the caller does not name renders in dev instead of 404ing.
- *
- * Art brings its own image, see `ArtFactory`.
+ * Unvalidated by default. An image alone is an orphan: approval queries only see it once something points
+ * at it. Default url is a numbered logo seeded to local storage so it renders in dev. Art: see `ArtFactory`.
  */
 export const { create } = defineFactory({
 	defaults: ({ seq }) => ({
diff --git a/app/db/seed/factories/LiveStreamFactory.ts b/app/db/seed/factories/LiveStreamFactory.ts
index d60757de5..54c0b2339 100644
--- a/app/db/seed/factories/LiveStreamFactory.ts
+++ b/app/db/seed/factories/LiveStreamFactory.ts
@@ -8,11 +8,8 @@ type Stream = Omit<Tables["LiveStream"], "id">;
 type StreamOverrides = Partial<Stream> & Pick<Stream, "userId">;
 
 /**
- * Replaces the live streams with one per entry, the same write the twitch poller
- * does. A later call replaces the earlier's streams, so seed them all at once.
- *
- * A stream credited to a user also links its Twitch account to them, as the poller
- * only credits a stream to the user who has that account on their profile.
+ * Same write as the twitch poller, so seed all streams at once. A stream credited to a user also links the
+ * Twitch account to them, as the poller only credits users with the account on their profile.
  */
 export async function replaceAll(streams: StreamOverrides[]) {
 	const filledStreams = streams.map(fillStream);
diff --git a/app/db/seed/factories/LogInLinkFactory.ts b/app/db/seed/factories/LogInLinkFactory.ts
index fc1bd22af..b405bbffe 100644
--- a/app/db/seed/factories/LogInLinkFactory.ts
+++ b/app/db/seed/factories/LogInLinkFactory.ts
@@ -1,10 +1,7 @@
 import * as LogInLinkRepository from "~/features/auth/LogInLinkRepository.server";
 import { defineFactory } from "../core/defineFactory";
 
-/**
- * Creates the single use links the log in with a code flow hands out. `userId` is
- * who the link logs in; its code and expiry are the repository's own.
- */
+/** Single use links of the log in with a code flow; `userId` is who the link logs in. */
 export const { create } = defineFactory({
 	insert: ({ userId }: { userId: number }) =>
 		LogInLinkRepository.insert(userId),
diff --git a/app/db/seed/factories/PlusSuggestionFactory.ts b/app/db/seed/factories/PlusSuggestionFactory.ts
index c14f62b8e..703197ef2 100644
--- a/app/db/seed/factories/PlusSuggestionFactory.ts
+++ b/app/db/seed/factories/PlusSuggestionFactory.ts
@@ -7,10 +7,7 @@ import invariant from "~/utils/invariant";
 import { defineFactory } from "../core/defineFactory";
 import { faker } from "../core/faker";
 
-/**
- * Creates plus server suggestions, `authorId` suggesting `suggestedId` for `tier`.
- * Defaults to the upcoming voting's month, i.e. a suggestion that is currently open.
- */
+/** `authorId` suggests `suggestedId` for `tier`. Defaults to the upcoming voting's month, i.e. currently open. */
 export const { create } = defineFactory({
 	defaults: () => ({
 		...upcomingVotingMonthYear(),
diff --git a/app/db/seed/factories/PlusVoteFactory.ts b/app/db/seed/factories/PlusVoteFactory.ts
index c2bfd1a33..375f1834e 100644
--- a/app/db/seed/factories/PlusVoteFactory.ts
+++ b/app/db/seed/factories/PlusVoteFactory.ts
@@ -12,11 +12,7 @@ type Vote = UpsertManyPlusVotesArgs[number];
 
 const VOTING_ENDED_AGO = { minutes: 5 };
 
-/**
- * Creates plus server votes, `authorId` being who cast the vote and `votedId` who it
- * was cast on. Defaults to a vote of the latest completed voting, which is one that
- * already counts towards the plus tiers.
- */
+/** `authorId` cast the vote on `votedId`. Defaults to the latest completed voting, which already counts towards tiers. */
 export const { create, createMany } = defineFactory({
 	defaults: () => ({
 		...lastCompletedVoting(new Date()),
@@ -25,9 +21,7 @@ export const { create, createMany } = defineFactory({
 		becomesValidAt: dateToDatabaseTimestamp(sub(new Date(), VOTING_ENDED_AGO)),
 	}),
 	insert: async (vote: Vote) => {
-		// `upsertMany` replaces every vote its author cast that month, being one
-		// submission of the voting form, so the votes cast before this one are read
-		// back and sent along
+		// `upsertMany` replaces every vote the author cast that month, so earlier ones are read back and sent along
 		const alreadyCast = await db
 			.selectFrom("PlusVote")
 			.selectAll()
diff --git a/app/db/seed/factories/ResultHighlightFactory.ts b/app/db/seed/factories/ResultHighlightFactory.ts
index 929c74275..64505e66b 100644
--- a/app/db/seed/factories/ResultHighlightFactory.ts
+++ b/app/db/seed/factories/ResultHighlightFactory.ts
@@ -9,11 +9,7 @@ type ReplaceAllArgs = {
 	resultTournamentTeamIds: number[];
 };
 
-/**
- * Replaces the results a user has highlighted on their profile, the same write the
- * highlight picking page does. A later call replaces the earlier's highlights, so
- * seed them all at once.
- */
+/** Same write as the highlight picking page, so seed all highlights at once. */
 export function replaceAll({ userId, ...args }: ReplaceAllArgs) {
 	return actAs(userId, () => UserRepository.updateOwnResultHighlights(args));
 }
diff --git a/app/db/seed/factories/SQGroupFactory.ts b/app/db/seed/factories/SQGroupFactory.ts
index 24896403c..c364630ca 100644
--- a/app/db/seed/factories/SQGroupFactory.ts
+++ b/app/db/seed/factories/SQGroupFactory.ts
@@ -18,11 +18,7 @@ type Options = {
 	likedByGroupIds?: number[];
 };
 
-/**
- * Creates SendouQ groups. The first of `memberUserIds` is the creator, whose
- * membership the repository creates with the group; the rest join it the way they do
- * in production. Invite and chat codes are the repository's own.
- */
+/** First of `memberUserIds` is the creator, the rest join like in production. */
 export const { create } = defineFactory({
 	defaults: () => ({
 		status: "ACTIVE" as const,
@@ -58,8 +54,7 @@ export const { create } = defineFactory({
 		}
 
 		if (isMatchmade) {
-			// written directly because the only production write of the column is
-			// `morphGroups`, which needs two separate groups to merge into one
+			// written directly: the only production write is `morphGroups`, which needs two groups to merge
 			await db
 				.updateTable("Group")
 				.set({ matchmade: 1 })
diff --git a/app/db/seed/factories/SQMatchFactory.ts b/app/db/seed/factories/SQMatchFactory.ts
index 7b29755e1..d4be90c62 100644
--- a/app/db/seed/factories/SQMatchFactory.ts
+++ b/app/db/seed/factories/SQMatchFactory.ts
@@ -33,17 +33,13 @@ type CancelReport = {
 };
 
 type Options = {
-	/** Play the match out, alpha winning every map, up to both teams having agreed
-	 * on the score. Leaves both groups inactive, as a real concluded match does. */
+	/** Alpha wins every map and both teams agree on the score. Both groups end up inactive. */
 	isConcluded?: boolean;
-	/** Cancel the match the way the two teams do: alpha's owner requests the
-	 * cancellation and bravo's owner accepts it, each giving their own account. */
+	/** Alpha's owner requests the cancellation and bravo's accepts, each giving their own account. */
 	cancel?: { requested: CancelReport; accepted: CancelReport };
 	/** Cancel the match the way staff does, leaving neither team an account of it. */
 	canceledByStaffUserId?: number;
-	/** Play the match out, alpha winning every map, and report the score as alpha —
-	 * leaving bravo still to confirm it. Alpha's group goes inactive, as reporting
-	 * makes it, so its members are free to queue again. */
+	/** Alpha wins every map and reports, bravo still to confirm. Alpha's group goes inactive. */
 	isReported?: boolean;
 	/** When the match was made, for one that should look older than now. */
 	createdAt?: Date;
@@ -51,11 +47,7 @@ type Options = {
 	confirmedAt?: Date;
 };
 
-/**
- * Creates SendouQ matches together with the two groups playing them: a match is
- * only ever made out of two full groups, the way the matchmaking UI makes one, so
- * the groups are not the caller's to bring. Both are returned with the match.
- */
+/** Creates the two full groups with the match, like the matchmaking UI does. Both are returned with the match. */
 export const { create } = defineFactory({
 	defaults: () => ({
 		mapList: SplatoonFaker.mapList(SENDOUQ_BEST_OF).map((map) => ({
@@ -139,8 +131,7 @@ function memberTiers(userIds: number[]) {
 	return userIds.map((userId) => ({ userId, tier: SEEDED_TIER }));
 }
 
-/** Concluding stamps the skill rows *now*; move them to when the match was played
- * so the season progression chart spreads over days. */
+/** Concluding stamps skill rows *now*; backdating spreads the season progression chart over days. */
 async function backdateSkills(matchId: number, createdAt: Date) {
 	const skills = await db
 		.selectFrom("Skill")
diff --git a/app/db/seed/factories/SQReadyCheckFactory.ts b/app/db/seed/factories/SQReadyCheckFactory.ts
index ba973053e..127f946ad 100644
--- a/app/db/seed/factories/SQReadyCheckFactory.ts
+++ b/app/db/seed/factories/SQReadyCheckFactory.ts
@@ -8,11 +8,7 @@ type Options = {
 	confirmedByUserIds?: number[];
 };
 
-/**
- * Creates the ready check two matched up groups go through before their match is
- * created. Both groups have to be active, since a ready check is what takes them
- * out of the looking pool.
- */
+/** Both groups have to be active, since a ready check is what takes them out of the looking pool. */
 export const { create } = defineFactory({
 	insert: (args: InsertArgs) => SQGroupRepository.insertReadyCheck(args),
 	applyOptions: async (readyCheck, { confirmedByUserIds }: Options) => {
diff --git a/app/db/seed/factories/SQReportedWeaponFactory.ts b/app/db/seed/factories/SQReportedWeaponFactory.ts
index d830c5afe..2c5866c10 100644
--- a/app/db/seed/factories/SQReportedWeaponFactory.ts
+++ b/app/db/seed/factories/SQReportedWeaponFactory.ts
@@ -7,13 +7,7 @@ type InsertArgs = Parameters<typeof ReportedWeaponRepository.upsertOwn>[0] & {
 	userId: number;
 };
 
-/**
- * Creates the weapons a SendouQ match's players report having used. `userId` is the
- * player whose weapon it was, on whose behalf it is reported.
- *
- * `mapIndex` is not defaulted: it is what identifies the row, so a second weapon
- * without one would replace the first rather than add to it.
- */
+/** `userId` is whose weapon it was. `mapIndex` identifies the row so it is not defaulted, or a second weapon would replace the first. */
 export const { createMany } = defineFactory({
 	defaults: () => ({
 		weaponSplId: SplatoonFaker.mainWeapon(),
diff --git a/app/db/seed/factories/SavedCalendarEventFactory.ts b/app/db/seed/factories/SavedCalendarEventFactory.ts
index a965437f0..5948f5566 100644
--- a/app/db/seed/factories/SavedCalendarEventFactory.ts
+++ b/app/db/seed/factories/SavedCalendarEventFactory.ts
@@ -8,10 +8,7 @@ type InsertArgs = {
 	tournamentId: number;
 };
 
-/**
- * Saves a tournament for a user, the way the star on its page does. Only a
- * tournament can be saved, a calendar event without one having nothing to save.
- */
+/** Like the star on a tournament page. Only tournaments can be saved. */
 export const { create } = defineFactory({
 	insert: async ({ userId, tournamentId }: InsertArgs) => {
 		await actAs(userId, () =>
diff --git a/app/db/seed/factories/ScrimPostFactory.ts b/app/db/seed/factories/ScrimPostFactory.ts
index ed99662c4..ba03e38ff 100644
--- a/app/db/seed/factories/ScrimPostFactory.ts
+++ b/app/db/seed/factories/ScrimPostFactory.ts
@@ -8,8 +8,7 @@ type InsertRequestArgs = Parameters<
 
 type Request = Pick<InsertRequestArgs, "users"> &
 	Partial<Pick<InsertRequestArgs, "startsAt">> & {
-		/** Books the scrim, the way accepting a request does in production. Only one
-		 * request of a post may be accepted. */
+		/** Books the scrim. Only one request of a post may be accepted. */
 		isAccepted?: boolean;
 	};
 
@@ -18,10 +17,7 @@ type Options = {
 	requests?: Array<Request>;
 };
 
-/**
- * Creates scrim posts. `users` is the side offering the scrim, one of them its owner.
- * The requests made to the post, and which of them booked it, are `options`.
- */
+/** `users` is the side offering the scrim, one of them its owner. Requests to the post are `options`. */
 export const { create } = defineFactory({
 	defaults: () => ({
 		startsAt: databaseTimestampNow(),
diff --git a/app/db/seed/factories/SkillFactory.ts b/app/db/seed/factories/SkillFactory.ts
index 34a1681ee..d3432c0a7 100644
--- a/app/db/seed/factories/SkillFactory.ts
+++ b/app/db/seed/factories/SkillFactory.ts
@@ -8,17 +8,12 @@ type Options = {
 	matchesCount: number;
 };
 
-/**
- * Creates a user's starting skill of a season. `mu` is the rating the ordinal every
- * ranking reads is derived from, so a user given a higher `mu` than another ranks
- * above them.
- */
+/** Starting skill of a season. Rankings read the ordinal derived from `mu`, so a higher `mu` ranks higher. */
 export const { create, createMany } = defineFactory({
 	defaults: () => ({ season: 1, ...rating() }),
 	insert: SkillRepository.addInitialSkill,
 	applyOptions: async (skill, { matchesCount }: Options) => {
-		// written directly because production only raises `matchesCount` while reporting
-		// a SendouQ match or finalizing a tournament, and a starting skill has neither
+		// written directly: production only raises `matchesCount` when reporting a match or finalizing a tournament
 		await db
 			.updateTable("Skill")
 			.set({ matchesCount })
diff --git a/app/db/seed/factories/SplatoonRotationFactory.ts b/app/db/seed/factories/SplatoonRotationFactory.ts
index 4fe8e3cf4..2aea4d09e 100644
--- a/app/db/seed/factories/SplatoonRotationFactory.ts
+++ b/app/db/seed/factories/SplatoonRotationFactory.ts
@@ -10,10 +10,7 @@ const ROTATION_TYPES = ["SERIES", "OPEN", "X"] as const;
 const ROTATIONS_PER_TYPE = 12;
 const TWO_HOURS = 2 * 60 * 60;
 
-/**
- * Replaces the Splatoon rotations with a schedule starting from the current
- * two-hour slot, the same write the rotation sync routine does.
- */
+/** Schedule starting from the current two-hour slot, same write as the rotation sync routine. */
 export function replaceAll() {
 	const nowUnix = Math.floor(Date.now() / 1000);
 	const currentSlotStartsAt = nowUnix - (nowUnix % TWO_HOURS);
diff --git a/app/db/seed/factories/TeamFactory.ts b/app/db/seed/factories/TeamFactory.ts
index ff7d02318..039e64174 100644
--- a/app/db/seed/factories/TeamFactory.ts
+++ b/app/db/seed/factories/TeamFactory.ts
@@ -25,12 +25,7 @@ type Options = {
 	roles?: Record<number, MemberRole>;
 };
 
-/**
- * Creates teams. The first of `memberUserIds` is the owner, whose membership the
- * repository creates with the team; the rest join it the way they do in production,
- * within the team count a non-patron is allowed. Custom url and invite code are the
- * repository's own, the custom url following from the name.
- */
+/** First of `memberUserIds` is the owner, the rest join like in production (within the non-patron team limit). */
 export const { create } = defineFactory({
 	defaults: ({ seq }) => ({
 		name: `Team ${seq}`,
@@ -88,8 +83,7 @@ export const { create } = defineFactory({
 			{ isValidated: true },
 		);
 
-		// the team edit page saves the whole profile at once; everything besides the
-		// name is still empty on a team the repository has only just inserted
+		// the team edit page saves the whole profile at once; the rest is still empty on a fresh insert
 		await TeamRepository.update({
 			id: team.id,
 			name: team.name,
diff --git a/app/db/seed/factories/TournamentFactory.ts b/app/db/seed/factories/TournamentFactory.ts
index 1c2a639e8..48cbff734 100644
--- a/app/db/seed/factories/TournamentFactory.ts
+++ b/app/db/seed/factories/TournamentFactory.ts
@@ -33,9 +33,7 @@ const SINGLE_ELIMINATION: TournamentSettings["bracketProgression"] = [
 	},
 ];
 
-/** Every round of a bracket the factory starts is played on these, unless the
- * caller passes a `maps` option. A bracket can not be created without a map list,
- * and picking one is the organizer's job. */
+/** Default maps of every round the factory starts; a bracket can't be created without a map list. */
 const ROUND_MAPS = {
 	count: 3,
 	type: "BEST_OF",
@@ -61,17 +59,10 @@ type Options = {
 	isLeague?: boolean;
 };
 
-/** Brackets to play out fully: one by its idx in the progression, several, or
- * `"all"` for every bracket followed by finalizing the tournament. */
+/** Bracket idx(s) in the progression, or `"all"` = every bracket then finalize. */
 type PlayedBrackets = number | number[] | "all";
 
-/**
- * Creates tournaments. Aggregate factory: the `CalendarEvent` wrapping the
- * tournament and its start date are created with it, because there is no such thing
- * as a tournament without one. Returns both ids.
- *
- * The bracket is a single elimination one unless `bracketProgression` says otherwise.
- */
+/** Creates the wrapping `CalendarEvent` too and returns both ids. Single elimination unless `bracketProgression` says otherwise. */
 export const { create } = defineFactory({
 	defaults: () => ({
 		...eventDefaults(),
@@ -110,13 +101,8 @@ export const { create } = defineFactory({
 });
 
 /**
- * Creates a tournament that has been played. Every entry of `teamRosters` registers
- * as a team owned by the first of its users and checks in, and the brackets
- * `playedOut` names are played out off that seeding — the first bracket when not
- * given, `"all"` for the whole tournament played and finalized.
- *
- * Returns the teams and the matches played alongside the tournament, so that a
- * test can carry on from wherever `playedOut` left the tournament.
+ * Each `teamRosters` entry registers (owned by its first user) and checks in; the brackets `playedOut`
+ * names (default: the first) are played out off that seeding. Returns the teams and matches played.
  */
 export async function createPlayed(
 	overrides: Parameters<typeof create>[0],
@@ -149,13 +135,8 @@ export async function createPlayed(
 }
 
 /**
- * Plays brackets out fully, in the order given: each is started and every match of
- * it played. `"all"` plays every bracket of the progression and then finalizes the
- * tournament the same way the organizer's finalize button does: results on
- * profiles, the tournament's badges awarded to its winning team, skills and
- * leaderboard entries.
- *
- * Returns the matches played, in play order.
+ * Starts and plays every match of each bracket in order. `"all"` also finalizes like the organizer's
+ * button does (results, badges, skills, leaderboard). Returns the matches in play order.
  */
 export async function playOut(
 	tournamentId: number,
@@ -191,14 +172,8 @@ export async function playOut(
 }
 
 /**
- * Starts one of the tournament's brackets, seeded by the teams that are in it —
- * the same teams the organizer would see offered on the bracket page. Every round
- * is played on `maps`, or the factory's default SZ Bo3 list.
- *
- * Later brackets of a progression are started by calling this again once the
- * matches they source their teams from have been played.
- *
- * Returns the matches the bracket was created with, in the generator's own order.
+ * Starts a bracket seeded by the teams in it, every round on `maps` (default SZ Bo3). Later brackets
+ * are started by calling again once their source matches are played. Returns the matches created.
  */
 export async function startBracket(
 	tournamentId: number,
@@ -242,10 +217,7 @@ export async function startBracket(
 	return startedBracket.data.match.map((match) => ({ id: match.id }));
 }
 
-/**
- * Marks a match as casted by a Twitch account, adding the account to the
- * tournament's cast accounts first, the way the organizer's stream page does.
- */
+/** Marks a match casted by a Twitch account, adding the account to the cast accounts first like the stream page does. */
 export async function castMatch({
 	tournamentId,
 	matchId,
@@ -285,13 +257,8 @@ interface PlayedMatch {
 }
 
 /**
- * Plays out every match both of whose teams are known, the higher seeded team
- * winning each map of it. Every map goes through `reportScore`, the same function
- * the match page reports through, so the bracket, the standings and the
- * participation rows end up exactly as they do when the teams play it.
- *
- * One pass only: matches the played ones advance teams into are left for the next
- * call, so a caller can stop after any round. `playOut` plays to the end.
+ * Plays every match with both teams known, the higher seed winning each map through `reportScore` like
+ * the match page. One pass only: matches these advance teams into are left for the next call.
  */
 export async function playMatches(
 	tournamentId: number,
@@ -309,14 +276,7 @@ export async function playMatches(
 	return played;
 }
 
-/**
- * Generates the matches of a swiss bracket's next round, each of its groups the
- * same way the organizer's advance button does. Swiss pairs a round off the
- * standings of the one before it, so the matches of a round only exist once the
- * previous round has been played.
- *
- * Returns whether there was a round left to generate.
- */
+/** Next swiss round per group, like the organizer's advance button. Returns whether a round was left to generate. */
 async function generateNextSwissRound(
 	tournamentId: number,
 	bracketIdx: number,
@@ -361,10 +321,7 @@ async function generateNextSwissRound(
 	return generated;
 }
 
-/** Writes the seeds the bracket was created off, the same way starting a bracket
- * through the site does. Without them the seeds shown are recomputed from the teams'
- * seeding skills every time, so they drift out of sync with the started bracket as
- * soon as those change. */
+/** Without persisted seeds the shown ones are recomputed from seeding skills and drift from the started bracket. */
 async function persistSeeds(
 	tournament: Awaited<ReturnType<typeof tournamentFromDB>>,
 ) {
@@ -501,7 +458,7 @@ async function finalize(tournamentId: number) {
 	});
 }
 
-/** Whose the tournament's prizes are, as the organizer typically assigns them. */
+/** Who the organizer typically assigns the prizes to. */
 function winningTeam(tournament: Awaited<ReturnType<typeof tournamentFromDB>>) {
 	const winner = Standings.flattenStandings(
 		Standings.tournamentStandings(tournament),
diff --git a/app/db/seed/factories/TournamentOrganizationFactory.ts b/app/db/seed/factories/TournamentOrganizationFactory.ts
index d9f11c1eb..35011db98 100644
--- a/app/db/seed/factories/TournamentOrganizationFactory.ts
+++ b/app/db/seed/factories/TournamentOrganizationFactory.ts
@@ -23,10 +23,7 @@ type Options = {
 	avatarFileName?: string;
 };
 
-/**
- * Creates tournament organizations. `ownerId` is who owns it, added as its admin by
- * the repository. Slug follows from the name, as it does in production.
- */
+/** `ownerId` is added as admin by the repository. Slug follows from the name. */
 export const { create, createMany } = defineFactory({
 	defaults: ({ seq }) => ({
 		name: `Organization ${seq}`,
@@ -88,8 +85,7 @@ async function applyUpdate(
 			)
 		: null;
 
-	// the org edit page saves everything at once, so what exists already is read
-	// back and sent along
+	// the org edit page saves everything at once, so existing values are read back and sent along
 	await TournamentOrganizationRepository.update({
 		id: org.id,
 		name: org.name,
diff --git a/app/db/seed/factories/TournamentReportedWeaponFactory.ts b/app/db/seed/factories/TournamentReportedWeaponFactory.ts
index 7a2544e61..a88846605 100644
--- a/app/db/seed/factories/TournamentReportedWeaponFactory.ts
+++ b/app/db/seed/factories/TournamentReportedWeaponFactory.ts
@@ -11,11 +11,8 @@ type InsertArgs = Parameters<
 };
 
 /**
- * Creates the weapons a tournament match's players report having used. `createdAt`
- * is an argument of the write itself: reporting is open long after the games were
- * played, so the app stamps the weapon with the tournament's start instead of now.
- *
- * `mapIndex` is not defaulted, for the same reason it is not in `SQReportedWeaponFactory`.
+ * `createdAt` is an argument of the write itself: reporting stays open long after, so the app stamps the
+ * tournament's start instead of now. `mapIndex` is not defaulted, see `SQReportedWeaponFactory`.
  */
 export const { createMany } = defineFactory({
 	defaults: () => ({
diff --git a/app/db/seed/factories/TournamentTeamFactory.ts b/app/db/seed/factories/TournamentTeamFactory.ts
index 39dd10ae0..ad6ae0717 100644
--- a/app/db/seed/factories/TournamentTeamFactory.ts
+++ b/app/db/seed/factories/TournamentTeamFactory.ts
@@ -31,12 +31,8 @@ type Options = {
 };
 
 /**
- * Creates tournament teams. The first of `memberUserIds` is the owner, on whose
- * behalf the team is registered; the rest are added to it the way they are in
- * production. Invite code and in-game names are the repository's own.
- *
- * A player looking for a team without one to register is a placeholder team
- * instead, see `TournamentLFGTeamFactory`.
+ * Registered by the first of `memberUserIds`, the rest added like in production. A player looking for a
+ * team is a placeholder team instead, see `TournamentLFGTeamFactory`.
  */
 export const { create } = defineFactory({
 	defaults: () => ({
diff --git a/app/db/seed/factories/TrophyFactory.ts b/app/db/seed/factories/TrophyFactory.ts
index 2ef5d79ec..621d39607 100644
--- a/app/db/seed/factories/TrophyFactory.ts
+++ b/app/db/seed/factories/TrophyFactory.ts
@@ -8,12 +8,7 @@ import trophies from "../data/trophies.json" with { type: "json" };
 /** Compressed model states of real trophies, one of which every trophy is given. */
 export const MODELS = Object.values(trophies);
 
-/**
- * Creates trophies. A trophy only comes into existence in production once a
- * submission has gathered its approvals, which `createPending` covers — one that
- * merely has to exist is written directly. Winning one is `TournamentFactory`'s
- * job: a trophy is awarded by finalizing the tournament it was the prize of.
- */
+/** Written directly; `createPending` covers the submission flow. Awarding is `TournamentFactory`'s job (finalizing). */
 export const { create } = defineFactory({
 	defaults: ({ seq }) => ({
 		name: `Trophy ${seq}`,
@@ -38,10 +33,7 @@ type PendingOptions = {
 	declinedBy?: { userId: number; reason: string };
 };
 
-/**
- * Creates trophy submissions awaiting review. The options review the submission the
- * way the review page does, so one can be brought to any point of its life.
- */
+/** Submissions awaiting review; the options review them the way the review page does. */
 export const { create: createPending, createMany: createManyPending } =
 	defineFactory({
 		defaults: ({ seq }) => ({
diff --git a/app/db/seed/factories/UserFactory.ts b/app/db/seed/factories/UserFactory.ts
index 03cdfb0c4..d6753ae71 100644
--- a/app/db/seed/factories/UserFactory.ts
+++ b/app/db/seed/factories/UserFactory.ts
@@ -50,8 +50,7 @@ type Options = {
 	weapons?: Parameters<typeof UserRepository.updateOwnProfile>[0]["weapons"];
 	/** User card fields, submitted as the user themselves. */
 	card?: Partial<CardArgs>;
-	/** Profile page widgets, replacing whatever the user had. Only shown to a user
-	 * who is a supporter and has `newProfileEnabled` in their `preferences`. */
+	/** Replaces the user's widgets. Only shown to a supporter with `newProfileEnabled` in `preferences`. */
 	widgets?: Parameters<typeof UserRepository.upsertWidgets>[1];
 	/** Preferences, merged into the ones the user has, as the settings pages save them. */
 	preferences?: UserPreferences;
@@ -87,8 +86,7 @@ const GRANT_ROLE: Record<Role, (userId: number) => Promise<unknown>> = {
 	API_ACCESSER: AdminRepository.makeApiAccesserByUserId,
 };
 
-/** Creates users. Columns outside `UserRepository.upsert` (patron status, plus tier,
- * match profile) are set by the repository function that owns them. */
+/** Columns outside `UserRepository.upsert` (patron status, plus tier, match profile) are set by their owning repository function. */
 export const { create, createMany } = defineFactory({
 	defaults: ({ seq }) => ({
 		discordId: fakeDiscordId(seq),
@@ -125,9 +123,7 @@ function fakeFriendCode() {
 	return `${faker.string.numeric(4)}-${faker.string.numeric(4)}-${faker.string.numeric(4)}`;
 }
 
-/** A real-looking Discord snowflake: 42 bits of timestamp, `seq` in the low 22.
- * Must stay 10+ characters — `userByIdentifierQuery` resolves shorter numeric
- * identifiers as row ids, which would break `/u/<discordId>` links. */
+/** Snowflake-like: 42 bits of timestamp, `seq` in the low 22. Must stay 10+ chars or `userByIdentifierQuery` reads it as a row id. */
 function fakeDiscordId(seq: number) {
 	const DISCORD_EPOCH_MS = 1420070400000n;
 	const FAKE_CREATED_AT_MS = 1685577600000n; // 2023-06-01
@@ -135,9 +131,7 @@ function fakeDiscordId(seq: number) {
 	return String(((FAKE_CREATED_AT_MS - DISCORD_EPOCH_MS) << 22n) + BigInt(seq));
 }
 
-/** Saves profile fields as the user, for a user that already exists. The profile page
- * submits every field at once, prefilled with what the user has, so the fields the
- * caller leaves out keep their current value instead of being cleared. */
+/** Saves profile fields as the user; like the profile page, fields left out keep their current value. */
 export async function updateProfile(
 	userId: number,
 	profile: Partial<ProfileArgs>,
@@ -187,8 +181,7 @@ async function currentProfile(userId: number): Promise<ProfileArgs> {
 	};
 }
 
-/** Links the Twitch account to the user, the way logging in with the account
- * connected on Discord does. */
+/** Links the Twitch account the way logging in with it connected on Discord does. */
 export async function linkTwitch(userId: number, twitch: string | null) {
 	const user = await db
 		.selectFrom("User")
@@ -206,8 +199,7 @@ export async function linkTwitch(userId: number, twitch: string | null) {
 	await UserRepository.upsert({ ...user, twitch });
 }
 
-/** Pronouns as the profile page saves them: the subject and object forms as one
- * JSON object, not the `he/him` string they are displayed as. */
+/** Subject and object forms as one JSON object, as the profile page saves them. */
 export function fakePronouns() {
 	return JSON.stringify(
 		faker.helpers.arrayElement([
@@ -218,8 +210,7 @@ export function fakePronouns() {
 	);
 }
 
-/** Country biased the way the player base is: US and the big European scenes
- * first, anything possible. */
+/** Biased like the player base: US and big European scenes first, anything possible. */
 export function fakeCountry() {
 	return faker.helpers.weightedArrayElement([
 		{ value: "US", weight: 30 },
@@ -262,23 +253,15 @@ function fakeProfile(): Partial<ProfileArgs> | null {
 	};
 }
 
-/**
- * Creates the admin user, on the id the app's permission logic treats as an admin.
- * Also who `wrappedAction({ user: "admin" })` submits as.
- *
- * Has to be created before any other user, see {@link pinUserId}.
- */
+/** The admin id user, who `wrappedAction({ user: "admin" })` submits as. Create before any other user, see {@link pinUserId}. */
 export const createAdmin = (
 	overrides?: Partial<UpsertArgs> | null,
 	options?: Options,
 ) => createPinned(ADMIN_ID, overrides, options);
 
 /**
- * Creates the user that `wrappedAction({ user: "regular" })` submits as. Has no
- * permissions of any kind unless `options` gives it some; use for the "somebody
- * else" side of a permission test.
- *
- * Has to be created before any user without a pinned id, see {@link pinUserId}.
+ * Who `wrappedAction({ user: "regular" })` submits as; no permissions unless `options` gives some.
+ * Create before any user without a pinned id, see {@link pinUserId}.
  */
 export const createRegular = (
 	overrides?: Partial<UpsertArgs> | null,
@@ -291,8 +274,7 @@ export const createOrgAdmin = (
 	options?: Options,
 ) => createPinned(ORG_ADMIN_TEST_ID, overrides, options);
 
-/** Creates the user on the id the app's permission logic treats as staff. Create
- * after every unpinned user, so the ids in between stay free. */
+/** The staff id user. Create after every unpinned user so the ids in between stay free. */
 export const createStaff = (
 	overrides?: Partial<UpsertArgs> | null,
 	options?: Options,
@@ -332,18 +314,8 @@ async function createPinned(
 }
 
 /**
- * A set of interchangeable users referred to by the order they were created in.
- * For tests needing more users than it makes sense to give names to; prefer
- * destructuring `createMany` into named users when there are only a few.
- *
- * @example
- * const users = UserFactory.pool();
- *
- * beforeEach(async () => {
- *   await users.create(20);
- * });
- *
- * test("notifies both", () => notify({ userIds: [users.id(1), users.id(2)] }));
+ * Interchangeable users referred to by creation order, for tests needing more users than it makes
+ * sense to name. Declare at module scope, fill in `beforeEach` with `users.create(20)`, read with `users.id(1)`.
  */
 export function pool() {
 	let created: Array<{ id: number }> = [];
@@ -372,11 +344,7 @@ export function pool() {
 	};
 }
 
-/**
- * What `create`'s second argument does, applied to a user that already exists — for
- * the tests whose users come from shared setup, or that want two of them given
- * different things.
- */
+/** `create`'s second argument applied to an existing user. */
 export async function grant(
 	userId: number,
 	{
@@ -434,8 +402,7 @@ export async function grant(
 	}
 
 	if (weapons) {
-		// the profile page saves every field at once; everything besides the weapons
-		// is still empty on a user the repository has only just upserted
+		// the profile page saves every field at once; the rest is still empty on a fresh upsert
 		await actAs(userId, () => UserRepository.updateOwnProfile({ weapons }));
 	}
 
@@ -453,8 +420,7 @@ export async function grant(
 }
 
 async function setPlusTier(userId: number, plusTier: number) {
-	// `replacePlusTiers` replaces every row, being the monthly recount of who is in
-	// what tier, so the tiers granted before this one are read back and sent along
+	// `replacePlusTiers` replaces every row (monthly recount), so earlier grants are read back and sent along
 	const others = await db
 		.selectFrom("PlusTier")
 		.select(["userId", "tier"])
diff --git a/app/db/seed/factories/VodFactory.ts b/app/db/seed/factories/VodFactory.ts
index 36e6fbaf9..f32890791 100644
--- a/app/db/seed/factories/VodFactory.ts
+++ b/app/db/seed/factories/VodFactory.ts
@@ -5,12 +5,7 @@ import * as SplatoonFaker from "../core/SplatoonFaker";
 
 const PUBLISHED_ON = { day: 1, month: 0, year: 2024 };
 
-/**
- * Creates vods. `submitterUserId` is who added it, `pov` whose point of view it is
- * from — a user, a plain name, or nobody at all for a cast. Defaults to one match on
- * a random map, the match and player rows every vod listing is read through being
- * what the repository derives from `matches`.
- */
+/** `pov` is a user, a plain name, or nobody for a cast. The repository derives the match and player rows from `matches`. */
 export const { create, createMany } = defineFactory({
 	defaults: ({ seq }) => ({
 		title: faker.lorem.words(3),
diff --git a/app/db/seed/factories/XRankPlacementFactory.ts b/app/db/seed/factories/XRankPlacementFactory.ts
index 4c2d2ca43..cd8070cf5 100644
--- a/app/db/seed/factories/XRankPlacementFactory.ts
+++ b/app/db/seed/factories/XRankPlacementFactory.ts
@@ -10,24 +10,18 @@ type InsertArgs = Omit<
 	XRankPlacementRepository.XRankPlacementInsertArgs,
 	"playerSplId"
 > & {
-	/** Defaults to one derived from `playerUserId`, for a player who only ever
-	 * appears as that user. */
+	/** Defaults to one derived from `playerUserId`. */
 	playerSplId?: string;
 };
 
 type Options = {
-	/** Derive `SplatoonPlayer.peakXp` from the placements, as the import does once
-	 * it has added a month's worth of them. */
+	/** Derive `SplatoonPlayer.peakXp` from the placements, as the import does after a month's worth. */
 	refreshPeakXp?: boolean;
 };
 
 /**
- * Creates X Rank placements. `playerSplId` is the in-game id of the player who
- * placed — the repository creates their `SplatoonPlayer` row if the id is new, so
- * repeating an id places the same player again. `playerUserId` is the site user
- * whose results they are, and stands in for the in-game id when none is given.
- *
- * Rank counts up, since a month's leaderboard has no two players at the same rank.
+ * Repeating a `playerSplId` places the same `SplatoonPlayer` again; `playerUserId` stands in for it when
+ * not given. Rank counts up since a month's leaderboard has no ties.
  */
 export const { create } = defineFactory({
 	defaults: ({ seq }) => ({
diff --git a/app/db/sql.ts b/app/db/sql.ts
index 1268e6179..9df06421f 100644
--- a/app/db/sql.ts
+++ b/app/db/sql.ts
@@ -21,24 +21,18 @@ if (ServerConfig.isTest) {
 }
 
 sql.exec("PRAGMA journal_mode = WAL");
-// In WAL mode synchronous=NORMAL only risks durability across a power loss,
-// transactions stay atomic, consistent and isolated
-// Source: https://sqlite.org/pragma.html
+// in WAL mode NORMAL only risks durability across a power loss (https://sqlite.org/pragma.html)
 sql.exec("PRAGMA synchronous = NORMAL");
 sql.exec("PRAGMA foreign_keys = ON");
 sql.exec("PRAGMA busy_timeout = 5000");
 // 64MB page cache (default is 2MB)
 sql.exec("PRAGMA cache_size = -65536");
-// lets reads come straight from the OS page cache without read() syscalls
-// Source: https://sqlite.org/mmap.html
+// reads straight from the OS page cache without read() syscalls (https://sqlite.org/mmap.html)
 sql.exec("PRAGMA mmap_size = 3221225472");
-// see https://sqlite.org/pragma.html#pragma_optimize — recommended for long-lived
-// connections; pair with a periodic `PRAGMA optimize;` (see OptimizeDatabase routine)
+// https://sqlite.org/pragma.html#pragma_optimize, paired with the periodic OptimizeDatabase routine
 sql.exec("PRAGMA optimize = 0x10002");
 
-// Strips diacritics so accent-insensitive name searches are possible
-// (e.g. "cafe" matches "Café"). Combined with LIKE's built-in ASCII
-// case-insensitivity this also folds case for the resulting latin letters.
+// strips diacritics ("cafe" matches "Café"); with LIKE's ASCII case-insensitivity this also folds case
 sql.function("unaccent", { deterministic: true }, (value) =>
 	typeof value === "string"
 		? value.normalize("NFD").replace(/\p{M}/gu, "")
@@ -56,11 +50,8 @@ export const db = new Kysely<DB>({
 	plugins: [new EmptyValuesNoopPlugin(), new WriteTrackerPlugin()],
 });
 
-// Every test worker gets its own in-memory database, built by replaying the
-// schema of the migrated (and otherwise empty) file that scripts/ensure-test-db.ts
-// creates in vitest's globalSetup. Replaying the DDL rather than copying the file
-// is what `node:sqlite` allows: unlike better-sqlite3 it cannot deserialize a
-// database into memory.
+// each test worker gets an in-memory db built by replaying the DDL of the migrated empty file from
+// scripts/ensure-test-db.ts; unlike better-sqlite3, `node:sqlite` can't deserialize a db into memory
 function applyMigratedSchema(target: DatabaseSync) {
 	const source = new DatabaseSync("db-test.sqlite3", {
 		readOnly: true,
@@ -68,8 +59,7 @@ function applyMigratedSchema(target: DatabaseSync) {
 	});
 
 	try {
-		// virtual tables create their own shadow tables (e.g. UserSearch_data), so
-		// replaying those would fail on a table that already exists
+		// virtual tables create their own shadow tables (e.g. UserSearch_data)
 		const statements = source
 			.prepare(`
 				SELECT sql FROM sqlite_master m
@@ -106,8 +96,6 @@ function logQuery(event: LogEvent) {
 	if (event.level === "query" && isSelectQuery) {
 		const from = () =>
 			(event.query.query as any).from.froms.map(
-				// plain tables have the name under table, aliased tables and
-				// subqueries under alias
 				(f: any) => f.table?.identifier?.name ?? f.alias?.name ?? "unknown",
 			);
 		// biome-ignore lint/suspicious/noConsole: dev only
@@ -129,8 +117,7 @@ function logQuery(event: LogEvent) {
 function logError(event: LogEvent) {
 	if (
 		event.level === "error" &&
-		// an error inside a transaction rolls it back implicitly, so kysely's explicit
-		// rollback then fails -> skip that follow-up error to avoid a double log
+		// an error inside a transaction rolls it back implicitly, so kysely's explicit rollback fails after
 		!(event.error as any).message.includes("no transaction is active")
 	) {
 		logger.error(event.error);
diff --git a/app/db/tables-json.ts b/app/db/tables-json.ts
index 41d711083..2afca6f6b 100644
--- a/app/db/tables-json.ts
+++ b/app/db/tables-json.ts
@@ -1,9 +1,4 @@
-/**
- * Shapes of JSON column payloads that have no natural feature home. Kept apart from
- * `tables.ts` so that what is declared there stays close to the `DB` interface. Payloads
- * that do belong to a feature (e.g. `StoredWidget`, `Notification`) live with that feature
- * and are imported by `tables.ts` directly.
- */
+/** JSON column payload shapes with no natural feature home; feature-owned ones (e.g. `StoredWidget`) live with their feature. */
 
 import type { DBBoolean } from "~/db/tables";
 import type { CalendarFilters } from "~/features/calendar/calendar-types";
@@ -54,17 +49,11 @@ export interface UserPreferences {
 	disallowScrimPickupsFromUntrusted?: boolean;
 	defaultCalendarFilters?: CalendarFilters;
 	defaultScrimsFilters?: ScrimFilters;
-	/**
-	 * What time format the user prefers?
-	 *
-	 * "auto" = use browser default (default value)
-	 * "24h" = 24 hour format (e.g. 14:00)
-	 * "12h" = 12 hour format (e.g. 2:00 PM)
-	 * */
+	/** "auto" (default) = browser default */
 	clockFormat?: "24h" | "12h" | "auto";
-	/** Is the new widget based user page enabled? (Supporter early preview) */
+	/** Widget based user page (supporter early preview) */
 	newProfileEnabled?: boolean;
-	/** Is spoiler-free mode enabled? Hides recent tournament results and scores until the user chooses to reveal them. */
+	/** Hides recent tournament results and scores until revealed */
 	spoilerFreeMode?: boolean;
 	weaponReportDefaultOpen?: boolean;
 	/** Start of the week the schedule sidebar nudge was last dismissed for, so it stays gone until the horizon rolls over. */
@@ -77,11 +66,8 @@ export type Pronouns = {
 };
 
 export interface PeakXP {
-	/** Peak XP across all divisions */
 	overall: number;
-	/** Peak XP (Takoroka division) */
 	takoroka: number | null;
-	/** Peak XP (Tentatek division) */
 	tentatek: number | null;
 }
 
@@ -117,9 +103,8 @@ export interface TournamentSettings {
 }
 
 export interface CastedMatchesInfo {
-	/** Array for matches that are locked because they are pending to be casted */
+	/** Matches locked because they are pending to be casted */
 	lockedMatches: Array<{ twitchAccount: string; matchId: number }>;
-	/** What matches are streamed currently & where */
 	castedMatches: { twitchAccount: string; matchId: number }[];
 	castedMatchHistory?: Array<{
 		twitchAccount: string;
@@ -185,10 +170,7 @@ export interface TournamentAuditLogMetadata {
 	tournamentName?: string | null;
 }
 
-/**
- * The result of sets in the tournament.
- * E.g. ["W", "L", null] would mean the user won the first set, lost the second and did not play the third.
- * */
+/** E.g. ["W", "L", null] = won the first set, lost the second, did not play the third. */
 export type WinLossParticipationArray = Array<"W" | "L" | null>;
 
 export interface NotificationSubscription {
diff --git a/app/db/tables.ts b/app/db/tables.ts
index 30f4a6bf7..9a213239c 100644
--- a/app/db/tables.ts
+++ b/app/db/tables.ts
@@ -98,7 +98,7 @@ export interface Team {
 	name: string;
 	bsky: string | null;
 	mapModePreferences: JSONColumnTypeNullable<UserMapModePreferences>;
-	/** Team's tag, typically used in-game in front of users' names to indicate they are a member of the team. */
+	/** Shown in-game in front of members' names */
 	tag: string | null;
 }
 
@@ -679,18 +679,10 @@ export interface TournamentBadgeOwner {
 	count: Generated<number>;
 }
 
-/** A group is a logical structure used to group multiple rounds together.
-
-- In round-robin stages, a group is a pool.
-- In swiss, a group is also a pool (can have one or multiple groups)
-- In elimination stages, a group is a bracket.
-    - A single elimination stage can have one or two groups:
-      - The unique bracket.
-      - If enabled, the Consolation Final.
-    - A double elimination stage can have two or three groups:
-      - Upper and lower brackets.
-      - If enabled, the Grand Final.
-*/
+/**
+ * Groups rounds together. In round-robin and swiss a group is a pool; in elimination it is a bracket
+ * (single: the bracket + optional consolation final, double: upper, lower + optional grand final).
+ */
 export interface TournamentGroup {
 	id: GeneratedAlways<number>;
 	number: number;
@@ -749,23 +741,14 @@ export interface TournamentResult {
 	placement: number;
 	tournamentId: number;
 	tournamentTeamId: number;
-	/**
-	 * The result of sets in the tournament.
-	 * E.g. ["W", "L", null] would mean the user won the first set, lost the second and did not play the third.
-	 * */
+	/** E.g. ["W", "L", null] = won the first set, lost the second, did not play the third. */
 	setResults: JSONColumnType<WinLossParticipationArray>;
 	userId: number;
 	/** Division label for tournaments with multiple starting brackets (e.g., "D1", "D2") */
 	div: string | null;
 }
 
-/**
- * A round is a logical structure used to group multiple matches together.
-
-  - In round-robin stages, a round can be viewed as a list of matches that can be played at the same time.
-  - In swiss, a round is a list of matches that are played at the same time.
-  - In elimination stages, a round is a round of a bracket, e.g. 8th finals, semi-finals, etc.
- */
+/** Groups matches played at the same time (round-robin, swiss) or one round of a bracket (elimination). */
 export interface TournamentRound {
 	groupId: number;
 	id: GeneratedAlways<number>;
@@ -861,7 +844,6 @@ export interface TournamentAuditLog {
 	id: GeneratedAlways<number>;
 	tournamentId: number;
 	type: TournamentAuditLogType;
-	/** The user who performed the action. */
 	actorUserId: number;
 	/** The affected member, for member-level events. `null` for team-level events. */
 	subjectUserId: number | null;
@@ -1014,10 +996,10 @@ export interface User {
 	noScreen: Generated<DBBoolean>;
 	buildSorting: JSONColumnTypeNullable<BuildSort[]>;
 	preferences: JSONColumnTypeNullable<UserPreferences>;
-	/** User creation date. Can be null because we did not always save this. */
+	/** Can be null because we did not always save this. */
 	createdAt: number | null;
 	joinOrder: number | null;
-	/** User card banner default selection, stored as raw text (not JSON): either a hex code (e.g. "#8b0000") or a stage id in string form (e.g. "16"). Note: supporters can also upload banner (stored in UserSubmittedImage, referenced by `bannerImgId` which takes precedence) */
+	/** User card banner preset, raw text (not JSON): a hex code ("#8b0000") or a stage id ("16"). `bannerImgId` takes precedence. */
 	bannerPresetImg: string | null;
 	/** Supporter-uploaded user card banner (UserSubmittedImage id). Takes precedence over `bannerPresetImg`. */
 	bannerImgId: number | null;
@@ -1208,7 +1190,6 @@ export interface XRankPlacement {
 
 export interface ScrimPost {
 	id: GeneratedAlways<number>;
-	/** When is the scrim scheduled to happen */
 	startsAt: number;
 	/** Optional end of time range indicating team accepts scrims starting between startsAt and rangeEndsAt */
 	rangeEndsAt: number | null;
@@ -1216,20 +1197,14 @@ export interface ScrimPost {
 	maxDiv: number | null;
 	/** Lowest LUTI div accepted */
 	minDiv: number | null;
-	/** Who sees the post */
 	visibility: JSONColumnTypeNullable<AssociationVisibility>;
-	/** Any additional info */
 	text: string | null;
 	chatRoomId: number | null;
 	/** Refers to the team looking for the team (can also be a pick-up) */
 	teamId: number | null;
-	/** Indicates if anyone in the post can manage it */
 	managedByAnyone: DBBoolean;
-	/** When the scrim was canceled */
 	canceledAt: number | null;
-	/** User id who canceled the scrim */
 	canceledByUserId: number | null;
-	/** Reason for canceling the scrim */
 	cancelReason: string | null;
 	/** When the post was made was it scheduled for a future time slot (as opposed to looking now) */
 	isScheduledForFuture: Generated<DBBoolean>;
@@ -1265,13 +1240,11 @@ export interface ScrimMap {
 export interface ScrimPostUser {
 	scrimPostId: number;
 	userId: number;
-	/** User is the author of the post */
 	isOwner: DBBoolean;
 }
 
 export interface ScrimPickupRoster {
 	id: GeneratedAlways<number>;
-	/** User who used the pick-up roster */
 	userId: number;
 	/** When the roster was last used to make a scrim post */
 	usedAt: Generated<number>;
@@ -1296,7 +1269,6 @@ export interface ScrimPostRequest {
 
 export interface ScrimPostRequestUser {
 	scrimPostRequestId: number;
-	/** User that made the request */
 	userId: number;
 	isOwner: DBBoolean;
 }
@@ -1394,16 +1366,9 @@ export type Tables = { [P in keyof DB]: Selectable<DB[P]> };
 export type TablesInsertable = { [P in keyof DB]: Insertable<DB[P]> };
 
 /**
- * Every table and view available to query.
- *
- * Some entries are SQL **views**, not tables. They are marked below and can not
- * be inserted into or updated. Two naming conventions exist for the
- * table/view pairing, both meaning "base table vs. filtered view":
- * - `All` prefix on the table: `AllTeam` (table) / `Team` (view)
- * - `Unvalidated` prefix on the table: `UnvalidatedVideo` (table) / `Video` (view)
- *
- * In both cases write to the prefixed table and read from the unprefixed view
- * unless you specifically want the filtered-out rows.
+ * Every table and view. Views (marked below) are read-only. Base table / filtered view pairs use an
+ * `All` or `Unvalidated` prefix on the table (`AllTeam`/`Team`, `UnvalidatedVideo`/`Video`): write to
+ * the prefixed table, read from the view unless you want the filtered-out rows.
  */
 export interface DB {
 	/** Table backing the `Team` view. Includes soft-deleted teams. */
diff --git a/app/db/wipe.ts b/app/db/wipe.ts
index 1a45b618a..e599113f9 100644
--- a/app/db/wipe.ts
+++ b/app/db/wipe.ts
@@ -1,13 +1,9 @@
 import { sql } from "kysely";
 import { db } from "~/db/sql";
 
-/**
- * Deletes every row of every table, leaving the schema (and the kysely
- * migration bookkeeping tables) in place.
- */
+/** Deletes every row of every table, leaving the schema and migration bookkeeping in place. */
 export async function deleteAllRows() {
-	// virtual tables and their shadow tables (e.g. UserSearch_data) can not be
-	// deleted from directly; the fts index stays in sync via the User triggers
+	// virtual tables and their shadow tables (e.g. UserSearch_data) can't be deleted from; the User triggers keep the fts index in sync
 	const { rows: tables } = await sql<{ name: string }>`
 		SELECT name FROM sqlite_master
 		WHERE type='table'
diff --git a/app/db/write-tracker.ts b/app/db/write-tracker.ts
index ff06b6ab1..8114faa17 100644
--- a/app/db/write-tracker.ts
+++ b/app/db/write-tracker.ts
@@ -9,12 +9,7 @@ import type {
 
 let dirty = false;
 
-/**
- * Records whether anything has been written to the database, so that a caller can
- * react to writes it did not make itself: the vitest teardown wipes only when a
- * test wrote something, and an e2e worker flushes the app server's caches only
- * when its factories wrote something.
- */
+/** Tracks writes so vitest teardown wipes only after a writing test and e2e workers flush caches only after factory writes. */
 export class WriteTrackerPlugin implements KyselyPlugin {
 	transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
 		if (args.node.kind !== "SelectQueryNode") {
diff --git a/app/entry.client.tsx b/app/entry.client.tsx
index 3a9f921f9..e5fa41188 100644
--- a/app/entry.client.tsx
+++ b/app/entry.client.tsx
@@ -9,9 +9,8 @@ import { loadDateFnsLocale } from "./utils/dates";
 import { logger } from "./utils/logger";
 import { getSessionId } from "./utils/session-id";
 
-/** Base delays in milliseconds before each retry attempt following the initial request. */
 const FETCH_RETRY_DELAYS_MS = [0, 5000, 15000];
-/** Random jitter added to each retry delay to avoid a thundering herd against a struggling server. */
+/** avoids a thundering herd against a struggling server */
 const FETCH_RETRY_JITTER_MS = 1000;
 
 writeViewerTimezoneCookie();
@@ -97,13 +96,11 @@ async function fetchWithRetry(
 
 if ("serviceWorker" in navigator) {
 	window.addEventListener("load", () => {
-		// we will register it after the page complete the load
 		void navigator.serviceWorker.register("/sw-2.js");
 	});
 }
 
-// the server rendered with the page language's date-fns locale, so it must be
-// cached before hydration to avoid a markup mismatch
+// the server rendered with the page language's date-fns locale, so cache it before hydration
 Promise.all([
 	i18nLoader(),
 	loadDateFnsLocale(document.documentElement.lang as LanguageCode),
diff --git a/app/entry.server.tsx b/app/entry.server.tsx
index feebadbd5..c6507290f 100644
--- a/app/entry.server.tsx
+++ b/app/entry.server.tsx
@@ -23,7 +23,6 @@ import { loadAllDateFnsLocales } from "./utils/dates";
 import { IS_E2E_TEST_RUN } from "./utils/e2e";
 import { logger } from "./utils/logger";
 
-// Reject/cancel all pending promises after 5 seconds
 export const streamTimeout = 5000;
 
 const dateFnsLocalesLoaded = loadAllDateFnsLocales();
@@ -76,13 +75,11 @@ async function handleRequest(
 			},
 		);
 
-		// Automatically timeout the React renderer after 6 seconds, which ensures
-		// React has enough time to flush down the rejected boundary contents
+		// +1s gives React time to flush the rejected boundary contents
 		setTimeout(abort, streamTimeout + 1000);
 	});
 }
 
-// example from https://github.com/BenMcH/remix-rss/blob/main/app/entry.server.tsx
 declare global {
 	var appStartSignal: undefined | true;
 }
@@ -109,8 +106,7 @@ if (!global.appStartSignal && ServerConfig.isProduction && !IS_E2E_TEST_RUN) {
 		}
 	});
 
-	// 9:00 AM Finnish time on Wednesdays, a quiet hour picked because vacuuming blocks
-	// writes for longer than the 5s busy_timeout
+	// 9:00 AM Finnish time on Wednesdays, a quiet hour since vacuuming blocks writes longer than the 5s busy_timeout
 	cron.schedule(
 		"0 9 * * 3",
 		async () => {
@@ -132,7 +128,7 @@ process.on("unhandledRejection", (reason: string, p: Promise<any>) => {
 	logger.error("Unhandled Rejection at:", p, "reason:", reason);
 });
 
-// wrapper so we get request id shown in the server logs
+// routes through logger so the request id shows in server logs
 export const handleError: HandleErrorFunction = (error) => {
 	logger.error(error);
 };
diff --git a/app/features/admin/AdminRepository.server.test.ts b/app/features/admin/AdminRepository.server.test.ts
index 55eacbdb4..f01f8aadc 100644
--- a/app/features/admin/AdminRepository.server.test.ts
+++ b/app/features/admin/AdminRepository.server.test.ts
@@ -11,8 +11,7 @@ import * as AdminRepository from "./AdminRepository.server";
 
 const users = UserFactory.pool();
 
-// the ban log records who banned by their Discord id, so the tests give the users
-// one they can name
+// the ban log records who banned by their Discord id
 const createUsers = (count: number) =>
 	users.create(count, (index) => ({ discordId: String(index) }));
 
diff --git a/app/features/admin/AdminRepository.server.ts b/app/features/admin/AdminRepository.server.ts
index b663c8fc8..caf6c3c2e 100644
--- a/app/features/admin/AdminRepository.server.ts
+++ b/app/features/admin/AdminRepository.server.ts
@@ -10,12 +10,8 @@ import { dateToDatabaseTimestamp } from "~/utils/dates";
 import invariant from "~/utils/invariant";
 
 /**
- * Migrates user-related data. Takes data from the "old user" and remaps it to the Discord ID of the "new user". Used when user switches their Discord accounts.
- *
- * @param args - An object containing:
- *   - `newUserId`: The ID of the user whose data will be migrated and then deleted.
- *   - `oldUserId`: The ID of the user who will receive the migrated data.
- * @returns A promise that resolves to `null` if the migration succeeds, or an error message if validation fails.
+ * For a user switching Discord accounts: moves the new account's data onto the old user and deletes
+ * the new one. Resolves to `null` on success, or an error message if validation fails.
  */
 export function migrate(args: { newUserId: number; oldUserId: number }) {
 	return db.transaction().execute(async (trx) => {
@@ -24,11 +20,8 @@ export function migrate(args: { newUserId: number; oldUserId: number }) {
 			return error;
 		}
 
-		// delete some limited data from the target user
-		// idea is to make the migration a bit more smooth
-		// since it won't fail if some small thing has been added
-		// but for bigger things (e.g. has played tournaments)
-		// it will still fail
+		// small data on the new account is dropped so it doesn't block the migration;
+		// bigger things (e.g. played tournaments) still fail validation
 		await trx
 			.deleteFrom("UserWeapon")
 			.where("userId", "=", args.newUserId)
@@ -126,8 +119,7 @@ export function migrate(args: { newUserId: number; oldUserId: number }) {
 			.set({ userId: args.oldUserId })
 			.execute();
 
-		// If both accounts own the same trophy, drop the
-		// migrated account's duplicate rows
+		// if both accounts own the same trophy, drop the migrated account's duplicate rows
 		await trx
 			.deleteFrom("TrophyOwner")
 			.where("userId", "=", args.newUserId)
@@ -228,10 +220,7 @@ export function migrate(args: { newUserId: number; oldUserId: number }) {
 	});
 }
 
-/**
- * Merging accounts can collide on the one-report-per-pair unique index; the newer
- * report (by `createdAt`, id as tie-breaker) wins and the other row is dropped.
- */
+/** Merging can collide on the one-report-per-pair unique index; the newer report (createdAt, then id) wins. */
 function deleteOlderCollidingUserReports(
 	trx: Transaction<DB>,
 	args: { newUserId: number; oldUserId: number },
@@ -423,7 +412,7 @@ export function banUser({
 	userId: number;
 	banned: 1 | Date;
 	bannedReason: string | null;
-	/** Which user banned the user? If null then it means it was an automatic ban. */
+	/** null means an automatic ban. */
 	bannedByUserId: number | null;
 }) {
 	return db.transaction().execute(async (trx) => {
diff --git a/app/features/admin/ExternalStreamRepository.server.ts b/app/features/admin/ExternalStreamRepository.server.ts
index 05bbc581e..158129c43 100644
--- a/app/features/admin/ExternalStreamRepository.server.ts
+++ b/app/features/admin/ExternalStreamRepository.server.ts
@@ -3,12 +3,10 @@ import type { TablesInsertable } from "~/db/tables";
 import { databaseTimestampNow } from "~/utils/dates";
 import { concatUserSubmittedImagePrefix } from "~/utils/kysely.server";
 
-/** Number of seconds an external stream keeps showing in the sidebar after its start time. */
 const SIDEBAR_VISIBLE_SECONDS = 6 * 60 * 60;
-/** Number of seconds after the start time before an external stream row is deleted. */
 const RETENTION_SECONDS = 24 * 60 * 60;
 
-/** Inserts a new admin-curated external stream. */
+/** Inserts an admin-curated external stream. */
 export function insert(
 	args: Pick<
 		TablesInsertable["ExternalStream"],
@@ -23,7 +21,7 @@ export function deleteById(id: number) {
 	return db.deleteFrom("ExternalStream").where("id", "=", id).execute();
 }
 
-/** Lists all external streams (for the admin management page), soonest start time first. */
+/** All external streams, soonest first. */
 export function findAll() {
 	return db
 		.selectFrom("ExternalStream")
@@ -45,7 +43,7 @@ export function findAll() {
 		.execute();
 }
 
-/** External streams that should currently show in the sidebar (started under 6h ago or upcoming). */
+/** Streams started under 6h ago or upcoming. */
 export function findAllForSidebar() {
 	return db
 		.selectFrom("ExternalStream")
@@ -71,7 +69,7 @@ export function findAllForSidebar() {
 		.execute();
 }
 
-/** Deletes external streams whose start time is more than 24h in the past. */
+/** Deletes streams that started over 24h ago. */
 export function deleteOld() {
 	return db
 		.deleteFrom("ExternalStream")
diff --git a/app/features/admin/core/discord-webhook.server.ts b/app/features/admin/core/discord-webhook.server.ts
index b1ecaeaf2..aeba7a7e6 100644
--- a/app/features/admin/core/discord-webhook.server.ts
+++ b/app/features/admin/core/discord-webhook.server.ts
@@ -6,15 +6,12 @@ import {
 	type WebhookUser,
 } from "~/modules/discord-webhook.server";
 
-/**
- * Posts a rich embed about a user getting banned to the mod channel Discord webhook.
- * Fire-and-forget (see `sendModDiscordWebhook`).
- */
+/** Fire-and-forget embed to the mod channel webhook. */
 export function sendUserBannedWebhook(args: {
 	bannedUser: WebhookUser;
 	bannedBy: WebhookUser;
 	reason: string | null;
-	/** When the ban ends, null when the ban has no end date */
+	/** null = permanent */
 	expiresAt: Date | null;
 }) {
 	sendModDiscordWebhook({
@@ -46,10 +43,7 @@ export function sendUserBannedWebhook(args: {
 	});
 }
 
-/**
- * Posts a rich embed about a user getting unbanned to the mod channel Discord webhook.
- * Fire-and-forget (see `sendModDiscordWebhook`).
- */
+/** Fire-and-forget embed to the mod channel webhook. */
 export function sendUserUnbannedWebhook(args: {
 	unbannedUser: WebhookUser;
 	unbannedBy: WebhookUser;
diff --git a/app/features/admin/core/plus-tier.server.ts b/app/features/admin/core/plus-tier.server.ts
index 3e2628f24..a67bb4eb2 100644
--- a/app/features/admin/core/plus-tier.server.ts
+++ b/app/features/admin/core/plus-tier.server.ts
@@ -33,9 +33,7 @@ async function fromLeaderboard(
 	if (currSeason) {
 		const range = seasonToVotingRange(currSeason);
 
-		// we are in the period of a season where the season's voting
-		// has ended but we don't yet have the latest leaderboard results
-		// -> last season's results are no longer valid
+		// voting has ended but the latest leaderboard isn't in yet, so last season's results are stale
 		if (range.endDate < now) return [];
 	}
 
diff --git a/app/features/admin/routes/admin.test.ts b/app/features/admin/routes/admin.test.ts
index 52cd561e0..0bc3b49d1 100644
--- a/app/features/admin/routes/admin.test.ts
+++ b/app/features/admin/routes/admin.test.ts
@@ -20,8 +20,7 @@ const adminAction = wrappedAction<typeof adminActionSchema>({
 
 const users = UserFactory.pool();
 
-// account migration is asserted through Discord ids, so the tests give the users
-// one they can name
+// account migration is asserted through Discord ids
 const createUsers = (count = 2) =>
 	users.create(count, (index) => ({ discordId: String(index) }));
 
diff --git a/app/features/admin/routes/og-images.module.css b/app/features/admin/routes/og-images.module.css
index b9ef3bb0e..08d95ea42 100644
--- a/app/features/admin/routes/og-images.module.css
+++ b/app/features/admin/routes/og-images.module.css
@@ -28,10 +28,7 @@
 	overflow: hidden;
 }
 
-/*
-The canvas is authored at the real 1200x630 OG image size and only scaled down
-for previewing, so the same styles can render the actual image.
-*/
+/* authored at the real 1200x630 OG size and only scaled down for previewing */
 .canvas {
 	--og-pink: #fd0075;
 	--og-cyan: #01d4ff;
diff --git a/app/features/admin/routes/og-images.tsx b/app/features/admin/routes/og-images.tsx
index bfb1f678e..b3b293eba 100644
--- a/app/features/admin/routes/og-images.tsx
+++ b/app/features/admin/routes/og-images.tsx
@@ -6,14 +6,11 @@ import { Main } from "~/components/Main";
 import { navIconUrl, OG_IMAGE_PAGES, type OgImagePage } from "~/utils/urls";
 import styles from "./og-images.module.css";
 
-// this page is not accessible in production, used to preview per page OG images
+// not accessible in production, previews per page OG images
 
 type IconColor = "pink" | "cyan" | "green";
 
-/**
- * Accent (blobs, sticker shadow, ring) and second accent (top blob) per page,
- * picked to match the two most used ink colors of that page's nav icon.
- */
+/** Accent (blobs, sticker shadow, ring) and second accent (top blob), matching the nav icon's two main ink colors. */
 const PAGE_COLORS: Record<
 	OgImagePage,
 	{ accent: IconColor; second: IconColor }
diff --git a/app/features/api-private/core/refresh-caches.server.ts b/app/features/api-private/core/refresh-caches.server.ts
index 0affc9a25..12fd5e833 100644
--- a/app/features/api-private/core/refresh-caches.server.ts
+++ b/app/features/api-private/core/refresh-caches.server.ts
@@ -11,11 +11,7 @@ import { refreshTentativeTiersCache } from "~/features/tournament-organization/c
 import { clearUserCardCache } from "~/features/user-card/UserCardRepository.server";
 import { cache } from "~/utils/cache.server";
 
-/**
- * Clears and refreshes every in-process cache, so the server serves what is in
- * the database right now. E2E workers call this (via the route) after writing
- * test data straight into the database file.
- */
+/** Clears and refreshes every in-process cache; E2E workers call this (via the route) after writing test data straight into the database file. */
 export async function refreshCaches() {
 	clearAllTournamentDataCache();
 	clearParticipationInfoMap();
diff --git a/app/features/api-public/api-action-wrapper.server.ts b/app/features/api-public/api-action-wrapper.server.ts
index 1d8bb226b..599a55220 100644
--- a/app/features/api-public/api-action-wrapper.server.ts
+++ b/app/features/api-public/api-action-wrapper.server.ts
@@ -1,13 +1,9 @@
 import type { ActionFunction, ActionFunctionArgs } from "react-router";
 
 /**
- * Wraps an existing action function for API use.
- * Converts redirect-based success/error responses to JSON responses.
- *
- * The existing actions use:
- * - `successToast(message)` which returns `redirect("?__success=message")`
- * - `errorToastIfFalsy/errorToastIfErr` which throw `redirect("?__error=message")`
- * - `{ fieldErrors }` returns for form validation failures
+ * Wraps an action for API use, converting its redirect-based responses to JSON: `successToast`
+ * returns `redirect("?__success=message")`, `errorToastIfFalsy/errorToastIfErr` throw
+ * `redirect("?__error=message")`, and validation failures return `{ fieldErrors }`.
  */
 export async function wrapActionForApi(
 	actionFn: ActionFunction,
diff --git a/app/features/api-public/schema.ts b/app/features/api-public/schema.ts
index 998be4aa5..8adb544c4 100644
--- a/app/features/api-public/schema.ts
+++ b/app/features/api-public/schema.ts
@@ -6,25 +6,15 @@ import type { BracketData } from "~/features/tournament-bracket/core/engine/type
 
 export interface GetUserResponse {
 	id: number;
-	/**
-	 * @example "Sendou"
-	 */
+	/** @example "Sendou" */
 	name: string;
-	/**
-	 * @example "79237403620945920"
-	 */
+	/** @example "79237403620945920" */
 	discordId: string;
-	/**
-	 * @example "https://sendou.ink/u/sendou"
-	 */
+	/** @example "https://sendou.ink/u/sendou" */
 	url: string;
-	/**
-	 * @example "https://cdn.discordapp.com/avatars/79237403620945920/6fc41a44b069a0d2152ac06d1e496c6c.png"
-	 */
+	/** @example "https://cdn.discordapp.com/avatars/79237403620945920/6fc41a44b069a0d2152ac06d1e496c6c.png" */
 	avatarUrl: string | null;
-	/**
-	 * @example "FI"
-	 */
+	/** @example "FI" */
 	country: string | null;
 	socials: {
 		twitch: string | null;
@@ -38,17 +28,9 @@ export interface GetUserResponse {
 	badges: Array<Badge>;
 	/** Teams user is member of. The main team is always first in the array. */
 	teams: Array<GlobalTeamMembership>;
-	/**
-	 * Splatoon 3 splashtag name & ID, if one is set.
-	 *
-	 * @example "Sendou#2955"
-	 */
+	/** Splatoon 3 splashtag name & ID, if one is set. @example "Sendou#2955" */
 	inGameName: string | null;
-	/**
-	 * User's pronouns.
-	 *
-	 * @example { "subject": "he", "object": "him" }
-	 */
+	/** User's pronouns. @example { "subject": "he", "object": "him" } */
 	pronouns: Pronouns | null;
 	peakXp: number | null;
 	/** Users current (or previous if it's off-season) ranked season (SendouQ & ranked tournaments) rank. Null if no rank for the season in question or the season does not have yet enough players on the leaderboard. */
@@ -59,13 +41,9 @@ export interface GetUserResponse {
 
 export interface GetUserIdsResponse {
 	id: number;
-	/**
-	 * @example "79237403620945920"
-	 */
+	/** @example "79237403620945920" */
 	discordId: string;
-	/**
-	 * @example "sendou"
-	 */
+	/** @example "sendou" */
 	customUrl: string | null;
 }
 
@@ -73,41 +51,23 @@ export interface GetUserIdsResponse {
 
 export interface GetTeamResponse {
 	id: number;
-	/**
-	 * Name of the global team.
-	 *
-	 * @example "Moonlight"
-	 */
+	/** Name of the global team. @example "Moonlight" */
 	name: string;
-	/**
-	 * URL for the global team page.
-	 *
-	 * @example "https://sendou.ink/t/moonlight"
-	 */
+	/** URL for the global team page. @example "https://sendou.ink/t/moonlight" */
 	teamPageUrl: string;
-	/**
-	 * URL for the global team logo.
-	 *
-	 * @example "https://sendou.nyc3.cdn.digitaloceanspaces.com/pickup-logo-uReSb1b1XS3TWGLCKMDUD-1719054364813.webp"
-	 */
+	/** URL for the global team logo. @example "https://sendou.nyc3.cdn.digitaloceanspaces.com/pickup-logo-uReSb1b1XS3TWGLCKMDUD-1719054364813.webp" */
 	logoUrl: string | null;
 }
 
 /** GET /api/calendar/{year}/{week} */
 
 export type GetCalendarWeekResponse = Array<{
-	/**
-	 * @example "In The Zone 30"
-	 */
+	/** @example "In The Zone 30" */
 	name: string;
 	tournamentId: number | null;
-	/**
-	 * @example "https://sendou.ink/to/9/brackets"
-	 */
+	/** @example "https://sendou.ink/to/9/brackets" */
 	tournamentUrl: string | null;
-	/**
-	 * @example "2024-01-12T20:00:00.000Z"
-	 */
+	/** @example "2024-01-12T20:00:00.000Z" */
 	startTime: string;
 }>;
 
@@ -147,7 +107,7 @@ type SendouqMatchTeam = {
 
 type SendouqMatchPlayer = {
 	userId: number;
-	/** User's at the start time of the match */
+	/** User's rank at the start time of the match */
 	rank: SendouQRank | null;
 };
 
@@ -156,21 +116,13 @@ type SendouQRank = { name: TierName; isPlus: boolean };
 /** GET /api/tournament/{tournamentId} */
 
 export interface GetTournamentResponse {
-	/**
-	 * @example "In The Zone 30"
-	 */
+	/** @example "In The Zone 30" */
 	name: string;
-	/**
-	 * @example "https://sendou.ink/to/9/brackets"
-	 */
+	/** @example "https://sendou.ink/to/9/brackets" */
 	url: string;
-	/**
-	 * @example "https://sendou-assets.nyc3.cdn.digitaloceanspaces.com/img/tournament-logos/itz.avif"
-	 */
+	/** @example "https://sendou-assets.nyc3.cdn.digitaloceanspaces.com/img/tournament-logos/itz.avif" */
 	logoUrl: string | null;
-	/**
-	 * @example "2024-01-12T20:00:00.000Z"
-	 */
+	/** @example "2024-01-12T20:00:00.000Z" */
 	startTime: string;
 	teams: {
 		registeredCount: number;
@@ -186,87 +138,44 @@ export interface GetTournamentResponse {
 
 export type GetTournamentTeamsResponse = Array<{
 	id: number;
-	/**
-	 * @example "Team Olive"
-	 */
+	/** @example "Team Olive" */
 	name: string;
-	/**
-	 * @example "2024-01-12T20:00:00.000Z"
-	 */
+	/** @example "2024-01-12T20:00:00.000Z" */
 	registeredAt: string;
 	checkedIn: boolean;
-	/**
-	 * URL for the tournament team page.
-	 *
-	 * @example "https://sendou.ink/to/9/teams/327"
-	 */
+	/** URL for the tournament team page. @example "https://sendou.ink/to/9/teams/327" */
 	url: string;
-	/**
-	 * URL for the global team page.
-	 *
-	 * @example "https://sendou.ink/t/moonlight"
-	 */
+	/** URL for the global team page. @example "https://sendou.ink/t/moonlight" */
 	teamPageUrl: string | null;
-	/**
-	 * @example "https://sendou.nyc3.cdn.digitaloceanspaces.com/pickup-logo-uReSb1b1XS3TWGLCKMDUD-1719054364813.webp"
-	 */
+	/** @example "https://sendou.nyc3.cdn.digitaloceanspaces.com/pickup-logo-uReSb1b1XS3TWGLCKMDUD-1719054364813.webp" */
 	logoUrl: string | null;
 	seed: number | null;
 	mapPool: Array<StageWithMode> | null;
-	/**
-	 *  Seeding power is a non-resetting MMR value that is used for sendou.ink's autoseeding capabilities.
-	 *  It is calculated as the average of the team's members' seeding power.
-	 *  Ranked and unranked tournaments contribute to different seeding power values.
-	 */
+	/** Non-resetting MMR used for autoseeding: average of the members' seeding power. Ranked and unranked tournaments feed separate values. */
 	seedingPower: {
 		ranked: number | null;
 		unranked: number | null;
 	};
 	members: Array<{
 		userId: number;
-		/**
-		 * @example "Sendou"
-		 */
+		/** @example "Sendou" */
 		name: string;
-		/**
-		 * @example "79237403620945920"
-		 */
+		/** @example "79237403620945920" */
 		discordId: string;
-		/**
-		 * @example "sendouc"
-		 */
+		/** @example "sendouc" */
 		battlefy: string | null;
-		/**
-		 * @example "https://cdn.discordapp.com/avatars/79237403620945920/6fc41a44b069a0d2152ac06d1e496c6c.png"
-		 */
+		/** @example "https://cdn.discordapp.com/avatars/79237403620945920/6fc41a44b069a0d2152ac06d1e496c6c.png" */
 		avatarUrl: string | null;
-		/**
-		 * @example "FI"
-		 */
+		/** @example "FI" */
 		country: string | null;
 		captain: boolean;
-		/**
-		 * Splatoon 3 splashtag name & ID. Notice the value returned is the player's set name at the time of the tournament.
-		 * Only available for tournaments with the "Require IGN's" option enabled.
-		 *
-		 * @example "Sendou#2955"
-		 */
+		/** Splatoon 3 splashtag as set at the time of the tournament. Only for tournaments with "Require IGN's" enabled. @example "Sendou#2955" */
 		inGameName: string | null;
-		/**
-		 * User's pronouns.
-		 *
-		 * @example { "subject": "he", "object": "him" }
-		 */
+		/** User's pronouns. @example { "subject": "he", "object": "him" } */
 		pronouns: Pronouns | null;
-		/**
-		 *  Switch friend code used for identification purposes.
-		 *
-		 * @example "1234-5678-9101"
-		 */
+		/** Switch friend code used for identification purposes. @example "1234-5678-9101" */
 		friendCode: string;
-		/**
-		 * @example "2024-01-12T20:00:00.000Z"
-		 */
+		/** @example "2024-01-12T20:00:00.000Z" */
 		joinedAt: string;
 	}>;
 }>;
@@ -295,9 +204,7 @@ export interface GetCastedTournamentMatchesResponse {
 
 type TournamentCastChannel = {
 	type: "TWITCH";
-	/**
-	 * @example "iplsplatoon"
-	 */
+	/** @example "iplsplatoon" */
 	channelId: string;
 };
 
@@ -316,22 +223,12 @@ export type GetTournamentStreamsResponse = Array<
 export interface GetTournamentMatchResponse {
 	teamOne: TournamentMatchTeam | null;
 	teamTwo: TournamentMatchTeam | null;
-	/**
-	 * Name of the bracket this match belongs to.
-	 *
-	 * @example "Alpha Bracket"
-	 */
+	/** Name of the bracket this match belongs to. @example "Alpha Bracket" */
 	bracketName: string | null;
-	/**
-	 * Name of the round this match belongs to.
-	 *
-	 * @example "Grand Finals"
-	 */
+	/** Name of the round this match belongs to. @example "Grand Finals" */
 	roundName: string | null;
 	mapList: Array<MapListMap> | null;
-	/**
-	 * @example "https://sendou.ink/to/9/matches/695"
-	 */
+	/** @example "https://sendou.ink/to/9/matches/695" */
 	url: string;
 }
 
@@ -385,18 +282,12 @@ export interface GetTournamentBracketStandingsResponse {
 
 export interface GetTournamentOrganizationResponse {
 	id: number;
-	/**
-	 * @example "Dapple Productions"
-	 */
+	/** @example "Dapple Productions" */
 	name: string;
 	description: string | null;
-	/**
-	 * @example "https://sendou.ink/org/dapple-productions"
-	 */
+	/** @example "https://sendou.ink/org/dapple-productions" */
 	url: string;
-	/**
-	 * @example "https://sendou.nyc3.cdn.digitaloceanspaces.com/gBn45bbUMXM6359ZDQS5_-1722059432073.webp"
-	 */
+	/** @example "https://sendou.nyc3.cdn.digitaloceanspaces.com/gBn45bbUMXM6359ZDQS5_-1722059432073.webp" */
 	logoUrl: string | null;
 	members: Array<TournamentOrganizationMember>;
 	socialLinkUrls: Array<string>;
@@ -404,19 +295,11 @@ export interface GetTournamentOrganizationResponse {
 
 interface TournamentOrganizationMember {
 	userId: number;
-	/**
-	 * @example "Sendou"
-	 */
+	/** @example "Sendou" */
 	name: string;
-	/**
-	 * @example "79237403620945920"
-	 */
+	/** @example "79237403620945920" */
 	discordId: string;
-	/**
-	 * User's pronouns.
-	 *
-	 * @example { "subject": "he", "object": "him" }
-	 */
+	/** User's pronouns. @example { "subject": "he", "object": "him" } */
 	pronouns: Pronouns | null;
 	role: "ADMIN" | "MEMBER" | "ORGANIZER" | "STREAMER";
 	roleDisplayName: string | null;
@@ -432,13 +315,9 @@ type Weapon = {
 type ProfileWeapon = Weapon & { isFiveStar: boolean };
 
 interface GlobalTeamMembership {
-	/**
-	 * ID for the global team page.
-	 */
+	/** ID for the global team page. */
 	id: number;
-	/**
-	 * Role of the user in the team.
-	 */
+	/** Role of the user in the team. */
 	role: TeamMemberRole | null;
 }
 
@@ -461,11 +340,7 @@ interface SeasonalRank {
 		name: RankTierName;
 		isPlus: boolean;
 	};
-	/**
-	 * Which season this rank is for.
-	 *
-	 * @example 7
-	 */
+	/** Which season this rank is for. @example 7 */
 	season: number;
 }
 
@@ -479,18 +354,12 @@ type RankTierName =
 	| "IRON";
 
 type Badge = {
-	/**
-	 * @example "Monday Afterparty"
-	 */
+	/** @example "Monday Afterparty" */
 	name: string;
 	count: number;
-	/**
-	 * @example "https://sendou-assets.nyc3.cdn.digitaloceanspaces.com/badges/monday.avif"
-	 */
+	/** @example "https://sendou-assets.nyc3.cdn.digitaloceanspaces.com/badges/monday.avif" */
 	imageUrl: string;
-	/**
-	 * @example "https://sendou-assets.nyc3.cdn.digitaloceanspaces.com/badges/monday.gif"
-	 */
+	/** @example "https://sendou-assets.nyc3.cdn.digitaloceanspaces.com/badges/monday.gif" */
 	gifUrl: string;
 };
 
diff --git a/app/features/api/core/perms.ts b/app/features/api/core/perms.ts
index 8a20acf31..e9be7c8ad 100644
--- a/app/features/api/core/perms.ts
+++ b/app/features/api/core/perms.ts
@@ -1,14 +1,7 @@
 import type { AuthenticatedUser } from "~/features/auth/core/user.server";
 import * as TournamentOrganizationRepository from "~/features/tournament-organization/TournamentOrganizationRepository.server";
 
-/**
- * Checks whether a user has permission to access the API.
- * A user has API access if they either have the API_ACCESSER role (includes supporters),
- * or are an admin/organizer/streamer of an established tournament organization.
- *
- * @param user - The authenticated user to check permissions for
- * @returns True if the user has API access, false otherwise
- */
+/** Whether the user may access the API: the API_ACCESSER role (includes supporters), or admin/organizer/streamer of an established tournament organization. */
 export async function checkUserHasApiAccess(user: AuthenticatedUser) {
 	// NOTE: permissions logic also exists in ApiRepository.findAllApiTokens function
 	if (user.roles.includes("API_ACCESSER")) {
diff --git a/app/features/art/ArtRepository.server.ts b/app/features/art/ArtRepository.server.ts
index e30530be6..813ec1ab3 100644
--- a/app/features/art/ArtRepository.server.ts
+++ b/app/features/art/ArtRepository.server.ts
@@ -30,9 +30,8 @@ export async function findShowcaseArts(): Promise<ListedArt[]> {
 	const arts = await db
 		.selectFrom((eb) =>
 			eb
-				// each author's most recent art (showcase ones first) via SQLite's
-				// max() + bare column rule, packed into one integer since createdAt
-				// always stays below the isShowcase component
+				// each author's most recent art (showcase first) via SQLite's max() + bare column rule,
+				// packed into one integer since createdAt always stays below the isShowcase component
 				.selectFrom("Art")
 				.innerJoin("User", "User.id", "Art.authorId")
 				.innerJoin("UserSubmittedImage", "UserSubmittedImage.id", "Art.imgId")
diff --git a/app/features/art/art-image.server.ts b/app/features/art/art-image.server.ts
index d227b2405..61badc70e 100644
--- a/app/features/art/art-image.server.ts
+++ b/app/features/art/art-image.server.ts
@@ -8,11 +8,7 @@ import { previewUrl } from "./art-utils";
 
 const ALLOWED_ART_IMAGE_EXTENSIONS = ["png", "jpeg", "webp"] as const;
 
-/**
- * Uploads both assets a newly submitted art needs — the full image and its thumbnail, following
- * the `<name>-small.<ext>` convention {@link previewUrl} resolves — and returns the full image's
- * file name to store on the art's image row.
- */
+/** Uploads the full image and its `<name>-small.<ext>` thumbnail ({@link previewUrl}); returns the full image's file name. */
 export async function uploadArtImage({
 	dataUrl,
 	thumbnailDataUrl,
diff --git a/app/features/art/art-image.ts b/app/features/art/art-image.ts
index 29e977c88..348162dbf 100644
--- a/app/features/art/art-image.ts
+++ b/app/features/art/art-image.ts
@@ -1,32 +1,18 @@
 import * as v from "valibot";
 
-/**
- * Allowed prefixes for an art data URL. Unlike the generic `image()` form field, art keeps the
- * uploaded image's own format instead of normalizing everything to webp.
- */
+/** Unlike the generic `image()` field, art keeps the uploaded format instead of normalizing to webp. */
 const ART_IMAGE_DATA_URL_PREFIX_REGEX = /^data:image\/(png|jpeg|webp);base64,/;
 
-/**
- * Largest full-size art image accepted, decoded. Art is submitted at its original resolution and
- * png keeps its detail losslessly, so this needs the same headroom the multipart upload flow used
- * to allow.
- */
+/** Decoded bytes. Art is submitted at original resolution, so png needs this much headroom. */
 const ART_IMAGE_MAX_BYTES = 5 * 1024 * 1024;
 
-/**
- * Largest art thumbnail accepted, decoded. The client caps the thumbnail's width to
- * `ART.THUMBNAIL_WIDTH`, which lands well below this.
- */
+/** Decoded bytes; the client caps the width to `ART.THUMBNAIL_WIDTH`, landing well below this. */
 const ART_THUMBNAIL_MAX_BYTES = 2 * 1024 * 1024;
 
-/**
- * Ceiling for the whole art submit body. Fits both data URLs at their maximum plus the rest of the
- * form's fields.
- */
+/** Fits both data URLs at their maximum plus the rest of the form's fields. */
 export const ART_FORM_MAX_BODY_BYTES =
 	maxDataUrlLength(ART_IMAGE_MAX_BYTES + ART_THUMBNAIL_MAX_BYTES) + 100_000;
 
-/** Error shown when a picked image doesn't fit within the limits above. */
 export const ART_IMAGE_TOO_LARGE_ERROR = "forms:errors.imageTooLarge";
 
 const artImageDataUrl = (maxBytes: number) =>
@@ -37,11 +23,9 @@ const artImageDataUrl = (maxBytes: number) =>
 	);
 
 /**
- * JSON-serializable value of the art image form field. Art can't use the generic `image()` field:
- * it preserves aspect ratio, keeps the original format and derives a separate thumbnail, which is
- * why a `NEW` value carries two data URLs. An `EXISTING` value marks art whose image was already
- * uploaded (only the preview url rides along, never bytes) — art images can't be swapped after
- * upload.
+ * Art can't use the generic `image()` field: it keeps aspect ratio and format and derives a
+ * thumbnail, hence two data URLs. `EXISTING` carries only the preview url; art images can't be
+ * swapped after upload.
  */
 export const artImageValue = v.nullable(
 	v.union([
@@ -59,10 +43,7 @@ export const artImageValue = v.nullable(
 
 export type ArtImageValue = v.InferOutput<typeof artImageValue>;
 
-/**
- * Does a freshly compressed art image exceed what the schema accepts? Lets the form field reject
- * an oversized pick right away instead of only when the filled-out form is submitted.
- */
+/** Lets the form field reject an oversized pick right away instead of only on submit. */
 export function isArtImageTooLarge({
 	dataUrl,
 	thumbnailDataUrl,
@@ -76,7 +57,7 @@ export function isArtImageTooLarge({
 	);
 }
 
-/** Length a base64 data URL encoding `bytes` decoded bytes can reach, `data:` prefix included. */
+/** Max length of a base64 data URL for `bytes` decoded bytes, prefix included. */
 function maxDataUrlLength(bytes: number) {
 	return Math.ceil(bytes / 3) * 4 + 32;
 }
diff --git a/app/features/art/components/ArtImageFormField.tsx b/app/features/art/components/ArtImageFormField.tsx
index 4752113d3..42e0e2d42 100644
--- a/app/features/art/components/ArtImageFormField.tsx
+++ b/app/features/art/components/ArtImageFormField.tsx
@@ -20,10 +20,8 @@ type ArtImageFormFieldProps = Omit<
 >;
 
 /**
- * Image picker for art. Produces both derived assets the art pipeline needs — the full image with
- * its aspect ratio and format preserved, and a thumbnail — as base64 data URLs so they can ride
- * along in `SendouForm`'s single JSON submit. Art of already uploaded art can't be swapped, so an
- * `EXISTING` value renders as a plain preview.
+ * Produces the full image (aspect ratio and format preserved) and a thumbnail as data URLs for
+ * `SendouForm`'s JSON submit. Uploaded art can't be swapped, so `EXISTING` renders a plain preview.
  */
 export function ArtImageFormField({
 	value,
diff --git a/app/features/art/components/ArtTagsFormField.tsx b/app/features/art/components/ArtTagsFormField.tsx
index 6e26f157e..9570015fc 100644
--- a/app/features/art/components/ArtTagsFormField.tsx
+++ b/app/features/art/components/ArtTagsFormField.tsx
@@ -11,12 +11,10 @@ import { TagSelect } from "./TagSelect";
 export type ArtTag = { name?: string; id?: number };
 
 type ArtTagsFormFieldProps = Omit<CustomFieldRenderProps<ArtTag[]>, "name"> & {
-	/** All tags that exist in the database, selectable without creating a new one. */
 	existingTags: Array<{ id: number; name: string }>;
 };
 
-// note: not handling edge case where a tag was added by another user while this
-// user was adding a new art with the same tag -> will crash
+// NOTE: a tag added by another user while this form is open will crash on submit
 export function ArtTagsFormField({
 	value,
 	onChange,
@@ -31,7 +29,6 @@ export function ArtTagsFormField({
 	const handleAddNewTag = () => {
 		const normalizedNewTagValue = newTagValue
 			.trim()
-			// replace many whitespaces with one
 			.replace(/\s\s+/g, " ")
 			.toLowerCase();
 
diff --git a/app/features/associations/associations-types.ts b/app/features/associations/associations-types.ts
index 65a373a1c..36c5434c7 100644
--- a/app/features/associations/associations-types.ts
+++ b/app/features/associations/associations-types.ts
@@ -1,12 +1,10 @@
 import type { AssociationIdentifier } from "./associations-constants";
 
 export interface AssociationVisibility {
-	/** Which association should see it */
 	forAssociation: AssociationIdentifier;
 	notFoundInstructions?: Array<{
-		/** When to expand the visibility */
 		at: number;
-		/** To which association expand the visibility to? null indicates public */
+		/** null = public */
 		forAssociation: AssociationIdentifier | null;
 	}>;
 }
diff --git a/app/features/auth/LogInLinkRepository.server.ts b/app/features/auth/LogInLinkRepository.server.ts
index 706433c68..a532ff755 100644
--- a/app/features/auth/LogInLinkRepository.server.ts
+++ b/app/features/auth/LogInLinkRepository.server.ts
@@ -6,7 +6,7 @@ import { databaseTimestampNow, dateToDatabaseTimestamp } from "~/utils/dates";
 const LOG_IN_LINK_LENGTH = 12;
 const LOG_IN_LINK_VALID_FOR_MINUTES = 10;
 
-/** Creates a new login link for a user with 10-minute expiration */
+/** Creates a login link valid for `LOG_IN_LINK_VALID_FOR_MINUTES`. */
 export function insert(userId: number) {
 	return db
 		.insertInto("LogInLink")
@@ -21,12 +21,12 @@ export function insert(userId: number) {
 		.executeTakeFirstOrThrow();
 }
 
-/** Deletes a login link by its code */
+/** Deletes a login link by its code. */
 export function deleteByCode(code: string) {
 	return db.deleteFrom("LogInLink").where("code", "=", code).execute();
 }
 
-/** Finds a valid (non-expired) login link by code, returns userId if valid */
+/** Non-expired login link by code. */
 export function findValidByCode(code: string) {
 	return db
 		.selectFrom("LogInLink")
diff --git a/app/features/auth/core/routes.server.ts b/app/features/auth/core/routes.server.ts
index 9ce0a175a..a8b564da6 100644
--- a/app/features/auth/core/routes.server.ts
+++ b/app/features/auth/core/routes.server.ts
@@ -26,7 +26,6 @@ import { getUser } from "./user.server";
 export const callbackLoader: LoaderFunction = async ({ request, url }) => {
 	// biome-ignore lint/plugin: OAuth callback param, its name and values defined by the provider
 	if (url.searchParams.get("error") === "access_denied") {
-		// The user denied the authentication request
 		// https://www.oauth.com/oauth2-servers/server-side-apps/possible-errors/
 
 		throw redirect(authErrorUrl("aborted"));
@@ -145,13 +144,9 @@ async function safeReturnTo(request: Request): Promise<string | null> {
 	return value;
 }
 
-// below is alternative log-in flow that is operated via the Lohi Discord bot
-// this is intended primarily as a workaround when website is having problems communicating
-// with the Discord due to rate limits or other reasons
-
-// only light validation here as we generally trust Lohi
-// auth flow params are infrastructure conventions and intentionally do not go
-// through app/modules/search-params/
+// alternative log-in flow via the Lohi Discord bot, a workaround for when the site can't reach
+// Discord (rate limits etc.). Only light validation as we trust Lohi; these params are
+// infrastructure conventions and intentionally bypass app/modules/search-params/
 function parseSearchParams<T extends AnySyncSchema>({
 	request,
 	schema,
diff --git a/app/features/auth/core/user.server.ts b/app/features/auth/core/user.server.ts
index 6b8efe8c9..3e9c4ffa9 100644
--- a/app/features/auth/core/user.server.ts
+++ b/app/features/auth/core/user.server.ts
@@ -21,24 +21,19 @@ export function requireUser(): AuthenticatedUser {
 	return user;
 }
 
-/** Id of the acting user, from request context. Throws an Error if there is no
- *  authenticated user (e.g. called outside a request) — repositories rely on a
- *  bouncer having already enforced auth, so absence here is a bug, not a 401. */
+/** Throws without an authenticated user: a bouncer should have enforced auth, so absence is a bug, not a 401. */
 export function actorId(): number {
 	const id = actorIdOrNull();
 	if (id === null) throw new Error("No acting user in context");
 	return id;
 }
 
-/** Id of the acting user, or null when unauthenticated. Use for reads that
- *  also serve anonymous visitors, where the actor only scopes the result. */
+/** For reads that also serve anonymous visitors, where the actor only scopes the result. */
 export function actorIdOrNull(): number | null {
 	return getUser()?.id ?? null;
 }
 
-/** Id of the acting user, or null when there is no actor *or* no request
- *  context at all (e.g. cron routines). Never throws, unlike actorIdOrNull —
- *  use for ambient side effects that may also run outside of a request. */
+/** Null also when there is no request context at all (e.g. cron routines); never throws. */
 export function actorIdOrNullSafe(): number | null {
 	return userAsyncLocalStorage.getStore()?.user?.id ?? null;
 }
diff --git a/app/features/availability/AvailabilityRepository.server.ts b/app/features/availability/AvailabilityRepository.server.ts
index c62dd7fcd..c374ec740 100644
--- a/app/features/availability/AvailabilityRepository.server.ts
+++ b/app/features/availability/AvailabilityRepository.server.ts
@@ -10,14 +10,12 @@ import {
 import { AVAILABILITY } from "./availability-constants";
 import type { TimeRange } from "./availability-types";
 
-/** Longest a week can be, a DST week included. Weeks are indexed by their start, so finding the ones overlapping a window means looking this far back. */
+/** Longest week (DST included). Weeks are indexed by start, so overlapping a window means looking this far back. */
 const WEEK_MAX_SECONDS = 169 * 60 * 60;
 
 /**
- * Reported availability of the given users for every week overlapping the given
- * window, with the week's slots and day notes. A week without slots was
- * submitted as "unavailable all week"; a user with no week at all for the
- * window simply has not reported anything.
+ * Reported weeks of the given users overlapping the window, with slots and day notes. A week
+ * without slots means "unavailable all week"; no week at all means nothing was reported.
  */
 export function findAllWeeksByUserIds({
 	userIds,
@@ -68,9 +66,8 @@ export function findAllWeeksByUserIds({
 }
 
 /**
- * Whether the user has reported the week starting at `weekStartsAt`. The week
- * is theirs to place, so a start within {@link AVAILABILITY.WEEK_MATCH_MAX_DISTANCE_SECONDS}
- * of the asked one is the same week seen from another timezone.
+ * Whether the user reported the week starting at `weekStartsAt`. A start within
+ * {@link AVAILABILITY.WEEK_MATCH_MAX_DISTANCE_SECONDS} is the same week seen from another timezone.
  */
 export async function hasReportedWeek({
 	userId,
@@ -99,10 +96,8 @@ export async function hasReportedWeek({
 }
 
 /**
- * Ids of the users who have not reported the week starting at `weekStartsAt`
- * while at least one of their teammates has — the reminder is only worth
- * sending when somebody else on the team already moved. Cheerleaders are left
- * out, the schedule surfaces do not show them.
+ * Users who have not reported the week starting at `weekStartsAt` while a teammate has (a reminder
+ * is only worth sending then). Cheerleaders are left out, the schedule views do not show them.
  */
 export async function findWeekReminderUserIds(weekStartsAt: number) {
 	const memberships = await db
@@ -149,9 +144,8 @@ export async function findWeekReminderUserIds(weekStartsAt: number) {
 }
 
 /**
- * Team events of every team the given users are members of (secondary teams
- * included) that overlap the given window, one row per member. Events limited
- * to selected participants only produce rows for those participants.
+ * Team events overlapping the window of every team (secondary included) the users are members of,
+ * one row per member. Events limited to selected participants only produce rows for those.
  */
 export function findAllTeamEventsByUserIds({
 	userIds,
@@ -200,7 +194,7 @@ export function findAllTeamEventsByUserIds({
 		.execute();
 }
 
-/** Team events of one team overlapping the given window, with the participant user ids of events limited to selected members (empty = the whole team). */
+/** One team's events overlapping the window, with the participant user ids (empty = the whole team). */
 export function findTeamEventsByTeamId({
 	teamId,
 	startsAt,
@@ -233,10 +227,9 @@ export function findTeamEventsByTeamId({
 }
 
 /**
- * Ongoing and upcoming team events of every team the given user is a member of
- * (secondary teams included), starting within the given window, with the
- * owning team attached. Events limited to selected participants show up only
- * for those participants. For the user's personal calendar surfaces.
+ * Ongoing and upcoming events starting within the window of every team (secondary included) the
+ * user is a member of, with the owning team. Events limited to selected participants show up only
+ * for those. For the user's personal calendar views.
  */
 export function findAllUpcomingTeamEventsByUserId({
 	userId,
@@ -303,13 +296,9 @@ interface UpsertOwnWeekArgs {
 }
 
 /**
- * Saves the acting user's availability for one week, replacing whatever they
- * had reported for it. The week is saved as a whole, so slots and day notes
- * left out are removed. A week reported earlier from another timezone (its
- * start hours apart, never days) is the same week and gets replaced, not
- * duplicated.
- *
- * @returns id of the week
+ * Replaces the acting user's week as a whole (slots and day notes left out are removed). A week
+ * reported earlier from another timezone (start hours apart, never days) is replaced, not duplicated.
+ * Returns the week id.
  */
 export function upsertOwnWeek(args: UpsertOwnWeekArgs) {
 	const userId = actorId();
@@ -391,10 +380,7 @@ export function upsertOwnWeek(args: UpsertOwnWeekArgs) {
 	});
 }
 
-/**
- * Deletes availability weeks that started before the given timestamp. Their
- * slots and day notes go with them via cascade delete.
- */
+/** Deletes weeks started before the timestamp; slots and day notes cascade. */
 export function deleteWeeksStartedBefore(weekStartsAt: number) {
 	return db
 		.deleteFrom("AvailabilityWeek")
@@ -410,12 +396,7 @@ export function deleteTeamEventsEndedBefore(endsAt: number) {
 		.executeTakeFirstOrThrow();
 }
 
-/**
- * Adds a team event. Author is the acting user. Without `participantUserIds`
- * the whole team takes part; with them only the given members do.
- *
- * @returns id of the new event
- */
+/** Adds a team event authored by the acting user; without `participantUserIds` the whole team takes part. Returns its id. */
 export function insertTeamEvent({
 	participantUserIds,
 	...args
diff --git a/app/features/availability/availability-constants.ts b/app/features/availability/availability-constants.ts
index 01722874b..10b689ac1 100644
--- a/app/features/availability/availability-constants.ts
+++ b/app/features/availability/availability-constants.ts
@@ -1,7 +1,7 @@
 export const AVAILABILITY = {
 	/** Granularity availability is entered and rendered at. */
 	SLOT_STEP_MINUTES: 30,
-	/** How many players have to be free at once for the team to be able to play. */
+	/** Players free at once for the team to be able to play. */
 	DEFAULT_MIN_PLAYERS: 4,
 	/** Shorter overlaps are not worth reporting as a playable window. */
 	MIN_WINDOW_MINUTES: 60,
@@ -11,9 +11,9 @@ export const AVAILABILITY = {
 	WEEK_HORIZON: 2,
 	/** Weeks whose end is further in the past than this are deleted. */
 	RETENTION_MONTHS: 3,
-	/** Assumed length of an accepted scrim when it blocks availability — the actual end is not in the data model. */
+	/** Assumed scrim length, the actual end is not in the data model. */
 	SCRIM_COMMITMENT_SECONDS: 1.5 * 60 * 60,
-	/** A reported week belongs to a viewer week when their starts are closer than this — timezones set them apart by hours, never by days. */
+	/** Week starts closer than this are the same week; timezones set them apart by hours, never days. */
 	WEEK_MATCH_MAX_DISTANCE_SECONDS: 3.5 * 24 * 60 * 60,
 	/** Left edge of the editor's clock window (14:00) — evenings are when people play. */
 	TRACK_START_MINUTES: 14 * 60,
diff --git a/app/features/availability/availability-schemas.ts b/app/features/availability/availability-schemas.ts
index 60305c538..c7985d0ea 100644
--- a/app/features/availability/availability-schemas.ts
+++ b/app/features/availability/availability-schemas.ts
@@ -82,9 +82,8 @@ const teamEventFields = {
 	startsAt: datetime({
 		label: "labels.start",
 		min: () => sub(new Date(), { hours: 1 }),
-		// end of the next week, the furthest the schedule shows; the hours are
-		// slack for server-side validation running in another timezone than the
-		// viewer's week
+		// end of the next week, the furthest the schedule shows, plus hours of slack for server-side
+		// validation running in another timezone than the viewer's
 		max: () =>
 			add(
 				startOfWeek(addWeeks(new Date(), AVAILABILITY.WEEK_HORIZON), {
diff --git a/app/features/availability/availability-types.ts b/app/features/availability/availability-types.ts
index a4b2b22bd..1e58eba15 100644
--- a/app/features/availability/availability-types.ts
+++ b/app/features/availability/availability-types.ts
@@ -10,11 +10,7 @@ export interface MemberAvailability {
 	ranges: Array<TimeRange>;
 }
 
-/**
- * A span the team could play in:
- * - `FULL` = the required amount of players is free for the whole window
- * - `ONE_SHORT` = one player short, so they would need a sub
- */
+/** `FULL` = the required players are free for the whole window, `ONE_SHORT` = one short, a sub is needed. */
 export type PlayableWindowTier = "FULL" | "ONE_SHORT";
 
 export interface PlayableWindow extends TimeRange {
@@ -23,10 +19,7 @@ export interface PlayableWindow extends TimeRange {
 	userIds: Array<number>;
 }
 
-/**
- * A span within one day of the schedule editor, in minutes from that day's
- * midnight. `end` may pass 1440 for a range crossing midnight.
- */
+/** A span within one editor day in minutes from midnight. `end` may pass 1440 for a range crossing midnight. */
 export interface DayTimeRange {
 	start: number;
 	end: number;
@@ -50,24 +43,16 @@ export interface EditorCommitment {
 	name: string;
 }
 
-/**
- * A span a commitment makes the user busy for, overriding whatever
- * availability they reported. `name` is what the user is at (e.g. the
- * tournament's name); `null` when the type alone says it (a scrim).
- */
+/** A commitment overriding reported availability. `name` is e.g. the tournament's name, null when the type says it (a scrim). */
 export interface BusyBlock extends TimeRange {
 	type: "tournament" | "scrim" | "teamEvent";
 	name: string | null;
 }
 
 /**
- * How one person's schedule relates to an event's window:
- * - `available` — reported availability covers the whole window
- * - `partial` — covers part of it; `ranges` show which part
- * - `unavailable` — a week was reported, none of it overlaps the window
- * - `busy` — a commitment elsewhere overlaps the window, overriding whatever
- *   was reported
- * - `unknown` — no reported week covers the window
+ * `available` = reported availability covers the window, `partial` = part of it (`ranges` say which),
+ * `unavailable` = a week was reported but none overlaps, `busy` = a commitment overrides whatever
+ * was reported, `unknown` = no reported week covers the window.
  */
 export type WindowAvailability =
 	| { status: "available" | "partial"; ranges: Array<TimeRange> }
@@ -75,11 +60,7 @@ export type WindowAvailability =
 	| { status: "unavailable" }
 	| { status: "unknown" };
 
-/**
- * How one person's schedule relates to a window, as the surfaces showing a
- * roster's fit render it. `notes` is left out by the surfaces that have no day
- * notes at hand.
- */
+/** One person's fit to a window as roster views render it. `notes` is left out by views without day notes at hand. */
 export interface WindowAvailabilityEntry {
 	userId: number;
 	availability: WindowAvailability;
@@ -87,27 +68,23 @@ export interface WindowAvailabilityEntry {
 }
 
 /**
- * What is known about one person inside a window: the material
- * `Availability.availabilityInWindow` resolves a status from. Sent to the
- * browser as is by the surfaces that ask about many windows at once, so that
- * narrowing one down (picking a start inside a post's flexibility) needs no
- * further round trip.
+ * What `Availability.availabilityInWindow` resolves a status from. Sent to the browser as is by
+ * views asking about many windows, so narrowing one down (a start inside a post's flexibility)
+ * needs no further round trip.
  */
 export interface WindowSchedule {
 	userId: number;
 	/** Whether they filled in the week the window falls in. */
 	reported: boolean;
-	/** Their effective availability inside the window. */
+	/** Effective availability inside the window. */
 	ranges: Array<TimeRange>;
-	/** Their commitments overlapping the window. */
+	/** Commitments overlapping the window. */
 	busy: Array<BusyBlock>;
 }
 
 /**
- * One person's week as the read-only week views render it: the seven days in
- * the viewer's timezone with the time they are effectively free to play. What
- * a commitment takes back is already cut out — the view answers "when can they
- * play", not "what are they doing".
+ * One person's week as read-only views render it: seven days in the viewer's timezone with the
+ * time they are free to play, commitments already cut out ("when can they play", not "what are they doing").
  */
 export interface ScheduleWeekView {
 	week: "current" | "next";
diff --git a/app/features/availability/components/MySchedule.tsx b/app/features/availability/components/MySchedule.tsx
index bf2ed3eb3..e9a8ee816 100644
--- a/app/features/availability/components/MySchedule.tsx
+++ b/app/features/availability/components/MySchedule.tsx
@@ -16,10 +16,7 @@ import styles from "./MySchedule.module.css";
 import { WeekAvailabilityEditor } from "./WeekAvailabilityEditor";
 import { WeekToggle } from "./WeekToggle";
 
-/**
- * The "My schedule" section of the events page: the schedule editor with a
- * current/next week toggle, "Copy last week" prefill and the save action.
- */
+/** The events page's "My schedule": editor with current/next week toggle, "Copy last week" prefill and save. */
 export function MySchedule({ data }: { data: MyScheduleData }) {
 	const { t } = useTranslation(["schedule"]);
 	const [{ week }, setParams] = useSearchParamsTyped(scheduleWeekSearchParams);
@@ -35,11 +32,9 @@ export function MySchedule({ data }: { data: MyScheduleData }) {
 		day: "numeric",
 	});
 
-	// dirty = the editor differs from what the loader last saw, or the day
-	// popover holds edits it has not committed yet; a successful save
-	// revalidates the loader, which makes this read clean again. Edits survive
-	// same-route navigations (the view tabs), so only a pathname change or a
-	// full unload warns.
+	// dirty = editor differs from the loader (a save revalidates it, reading clean again) or the day
+	// popover holds uncommitted edits. Edits survive same-route navigations (view tabs), so only a
+	// pathname change or a full unload warns
 	const hasPendingDraftRef = React.useRef(false);
 	const hasUnsavedChangesRef = React.useRef<
 		Parameters<typeof useUnsavedChangesChecker>[0]["current"]
diff --git a/app/features/availability/components/RegistrationAvailabilityPanel.tsx b/app/features/availability/components/RegistrationAvailabilityPanel.tsx
index 4314451b2..66140fbf4 100644
--- a/app/features/availability/components/RegistrationAvailabilityPanel.tsx
+++ b/app/features/availability/components/RegistrationAvailabilityPanel.tsx
@@ -34,11 +34,7 @@ export type AvailabilityRowStatus =
 	/** On the roster, but their schedule is not visible to the viewer (neither a teammate nor a friend). */
 	| "hidden";
 
-/**
- * The tournament registration page's availability panel: how each member of
- * the roster relates to the event's estimated window, plus the friends who
- * could sub (the ones actually free during it).
- */
+/** How each roster member relates to the event's estimated window, plus the friends free to sub. */
 export function RegistrationAvailabilityPanel({
 	availability,
 	roster,
@@ -131,11 +127,7 @@ export function RegistrationAvailabilityPanel({
 	);
 }
 
-/**
- * One user's availability as a list row: status icon, avatar, name and the
- * availability detail. The registration page composes it with roster extras
- * (an in-game name line, a remove button).
- */
+/** One user's availability row; the registration page composes it with roster extras (IGN line, remove button). */
 export function AvailabilityMemberRow({
 	user,
 	entry,
@@ -183,10 +175,7 @@ export function AvailabilityMemberRow({
 	);
 }
 
-/**
- * Resolves the shown status for a roster member; no entry at all means their
- * schedule is not visible to the viewer.
- */
+/** Shown status of a roster member; no entry means their schedule is not visible to the viewer. */
 export function availabilityRowStatus(
 	entry?: AvailabilityPanelEntry,
 ): AvailabilityRowStatus {
diff --git a/app/features/availability/components/ScheduleDayCell.tsx b/app/features/availability/components/ScheduleDayCell.tsx
index e3c4311be..135706bd6 100644
--- a/app/features/availability/components/ScheduleDayCell.tsx
+++ b/app/features/availability/components/ScheduleDayCell.tsx
@@ -7,10 +7,8 @@ import type { BusyBlock, TimeRange } from "../availability-types";
 import styles from "./ScheduleDayCell.module.css";
 
 /**
- * One day of one person's week: the ranges they are effectively free for and,
- * where the surface shows them, the commitments taking time back and the note
- * they left on the day. Shared by the team schedule grid and the single person
- * week view so the two cannot drift apart.
+ * One day of one person's week: free ranges plus, where shown, commitments and the day note.
+ * Shared by the team schedule grid and the single person week view so they cannot drift apart.
  */
 export function ScheduleDayCell({
 	reported,
@@ -73,11 +71,7 @@ export function ScheduleDayCell({
 	);
 }
 
-/**
- * Formats a range as times only. `formatRange` expands to full dates when the
- * ends fall on different calendar days, so a range crossing (or ending exactly
- * at) midnight formats its ends separately.
- */
+/** Times only: `formatRange` expands to full dates across days, so a range crossing midnight formats its ends separately. */
 export function useRangeText() {
 	const { formatter } = useDateTimeFormat({
 		hour: "numeric",
diff --git a/app/features/availability/components/ScheduleNudge.tsx b/app/features/availability/components/ScheduleNudge.tsx
index 16f2f00a6..d0a36e456 100644
--- a/app/features/availability/components/ScheduleNudge.tsx
+++ b/app/features/availability/components/ScheduleNudge.tsx
@@ -10,12 +10,7 @@ import { dismissScheduleNudgeSchema } from "../availability-schemas";
 import { scheduleWeekSearchParams } from "../availability-search-params";
 import styles from "./ScheduleNudge.module.css";
 
-/**
- * Prompt to report next week's availability, shown on the last day of the week
- * while next week is still empty. Sits as a band right under the events header.
- * Dismissing it is remembered for the week, so it can be waved away without
- * filling anything in.
- */
+/** Band under the events header on the last day of the week while next week is empty; dismissal is remembered for the week. */
 export function ScheduleNudge({
 	panel,
 	onNavigate,
diff --git a/app/features/availability/components/ScheduleTracks.tsx b/app/features/availability/components/ScheduleTracks.tsx
index 477a519a1..29f84f646 100644
--- a/app/features/availability/components/ScheduleTracks.tsx
+++ b/app/features/availability/components/ScheduleTracks.tsx
@@ -15,14 +15,10 @@ const MIN_FITTED_SPAN_MINUTES = 4 * MINUTES_IN_HOUR;
 export type ClockWindow = ReturnType<typeof useClockWindow>;
 
 /**
- * The hours the day tracks put on screen and how a range of a day maps onto
- * them. Defaults to the evening hours people play in, the expanders widening
- * it towards the morning on either end.
- *
- * `fitTo` compacts it around what is actually on the tracks instead, for views
- * that only show availability: the width then goes to the bars and their
- * labels rather than to hours nobody is free in. The expanders still open the
- * full day either way.
+ * The hours the day tracks show and how a day range maps onto them. Defaults to the evening
+ * hours people play in, the expanders widening towards the morning on either end. `fitTo`
+ * compacts it around what is on the tracks instead (read-only views), so the width goes to the
+ * bars rather than hours nobody is free in. The expanders still open the full day either way.
  */
 export function useClockWindow({
 	fitTo,
@@ -30,11 +26,7 @@ export function useClockWindow({
 }: {
 	/** Everything drawn on the tracks, in minutes from their own day's midnight. */
 	fitTo?: Array<DayTimeRange>;
-	/**
-	 * Content the window must reach even when it falls outside the default
-	 * hours (a time typed by hand, a week saved in another timezone), for
-	 * views that keep the default window otherwise — the editor.
-	 */
+	/** Content the window must reach even outside the default hours (a typed time, a week saved in another timezone). For the editor. */
 	expandTo?: Array<DayTimeRange>;
 } = {}) {
 	const [earlierShown, setEarlierShown] = React.useState(false);
@@ -92,11 +84,7 @@ export function useClockWindow({
 	};
 }
 
-/**
- * Whole hours around everything on the tracks, the span rounded up so that a
- * label lands on both edges. Null when there is nothing to fit, leaving the
- * default window in place.
- */
+/** Whole hours around everything on the tracks, rounded so a label lands on both edges. Null when nothing to fit. */
 function fittedWindow(ranges?: Array<DayTimeRange>) {
 	if (!ranges || ranges.length === 0) return null;
 
diff --git a/app/features/availability/components/ScheduleWeekDialog.tsx b/app/features/availability/components/ScheduleWeekDialog.tsx
index e8861d25b..e3902a7c2 100644
--- a/app/features/availability/components/ScheduleWeekDialog.tsx
+++ b/app/features/availability/components/ScheduleWeekDialog.tsx
@@ -8,10 +8,7 @@ import { ScheduleDayCell } from "./ScheduleDayCell";
 import styles from "./ScheduleWeekDialog.module.css";
 import { WeekToggle } from "./WeekToggle";
 
-/**
- * One person's reportable weeks as a read-only day-by-day list of the time
- * they are free to play.
- */
+/** One person's reportable weeks as a read-only day-by-day list of their free time. */
 export function ScheduleWeekDialog({
 	username,
 	weeks,
diff --git a/app/features/availability/components/WeekAvailabilityEditor.tsx b/app/features/availability/components/WeekAvailabilityEditor.tsx
index dc1b6b58b..03806959e 100644
--- a/app/features/availability/components/WeekAvailabilityEditor.tsx
+++ b/app/features/availability/components/WeekAvailabilityEditor.tsx
@@ -69,12 +69,10 @@ interface DayDraft {
 }
 
 /**
- * One week of the user's own availability as an editable timeline: on wide
- * containers each day is a track where ranges are painted, moved, resized and
- * drag-filled with the pointer; on narrow containers a stacked per-day list.
- * Both share the same popover with exact time inputs and the day note, which
- * is also the keyboard path. Commitments render as locked blocks on the
- * tracks; gestures may cross them, but a new range cannot start on one.
+ * One week of the user's own availability: on wide containers a track per day where ranges are
+ * painted, moved, resized and drag-filled; on narrow ones a stacked per-day list. Both share the
+ * popover with exact time inputs and the day note, also the keyboard path. Commitments are locked
+ * blocks: gestures may cross them, but a new range cannot start on one.
  */
 export function WeekAvailabilityEditor({
 	value,
@@ -391,9 +389,7 @@ export function WeekAvailabilityEditor({
 		setOpenDayDate(null);
 	};
 
-	// deleting commits right away so the bar disappears as the button is
-	// pressed; once no ranges are left the popover has nothing to edit and
-	// closes too
+	// deleting commits right away so the bar disappears as pressed; with no ranges left the popover closes too
 	const handleRangeDelete = (draft: DayDraft) => {
 		if (!openDayDate) return;
 
@@ -436,8 +432,7 @@ export function WeekAvailabilityEditor({
 			gesture && gesture.type !== "fill" && gesture.dayIndex === dayIndex
 				? gesture
 				: null;
-		// a plain click on a bar starts a move gesture too; the live time label
-		// only belongs to an actual drag, not to the click opening the popover
+		// a plain click on a bar starts a move gesture too; the live time label belongs only to an actual drag
 		const liveRange =
 			dayGesture?.type === "move" && !dayGesture.moved
 				? null
@@ -674,7 +669,7 @@ function DayEditor({
 	/** Opens with an empty row already appended, for an "add time" entry point. */
 	startWithNewRow: boolean;
 	onDraftChange: (draft: DayDraft) => void;
-	/** Called with the remaining draft after a range row is deleted — deletes commit instantly instead of waiting for the popover to close. */
+	/** Called with the remaining draft after a range row is deleted; deletes commit instantly. */
 	onRangeDelete: (draft: DayDraft) => void;
 }) {
 	const { t } = useTranslation(["schedule", "common", "forms"]);
diff --git a/app/features/availability/core/Availability.ts b/app/features/availability/core/Availability.ts
index 98552dba3..8bcd7566c 100644
--- a/app/features/availability/core/Availability.ts
+++ b/app/features/availability/core/Availability.ts
@@ -26,10 +26,7 @@ import type {
 const MINUTE_IN_SECONDS = 60;
 const DAY_MINUTES = 24 * 60;
 
-/**
- * Database timestamp of the Monday 00:00 that starts the week `date` falls in,
- * as the week is seen in `timezone`.
- */
+/** Database timestamp of the Monday 00:00 starting the week `date` falls in, as seen in `timezone`. */
 export function weekStartsAt(date: Date, timezone: string) {
 	const zoned = new TZDate(date.getTime(), timezone);
 
@@ -37,9 +34,8 @@ export function weekStartsAt(date: Date, timezone: string) {
 }
 
 /**
- * The week `date` falls in as a time range, `endsAt` being the Monday 00:00 that
- * starts the next week. Not always 7×24h long: a week with a DST transition in
- * it is an hour shorter or longer.
+ * The week `date` falls in, `endsAt` being the next Monday 00:00. Not always 7×24h:
+ * a week with a DST transition is an hour shorter or longer.
  */
 export function weekRange(date: Date, timezone: string): TimeRange {
 	const zoned = new TZDate(date.getTime(), timezone);
@@ -66,11 +62,7 @@ export function isoWeekNumber(timestamp: number, timezone: string) {
 	return getISOWeek(inTimezone(timestamp, timezone));
 }
 
-/**
- * Whether a week reported to start at `weekStartsAt` is the week starting at
- * `rangeStartsAt`: the two starts are closer than timezones can set them
- * apart (hours, never days).
- */
+/** Whether the two week starts name the same week: closer than timezones can set them apart (hours, never days). */
 export function isSameWeek(weekStartsAt: number, rangeStartsAt: number) {
 	return (
 		Math.abs(weekStartsAt - rangeStartsAt) <
@@ -78,11 +70,7 @@ export function isSameWeek(weekStartsAt: number, rangeStartsAt: number) {
 	);
 }
 
-/**
- * Database timestamp of the given wall clock time in `timezone`. `date` is
- * `YYYY-MM-DD` and `time` is `HH:mm`, the shapes the availability tables and
- * form fields use.
- */
+/** Database timestamp of `date` (`YYYY-MM-DD`) at `time` (`HH:mm`) in `timezone`. */
 export function localToTimestamp({
 	date,
 	time,
@@ -106,11 +94,9 @@ export function localToTimestamp({
 }
 
 /**
- * Database timestamp of the given minutes from midnight of `date` in
- * `timezone`, the clock representation the schedule editor uses. Minutes past
- * 1440 roll into the next day, so the end of a range crossing midnight
- * converts like any other. On a DST transition day the clock simply rolls
- * through the change, same as entering the time by hand would.
+ * Database timestamp of `minutes` from midnight of `date` in `timezone`. Minutes past
+ * 1440 roll into the next day; on a DST day the clock rolls through the change like a
+ * hand-entered time would.
  */
 export function dayMinutesToTimestamp({
 	date,
@@ -134,9 +120,8 @@ export function dayMinutesToTimestamp({
 }
 
 /**
- * `YYYY-MM-DD` of the timestamp in `timezone`. What day a slot belongs to
- * depends on who is looking at it, so the day of a slot is always resolved from
- * its timestamp rather than from the day its author entered it on.
+ * `YYYY-MM-DD` of the timestamp in `timezone`. A slot's day depends on who is looking,
+ * so it is always resolved from the timestamp, never from the day its author entered it on.
  */
 export function dateInTimezone(timestamp: number, timezone: string) {
 	return format(inTimezone(timestamp, timezone), "yyyy-MM-dd");
@@ -148,9 +133,8 @@ export function timeInTimezone(timestamp: number, timezone: string) {
 }
 
 /**
- * `YYYY-MM-DD` in the `to` timezone of a day saved as a date in the `from`
- * timezone, mapped through that day's noon in case the viewer has since
- * moved. How day notes find their viewer-local day.
+ * `YYYY-MM-DD` in `to` of a day saved as a date in `from`, mapped through that day's
+ * noon in case the viewer has since moved. How day notes find their viewer-local day.
  */
 export function dateAcrossTimezones({
 	date,
@@ -172,10 +156,7 @@ export function overlaps(one: TimeRange, other: TimeRange) {
 	return one.startsAt < other.endsAt && other.startsAt < one.endsAt;
 }
 
-/**
- * The given ranges sorted and merged, so that no two of them overlap or touch.
- * Empty ranges are dropped.
- */
+/** The ranges sorted and merged so that no two overlap or touch. Empty ranges are dropped. */
 export function normalize(ranges: Array<TimeRange>): Array<TimeRange> {
 	const sorted = R.sortBy(
 		ranges.filter((range) => range.endsAt > range.startsAt),
@@ -196,10 +177,7 @@ export function normalize(ranges: Array<TimeRange>): Array<TimeRange> {
 	return merged;
 }
 
-/**
- * Effective availability: what is left of `ranges` once every busy block is cut
- * out of them. A commitment always wins over what the user reported.
- */
+/** What is left of `ranges` once every busy block is cut out: a commitment always wins over what was reported. */
 export function subtract(
 	ranges: Array<TimeRange>,
 	busy: Array<TimeRange>,
@@ -229,10 +207,7 @@ export function subtract(
 	return remaining;
 }
 
-/**
- * The parts of the ranges that fall inside `window`, sorted and merged. Used to
- * keep one week's view from picking up windows that belong to the next.
- */
+/** The parts of the ranges inside `window`, sorted and merged. Keeps one week's view from picking up the next week's windows. */
 export function clip(
 	ranges: Array<TimeRange>,
 	window: TimeRange,
@@ -246,13 +221,10 @@ export function clip(
 }
 
 /**
- * How one person's schedule relates to an event's window. A busy block
- * overlapping the window wins over anything reported — the person is committed
- * elsewhere, whether or not their schedule is known. Otherwise the reported
- * slots either cover the window (`available`, with the overlapping ranges as
- * reported), cover part of it (`partial`, with the overlap clipped to the
- * window so it reads as "which part"), miss it entirely (`unavailable`) or do
- * not exist (`unknown`).
+ * How one person's schedule relates to an event's window. A busy block overlapping it
+ * wins over anything reported (committed elsewhere, schedule known or not). Otherwise the
+ * slots cover the window (`available`, ranges as reported), part of it (`partial`, overlap
+ * clipped to the window), miss it (`unavailable`) or do not exist (`unknown`).
  */
 export function availabilityInWindow({
 	reported,
@@ -286,11 +258,9 @@ export function availabilityInWindow({
 }
 
 /**
- * The windows the team could play in: spans
- * where `minPlayers` of the members (`FULL`) or one fewer (`ONE_SHORT`) are all
- * free from the first minute of the window to the last. Windows shorter than
- * `minDurationMinutes` are left out, as is any `ONE_SHORT` window that already
- * contains a `FULL` one.
+ * Spans where `minPlayers` members (`FULL`) or one fewer (`ONE_SHORT`) are free throughout.
+ * Windows shorter than `minDurationMinutes` are dropped, as is a `ONE_SHORT` window
+ * containing a `FULL` one.
  */
 export function playableWindows({
 	members,
@@ -335,10 +305,7 @@ export function snapMinutes(
 	return Math.round(minutes / step) * step;
 }
 
-/**
- * Splits the members' availability into the spans between every start and end
- * of it, each with the members free for the whole span.
- */
+/** Splits the members' availability at every start/end into spans, each with the members free throughout. */
 function availabilitySegments(members: Array<MemberAvailability>) {
 	const normalized = members.map((member) => ({
 		userId: member.userId,
@@ -372,11 +339,7 @@ function availabilitySegments(members: Array<MemberAvailability>) {
 
 type AvailabilitySegment = ReturnType<typeof availabilitySegments>[number];
 
-/**
- * The longest possible windows over which at least `threshold` of the same
- * members are free throughout. A window is only reported when no longer window
- * contains it.
- */
+/** Longest windows over which at least `threshold` of the same members are free; windows inside a longer one are skipped. */
 function maximalWindows({
 	segments,
 	threshold,
@@ -431,10 +394,7 @@ export function timeToMinutes(time: string) {
 	return hours * 60 + minutes;
 }
 
-/**
- * `HH:mm` on the clock at the given minutes from midnight. Minutes past 24h
- * wrap around, so the end of a range crossing midnight prints as e.g. `02:00`.
- */
+/** `HH:mm` at the given minutes from midnight; minutes past 24h wrap, so a range crossing midnight ends at e.g. `02:00`. */
 export function minutesToTime(minutes: number) {
 	const onClock = ((minutes % DAY_MINUTES) + DAY_MINUTES) % DAY_MINUTES;
 
@@ -444,9 +404,8 @@ export function minutesToTime(minutes: number) {
 }
 
 /**
- * Editor day range of the given start and end times. An end earlier than the
- * start means the range crosses midnight; an end equal to the start is an
- * empty range (dropped by {@link mergedDayRanges}).
+ * Editor day range of the given times. An end before the start crosses midnight;
+ * an end equal to the start is an empty range (dropped by {@link mergedDayRanges}).
  */
 export function dayRangeFromTimes(start: string, end: string): DayTimeRange {
 	const startMinutes = timeToMinutes(start);
@@ -458,10 +417,7 @@ export function dayRangeFromTimes(start: string, end: string): DayTimeRange {
 	};
 }
 
-/**
- * The ranges of one day track sorted and merged so that no two of them overlap
- * or touch. Empty ranges are dropped.
- */
+/** One day track's ranges sorted and merged so that no two overlap or touch. Empty ranges are dropped. */
 export function mergedDayRanges(
 	ranges: Array<DayTimeRange>,
 ): Array<DayTimeRange> {
@@ -476,19 +432,16 @@ interface TrackWindowArgs {
 }
 
 /**
- * Latest minute a range may start on: the last step before midnight. A range
- * belongs to the day it starts on, so a start past midnight would silently be
- * another day's range — the track's post-midnight zone only extends ends.
+ * Last step before midnight. A range belongs to the day it starts on, so a start past
+ * midnight would silently be another day's range — the post-midnight zone only extends ends.
  */
 const MAX_RANGE_START = DAY_MINUTES - AVAILABILITY.SLOT_STEP_MINUTES;
 
 /**
- * Range painted by dragging on an empty part of a day track from `anchor` to
- * `cursor` (both minutes from midnight): ends snapped to the entry step, at
- * least one step long and kept inside the track. The start is kept before
- * midnight — a paint anchored past it grows leftwards from the day's last
- * step. Painting cannot start on a wall (a commitment) but may extend across
- * one — null when the anchor is inside a wall.
+ * Range painted by dragging an empty part of a day track from `anchor` to `cursor` (minutes
+ * from midnight): snapped to the entry step, at least one step long, inside the track, start
+ * kept before midnight (a paint anchored past it grows leftwards from the day's last step).
+ * Null when the anchor is inside a wall (a commitment); a paint may still extend across one.
  */
 export function paintedRange({
 	anchor,
@@ -524,10 +477,7 @@ export function paintedRange({
 	return { start, end };
 }
 
-/**
- * `range` moved by `delta` minutes: the move is snapped to the entry step and
- * stopped at the track edges, with the start kept before midnight.
- */
+/** `range` moved by `delta` minutes, snapped to the entry step, stopped at the track edges, start kept before midnight. */
 export function movedRange({
 	range,
 	delta,
@@ -548,11 +498,7 @@ export function movedRange({
 	return { start, end: start + length };
 }
 
-/**
- * `range` with one edge dragged to `cursor`: snapped to the entry step, kept
- * at least one step long and stopped at the track edges, with the start kept
- * before midnight.
- */
+/** `range` with one edge dragged to `cursor`: snapped, at least one step long, inside the track, start kept before midnight. */
 export function resizedRange({
 	range,
 	edge,
diff --git a/app/features/availability/core/Commitments.server.ts b/app/features/availability/core/Commitments.server.ts
index 979cf66f1..606cf6a34 100644
--- a/app/features/availability/core/Commitments.server.ts
+++ b/app/features/availability/core/Commitments.server.ts
@@ -10,16 +10,11 @@ import * as TournamentDuration from "./TournamentDuration";
 import { estimatedEndsAtWith } from "./TournamentDuration.server";
 
 /**
- * The busy blocks of the given users within the given window, keyed by user
- * id and sorted by start. A busy block overrides whatever availability the
- * user reported: effective availability = reported − busy blocks.
- *
- * Sourced from tournament registrations (start + estimated duration, see
- * {@link TournamentDuration.estimateSeconds}), accepted scrims (start + an
- * assumed length) and team events (their actual span). League registrations
- * are not blocks — a league runs over weeks and its matches are scheduled
- * separately. `excludeTournamentId` leaves that tournament's registrations
- * out, for surfaces asking "busy elsewhere" while looking at that tournament.
+ * Busy blocks of the users within the window, keyed by user id, sorted by start (effective
+ * availability = reported − busy). From tournament registrations (start + estimated duration,
+ * {@link TournamentDuration.estimateSeconds}), accepted scrims (start + assumed length) and team
+ * events (actual span). Leagues are not blocks, their matches are scheduled separately.
+ * `excludeTournamentId` leaves one tournament out, for "busy elsewhere" views of that tournament.
  */
 export async function busyBlocksByUserIds({
 	userIds,
diff --git a/app/features/availability/core/FriendSchedule.server.ts b/app/features/availability/core/FriendSchedule.server.ts
index 24b6615db..da02ce2f9 100644
--- a/app/features/availability/core/FriendSchedule.server.ts
+++ b/app/features/availability/core/FriendSchedule.server.ts
@@ -8,14 +8,9 @@ import * as Commitments from "./Commitments.server";
 import * as ScheduleWeek from "./ScheduleWeek";
 
 /**
- * The reportable weeks of the given users as the friends page's week modal
- * shows them, keyed by user id: nothing but the time they are free to play,
- * commitments already subtracted. Users who reported neither week are left out,
- * so a missing key is what "no schedule to show" means — and the friends page
- * both sorts and shows its calendar icon by that.
- *
- * Everyone asked about is a friend or a teammate of the viewer, which is what
- * makes their schedule theirs to see; the caller owns that guarantee.
+ * Reportable weeks keyed by user id, free time only (commitments subtracted). Users who reported
+ * neither week are left out; the friends page sorts and shows its calendar icon by the missing key.
+ * The caller guarantees everyone asked about is a friend or teammate of the viewer.
  */
 export async function findByUserIds({
 	userIds,
diff --git a/app/features/availability/core/MySchedule.server.ts b/app/features/availability/core/MySchedule.server.ts
index 0815ad60b..7c06961fe 100644
--- a/app/features/availability/core/MySchedule.server.ts
+++ b/app/features/availability/core/MySchedule.server.ts
@@ -14,10 +14,8 @@ export type MyScheduleData = SerializeFrom<
 >;
 
 /**
- * The user's own reported schedule for the editable weeks (current and next)
- * in their timezone, as the wall-clock representation the schedule editor
- * uses. Also carries the ranges of the week before the current one for the
- * "Copy last week" prefill.
+ * The user's reported current and next week in their timezone as the editor's wall-clock
+ * representation, plus the week before for the "Copy last week" prefill.
  */
 export async function myScheduleData(userId: number) {
 	const timezone = getViewerTimezone() ?? "UTC";
diff --git a/app/features/availability/core/RegistrationAvailability.server.ts b/app/features/availability/core/RegistrationAvailability.server.ts
index ef3189cd6..95153fe59 100644
--- a/app/features/availability/core/RegistrationAvailability.server.ts
+++ b/app/features/availability/core/RegistrationAvailability.server.ts
@@ -13,15 +13,9 @@ export type RegistrationAvailability = Awaited<
 >;
 
 /**
- * Availability of the given users for a tournament's estimated window
- * (start to {@link estimatedEndsAt}), for the registration
- * page's availability panel. The tournament's own registrations do not count
- * as being busy — the panel asks whether people can play this very event.
- *
- * When the event starts past the reportable horizon there is nothing to
- * compute: every schedule would be unknown, so the result is only when
- * schedules for the event's week open up (the Monday its week becomes the
- * "next week").
+ * Availability of the users for the tournament's estimated window (start to
+ * {@link estimatedEndsAt}); its own registrations don't count as busy. Past the reportable
+ * horizon every schedule would be unknown, so the result is only when the event's week opens up.
  */
 export async function registrationAvailability({
 	tournament,
diff --git a/app/features/availability/core/RosterSchedule.server.ts b/app/features/availability/core/RosterSchedule.server.ts
index 04b9ba914..6a0ff69f7 100644
--- a/app/features/availability/core/RosterSchedule.server.ts
+++ b/app/features/availability/core/RosterSchedule.server.ts
@@ -19,13 +19,10 @@ export type RosterScheduleData = SerializeFrom<
 >;
 
 /**
- * Effective availability of the given users over the reportable horizon, laid
- * out as the viewer-local weeks and days the schedule surfaces render on.
- *
- * Which of these users make up a roster is only known in the browser (the
- * scrim post form's team select, its pick-up member search), so the roster's
- * shared free time is not resolved here — the members come out one by one and
- * {@link Availability.playableWindows} merges the picked ones client side.
+ * Effective availability of the users over the reportable horizon as viewer-local weeks and
+ * days. Which users form a roster is only known in the browser (scrim post form's team select,
+ * pick-up search), so members come out one by one and {@link Availability.playableWindows}
+ * merges the picked ones client side.
  */
 export async function rosterScheduleData({
 	userIds,
@@ -114,13 +111,9 @@ function weekView({ range, timezone }: { range: TimeRange; timezone: string }) {
 }
 
 /**
- * What the given users' schedules say about each of the given windows: what
- * they reported inside it, the commitments overriding that and whether they
- * filled in the week it falls in at all.
- *
- * The windows are resolved in one go so that a page showing many of them (the
- * scrim browsing page's fit indicators) reads the schedules once. Windows past
- * the reportable horizon are left out — nothing could be known about them.
+ * What the users' schedules say about each window: reported ranges inside it, overriding
+ * commitments and whether the week was filled in at all. Resolved in one go so a page with many
+ * windows (scrim fit indicators) reads the schedules once. Windows past the horizon are left out.
  */
 export async function windowSchedules({
 	windows,
@@ -129,8 +122,7 @@ export async function windowSchedules({
 	windows: Array<TimeRange & { id: number }>;
 	userIds: Array<number>;
 }) {
-	// the horizon's last week starts at the current week's start at the latest,
-	// so nothing inside it reaches this far
+	// the horizon's last week starts at the current week's start at the latest, so nothing inside it reaches this far
 	const horizonEndsAt = dateToDatabaseTimestamp(
 		addWeeks(new Date(), AVAILABILITY.WEEK_HORIZON),
 	);
@@ -162,8 +154,7 @@ export async function windowSchedules({
 
 			return {
 				userId,
-				// which week a window falls in is a question about the member's own
-				// clock, the same one they filled the week in on
+				// which week a window falls in goes by the member's own clock, the one they filled the week in on
 				reported: memberWeeks.some(
 					(week) =>
 						Availability.weekStartsAt(
diff --git a/app/features/availability/core/ScheduleWeek.ts b/app/features/availability/core/ScheduleWeek.ts
index 39e17a9bf..7a40c3f84 100644
--- a/app/features/availability/core/ScheduleWeek.ts
+++ b/app/features/availability/core/ScheduleWeek.ts
@@ -47,13 +47,9 @@ export function weekNumber(range: TimeRange, timezone: string) {
 }
 
 /**
- * One member's week bucketed into the viewer's days: what they are effectively
- * free for, the commitments taking time back and the notes they left.
- *
- * Slots are placed on the viewer-local day they start on, wherever their
- * author's week put them — the adjacent weeks' spillover included. What a
- * commitment takes back is cut out first: the days show when the member is
- * actually free.
+ * One member's week bucketed into the viewer's days: effective free time (commitments cut out
+ * first), the commitments and their notes. Slots land on the viewer-local day they start on,
+ * wherever the author's week put them, adjacent weeks' spillover included.
  */
 export function memberRow({
 	userId,
diff --git a/app/features/availability/core/TournamentDuration.server.ts b/app/features/availability/core/TournamentDuration.server.ts
index 9e9bf3063..82a9e03ed 100644
--- a/app/features/availability/core/TournamentDuration.server.ts
+++ b/app/features/availability/core/TournamentDuration.server.ts
@@ -13,10 +13,8 @@ interface EstimatedTournament {
 }
 
 /**
- * When a tournament is estimated to end: its start plus
- * {@link TournamentDuration.estimateSeconds}, sized by the count the event is
- * expected to draw rather than the one registered so far. Every surface showing
- * or blocking out a tournament's window goes through this so the two agree.
+ * Start plus {@link TournamentDuration.estimateSeconds} sized by the expected team count. Every
+ * view showing or blocking out a tournament's window goes through this so they agree.
  */
 export async function estimatedEndsAt(tournament: EstimatedTournament) {
 	return estimatedEndsAtWith(tournament, await SeriesTeamCount.lookup());
diff --git a/app/features/availability/loaders/t.$customUrl.schedule.server.ts b/app/features/availability/loaders/t.$customUrl.schedule.server.ts
index 30a7af45c..5893b3859 100644
--- a/app/features/availability/loaders/t.$customUrl.schedule.server.ts
+++ b/app/features/availability/loaders/t.$customUrl.schedule.server.ts
@@ -160,10 +160,7 @@ function weekView({
 	};
 }
 
-/**
- * Tier of the best playable window starting on the given viewer-local day, the
- * same day a window renders its grid ranges on.
- */
+/** Tier of the best playable window starting on the viewer-local day (the day it renders its grid ranges on). */
 function bestWindowTierOfDay({
 	date,
 	windows,
diff --git a/app/features/availability/routes/t.$customUrl.schedule.module.css b/app/features/availability/routes/t.$customUrl.schedule.module.css
index de035697c..a05e0b568 100644
--- a/app/features/availability/routes/t.$customUrl.schedule.module.css
+++ b/app/features/availability/routes/t.$customUrl.schedule.module.css
@@ -11,9 +11,8 @@
 	color: var(--color-text);
 }
 
-/* Lets the grid size against the full content area instead of the page width
-   (the team layout renders its <main> in breakout mode), capped at the wide
-   page width and centered back under the normal-width column. */
+/* sizes the grid against the breakout <main> of the team layout, capped at the wide page width
+   and centered under the normal-width column */
 .gridScroll {
 	overflow-x: auto;
 
@@ -36,8 +35,7 @@
 		white-space: nowrap;
 	}
 
-	/* the member column centers between the row lines while the day cells stay
-	   a top-aligned list */
+	/* the member column centers between the row lines, the day cells stay a top-aligned list */
 	& tbody th[scope="row"] {
 		vertical-align: middle;
 	}
@@ -62,8 +60,7 @@
 	overflow: hidden;
 	text-overflow: ellipsis;
 
-	/* block-level so the link centers by the cell's vertical-align alone,
-	   without the descender gap an inline box leaves under the baseline */
+	/* block-level so the link centers by vertical-align alone, without an inline box's descender gap */
 	& .memberLink {
 		display: flex;
 	}
diff --git a/app/features/badges/BadgeRepository.server.ts b/app/features/badges/BadgeRepository.server.ts
index a06452a66..2471fda6c 100644
--- a/app/features/badges/BadgeRepository.server.ts
+++ b/app/features/badges/BadgeRepository.server.ts
@@ -40,8 +40,7 @@ const withManagers = (eb: ExpressionBuilder<DB, "Badge">) => {
 	).as("managers");
 };
 
-// takes badgeId as a constant instead of correlating to "Badge"."id" so that
-// SQLite can push the predicate down into both arms of the BadgeOwner view
+// a constant badgeId (not correlated to "Badge"."id") lets SQLite push the predicate into both arms of the BadgeOwner view
 const withOwners = (eb: ExpressionBuilder<DB, "Badge">, badgeId: number) => {
 	return jsonArrayFrom(
 		eb
diff --git a/app/features/badges/components/BadgeDisplay.browser.test.tsx b/app/features/badges/components/BadgeDisplay.browser.test.tsx
index fcd17e222..846310f60 100644
--- a/app/features/badges/components/BadgeDisplay.browser.test.tsx
+++ b/app/features/badges/components/BadgeDisplay.browser.test.tsx
@@ -11,8 +11,7 @@ const badge = (id: number, displayName: string) => ({
 
 describe("BadgeDisplay", () => {
 	test("shows the badges of the props it is given after they change", async () => {
-		// e.g. navigating from one organization's page to another's: the route
-		// component stays mounted and only the badges prop changes
+		// e.g. navigating between organization pages: only the badges prop changes
 		const screen = await render(
 			<BadgeDisplay badges={[badge(1, "Alpha Invitational")]} />,
 		);
diff --git a/app/features/badges/components/BadgeDisplay.tsx b/app/features/badges/components/BadgeDisplay.tsx
index 1b5355a6f..4a6b310d1 100644
--- a/app/features/badges/components/BadgeDisplay.tsx
+++ b/app/features/badges/components/BadgeDisplay.tsx
@@ -36,7 +36,7 @@ export function BadgeDisplay({
 		badgeIdsKey(_badges),
 	);
 
-	// the badges given as props can change without a remount e.g. when navigating from one organization's page to another
+	// props can change without a remount e.g. navigating between organization pages
 	if (shownBadgeIds !== badgeIdsKey(_badges)) {
 		setShownBadgeIds(badgeIdsKey(_badges));
 		setBadges(_badges);
diff --git a/app/features/bracket-test/routes/bracket-test.tsx b/app/features/bracket-test/routes/bracket-test.tsx
index 73690ca35..778ea6773 100644
--- a/app/features/bracket-test/routes/bracket-test.tsx
+++ b/app/features/bracket-test/routes/bracket-test.tsx
@@ -269,7 +269,7 @@ function markMatchesCompleted(
 ) {
 	for (const match of data.match) {
 		if (!completedRoundIds.has(match.roundId)) continue;
-		// skip BYE matches (opponent slot is null entirely)
+		// BYE matches
 		if (match.opponent1 === null || match.opponent2 === null) continue;
 
 		match.opponent1 = { ...match.opponent1, score: 2 };
diff --git a/app/features/build-analyzer/analyzer-hooks.ts b/app/features/build-analyzer/analyzer-hooks.ts
index 2626bfb24..c5186e285 100644
--- a/app/features/build-analyzer/analyzer-hooks.ts
+++ b/app/features/build-analyzer/analyzer-hooks.ts
@@ -124,8 +124,7 @@ function validatedEffects({
 		const effectObj = SPECIAL_EFFECTS.find((e) => e.type === effect);
 		if (!effectObj) continue;
 
-		// e.g. even if OG effect is active in state
-		// it can't be on unless build has OG
+		// an ability effect can't be on unless the build has the ability
 		if (isAbility(effect) && !buildAbilities.includes(effect)) {
 			continue;
 		}
@@ -133,8 +132,7 @@ function validatedEffects({
 		result.push(effect);
 	}
 
-	// lde is a special case in that it's always
-	// considered active when in the build
+	// LDE is always considered active when in the build
 	if (buildAbilities.includes("LDE") && !result.includes("LDE")) {
 		result.push("LDE");
 	}
diff --git a/app/features/build-analyzer/analyzer-types.ts b/app/features/build-analyzer/analyzer-types.ts
index bb14ce95f..a965be6da 100644
--- a/app/features/build-analyzer/analyzer-types.ts
+++ b/app/features/build-analyzer/analyzer-types.ts
@@ -68,8 +68,6 @@ export interface BaseWeaponStats {
 	DamageParam_ValueMinCharge?: number;
 	BlastParam_SplashDamage?: number;
 	BlastParam_DistanceDamage?: Array<DistanceDamage>;
-	// DamageParam_ReduceStartFrame?: number;
-	// DamageParam_ReduceEndFrame?: number;
 	/** Brella shield HP */
 	CanopyHP?: number;
 	/** Amount of frames white ink (=no ink recovery during this time) takes */
@@ -100,9 +98,6 @@ export interface BaseWeaponStats {
 	InkConsume_SideStepParam?: number;
 	/** How much ink a fully charged Splatana shot consumes? */
 	InkConsumeFullCharge_ChargeParam?: number;
-	//InkConsumeMidCharge_ChargeParam?: number;
-	// SpeedInkConsumeMax_WeaponRollParam?: number;
-	// SpeedInkConsumeMin_WeaponRollParam?: number;
 
 	// Range parameters for shooters/blasters/sloshers/splatlings/dualies
 	/** Initial bullet velocity */
@@ -293,7 +288,7 @@ export interface AnalyzedBuild {
 		specialPoint: Stat;
 		specialLost: Stat;
 		specialLostSplattedByRP: Stat;
-		/** Seconds it takes Tenacity to fill the special gauge, keyed by how many active players the user's team is down. Only set if the build has Tenacity. */
+		/** Seconds for Tenacity to fill the special gauge, keyed by how many players the team is down. */
 		tenacitySecondsToSpecial?: Record<TenacityPlayerDeficit, number>;
 		mainWeaponWhiteInkSeconds?: number;
 		subWeaponWhiteInkSeconds: number;
diff --git a/app/features/build-analyzer/components/PerInkTankGrid.tsx b/app/features/build-analyzer/components/PerInkTankGrid.tsx
index 651dc91e1..4747bd0f9 100644
--- a/app/features/build-analyzer/components/PerInkTankGrid.tsx
+++ b/app/features/build-analyzer/components/PerInkTankGrid.tsx
@@ -233,8 +233,7 @@ function calculateGrid({
 	return withColors;
 }
 
-// this is a performance optimization over simply calling "buildStats"
-// as it would be doing a lot of unnecessary work
+// cheaper than calling "buildStats", which would do a lot of unnecessary work
 function inkTankOptionsWhenNSubsUsed({
 	issAP,
 	ismAP,
@@ -330,9 +329,8 @@ function generateHexCode({
 	const clampedValue = Math.max(minValue, Math.min(value, maxValue));
 	const normalizedPosition = (clampedValue - minValue) / (maxValue - minValue);
 
-	// Adjust saturation and brightness to lighten the colors
-	const saturationFactor = 0.5; // Adjust this to control the saturation
-	const brightnessFactor = 0.8; // Adjust this to control the brightness
+	const saturationFactor = 0.5;
+	const brightnessFactor = 0.8;
 
 	const red =
 		Math.floor(255 * (1 - normalizedPosition) * saturationFactor) +
diff --git a/app/features/build-analyzer/core/ability-points.ts b/app/features/build-analyzer/core/ability-points.ts
index dc298336d..3d69f3543 100644
--- a/app/features/build-analyzer/core/ability-points.ts
+++ b/app/features/build-analyzer/core/ability-points.ts
@@ -8,11 +8,7 @@ import invariant from "~/utils/invariant";
 import { MAIN_SLOT_AP, SUB_SLOT_AP } from "../analyzer-constants";
 import type { AbilityPoints } from "../analyzer-types";
 
-/**
- * Sums a build's stackable ability points per ability, accounting for
- * Ability Doubler doubling the sub slots of its row. Main-only abilities are
- * left out as they have no ability point value.
- */
+/** AP per stackable ability, Ability Doubler doubling its row's subs. Main-only abilities are left out. */
 export function buildToAbilityPoints(build: BuildAbilitiesTupleWithUnknown) {
 	const result: AbilityPoints = new Map();
 
@@ -37,7 +33,7 @@ export function buildToAbilityPoints(build: BuildAbilitiesTupleWithUnknown) {
 	return result;
 }
 
-/** Whether the ability stacks in sub slots as ability points (e.g. ISM) as opposed to a main-only ability (e.g. SJ). */
+/** Stacks as AP (e.g. ISM), as opposed to a main-only ability (e.g. SJ). */
 export function isStackableAbility(
 	ability: AbilityWithUnknown,
 ): ability is Ability {
@@ -48,7 +44,7 @@ export function isStackableAbility(
 	return abilityObj.type === "STACKABLE";
 }
 
-/** Whether the ability only exists in the main slot of one gear type (e.g. SJ). */
+/** Only exists in the main slot of one gear type (e.g. SJ). */
 export function isMainOnlyAbility(
 	ability: AbilityWithUnknown,
 ): ability is Ability {
diff --git a/app/features/build-analyzer/core/abilityChunksCalc.test.ts b/app/features/build-analyzer/core/abilityChunksCalc.test.ts
index 0cf946d8c..a51781c56 100644
--- a/app/features/build-analyzer/core/abilityChunksCalc.test.ts
+++ b/app/features/build-analyzer/core/abilityChunksCalc.test.ts
@@ -5,8 +5,7 @@ import type {
 } from "~/modules/in-game-lists/types";
 import { getAbilityChunksMapAsArray } from "./abilityChunksCalc";
 
-// Utility function that performs an order-agnostic check to see
-//  if the abilityChunksArray contains all elements from the expected output.
+// order-agnostic check that abilityChunksArray contains all expected elements
 function validateAbilityChunksArray(
 	abilityChunksArray: [AbilityWithUnknown, number][],
 	expectedOutput: (string | number)[][],
diff --git a/app/features/build-analyzer/core/abilityChunksCalc.ts b/app/features/build-analyzer/core/abilityChunksCalc.ts
index f9d040773..6622bb778 100644
--- a/app/features/build-analyzer/core/abilityChunksCalc.ts
+++ b/app/features/build-analyzer/core/abilityChunksCalc.ts
@@ -10,23 +10,18 @@ const MAIN_REQUIRED_ABILITY_CHUNKS_COUNT = 45;
 const PRIMARY_SLOT_ONLY_REQUIRED_ABILITY_CHUNKS_COUNT = 15;
 const SUB_REQUIRED_ABILITY_CHUNKS_COUNT = 10;
 
-// Ability Doubler: cost of adding a non-duplicate secondary ability only costs 3 ability chunks
-// Reference: https://splatoonwiki.org/wiki/Splatfest_Tee#Splatoon_3_2
+// Ability Doubler: a non-duplicate secondary ability costs 3 chunks, https://splatoonwiki.org/wiki/Splatfest_Tee#Splatoon_3_2
 const SUB_WITH_ABILITY_DOUBLER_REQUIRED_ABILITY_CHUNKS_COUNT = 3;
 
 export const ABILITIES_WITHOUT_CHUNKS = new Set(["UNKNOWN", "AD"]);
 
-/**
- * Ability chunks required to make the given build, as [ability, count] entries
- * sorted by count descending.
- */
+/** Chunks required for the build, as [ability, count] sorted by count descending. */
 export function getAbilityChunksMapAsArray(
 	build: BuildAbilitiesTupleWithUnknown,
 ) {
 	const abilityChunksMap: AbilityChunks = new Map<AbilityWithUnknown, number>();
 	updateAbilityChunksMap(abilityChunksMap, build);
 
-	// Sort by value (number, descending) first, then sort by name (string, ascending)
 	return Array.from(abilityChunksMap).sort(
 		(a, b) => b[1] - a[1] || a[0].localeCompare(b[0]),
 	);
@@ -41,20 +36,18 @@ function updateAbilityChunksMap(
 	for (const gear of build) {
 		let hasAbilityDoubler = false;
 
-		// Handles the incremental amount of ability chunks required for the same ability for 1 piece of gear
+		// chunk cost of the same ability escalates within one piece of gear
 		const abilityChunksMapForGear = new Map<AbilityWithUnknown, number>();
 
 		for (const [index, selectedAbility] of gear.entries()) {
 			if (!selectedAbility) continue;
 			if (ABILITIES_WITHOUT_CHUNKS.has(selectedAbility)) {
-				// Detect the presence of Ability Doubler in the Clothing gear slot
 				if (selectedAbility === "AD" && buildIndex === 1) {
 					hasAbilityDoubler = true;
 				}
 				continue;
 			}
 
-			// Ability is in main slot
 			if (index === 0) {
 				const primarySlotOnlyAbilityRef = abilities.filter(
 					(a) =>
@@ -62,8 +55,7 @@ function updateAbilityChunksMap(
 						a.abilityChunkTypesRequired.length > 0,
 				);
 
-				// Extra processing is required for Main abilities that are primary slot-only abilities,
-				//    as they are comprised of 3 stackable ability chunks at a lower ability chunk count than usual.
+				// primary slot-only abilities are made of 3 stackable chunks at a lower count than usual
 				if (primarySlotOnlyAbilityRef.length === 1) {
 					const primaryAbility = primarySlotOnlyAbilityRef[0];
 					if (!primaryAbility) continue;
@@ -82,12 +74,8 @@ function updateAbilityChunksMap(
 							MAIN_REQUIRED_ABILITY_CHUNKS_COUNT,
 					);
 				}
-			}
-
-			// Ability is in a sub slot
-			else {
-				// 1 Ability in sub slot = 10 chunks, 2 abilities = 20 chunks, 3 abilities = 30 chunks
-				// Also handle the edge case for when the piece of gear has Ability Doubler (3/6/9 chunks for 1/2/3 of the same ability)
+			} else {
+				// 10/20/30 chunks for 1/2/3 of the same sub ability, 3/6/9 with Ability Doubler
 				abilityChunksMapForGear.set(
 					selectedAbility,
 					(abilityChunksMapForGear.get(selectedAbility) ?? 0) +
diff --git a/app/features/build-analyzer/core/serializer.ts b/app/features/build-analyzer/core/serializer.ts
index 297648657..98b855499 100644
--- a/app/features/build-analyzer/core/serializer.ts
+++ b/app/features/build-analyzer/core/serializer.ts
@@ -7,11 +7,8 @@ import type {
 import { UNKNOWN_SHORT } from "../analyzer-constants";
 
 /**
- * Serializes a build to a comma separated string for use in URLs.
- *
- * Lives in its own module (instead of `core/utils.ts`) so that URL-building
- * code can import it without pulling the weapon params data into the eager
- * bundle.
+ * Comma separated build for URLs. Kept out of `core/utils.ts` so URL-building code doesn't pull
+ * the weapon params data into the eager bundle.
  */
 export function serializeBuild(build: BuildAbilitiesTupleWithUnknown) {
 	return build
diff --git a/app/features/build-analyzer/core/stats.ts b/app/features/build-analyzer/core/stats.ts
index 19b137db4..7e1dfed9c 100644
--- a/app/features/build-analyzer/core/stats.ts
+++ b/app/features/build-analyzer/core/stats.ts
@@ -221,8 +221,7 @@ function tenacitySecondsToSpecial({
 }: StatFunctionInput): AnalyzedBuild["stats"]["tenacitySecondsToSpecial"] {
 	if (!mainOnlyAbilities.includes("T")) return;
 
-	// Special Charge Up does not affect the rate Tenacity fills the gauge at
-	// so the unmodified amount of points needed is used here
+	// Special Charge Up does not affect Tenacity's fill rate, so the unmodified points are used
 	const secondsToSpecial = (playerDeficit: TenacityPlayerDeficit) =>
 		roundToNDecimalPlaces(
 			mainWeaponParams.SpecialPoint /
@@ -282,9 +281,7 @@ function subWeaponInkConsumptionPercentage(args: StatFunctionInput) {
 			(args.subWeaponParams.InkConsume * 100) / inkTankSize(args.weaponSplId),
 		),
 		value: roundToNDecimalPlaces(
-			// + 0.004 is a hack to avoid situation where the value is e.g. 50.0005
-			// -> rounds to 50% so it appears you can throw two subs
-			// which is not correct so we force the round upwards
+			// + 0.0045 forces e.g. 50.0005 to round up, else it shows 50% as if two subs fit
 			(subWeaponConsume(args).inkConsume * 100 + 0.0045) /
 				inkTankSize(args.weaponSplId),
 		),
@@ -407,8 +404,7 @@ function mainWeaponInkConsumeByType({
 		weapon: mainWeaponParams,
 	});
 
-	// these keys are always mutually exclusive i.e. even if inkConsumeTypeToParamsKeys() returns many keys
-	// then weapon params of this weapon should only have one defined
+	// the keys are mutually exclusive, a weapon's params only ever define one of them
 	for (const key of inkConsumeTypeToParamsKeys(type)) {
 		const value = mainWeaponParams[key];
 
@@ -417,8 +413,7 @@ function mainWeaponInkConsumeByType({
 		}
 	}
 
-	// not all weapons have all ink consume types
-	// i.e. blaster does not (hopefully) perform dualie dodge rolls
+	// not all weapons have all ink consume types (a blaster has no dodge roll)
 	return;
 }
 
@@ -1442,7 +1437,7 @@ function subQsjBoost(
 
 	const SUB_QSJ_BOOST_KEY = "BRU";
 
-	// Lean: This is the base that is used with their weird formula (I didn't even bother renaming the vars and just used what my disassembler gave me)
+	// Lean: base of their weird formula, var names as given by the disassembler
 	const calculate = (ap: number) => {
 		const multiplier = abilityValues({
 			key: "SubSpecUpParam",
diff --git a/app/features/build-analyzer/core/utils.ts b/app/features/build-analyzer/core/utils.ts
index 7398a30fb..747bfd8be 100644
--- a/app/features/build-analyzer/core/utils.ts
+++ b/app/features/build-analyzer/core/utils.ts
@@ -171,12 +171,7 @@ const rawMultiShot: Partial<Record<MainWeaponId, number>> = {
 	3050: 2,
 };
 
-/**
- * Returns the multi-shot count for a given weapon ID. Multi-shot refers to the number of projectiles fired in a single shot,
- * e.g. H-3 Nozzlenose fires 3 projectiles per one trigger press.
- *
- * @returns The multi-shot count associated with the weapon, or `undefined` if not found.
- */
+/** Projectiles fired per trigger press (e.g. 3 for H-3 Nozzlenose), or `undefined` for single-shot weapons. */
 export const weaponIdToMultiShotCount = (weaponId: MainWeaponId) => {
 	return rawMultiShot[
 		weaponIdToBaseWeaponId(weaponId) as keyof typeof rawMultiShot
diff --git a/app/features/build-analyzer/routes/analyzer.module.css b/app/features/build-analyzer/routes/analyzer.module.css
index 17e895950..c27774941 100644
--- a/app/features/build-analyzer/routes/analyzer.module.css
+++ b/app/features/build-analyzer/routes/analyzer.module.css
@@ -255,8 +255,7 @@
 	align-items: center;
 }
 
-/* doubled class to outweigh the Table cell padding rule so the popover
-   button does not make these rows taller than the text-only rows */
+/* doubled class to outweigh the Table cell padding so the popover button doesn't make rows taller */
 .popoverCell.popoverCell {
 	padding-block: 0;
 }
@@ -268,13 +267,11 @@
 	--chart-height: 250px;
 	--chart-width: 340px;
 
-	/* Let the chart shrink to whatever height react-aria allots the popover
-	   (so it never gets clipped) by threading a flex column down to it. */
+	/* flex column threaded down so the chart shrinks to the popover height instead of clipping */
 	display: flex;
 	flex-direction: column;
 
-	/* The chart shrinks to fit, so no scroll is needed here; keep visible so the
-	   hover tooltip can overlay the chart instead of being clipped. */
+	/* visible so the hover tooltip can overlay the chart instead of being clipped */
 	overflow: visible;
 }
 
diff --git a/app/features/build-analyzer/routes/analyzer.tsx b/app/features/build-analyzer/routes/analyzer.tsx
index a2a5eaabd..324cab42e 100644
--- a/app/features/build-analyzer/routes/analyzer.tsx
+++ b/app/features/build-analyzer/routes/analyzer.tsx
@@ -112,7 +112,7 @@ export const handle: SendouRouteHandle = {
 	}),
 };
 
-// Resolves this Github issue: https://github.com/sendou-ink/sendou.ink/issues/1053
+// https://github.com/sendou-ink/sendou.ink/issues/1053
 export const shouldRevalidate: ShouldRevalidateFunction = () => false;
 
 export default function BuildAnalyzerShell() {
@@ -254,8 +254,7 @@ function BuildAnalyzerPage() {
 		),
 	].filter(Boolean);
 
-	// Handles edge case where a primary slot-only ability (e.g. Ninja Squid) is selected & the 'abilityPoints' count is still 0,
-	//  and also fixes an edge case with Ability Doubler as the only ability in the build
+	// a primary slot-only ability (e.g. Ninja Squid) or Ability Doubler alone leaves abilityPoints at 0
 	const showAbilityChunksRequired: boolean = build.some(
 		(gear) =>
 			gear.filter((ability) => !ABILITIES_WITHOUT_CHUNKS.has(ability)).length,
@@ -335,8 +334,7 @@ function BuildAnalyzerPage() {
 																.every((ability) => ability === "UNKNOWN") &&
 															focused === 1;
 
-														// if we don't do this the
-														// build2 would be duplicated
+														// otherwise build2 would be duplicated
 														if (buildWasEmptied) {
 															handleChange({
 																newBuild: build2,
@@ -1482,10 +1480,7 @@ function StatCard({
 		if (isStaticValue) return false;
 		if (isComparing) return true;
 
-		// slightly hacky but handles the edge case
-		// where baseValue === value which can happen when
-		// you have Ninja Squid and stack swim speed
-		// -> we still want to show the build value
+		// baseValue === value can happen with Ninja Squid + stacked swim speed; still show the build value
 		return [stat[0].modifiedBy].flat().some((ability) => {
 			const hasStackable = (abilityPoints.get(ability) ?? 0) > 0;
 			const hasEffect = baseValue !== stat[0].value;
@@ -1823,9 +1818,7 @@ function ConsumptionTable({
 
 						const cells: React.ReactNode[] = [];
 
-						// weird using basic for loop in react code but here we are essentially
-						// zipping these two arrays into one cell and if one of the arrays
-						// doesn't have value then it shows as a dash instead
+						// zips the two arrays into one cell, a missing value shows as a dash
 						for (
 							let i = 0;
 							i <
diff --git a/app/features/build-stats/build-stats-utils.ts b/app/features/build-stats/build-stats-utils.ts
index 31c7a0165..270762349 100644
--- a/app/features/build-stats/build-stats-utils.ts
+++ b/app/features/build-stats/build-stats-utils.ts
@@ -94,8 +94,6 @@ export function abilityPointCountsToAverages({
 	};
 }
 
-// ---
-
 export function popularBuilds(rows: Array<PopularBuildsRow>) {
 	let previousCount: number;
 	return rows.map(({ abilitiesSignature, count }) => {
diff --git a/app/features/builds/BuildRepository.server.test.ts b/app/features/builds/BuildRepository.server.test.ts
index 6796fc522..b934f0d81 100644
--- a/app/features/builds/BuildRepository.server.test.ts
+++ b/app/features/builds/BuildRepository.server.test.ts
@@ -12,8 +12,7 @@ import * as BuildRepository from "./BuildRepository.server";
 
 const users = UserFactory.pool();
 
-// Splattershot (40) is the canonical base, Hero Shot Replica (45) is an alt skin
-// that should be folded to 40 by the canonical id mapping.
+// Hero Shot Replica (45) is an alt skin folded to Splattershot (40) by the canonical id mapping
 const SPLATTERSHOT: MainWeaponId = 40;
 const HERO_SHOT_REPLICA: MainWeaponId = 45;
 const SPLATTERSHOT_NOUVEAU: MainWeaponId = 41;
@@ -318,9 +317,7 @@ describe("BuildRepository.findAllPopularAbilitiesByWeaponId", () => {
 	});
 
 	test("counts each user at most once across signature buckets", async () => {
-		// Each user has two Splattershot builds with different signatures.
-		// Without per-user dedup, both users would inflate both buckets and
-		// the total count across rows would be 4 instead of <=2.
+		// without per-user dedup both users would inflate both buckets (4 total instead of <= 2)
 		await createBuild({ ownerId: users.id(1) });
 		await createBuild({ ownerId: users.id(1), abilities: SS_ABILITIES });
 		await createBuild({ ownerId: users.id(2) });
diff --git a/app/features/builds/BuildRepository.server.ts b/app/features/builds/BuildRepository.server.ts
index f8eebc418..ef37aa191 100644
--- a/app/features/builds/BuildRepository.server.ts
+++ b/app/features/builds/BuildRepository.server.ts
@@ -180,8 +180,7 @@ export async function findOwnerIdById(buildId: number) {
 export async function findAllAbilityPointAverages(
 	weaponSplId?: MainWeaponId | null,
 ) {
-	// Sum tables only contain rows for public builds,
-	// so the queries below need no private filter and no `Build` join.
+	// sum tables only hold public builds, so no private filter or `Build` join is needed
 	if (typeof weaponSplId === "number") {
 		return db
 			.selectFrom("BuildWeaponAbility")
@@ -213,11 +212,9 @@ export async function findAllAbilityPointAverages(
 export async function findAllPopularAbilitiesByWeaponId(
 	weaponSplId: MainWeaponId,
 ) {
-	// One signature per user — otherwise a user with several builds for the
-	// same weapon (e.g. three different Slosher loadouts) would inflate three
-	// different signature buckets. The CTE picks each user's most recently
-	// updated public build for the weapon via SQLite's MAX() + bare columns
-	// rule (https://www.sqlite.org/lang_select.html#bareagg).
+	// one signature per user so several builds for the same weapon don't inflate several buckets;
+	// the CTE picks the most recently updated one via SQLite's MAX() + bare columns rule
+	// (https://www.sqlite.org/lang_select.html#bareagg)
 	return db
 		.with("UserSignature", (cte) =>
 			cte
@@ -304,9 +301,7 @@ export async function findAllByWeaponId(
 	return rows.map((row) => buildRowToResult(row, shouldSortAbilities));
 }
 
-/** Recomputes `BuildWeapon.sortValue` for every (build, weapon) from scratch
- * (plus tier + per-weapon top500). When `userId` is provided, only the builds
- * owned by that user are recomputed. */
+/** Recomputes `BuildWeapon.sortValue` (plus tier + per-weapon top500), for one user's builds if given. */
 export async function recalculateAllSortValues(
 	userId?: number,
 	trx?: Transaction<DB>,
@@ -320,8 +315,6 @@ export async function recalculateAllSortValues(
 		.execute((newTrx) => recalculateSortValues(newTrx, userId));
 }
 
-// ---
-
 async function recalculateSortValues(trx: Transaction<DB>, userId?: number) {
 	// Pass 1: tier*2 + 1 for public, NULL for private.
 	await trx
@@ -529,9 +522,8 @@ async function insertBuildChildren(
 		)
 		.execute();
 
-	// Private builds are excluded from the sum tables so the stats queries can
-	// run as pure covering-index scans. Visibility flips are handled implicitly
-	// by `update`'s delete-then-reinsert.
+	// private builds are excluded so the stats queries are pure covering-index scans;
+	// visibility flips are handled by `update`'s delete-then-reinsert
 	if (args.isPrivate) return;
 
 	await trx
diff --git a/app/features/builds/builds-constants.ts b/app/features/builds/builds-constants.ts
index 25a55b754..0e54bb0c5 100644
--- a/app/features/builds/builds-constants.ts
+++ b/app/features/builds/builds-constants.ts
@@ -6,10 +6,9 @@ export const MAX_BUILD_FILTERS = 6;
 type Patch = { patch: string; date: string };
 
 /**
- * Every Splatoon 3 game version that introduced weapon parameter changes, newest first,
- * with its release date (`YYYY-MM-DD`). The version strings match those tracked in the
- * weapon params data (`metadata.versions`), so this is the single source of patch dates
- * used by both the builds date filter and the weapon params patch history.
+ * Every game version with weapon parameter changes, newest first, dates as `YYYY-MM-DD`. Versions
+ * match the weapon params data's `metadata.versions`; single source for the builds date filter and
+ * the patch history.
  */
 export const PATCHES: Array<Patch> = [
 	{ patch: "11.3.0", date: "2026-08-19" },
@@ -48,11 +47,7 @@ export const PATCHES: Array<Patch> = [
 
 const RECENT_PATCH_MAX_AGE_IN_DAYS = 365;
 
-/**
- * The subset of {@link PATCHES} released within roughly a year of the newest patch. Used
- * for the builds date filter so its dropdown stays short while always covering the patches
- * builds are most likely to be filtered against.
- */
+/** {@link PATCHES} from roughly the last year, keeping the builds date filter dropdown short. */
 export const RECENT_PATCHES: Array<Patch> = PATCHES.filter(
 	({ date }) =>
 		differenceInCalendarDays(new Date(PATCHES[0].date), new Date(date)) <=
diff --git a/app/features/builds/core/filter.server.ts b/app/features/builds/core/filter.server.ts
index 6ae621b15..0cf1dec2c 100644
--- a/app/features/builds/core/filter.server.ts
+++ b/app/features/builds/core/filter.server.ts
@@ -19,11 +19,7 @@ interface BuildFilters {
 	date: string | null;
 }
 
-/**
- * Filters an array of builds based on the provided filter criteria and returns up to a specified count of matching builds.
- *
- * Filters are applied on "AND" basis, meaning all filters must match for a build to be included in the result.
- */
+/** Up to `count` builds matching every filter (AND). */
 export function filterBuilds<T extends PartialBuild>({
 	abilities,
 	mode,
diff --git a/app/features/calendar/CalendarRepository.server.ts b/app/features/calendar/CalendarRepository.server.ts
index 32f8eeedd..edd8439df 100644
--- a/app/features/calendar/CalendarRepository.server.ts
+++ b/app/features/calendar/CalendarRepository.server.ts
@@ -168,7 +168,7 @@ function findAllBetweenTwoTimestampsQuery({
 			"CalendarEvent.name",
 			"CalendarEvent.tags",
 			"CalendarEventDate.startsAt",
-			// events get grouped to their closest :00 or :30 so for example users can't make their event start at :59 to make it show at the top
+			// grouped to the closest :00 or :30 so a :59 start can't game its way to the top
 			sql<number>`(("CalendarEventDate"."startsAt" + 900) / 1800) * 1800`.as(
 				"normalizedStartsAt",
 			),
@@ -360,10 +360,8 @@ export async function findById(
 }
 
 /**
- * Tournaments from the past year organized by the user (as the author, via an
- * organization ADMIN/ORGANIZER role or as tournament staff ORGANIZER), newest first.
- * Only the latest event of each tournament series is included, unless there are fewer
- * series than spots to show, in which case the next newest events fill the rest.
+ * Past year's tournaments the user organized (author, organization ADMIN/ORGANIZER or staff
+ * ORGANIZER), newest first. Latest event per series only, the next newest filling spare spots.
  */
 export async function findRecentTournamentsByOrganizerUserId(userId: number) {
 	const tournaments = await db
@@ -479,10 +477,7 @@ export async function findResultsByEventId(eventId: number) {
 		.execute();
 }
 
-/**
- * Players of the podium teams of the given events, one row per player. Players reported as plain
- * text rather than linked to an account have a `null` id.
- */
+/** Podium players of the events, one row each; players reported as plain text have a `null` id. */
 export async function findTopThreeResultsByEventIds(eventIds: number[]) {
 	if (eventIds.length === 0) return [];
 
diff --git a/app/features/calendar/actions/calendar.new.server.ts b/app/features/calendar/actions/calendar.new.server.ts
index 5678dfbb0..028c16555 100644
--- a/app/features/calendar/actions/calendar.new.server.ts
+++ b/app/features/calendar/actions/calendar.new.server.ts
@@ -164,7 +164,6 @@ export const action: ActionFunction = async ({ request }) => {
 				commonArgs.isDraft = false;
 			}
 		} else {
-			// editing regular calendar event
 			requirePermission(eventToEdit, "EDIT");
 		}
 
@@ -218,7 +217,7 @@ export const action: ActionFunction = async ({ request }) => {
 	throw redirect(calendarEventPage(createdEventId));
 };
 
-/** Resolves the validated bracket progression from the `brackets` + `progression` form fields (already validated by the schema's refine). */
+/** Bracket progression from the `brackets` + `progression` fields, already validated by the schema's refine. */
 function bracketProgressionFromFormData(data: {
 	toToolsEnabled: boolean;
 	brackets: Parameters<typeof formValuesToInputBrackets>[0];
@@ -233,7 +232,7 @@ function bracketProgressionFromFormData(data: {
 	return Progression.isBrackets(validated) ? validated : null;
 }
 
-/** Checks user has permissions to create a tournament in this organization */
+/** The user may create a tournament in this organization. */
 async function validateOrganization({
 	userId,
 	organizationId,
diff --git a/app/features/calendar/calendar-constants.ts b/app/features/calendar/calendar-constants.ts
index adb183f60..04d5e62d0 100644
--- a/app/features/calendar/calendar-constants.ts
+++ b/app/features/calendar/calendar-constants.ts
@@ -62,7 +62,7 @@ export const CALENDAR_EVENT = {
 	DISCORD_INVITE_CODE_MAX_LENGTH: 50,
 	BRACKET_URL_MAX_LENGTH: 200,
 	MAX_AMOUNT_OF_DATES: 5,
-	/** Calendar event tag that is persisted in the database */
+	/** Tags persisted in the database */
 	TAGS: Object.keys(tags) as Array<CalendarEventTag>,
 };
 
@@ -86,7 +86,7 @@ export const REG_CLOSES_AT_OPTIONS = [
 
 export type RegClosesAtOption = (typeof REG_CLOSES_AT_OPTIONS)[number];
 
-/** How many days are shown at the /calendar page at a time (full week from Monday to Sunday) */
+/** Days shown on /calendar at a time (Monday to Sunday) */
 export const DAYS_SHOWN_AT_A_TIME = 7;
 
 /** Tags not shown on the tournament cards */
diff --git a/app/features/calendar/calendar-hooks.ts b/app/features/calendar/calendar-hooks.ts
index 8c341c25e..fd23aa66e 100644
--- a/app/features/calendar/calendar-hooks.ts
+++ b/app/features/calendar/calendar-hooks.ts
@@ -13,12 +13,7 @@ interface CollapsedEvents {
 	onToggleHidden: () => void;
 }
 
-/**
- * Custom hook to manage hiding/showing calendar events. Handles collapsing adjacent times given both of them have only hidden events.
- * E.g. 10pm with all hidden and 11pm with all hidden should be shown in one section as 10pm - 11pm to the user.
- *
- * @param eventTimes - Array of event times as returned by the calendar data loader.
- */
+/** Hiding/showing calendar events, collapsing adjacent times with only hidden events into one section (10pm - 11pm). */
 export function useCollapsableEvents(
 	eventTimes: CalendarLoaderData["eventTimes"],
 ) {
@@ -60,7 +55,7 @@ export function useCollapsableEvents(
 			date,
 			hiddenShown,
 			onToggleHidden: () => {
-				// if we clicked a range section, uncollapse it
+				// a range section uncollapses
 				if (containedTimes.size > 1) {
 					setCollapsingDisabled(true);
 				}
diff --git a/app/features/calendar/calendar-new-schemas.ts b/app/features/calendar/calendar-new-schemas.ts
index 85733ee50..93a89754a 100644
--- a/app/features/calendar/calendar-new-schemas.ts
+++ b/app/features/calendar/calendar-new-schemas.ts
@@ -35,8 +35,7 @@ const calendarEventDateField = datetime({
 	max: calendarEventMaxDate,
 });
 
-// extracted so its literal item values don't widen to `string` in the
-// object's inferred value type
+// extracted so the literal item values don't widen to `string` in the object's inferred value type
 const toToolsModeField = select({
 	label: "labels.mapPickingStyle",
 	items: [
@@ -69,9 +68,8 @@ export const calendarNewBaseSchema = v.object({
 		bottomText: "bottomTexts.bioMarkdown",
 		maxLength: CALENDAR_EVENT.RULES_MAX_LENGTH,
 	}),
-	// calendar events can span multiple dates; tournaments always have exactly one
-	// (`startTime`). Only the relevant field is rendered, and the other stays at its
-	// empty initial value — `calendarNewSyncRefine` enforces the right one per type.
+	// calendar events span multiple dates, tournaments have exactly one (`startTime`); only the
+	// relevant field is rendered, `calendarNewSyncRefine` enforces the right one per type
 	date: array({
 		label: "labels.dates",
 		max: CALENDAR_EVENT.MAX_AMOUNT_OF_DATES,
@@ -128,8 +126,7 @@ export const calendarNewBaseSchema = v.object({
 	}),
 	toToolsMode: toToolsModeField,
 	pool: customField({ initialValue: "" }, v.optional(v.string())),
-	// the two bracket progression fields are only rendered (and validated) for
-	// tournaments; for calendar events both stay at their empty initial value
+	// only rendered (and validated) for tournaments, calendar events keep the empty initial values
 	brackets: bracketsFormField,
 	progression: progressionFormField,
 	isRanked: toggle({
diff --git a/app/features/calendar/calendar-progression-form.ts b/app/features/calendar/calendar-progression-form.ts
index 8ace15483..736f759b6 100644
--- a/app/features/calendar/calendar-progression-form.ts
+++ b/app/features/calendar/calendar-progression-form.ts
@@ -44,8 +44,7 @@ export interface ProgressionFormValue {
 	sources: ProgressionSourceFormValue[];
 }
 
-// extracted so their literal item values don't widen to `string` in the
-// fieldset's inferred value type
+// extracted so the literal item values don't widen to `string` in the fieldset's inferred value type
 const bracketTypeField = select({
 	label: "labels.format",
 	items: [
@@ -202,7 +201,7 @@ function newBracketFormValue(): BracketFormValue {
 	};
 }
 
-/** Progression form field value appended when a new bracket is added: a follow-up bracket sourcing teams from the first bracket. */
+/** Progression entry of a newly added bracket: a follow-up sourcing teams from the first bracket. */
 export function newFollowUpProgressionEntry(): ProgressionFormValue {
 	return { source: "BRACKET", sources: [newProgressionSource()] };
 }
@@ -295,7 +294,7 @@ export function progressionToFormValues(
 	};
 }
 
-/** Does the bracket of the given progression source advance teams via a Swiss early advance threshold (meaning placements are not specified)? */
+/** Whether the source bracket advances teams via a Swiss early advance threshold (so placements are not specified). */
 export function sourceBracketHasEarlyAdvance(
 	brackets: BracketFormValue[],
 	source: ProgressionSourceFormValue,
@@ -304,7 +303,7 @@ export function sourceBracketHasEarlyAdvance(
 	return sourceBracket?.type === "swiss" && sourceBracket.earlyAdvance;
 }
 
-/** Validates the `brackets` + `progression` form values together via {@link Progression.validatedBrackets}, attaching each error to the closest form field. */
+/** Validates `brackets` + `progression` via {@link Progression.validatedBrackets}, attaching each error to the closest field. */
 export function validateBracketProgressionFormValues(
 	brackets: BracketFormValue[],
 	progression: ProgressionFormValue[],
@@ -373,8 +372,7 @@ function progressionErrorPaths(
 		case "GAP_IN_PLACEMENTS":
 		case "CYCLIC_PROGRESSION":
 			return error.bracketIdxs.map((idx) => ["progression", idx, "sources"]);
-		// a bracket can have many sources but the error only identifies the bracket,
-		// so the message attaches to the sources list rather than one source's placements
+		// the error only identifies the bracket, not which of its sources, so it attaches to the sources list
 		case "PLACEMENTS_PARSE_ERROR":
 		case "TOO_MANY_PLACEMENTS":
 		case "PLACEMENT_TOO_HIGH":
diff --git a/app/features/calendar/calendar-search-params.ts b/app/features/calendar/calendar-search-params.ts
index 9dd7475ae..38abfe86b 100644
--- a/app/features/calendar/calendar-search-params.ts
+++ b/app/features/calendar/calendar-search-params.ts
@@ -27,8 +27,7 @@ const tierNumber = v.pipe(
 	v.maxValue(WORST_TIER_NUMBER),
 );
 
-// plain number schemas (not `dayMonthYear`'s coercing ones) because SP.param
-// derives the URL encoding from the schema's base type and coerces itself
+// plain number schemas, not `dayMonthYear`'s coercing ones: SP.param derives the encoding from the base type and coerces itself
 const dayNumber = v.pipe(
 	v.number(),
 	v.integer(),
diff --git a/app/features/calendar/calendar-types.ts b/app/features/calendar/calendar-types.ts
index e30b2dc18..cc2bb39c4 100644
--- a/app/features/calendar/calendar-types.ts
+++ b/app/features/calendar/calendar-types.ts
@@ -11,12 +11,12 @@ interface CommonEvent {
 	id: number;
 	name: string;
 	teamsCount: number;
-	/** How many players in total are rostered in the counted teams */
+	/** Players rostered in the counted teams in total */
 	membersCount: number;
 	minMembersPerTeam: number;
 	logoUrl: string | null;
 	url: string;
-	/** Is the tournament ranked? If null, tournament is not hosted on sendou.ink */
+	/** Null when not hosted on sendou.ink */
 	isRanked: boolean | null;
 	/** Tournament tier (1=X, 2=S+, 3=S, 4=A+, 5=A, 6=B+, 7=B, 8=C+, 9=C). Null if not tiered. */
 	tier: number | null;
@@ -27,7 +27,6 @@ interface CommonEvent {
 		name: string;
 		slug: string;
 	} | null;
-	/** User id of the author of the event */
 	authorId: number;
 }
 
@@ -36,7 +35,7 @@ export interface CalendarEvent extends CommonEvent {
 	at: number;
 	type: "calendar";
 	tags: Array<CalendarEventTag>;
-	/** Used for comparison, teams count where it is taken in account whether the tournament is 4v4, 3v3, 2v2 or 1v1 */
+	/** Team count weighted by team size (4v4, 3v3, 2v2, 1v1), for comparison */
 	normalizedTeamCount: number;
 	/** For multi-day tournaments, which day of the event is this */
 	day?: number;
@@ -49,7 +48,6 @@ export interface CalendarEvent extends CommonEvent {
 export interface ShowcaseCalendarEvent extends CommonEvent {
 	type: "showcase";
 	startsAt: number;
-	/** Id of the organization the event belongs to, if any */
 	organizationId: number | null;
 	/** Tournament is hidden from the public (test tournament) */
 	hidden: boolean;
diff --git a/app/features/calendar/components/BracketProgressionFormFields.tsx b/app/features/calendar/components/BracketProgressionFormFields.tsx
index 7a839c777..a17d7f6ef 100644
--- a/app/features/calendar/components/BracketProgressionFormFields.tsx
+++ b/app/features/calendar/components/BracketProgressionFormFields.tsx
@@ -26,15 +26,14 @@ export function BracketProgressionFormFields({
 	isInvitational: boolean;
 	/** Idxs of brackets that have already started and can no longer be edited or deleted. */
 	disabledBracketIdxs?: number[];
-	/** When the tournament is in progress, which brackets are starting brackets can no longer be changed. */
+	/** In progress: which brackets are starting brackets can no longer change. */
 	isTournamentInProgress?: boolean;
 }) {
 	const { values, setValue } = useFormFieldContext();
 	const brackets = (values.brackets ?? []) as BracketFormValue[];
 	const progression = (values.progression ?? []) as ProgressionFormValue[];
 
-	// the array field's own add/remove buttons only report the new value, so the
-	// removed bracket is located by reference diffing against the previous value
+	// the array field only reports the new value, so the removed bracket is found by reference diffing
 	const handleBracketsChanged = (newValue: unknown) => {
 		const newBrackets = newValue as BracketFormValue[];
 
@@ -67,9 +66,8 @@ export function BracketProgressionFormFields({
 		<>
 			<FormField
 				name="brackets"
-				// removing a bracket shifts the idxs of the brackets after it, so
-				// brackets before a started one must stay to keep started brackets'
-				// idxs (and disabledBracketIdxs) stable, matching the server's guard
+				// removing shifts later idxs, so brackets before a started one must stay to keep its idx
+				// (and disabledBracketIdxs) stable, matching the server's guard
 				canRemoveItem={(_, idx) =>
 					idx !== 0 &&
 					disabledBracketIdxs.every((disabledIdx) => disabledIdx < idx)
@@ -234,8 +232,7 @@ function ProgressionEntryFields({
 
 	const isFirstBracket = index === 0;
 
-	// a newly added row defaults to the first bracket, which is usually already a
-	// source of this bracket, so it gets moved to the first one not sourced yet
+	// a new row defaults to the first bracket, usually already a source, so it moves to the first one not sourced yet
 	const handleSourcesChanged = (newValue: unknown) => {
 		const newSources = newValue as ProgressionSourceFormValue[];
 		if (newSources.length <= sources.length) return;
@@ -309,8 +306,7 @@ function SourceFields({
 		[]) as ProgressionFormValue[];
 	const siblingSources = progression[destinationBracketIdx]?.sources ?? [];
 
-	// a bracket can be sourced only once, so the brackets taken by the other rows
-	// are not offered here
+	// a bracket can be sourced only once, so the ones taken by other rows are not offered
 	const bracketOptions = brackets.flatMap((bracket, bracketIdx) =>
 		bracketIdx === destinationBracketIdx ||
 		!bracket.name ||
diff --git a/app/features/calendar/components/Tags.tsx b/app/features/calendar/components/Tags.tsx
index cc212f345..ca729d7ca 100644
--- a/app/features/calendar/components/Tags.tsx
+++ b/app/features/calendar/components/Tags.tsx
@@ -17,10 +17,10 @@ export function Tags({
 	tags: Array<CalendarEventTag>;
 	small?: boolean;
 	centered?: boolean;
-	/** How many tags to show at most, rest are collapsed into a "+N" indicator. If undefined all tags are shown. */
+	/** Rest are collapsed into a "+N" indicator; undefined shows all. */
 	maxVisible?: number;
 
-	/** Called when tag delete button clicked. If undefined delete buttons won't be shown. */
+	/** Undefined hides the delete buttons. */
 	onDelete?: (tag: CalendarEventTag) => void;
 }) {
 	const { t } = useTranslation();
diff --git a/app/features/calendar/components/TournamentCard.tsx b/app/features/calendar/components/TournamentCard.tsx
index cde2ab79b..63f3050c7 100644
--- a/app/features/calendar/components/TournamentCard.tsx
+++ b/app/features/calendar/components/TournamentCard.tsx
@@ -19,8 +19,7 @@ import type { CalendarEvent, ShowcaseCalendarEvent } from "../calendar-types";
 import { Tags } from "./Tags";
 import styles from "./TournamentCard.module.css";
 
-// lazy loaded so the WebGL renderer stays out of the eager bundle of every
-// page showing tournament cards, as the trophy only renders inside a popover
+// lazy so the WebGL renderer stays out of every tournament card page's eager bundle; it only renders inside a popover
 const Trophy = lazy(() =>
 	import("~/features/trophies/components/Trophy").then((module) => ({
 		default: module.Trophy,
diff --git a/app/features/calendar/core/CalendarEvent.ts b/app/features/calendar/core/CalendarEvent.ts
index 5009ad0bc..dab33ddb8 100644
--- a/app/features/calendar/core/CalendarEvent.ts
+++ b/app/features/calendar/core/CalendarEvent.ts
@@ -34,9 +34,7 @@ export const FILTERS_KEYS = [
 assertType<(typeof FILTERS_KEYS)[number], keyof CalendarFilters>();
 assertType<keyof CalendarFilters, (typeof FILTERS_KEYS)[number]>();
 
-/**
- * Returns the default empty state of filter settings for calendar events.
- */
+/** Default empty calendar filters. */
 export function defaultFilters(): CalendarFilters {
 	return {
 		preferredStartTime: "ANY",
@@ -59,9 +57,7 @@ export function defaultFilters(): CalendarFilters {
 
 const defaultFiltersString = filtersToString(defaultFilters());
 
-/**
- * Determines whether the provided calendar filters match the default filter settings.
- */
+/** Whether the filters equal the defaults. */
 export function isDefaultFilters(filters: CalendarFilters): boolean {
 	return filtersToString(filters) === defaultFiltersString;
 }
@@ -76,11 +72,7 @@ function filtersToString(filters: CalendarFilters): string {
 	return result;
 }
 
-/**
- * Applies the provided calendar filters to a list of grouped calendar events.
- *
- * Returns a new array where each group contains separated lists of shown and hidden events. Event is shown if it matches all set filters.
- */
+/** Splits each group's events into shown (matching every set filter) and hidden. */
 export function applyFilters(
 	events: {
 		at: number;
diff --git a/app/features/calendar/core/ICal.server.ts b/app/features/calendar/core/ICal.server.ts
index 37f3869ef..298fb8872 100644
--- a/app/features/calendar/core/ICal.server.ts
+++ b/app/features/calendar/core/ICal.server.ts
@@ -4,7 +4,7 @@ import { logger } from "~/utils/logger";
 import { SENDOU_INK_BASE_URL } from "~/utils/urls";
 
 export async function getICalendar(events: Array<CalendarEvent>) {
-	// ical doesnt allow calendars with no events
+	// ical doesn't allow calendars with no events
 	if (events.length === 0) {
 		logger.warn("Could not construct ical feed, no events within time period");
 		return null;
diff --git a/app/features/calendar/loaders/calendar.new.server.ts b/app/features/calendar/loaders/calendar.new.server.ts
index 247a379ab..c18e4792b 100644
--- a/app/features/calendar/loaders/calendar.new.server.ts
+++ b/app/features/calendar/loaders/calendar.new.server.ts
@@ -106,8 +106,7 @@ export const loader = async ({ url }: LoaderFunctionArgs) => {
 			}
 		: undefined;
 
-	// the badges the user can pick from, plus any already-attached prize badges they no
-	// longer manage (so an existing selection still renders and stays removable)
+	// plus already-attached prize badges the user no longer manages, so the selection still renders and stays removable
 	const badgeOptions = R.uniqueBy(
 		[...managedBadges, ...(eventToEdit?.badgePrizes ?? [])].map((badge) => ({
 			id: badge.id,
diff --git a/app/features/calendar/loaders/calendar.server.test.ts b/app/features/calendar/loaders/calendar.server.test.ts
index 3586c10e1..14c997a5c 100644
--- a/app/features/calendar/loaders/calendar.server.test.ts
+++ b/app/features/calendar/loaders/calendar.server.test.ts
@@ -18,12 +18,9 @@ describe("calendar loader default view", () => {
 		vi.useRealTimers();
 	});
 
-	// The client resolves the shown week from the user's local clock while the
-	// loader resolves the fetched week from the server's clock. Around the week
-	// boundary these disagree by a full week for users ahead of UTC: e.g. in
-	// Auckland (UTC+13) Monday 2026-01-12 10:00 local is still Sunday 2026-01-11
-	// 21:00 UTC, so the user is shown the week Jan 12–18 but the loader only
-	// fetches up to ~Jan 13. Events from Tuesday evening onwards are missing.
+	// the client's shown week (local clock) and the loader's fetched week (server clock) disagree by a
+	// full week around the boundary for users ahead of UTC: in Auckland (UTC+13) Monday 2026-01-12
+	// 10:00 is still Sunday 21:00 UTC, so the user sees Jan 12–18 but the loader fetched up to ~Jan 13
 	test("fetches events for the whole week shown to a user ahead of UTC", async () => {
 		vi.useFakeTimers({ toFake: ["Date"] });
 		vi.setSystemTime(new Date("2026-01-11T21:00:00Z"));
diff --git a/app/features/calendar/loaders/calendar.server.ts b/app/features/calendar/loaders/calendar.server.ts
index ca412d210..de8e5f613 100644
--- a/app/features/calendar/loaders/calendar.server.ts
+++ b/app/features/calendar/loaders/calendar.server.ts
@@ -33,9 +33,8 @@ export const loader = async (args: LoaderFunctionArgs) => {
 
 	const weekStart = startOfWeek(new Date(date), { weekStartsOn: 1 });
 	const events = await CalendarRepository.findAllBetweenTwoTimestamps({
-		// on the default view the client resolves the shown week from its own clock,
-		// which around the week boundary can be a full week ahead of or behind the
-		// server's week, so fetch wide enough to cover every timezone's current week
+		// the client resolves the default week from its own clock, which around the week boundary
+		// can be a full week off the server's, so fetch wide enough for every timezone's current week
 		startTime: sub(weekStart, { days: DAYS_SHOWN_AT_A_TIME + 1 }),
 		endTime: add(weekStart, { days: DAYS_SHOWN_AT_A_TIME * 2 + 1 }),
 	});
@@ -86,8 +85,7 @@ function resolveFilters(
 	const searchParams = calendarSearchParams.parse(request);
 	const parsed = R.pick(searchParams, [...CalendarEvent.FILTERS_KEYS]);
 
-	// the user cleared or edited the filters, so the URL is the whole truth
-	// even when it ends up holding no filters at all
+	// the user cleared or edited the filters, so the URL is the whole truth even when empty
 	if (!searchParams.useDefaults) {
 		return parsed;
 	}
diff --git a/app/features/calendar/loaders/calendar[.]ics.server.ts b/app/features/calendar/loaders/calendar[.]ics.server.ts
index 74b70bed3..a82c5cb31 100644
--- a/app/features/calendar/loaders/calendar[.]ics.server.ts
+++ b/app/features/calendar/loaders/calendar[.]ics.server.ts
@@ -14,7 +14,7 @@ export const loader = async ({ request }: LoaderFunctionArgs) => {
 	const startTime = new Date();
 	const endTime = new Date(startTime);
 
-	// get all events over the two weeks, might be good to make this an parameter in the future
+	// two weeks of events, could be a parameter in the future
 	endTime.setDate(startTime.getDate() + 14);
 
 	// handle timezone mismatch between server and client
diff --git a/app/features/calendar/routes/calendar.new.tsx b/app/features/calendar/routes/calendar.new.tsx
index 9cbd4f157..8cb36e986 100644
--- a/app/features/calendar/routes/calendar.new.tsx
+++ b/app/features/calendar/routes/calendar.new.tsx
@@ -198,8 +198,7 @@ function useDefaultValues() {
 				? databaseTimestampToDate(data.eventToEdit.startTimes[0])
 				: getDateAtNextFullHour(new Date())
 			: null,
-		// tournaments hide this field, so seed a valid URL to satisfy the url-format
-		// validation (the action coalesces to the same default)
+		// tournaments hide this field, so seed a valid URL for the url-format validation (the action coalesces to the same default)
 		bracketUrl: data.isAddingTournament
 			? "https://sendou.ink"
 			: (data.eventToEdit?.bracketUrl ?? ""),
diff --git a/app/features/changelog/changelog-constants.ts b/app/features/changelog/changelog-constants.ts
index 9c9dbf161..d542d069d 100644
--- a/app/features/changelog/changelog-constants.ts
+++ b/app/features/changelog/changelog-constants.ts
@@ -2,11 +2,7 @@ import type { OgImagePage } from "~/utils/urls";
 
 export const CHANGELOG_FOLDER_PATH = "changelog";
 
-/**
- * Discord emoji shortcode per nav item, either one uploaded to the server or a
- * built-in. Typing `:name:` in the Discord client resolves to the emoji, so the
- * generated post is copy-pasteable. Most match the nav item name but not all.
- */
+/** Discord emoji shortcode per nav item (server-uploaded or built-in), so the generated post is copy-pasteable. */
 export const DISCORD_EMOJI_NAMES: Record<OgImagePage, string> = {
 	settings: "settings",
 	sendouq: "sendouq",
diff --git a/app/features/changelog/core/entries.server.ts b/app/features/changelog/core/entries.server.ts
index e15b8ad52..b77658daa 100644
--- a/app/features/changelog/core/entries.server.ts
+++ b/app/features/changelog/core/entries.server.ts
@@ -18,11 +18,7 @@ const frontmatterSchema = v.object({
 	type: v.picklist(["feature", "bug"] as const),
 });
 
-/**
- * Every changelog entry added between the given commit and HEAD, oldest first.
- *
- * @param since Sha of the commit the previous update was shipped from.
- */
+/** Entries added between `since` (sha the previous update shipped from) and HEAD, oldest first. */
 export function entriesSince(since: string): ChangelogGraphicEntry[] {
 	const output = execFileSync(
 		"git",
@@ -55,10 +51,7 @@ export function allEntries(): ChangelogGraphicEntry[] {
 		.map(parseEntryFile);
 }
 
-/**
- * Sha of the commit the entries are read from, letting a caller check it is
- * talking to a server running the same checkout it is.
- */
+/** Sha the entries are read from, so a caller can check the server runs the same checkout. */
 export function headSha(): string {
 	return execFileSync("git", ["rev-parse", "HEAD"], {
 		encoding: "utf8",
diff --git a/app/features/chat/ChatProvider.tsx b/app/features/chat/ChatProvider.tsx
index e55436776..04a09e94a 100644
--- a/app/features/chat/ChatProvider.tsx
+++ b/app/features/chat/ChatProvider.tsx
@@ -47,11 +47,7 @@ interface ChatContextValue {
 	totalUnreadCount: number;
 	chatOpen: boolean;
 	setChatOpen: (open: boolean) => void;
-	/**
-	 * Rooms the user is currently viewing. Empty means none are open, one
-	 * renders a single chat, more than one renders the split view. The first room
-	 * is the primary one (shown on top / given the larger share in split view).
-	 */
+	/** Rooms on screen: none, one, or several (split view, the first being primary). */
 	activeRoomIds: number[];
 	setActiveRoomIds: (roomIds: number[]) => void;
 }
@@ -351,12 +347,9 @@ function useChatRouteSync({
 }
 
 /**
- * Chat rooms the current route surfaces, from its loader's `chatRooms`. The
- * `autoOpen` ones are opened for the viewer (a route may expose several, e.g. a
- * SendouQ match exposes the match chat alongside the user's own group chat,
- * which are then shown as a single combined split view); the rest are only
- * listed in the sidebar for the viewer to open themselves (a staff member
- * reading the group chats of a SendouQ match they are not in).
+ * Chat rooms the current route surfaces (loader `chatRooms`). `autoOpen` ones open for the viewer
+ * (a SendouQ match opens match chat and group chat as one split view); the rest are only listed
+ * for the viewer to open (staff reading group chats of a match they are not in).
  */
 export function useCurrentRouteChatRooms(): RouteChatRoom[] {
 	const matches = useMatches();
diff --git a/app/features/chat/ChatRepository.server.ts b/app/features/chat/ChatRepository.server.ts
index 089f130d5..5b8e0cb30 100644
--- a/app/features/chat/ChatRepository.server.ts
+++ b/app/features/chat/ChatRepository.server.ts
@@ -17,11 +17,9 @@ import type { ChatRoomType, PersistedSystemMessageType } from "./chat-types";
 const MESSAGES_DEFAULT_LIMIT = 500;
 
 /**
- * How far back the room list looks for the user's SendouQ memberships. An
- * unmatched group goes inactive an hour after its last action and a match room
- * lives a day, so no open SQ room hangs off a membership older than this. The
- * bound is what keeps a veteran's thousands of past groups out of the lookup —
- * raise it rather than let a room quietly stop showing up.
+ * How far back the room list looks for SendouQ memberships: an unmatched group goes inactive
+ * after an hour and a match room lives a day, so no open room hangs off an older membership.
+ * Keeps a veteran's thousands of past groups out of the lookup — raise rather than let a room vanish.
  */
 const SQ_MEMBERSHIP_LOOKBACK_HOURS = 72;
 
@@ -37,13 +35,9 @@ export async function findAllRoomsByIds(roomIds: number[]) {
 }
 
 /**
- * Ids of the rooms the user currently participates in (unexpired and unclosed).
- * Membership-first: every branch starts from the user's own membership rows and
- * probes forward to the room, so the cost tracks how much the user takes part in
- * rather than how many rooms the site has open. Driving from the open room set
- * instead costs the same for every user, participant or not, and grows with the
- * site. The SendouQ branches narrow that further to
- * {@link SQ_MEMBERSHIP_LOOKBACK_HOURS}, past which no room can still be open.
+ * Ids of the open rooms the user participates in. Membership-first: every branch starts from the
+ * user's own membership rows so the cost tracks their participation, not the site's open room
+ * count. SendouQ branches narrow further to {@link SQ_MEMBERSHIP_LOOKBACK_HOURS}.
  */
 export async function findAllOpenRoomIdsByUserId(
 	userId: number,
@@ -380,11 +374,7 @@ export async function closeExpiredRooms(expiredBefore: Date) {
 	return Number(result.numUpdatedRows);
 }
 
-/**
- * Deletes rooms no owner row points at any more, returning how many. Backstop
- * for owner deletes that missed their room. A room's type names the one table
- * that can own it, so each room is checked against that table alone.
- */
+/** Deletes rooms no owner row points at any more (backstop for owner deletes that missed their room), returning how many. A room's type names its one owner table. */
 export async function deleteOrphanedRooms() {
 	const result = await db
 		.deleteFrom("ChatRoom")
diff --git a/app/features/chat/ChatRoomResolver.server.ts b/app/features/chat/ChatRoomResolver.server.ts
index 30aaa6c97..dabc76210 100644
--- a/app/features/chat/ChatRoomResolver.server.ts
+++ b/app/features/chat/ChatRoomResolver.server.ts
@@ -42,10 +42,8 @@ export interface ResolvedRoom {
 	/** Role labels (e.g. "TO", "Stream") shown next to non-participant authors, keyed by user id. */
 	labelByUserId: Record<number, string>;
 	/**
-	 * - `VIEW`: reading the room. After `closedAt` only observers keep it.
-	 * - `POST`: sending a message, while the room is unexpired and unclosed.
-	 * - `OBSERVE`: read-only access resolved from the owning entity (tournament
-	 *   organizers and streamers), plus site staff who observe every room.
+	 * `VIEW`: reading the room, after `closedAt` only observers keep it. `POST`: sending while unexpired
+	 * and unclosed. `OBSERVE`: read-only access from the owning entity (organizers, streamers) plus site staff.
 	 */
 	permissions: {
 		VIEW: number[];
@@ -60,21 +58,14 @@ export interface ResolvedRoom {
 
 type ChatRoomRow = Tables["ChatRoom"];
 
-/**
- * Resolves a room's participants, title and access live from its owning entity.
- * A room whose owner row is gone resolves to `null`.
- */
+/** Resolves a room's participants, title and access live from its owning entity; `null` when the owner row is gone. */
 export async function resolve(roomId: number): Promise<ResolvedRoom | null> {
 	const [room] = await resolveAll([roomId]);
 
 	return room ?? null;
 }
 
-/**
- * Resolves a room for the current user.
- *
- * @throws {Response} 404 if the room does not resolve, 403 without the permission.
- */
+/** Resolves a room for the current user. @throws {Response} 404 if it does not resolve, 403 without the permission. */
 export async function requireRoom(
 	roomId: number,
 	permission: keyof ResolvedRoom["permissions"],
diff --git a/app/features/chat/ChatSystemMessage.server.ts b/app/features/chat/ChatSystemMessage.server.ts
index c8a270362..5a49249aa 100644
--- a/app/features/chat/ChatSystemMessage.server.ts
+++ b/app/features/chat/ChatSystemMessage.server.ts
@@ -38,11 +38,7 @@ const revalidateThrottle = createRevalidateBroadcastThrottle({
 		}),
 });
 
-/**
- * Publishes a contentless revalidate broadcast to the channel(s), prompting the
- * subscribed pages to refetch. Throttled per channel for the noisy kinds, see
- * {@link createRevalidateBroadcastThrottle}.
- */
+/** Publishes a contentless revalidate broadcast to the channel(s) so subscribed pages refetch. Noisy kinds are throttled per channel, see {@link createRevalidateBroadcastThrottle}. */
 export function send(broadcast: RevalidateBroadcast | RevalidateBroadcast[]) {
 	for (const msg of Array.isArray(broadcast) ? broadcast : [broadcast]) {
 		if (revalidateThrottle.throttles(msg)) {
@@ -53,11 +49,7 @@ export function send(broadcast: RevalidateBroadcast | RevalidateBroadcast[]) {
 	}
 }
 
-/**
- * Persists a system message (e.g. a reported score) as a chat line of the room
- * and publishes it, plus a revalidate broadcast so subscribed pages refetch.
- * Fire and forget like {@link send}: failures are logged, never thrown.
- */
+/** Persists a system message (e.g. a reported score) as a chat line and publishes it plus a revalidate broadcast. Fire and forget like {@link send}: failures are logged, never thrown. */
 export function sendPersisted(args: {
 	roomId: number;
 	type: PersistedSystemMessageType;
@@ -105,11 +97,7 @@ function publishRevalidate(msg: {
 	});
 }
 
-/**
- * Publishes a contentless "your notifications changed" event to the users'
- * event streams, prompting their clients to refetch. Fire and forget like the
- * other system messages; a missed event only delays the refetch.
- */
+/** Publishes a contentless "your notifications changed" event to the users' streams. Fire and forget; a missed event only delays the refetch. */
 export function notifyNotificationsChanged(userIds: number[]) {
 	if (userIds.length === 0) return;
 
@@ -118,12 +106,7 @@ export function notifyNotificationsChanged(userIds: number[]) {
 	});
 }
 
-/**
- * Publishes a "your chat room set changed" event to the users' event streams
- * after a membership change (leave, kick, group merge, added member). Clients
- * refetch their room list and drop rooms — including any locally held history —
- * they no longer have access to.
- */
+/** Publishes a "your chat room set changed" event after a membership change; clients refetch their room list and drop rooms (and held history) they lost access to. */
 export function notifyRoomsChanged(userIds: number[]) {
 	if (userIds.length === 0) return;
 
@@ -132,13 +115,7 @@ export function notifyRoomsChanged(userIds: number[]) {
 	});
 }
 
-/**
- * Same, for a change to the rooms themselves rather than to who is in them: the
- * participants are resolved from the rooms. Sent when a room's inactive flag
- * flips with its owner's state (e.g. its match completing), which the room list
- * would otherwise only pick up on the next page load. Fire and forget like
- * {@link send}: failures are logged, never thrown.
- */
+/** Same, for a change to the rooms themselves (participants resolved from them), e.g. the inactive flag flipping with a match completing. Fire and forget like {@link send}. */
 export function notifyRoomsChangedByRoomIds(roomIds: number[]): Promise<void> {
 	return notifyParticipantsOfRoomsChanged(roomIds).catch((err) =>
 		logger.error("Notifying participants of changed chat rooms failed:", err),
diff --git a/app/features/chat/chat-hooks.ts b/app/features/chat/chat-hooks.ts
index 59cce5574..c2acff969 100644
--- a/app/features/chat/chat-hooks.ts
+++ b/app/features/chat/chat-hooks.ts
@@ -60,10 +60,8 @@ export function useChatAutoScroll(
 				messagesContainer.scrollTop + messagesContainer.clientHeight >=
 				messagesContainer.scrollHeight - THRESHOLD;
 
-			// react-aria's Virtualizer resets the scroll position to the top
-			// whenever the message collection changes; undo those resets so
-			// they neither unpin the auto scroll nor yank the user out of the
-			// history they were reading
+			// react-aria's Virtualizer resets scroll to the top whenever the collection
+			// changes; undo so it neither unpins auto scroll nor yanks the user out of history
 			if (!isUserScroll) {
 				if (pinnedToBottomRef.current && !isScrolledToBottom) {
 					messagesContainer.scrollTop = messagesContainer.scrollHeight;
@@ -109,9 +107,8 @@ export function useChatAutoScroll(
 
 	const hasMessages = messages.length > 0;
 
-	// the virtualizer resizes the scrollable content asynchronously as it
-	// measures rows, without scroll events firing, so keep the view glued to
-	// the bottom whenever the content height changes while pinned there
+	// the virtualizer resizes the content asynchronously as it measures rows, without
+	// scroll events, so keep the view glued to the bottom while pinned there
 	React.useEffect(() => {
 		if (!hasMessages) return;
 
@@ -151,11 +148,9 @@ export function useChatAutoScroll(
 }
 
 /**
- * Subscribes the page to a server event topic over the shared SSE connection so
- * that `revalidate` broadcasts to the topic trigger a data loader revalidation.
- * Topics are lightweight: no metadata, no participants, no history — purely a
- * fan-out channel. Pass `connected=false` to opt out (e.g. once a tournament
- * has been finalized and no further updates are expected).
+ * Subscribes the page to a server event topic (a pure fan-out channel: no metadata, participants
+ * or history) so `revalidate` broadcasts to it revalidate loaders. `connected=false` opts out,
+ * e.g. once a tournament is finalized.
  */
 export function useTopicRevalidation(topic: string, connected = true) {
 	useLiveRevalidation(connected);
@@ -176,11 +171,7 @@ export function useLiveRevalidation(enabled = true) {
 	});
 }
 
-/**
- * Handles `revalidate` events arriving over the shared SSE connection: plays the
- * sound the event carries and schedules a loader revalidation, skipping the
- * actor's own broadcasts (their form submission already reran the loaders).
- */
+/** Handles SSE `revalidate` events: plays the carried sound and schedules a loader revalidation, skipping the actor's own broadcasts (their submission already reran the loaders). */
 export function useServerRevalidationEvents(userId: number) {
 	const { revalidate } = useRevalidator();
 
diff --git a/app/features/chat/components/Chat.tsx b/app/features/chat/components/Chat.tsx
index 0d2269680..fcbc83a3d 100644
--- a/app/features/chat/components/Chat.tsx
+++ b/app/features/chat/components/Chat.tsx
@@ -177,7 +177,7 @@ function Composer({ onSend }: { onSend: ChatProps["onSend"] }) {
 	const [publicId, setPublicId] = React.useState(() => shortNanoid());
 	const [hasSent, setHasSent] = React.useState(false);
 
-	// don't let a send's autofocus carry over to an unrelated page
+	// a send's autofocus must not carry over to an unrelated page
 	React.useEffect(() => {
 		setHasSent(false);
 	}, [pathname]);
diff --git a/app/features/chat/revalidate-broadcast-throttle.ts b/app/features/chat/revalidate-broadcast-throttle.ts
index bad28cd9f..5334cfcdc 100644
--- a/app/features/chat/revalidate-broadcast-throttle.ts
+++ b/app/features/chat/revalidate-broadcast-throttle.ts
@@ -19,22 +19,13 @@ interface ThrottleEntry {
 export const MAX_ENTRIES = 5_000;
 
 /**
- * Rate limits revalidation broadcasts per channel so that a burst of them
- * (e.g. every player of a forming SendouQ match confirming within seconds, or every
- * reported game of a live tournament) fans out to the channel's subscribers at most
- * twice per window instead of once per event — each fan-out makes every subscribed
- * client refetch its loaders at once.
+ * Rate limits revalidation broadcasts per channel so a burst (every player of a forming SendouQ
+ * match confirming, every reported game of a live tournament) fans out at most twice per window:
+ * the first is delivered immediately, the rest coalesce into one trailing broadcast at the
+ * window's end whose scope is the broadest seen and which carries no author or type.
  *
- * The first broadcast of a window is delivered immediately; further broadcasts for
- * the same channel within the window coalesce into a single trailing broadcast at the
- * window's end, so subscribers never miss the final state. A trailing broadcast
- * covers every coalesced one: its scope is widened to the broadest seen and it
- * carries no author (nobody may skip it as their own) and no type.
- *
- * Broadcasts whose type plays a sound (a starting match, a ready check) are left alone:
- * coalescing would cost the player the sound, and they are rare enough not to be worth
- * rate limiting. Soundless types (a reported tournament game) are throttled like the
- * rest — they are the bulk of the traffic the throttle exists for.
+ * Types that play a sound (starting match, ready check) are left alone: coalescing would cost
+ * the sound, and they are rare. Soundless types are the bulk the throttle exists for.
  */
 export function createRevalidateBroadcastThrottle({
 	windowMs,
diff --git a/app/features/chat/revalidation-scope.ts b/app/features/chat/revalidation-scope.ts
index 503976fee..77a2b766a 100644
--- a/app/features/chat/revalidation-scope.ts
+++ b/app/features/chat/revalidation-scope.ts
@@ -12,11 +12,7 @@ let oldestPendingStartedAt: number | null = null;
 let revalidationGeneration = 0;
 let scheduledBroadcast: { scope: RevalidateScope | null } | null = null;
 
-/**
- * Runs a broadcast triggered revalidation, remembering the broadcast's scope
- * while it is in flight so `shouldRevalidate` implementations can skip loaders whose
- * data the broadcast can not have changed.
- */
+/** Runs a broadcast triggered revalidation, remembering its scope while in flight so `shouldRevalidate` can skip loaders the broadcast cannot have changed. */
 export function revalidateWithScope(
 	revalidate: () => Promise<void>,
 	scope: RevalidateScope | undefined,
@@ -47,12 +43,9 @@ export function revalidateWithScope(
 }
 
 /**
- * Runs a broadcast triggered revalidation after a random delay so the clients
- * subscribed to a topic do not all refetch in the same instant the broadcast fans out
- * (thundering herd — a broadcast to e.g. the SendouQ looking channel or a live tournament's
- * channel reaches every client on that page at once). A broadcast arriving while one is
- * already scheduled is absorbed into it, widening its scope as needed: the eventual
- * single fetch returns data fresh enough to cover both.
+ * Runs a broadcast triggered revalidation after a random delay so a topic's clients do not all
+ * refetch in the same instant (thundering herd on e.g. the SendouQ looking channel). A broadcast
+ * arriving while one is scheduled is absorbed into it, widening its scope as needed.
  */
 export function scheduleBroadcastRevalidation(
 	revalidate: () => Promise<void>,
@@ -74,10 +67,9 @@ export function scheduleBroadcastRevalidation(
 }
 
 /**
- * Whether the pending revalidation is a broadcast scoped to match results,
- * meaning only match data (reported scores, pick/ban events) changed. Loaders whose data
- * does not derive from match data can return `false` from `shouldRevalidate` for these —
- * during a live tournament this is the most frequent broadcast: one per reported game.
+ * Whether the pending revalidation is scoped to match results (reported scores, pick/ban events).
+ * Loaders not derived from match data can return `false` from `shouldRevalidate` for these — the
+ * most frequent broadcast during a live tournament, one per reported game.
  */
 export function isMatchResultsScopedRevalidation(
 	args: ShouldRevalidateFunctionArgs,
@@ -86,11 +78,9 @@ export function isMatchResultsScopedRevalidation(
 }
 
 /**
- * Drops the bookkeeping of revalidations counted as in flight for longer than one can
- * plausibly take. A `revalidate()` interrupted by a navigation never settles, which would
- * otherwise leave `activeScope` stuck for the life of the tab and make every later
- * broadcast skip the loaders it narrows away. Only the stuck case is forgotten, so a
- * revalidation genuinely in flight keeps its scope from being narrowed under it.
+ * Forgets revalidations counted as in flight for implausibly long: a `revalidate()` interrupted
+ * by a navigation never settles and would leave `activeScope` stuck for the life of the tab.
+ * Only the stuck case is forgotten, so a genuine in-flight one keeps its scope.
  */
 function forgetStalePendingRevalidations() {
 	const isStale =
diff --git a/app/features/chat/routes/api.chat.rooms.ts b/app/features/chat/routes/api.chat.rooms.ts
index 82c7dbc20..ac205f538 100644
--- a/app/features/chat/routes/api.chat.rooms.ts
+++ b/app/features/chat/routes/api.chat.rooms.ts
@@ -4,11 +4,7 @@ import * as ChatRoomResolver from "../ChatRoomResolver.server";
 import { roomListItem } from "../chat-room-list.server";
 import type { ChatRoomListItem } from "../chat-types";
 
-/**
- * The user's open chat rooms with server-computed unread counts. A background
- * resource like the notifications peek: fetched after mount and refetched on
- * `chatMessage` / `roomsChanged` events instead of riding any page loader.
- */
+/** The user's open chat rooms with unread counts; fetched after mount and refetched on `chatMessage` / `roomsChanged` events, never riding a page loader. */
 export const loader = async (): Promise<{ rooms: ChatRoomListItem[] }> => {
 	const user = requireUser();
 
diff --git a/app/features/comp-analyzer/components/RangeVisualization.tsx b/app/features/comp-analyzer/components/RangeVisualization.tsx
index 7928eee4f..9920fa560 100644
--- a/app/features/comp-analyzer/components/RangeVisualization.tsx
+++ b/app/features/comp-analyzer/components/RangeVisualization.tsx
@@ -119,9 +119,7 @@ function TrajectoryChart({
 	const yScale = (y: number) =>
 		innerHeight - ((y - minY) / (maxY - minY)) * innerHeight;
 
-	// Returns the point where trajectory hits y=0 (ground level).
-	// This differs from lastPoint which may be below ground or mid-air.
-	// Used for blast radius positioning since explosions happen at ground impact.
+	// where the trajectory hits the ground (lastPoint may be below it or mid-air); blasts happen there
 	const getGroundIntersection = (
 		trajectory: TrajectoryPoint[],
 	): TrajectoryPoint | null => {
diff --git a/app/features/comp-analyzer/core/damage-combinations.ts b/app/features/comp-analyzer/core/damage-combinations.ts
index 8caebc6ed..54e3d1155 100644
--- a/app/features/comp-analyzer/core/damage-combinations.ts
+++ b/app/features/comp-analyzer/core/damage-combinations.ts
@@ -211,10 +211,8 @@ interface PartialCombo {
 }
 
 /**
- * Groups a weapon slot's damage into a single "channel" that may only ever
- * contribute one damage type per combo. In single-weapon mode each weapon type
- * (main/sub/special) is its own channel so a single weapon can pair e.g. its
- * main damage with its sub; otherwise a whole slot is one channel.
+ * A "channel" contributes at most one damage type per combo: in single-weapon mode each of
+ * main/sub/special is its own channel, otherwise a whole slot is one.
  */
 function slotDamageChannel(
 	option: DamageOption,
@@ -460,13 +458,8 @@ function isExcessiveCombo(combo: DamageCombo): boolean {
 const SPLASH_O_MATIC_ID = 20;
 
 /**
- * Calculates the number of frames needed for enemy ink damage to finish off
- * a target after dealing a certain amount of combo damage.
- *
- * @param comboDamage - The damage dealt by the combo
- * @param targetResAp - The target's Ink Resistance Up ability points (0-57)
- * @returns The number of frames needed, or null if the combo is already lethal
- *          or ink damage cannot finish the kill (remaining damage exceeds ink damage limit)
+ * Frames of enemy ink damage needed to finish a target after `comboDamage`. `targetResAp` is Ink
+ * Resistance Up AP (0-57). Null when the combo is already lethal or ink damage can't finish it.
  */
 export function calculateInkTimeToKill(
 	comboDamage: number,
diff --git a/app/features/comp-analyzer/core/special-weapon-range.ts b/app/features/comp-analyzer/core/special-weapon-range.ts
index 4c22cb0b5..4b526a243 100644
--- a/app/features/comp-analyzer/core/special-weapon-range.ts
+++ b/app/features/comp-analyzer/core/special-weapon-range.ts
@@ -14,18 +14,16 @@ const DEFAULT_FREE_GRAVITY = 0.016;
 const DEFAULT_FREE_AIR_RESIST = 0;
 
 export interface SpecialWeaponRangeResult {
-	/** Radius of the range circle, in game distance units. */
+	/** In game distance units. */
 	range: number;
-	/** Extra outer radius covered by the projectile's blast, in game distance units. */
+	/** Extra outer radius of the projectile's blast, in game distance units. */
 	blastRadius?: number;
 	rangeType: "projectile" | "radius";
 }
 
 /**
- * Range circle definition for a special weapon, or `null` when the special has no meaningful
- * range to draw. The underlying values come from `weapon-params.ts` (populated by
- * `scripts/create-analyzer-json.ts`): projectile specials reuse the main weapon trajectory
- * model, the rest carry a single effect radius.
+ * Range circle of a special, or `null` when it has none worth drawing. Values come from
+ * `weapon-params.ts`: projectile specials reuse the main weapon trajectory model, the rest carry a radius.
  */
 export function getSpecialWeaponRange(
 	specialWeaponId: SpecialWeaponId,
@@ -74,10 +72,7 @@ export interface SpecialWeaponWithRange extends SpecialWeaponRangeResult {
 	specialWeaponId: SpecialWeaponId;
 }
 
-/**
- * Every special weapon that has a range to draw, widest first. Specials without a meaningful
- * range circle are omitted.
- */
+/** Every special with a range to draw, widest first. */
 export function getSpecialsWithRange(): SpecialWeaponWithRange[] {
 	return specialWeaponIds
 		.flatMap((specialWeaponId): SpecialWeaponWithRange[] => {
diff --git a/app/features/components-showcase/form-examples-schema.ts b/app/features/components-showcase/form-examples-schema.ts
index f056d0aa3..3a5732ead 100644
--- a/app/features/components-showcase/form-examples-schema.ts
+++ b/app/features/components-showcase/form-examples-schema.ts
@@ -25,7 +25,6 @@ import {
 } from "~/form/fields";
 
 export const formFieldsShowcaseSchema = v.object({
-	// Text fields
 	requiredText: textField({
 		label: "labels.name",
 		maxLength: 100,
@@ -38,7 +37,6 @@ export const formFieldsShowcaseSchema = v.object({
 		label: "labels.vodTeamSize",
 	}),
 
-	// Text areas
 	requiredTextArea: textArea({
 		label: "labels.description",
 		maxLength: 500,
@@ -48,7 +46,6 @@ export const formFieldsShowcaseSchema = v.object({
 		maxLength: 1000,
 	}),
 
-	// Toggles
 	isPublic: toggle({
 		label: "labels.buildPrivate",
 	}),
@@ -56,7 +53,6 @@ export const formFieldsShowcaseSchema = v.object({
 		label: "labels.isEstablished",
 	}),
 
-	// Selects
 	requiredSelect: select({
 		label: "labels.voiceChat",
 		items: [
@@ -99,7 +95,6 @@ export const formFieldsShowcaseSchema = v.object({
 		],
 	}),
 
-	// Radio & Checkbox groups
 	matchType: radioGroup({
 		label: "labels.scrimMaps",
 		items: [
@@ -118,7 +113,6 @@ export const formFieldsShowcaseSchema = v.object({
 		],
 	}),
 
-	// Date & Time
 	requiredDatetime: datetime({
 		label: "labels.startTime",
 	}),
@@ -134,7 +128,6 @@ export const formFieldsShowcaseSchema = v.object({
 		endLabel: "labels.end",
 	}),
 
-	// Game-specific fields
 	weapons: weaponPool({
 		label: "labels.weaponPool",
 		maxCount: 5,
@@ -150,7 +143,6 @@ export const formFieldsShowcaseSchema = v.object({
 		label: "labels.player",
 	}),
 
-	// Image fields
 	logo: image({
 		label: "labels.logo",
 	}),
@@ -159,7 +151,6 @@ export const formFieldsShowcaseSchema = v.object({
 		dimensions: "thick-banner",
 	}),
 
-	// Custom field
 	customValue: customField(
 		{ initialValue: "custom initial value" },
 		v.optional(v.string()),
diff --git a/app/features/events/core/EventBus.server.ts b/app/features/events/core/EventBus.server.ts
index 8c4ce40bd..8c88dcac4 100644
--- a/app/features/events/core/EventBus.server.ts
+++ b/app/features/events/core/EventBus.server.ts
@@ -7,7 +7,7 @@ interface Subscriber {
 
 const subscribersByChannel = new Map<string, Set<Subscriber>>();
 
-/** Delivers the event to every live subscriber of the given channels, once per subscriber even when it listens on several of them. */
+/** Delivers the event to every live subscriber of the channels, once each even when listening on several. */
 export function publish(channels: string[], event: ServerEvent): void {
 	const recipients = new Set<Subscriber>();
 	for (const channel of channels) {
@@ -22,7 +22,7 @@ export function publish(channels: string[], event: ServerEvent): void {
 	}
 }
 
-/** Subscribes to the given channels, yielding events as they are published until the signal aborts (pending events are dropped) or the consumer stops iterating. */
+/** Yields the channels' events until the signal aborts (pending events dropped) or the consumer stops iterating. */
 export function subscribe(
 	channels: string[],
 	signal: AbortSignal,
diff --git a/app/features/events/events-hooks.browser.test.tsx b/app/features/events/events-hooks.browser.test.tsx
index 267ebbe24..5c183fcc5 100644
--- a/app/features/events/events-hooks.browser.test.tsx
+++ b/app/features/events/events-hooks.browser.test.tsx
@@ -165,10 +165,8 @@ function CatchUpHarness({ enabled }: { enabled: boolean }) {
 }
 
 /**
- * Runs the fake clock forward and lets React paint what the fired timers
- * changed. React schedules its render through a MessageChannel, which fake
- * timers do not control, so a message of our own posted afterwards is what
- * tells us the render already happened.
+ * Runs the fake clock forward and lets React paint. React renders through a MessageChannel fake
+ * timers don't control, so a message of our own posted afterwards tells us the render happened.
  */
 const advanceTimers = async (ms = 0) => {
 	await vi.advanceTimersByTimeAsync(ms);
diff --git a/app/features/events/events-hooks.ts b/app/features/events/events-hooks.ts
index 98e709905..98932c7aa 100644
--- a/app/features/events/events-hooks.ts
+++ b/app/features/events/events-hooks.ts
@@ -7,15 +7,13 @@ import type { ServerEvent } from "~/features/events/events-types";
 
 // how long the page must have been away for coming back to it to be worth a catch-up
 const CATCH_UP_AWAY_MS = 20 * 1000;
-// how often the page marks itself as running in the foreground; the gap left in these
-// ticks is what an absence is measured by, so it bounds how much of one goes unnoticed
+// foreground heartbeat; an absence is measured by the gap in these ticks, so this bounds how much of one goes unnoticed
 const FOREGROUND_TICK_MS = 5 * 1000;
 // how often to catch up while the event stream is down and nothing can arrive over it
 const EVENTS_DOWN_CATCH_UP_MS = 2 * 60 * 1000;
 // spreads out the catch-ups of the many clients that reconnect at once after a deploy
 const CATCH_UP_MAX_JITTER_MS = 3_000;
-// a first connect slower than this did not happen as part of page load, so what was
-// published between the two can only be caught up on
+// a first connect slower than this was not part of page load, so what was published in between must be caught up on
 const LATE_FIRST_CONNECT_MS = 2_000;
 
 /** Keeps the shared SSE connection open while mounted and enabled. */
@@ -54,14 +52,10 @@ export function useEventsTopic(topic: string, enabled = true) {
 }
 
 /**
- * Calls `onCatchUp` whenever events may have been missed: the stream came back up, the
- * page was returned to after being away long enough, or the stream is down and nothing
- * can arrive over it at all. Returns the same trigger for callers that have a reason of
- * their own to catch up.
- *
- * Every catch-up is jittered so the clients that reconnect together after a deploy do
- * not all refetch in the same instant, and one triggered while another is already
- * scheduled is absorbed into it.
+ * Calls `onCatchUp` whenever events may have been missed: the stream came back up, the page
+ * returned after being away long enough, or the stream is down. Returns the trigger for callers
+ * with reasons of their own. Catch-ups are jittered so clients reconnecting together after a
+ * deploy don't refetch at once; one triggered while another is scheduled is absorbed into it.
  */
 export function useEventStreamCatchUp({
 	enabled,
@@ -113,10 +107,8 @@ export function useEventStreamCatchUp({
 }
 
 /**
- * Calls `onConnect` every time the event stream comes up, skipping a first connect
- * that page load itself waited for: only what happened while nothing was listening
- * needs catching up on. A first connect that took longer than that left a window
- * whose events reach the page no other way.
+ * Calls `onConnect` every time the stream comes up, skipping a first connect page load itself
+ * waited for: only what happened while nothing was listening needs catching up on.
  */
 function useCatchUpOnConnect(
 	enabled: boolean,
@@ -127,8 +119,7 @@ function useCatchUpOnConnect(
 	const listeningSinceRef = React.useRef<number | null>(null);
 
 	React.useEffect(() => {
-		// while disabled nothing can be missed, so the wait for the connect that
-		// follows starts over from the moment listening resumes
+		// while disabled nothing can be missed, so the wait for the next connect restarts when listening resumes
 		if (!enabled) {
 			listeningSinceRef.current = null;
 			return;
@@ -155,13 +146,10 @@ let foregroundTicker: ReturnType<typeof setInterval> | null = null;
 let lastForegroundTickAt = 0;
 
 /**
- * Notifies every listener when the page comes back from being away long enough that the
- * event stream can not be trusted to have delivered everything: a backgrounded tab, an
- * app the phone suspended, a sleeping device. Returns an unsubscribe function.
- *
- * Time away is the gap between the ticks of a heartbeat that only runs while the page is
- * in the foreground, since a suspended page is never handed the transition to hidden that
- * a return would otherwise be measured against.
+ * Notifies listeners when the page comes back from being away long enough (backgrounded tab,
+ * suspended app, sleeping device) that the stream can't be trusted to have delivered everything.
+ * Time away is the gap between foreground heartbeat ticks, since a suspended page never gets
+ * the transition to hidden a return could otherwise be measured against. Returns an unsubscribe.
  */
 function subscribeToPageReturn(listener: () => void) {
 	returnListeners.add(listener);
@@ -190,8 +178,7 @@ function noticeReturn() {
 	const awayFor = Date.now() - lastForegroundTickAt;
 	lastForegroundTickAt = Date.now();
 
-	// a quick tab away can not have missed anything the stream would not still
-	// deliver, and catching up for it would be pure server load
+	// a quick tab away misses nothing the stream won't still deliver; catching up would be pure server load
 	if (awayFor < CATCH_UP_AWAY_MS) return;
 
 	for (const listener of returnListeners) {
diff --git a/app/features/events/routes/sse.ts b/app/features/events/routes/sse.ts
index 0c1d2f626..5360a95fa 100644
--- a/app/features/events/routes/sse.ts
+++ b/app/features/events/routes/sse.ts
@@ -86,7 +86,7 @@ export const loader = ({ request }: LoaderFunctionArgs) => {
 	return new Response(stream, {
 		headers: {
 			"Content-Type": "text/event-stream",
-			// no-transform keeps the compression middleware from buffering the stream
+			// no-transform keeps compression from buffering the stream
 			"Cache-Control": "no-cache, no-transform",
 			"X-Accel-Buffering": "no",
 		},
diff --git a/app/features/friends/friends-utils.server.ts b/app/features/friends/friends-utils.server.ts
index ec21293bd..981833608 100644
--- a/app/features/friends/friends-utils.server.ts
+++ b/app/features/friends/friends-utils.server.ts
@@ -38,10 +38,7 @@ const TOURNAMENT_STATUS_IS_IN_PROGRESS: Record<
 	THANKS_FOR_PLAYING: false,
 };
 
-/**
- * Twitch account streaming each ongoing SendouQ match, keyed by match id. Resolved
- * once per request as activity is resolved separately for every friend.
- */
+/** Twitch account streaming each ongoing SendouQ match, keyed by match id. Resolved once per request, activity being resolved per friend. */
 export async function resolveSendouQMatchStreams() {
 	const streams = await cachedStreams();
 
@@ -55,11 +52,7 @@ export async function resolveSendouQMatchStreams() {
 	return result;
 }
 
-/**
- * Resolves what a friend is currently doing for display in the friends list,
- * prioritizing in-progress activity (an ongoing SendouQ or tournament match) over
- * looking-for-members activity.
- */
+/** What a friend is currently doing, an ongoing SendouQ or tournament match taking priority over looking for members. */
 export function resolveFriendActivity({
 	friendId,
 	tournamentId,
@@ -156,11 +149,7 @@ function resolveTournamentActivity(friendId: number): FriendActivity | null {
 	return null;
 }
 
-/**
- * Where the friend's ongoing tournament match can be watched, preferring the view
- * that shows the friend best: their own stream, then a teammate's stream, then the
- * official cast of the match and finally an opponent's.
- */
+/** Where the friend's tournament match can be watched, preferring the view showing them best: own stream, teammate's, official cast, opponent's. */
 function tournamentStreamUrl({
 	tournament,
 	friendId,
diff --git a/app/features/front-page/core/ShowcaseTournaments.server.ts b/app/features/front-page/core/ShowcaseTournaments.server.ts
index d9940c4e3..b93baf2aa 100644
--- a/app/features/front-page/core/ShowcaseTournaments.server.ts
+++ b/app/features/front-page/core/ShowcaseTournaments.server.ts
@@ -120,10 +120,7 @@ export function removeFromCached({
 	participationInfoMap.set(userId, participation);
 }
 
-/**
- * Re-reads the team & participant counts of one tournament from the database into the cached
- * showcase tournaments. No-op if the tournament is not part of the current cache.
- */
+/** Refreshes one cached showcase tournament's team & participant counts; no-op if not cached. */
 export async function refreshCachedTournamentCounts(tournamentId: number) {
 	if (!cache.has(SHOWCASE_TOURNAMENTS_CACHE_KEY)) return;
 
diff --git a/app/features/img-export/components/Graphic.module.css b/app/features/img-export/components/Graphic.module.css
index 9542f1b5c..a07193a1f 100644
--- a/app/features/img-export/components/Graphic.module.css
+++ b/app/features/img-export/components/Graphic.module.css
@@ -28,10 +28,7 @@
 	border-radius: var(--radius-box);
 }
 
-/*
-Zero-specificity theme scoping so that a forced [data-theme] wrapper always
-beats the html class regardless of which one is in effect
-*/
+/* zero specificity so a forced [data-theme] wrapper always beats the html class */
 :global(:where(html.light)) .container,
 :global(:where([data-theme="light"])) .container {
 	--graphic-first: oklch(58% 0.12 85);
@@ -51,11 +48,7 @@ beats the html class regardless of which one is in effect
 	gap: var(--s-3);
 }
 
-/*
-The image export freezes each element's width, so a shrink-to-fit box would clip its own
-text. Both sides of the header grow into the free space instead, which keeps them at the
-same place as an auto margin would but leaves their text room to breathe.
-*/
+/* the export freezes widths, so both header sides grow into the free space instead of shrink-to-fit */
 .headerText {
 	flex: 1 1 auto;
 	min-width: 0;
@@ -72,9 +65,8 @@ same place as an auto margin would but leaves their text room to breathe.
 }
 
 .headerTitle {
-	/* the export freezes this box at its exact text width, so it has to claim the row's free
-	space rather than shrink-wrap, or a glyph the raster measures wider gets ellipsised away.
-	Basis stays auto so the title still contributes its text to the row's intrinsic width */
+	/* claims the row's free space or a glyph the raster measures wider gets ellipsised;
+	auto basis so the title still contributes to the row's intrinsic width */
 	flex: 1 1 auto;
 	min-width: 0;
 	overflow: hidden;
@@ -210,8 +202,7 @@ same place as an auto margin would but leaves their text room to breathe.
 	color: var(--graphic-text-dim);
 }
 
-/* no ellipsis: the chips wrap and a username is capped well below the row width, so truncating
-here only ever fired on the frozen-width rounding described above */
+/* no ellipsis: chips wrap and usernames are capped, so truncation only fired on frozen-width rounding */
 .playerName {
 	white-space: nowrap;
 }
diff --git a/app/features/img-export/components/Graphic.tsx b/app/features/img-export/components/Graphic.tsx
index aa0972696..df10c852a 100644
--- a/app/features/img-export/components/Graphic.tsx
+++ b/app/features/img-export/components/Graphic.tsx
@@ -17,10 +17,7 @@ const GRAPHIC_DATE_FORMAT_OPTIONS: Intl.DateTimeFormatOptions = {
 	year: "numeric",
 };
 
-/**
- * Sizes that keep the code at roughly two pixels per module. The lengths are the byte
- * capacities of the QR versions used at the default "L" error correction level.
- */
+/** ~2px per module; the lengths are byte capacities of the QR versions at "L" error correction. */
 const QR_CODE_SIZE_BREAKPOINTS = [
 	{ maxUrlLength: 106, size: 56 },
 	{ maxUrlLength: 271, size: 84 },
@@ -29,7 +26,7 @@ const QR_CODE_SIZE_BREAKPOINTS = [
 
 const QR_CODE_SIZE_MAX = 144;
 
-/** Full URL the graphic's QR code should link to, provided by `ImageExportDialog` (null = no QR code) */
+/** URL the QR code links to, provided by `ImageExportDialog` (null = no QR code) */
 export const GraphicQrCodeContext = React.createContext<string | null>(null);
 
 export interface GraphicPlayer {
@@ -80,7 +77,7 @@ export function GraphicHeader({
 	titleRow: React.ReactNode;
 	subtitle: React.ReactNode;
 	trailing?: React.ReactNode;
-	/** Line the trailing content up with the title instead of centering it against the title and subtitle together */
+	/** Align the trailing content with the title instead of the title + subtitle block */
 	alignTrailingWithTitle?: boolean;
 } & (
 	| { avatarUrl?: string; identiconInput: string; leading?: never }
@@ -112,7 +109,6 @@ export function GraphicHeader({
 	);
 }
 
-/** the graphic's headline text, sized to claim the header row's free space */
 export function GraphicTitle({ children }: { children: React.ReactNode }) {
 	return <span className={styles.headerTitle}>{children}</span>;
 }
@@ -220,10 +216,7 @@ export function GraphicTeamRow({
 	);
 }
 
-/**
- * A chip is sized by its content, and the image export freezes each element's width. Inline
- * elements are exempt from that, so the chip must stay a `span` or its name gets clipped.
- */
+/** Must stay a `span`: the export freezes block widths and would clip the content-sized name. */
 export function GraphicPlayerChip({ player }: { player: GraphicPlayer }) {
 	return (
 		<span className={styles.player}>
diff --git a/app/features/img-export/components/ImageExportDialog.tsx b/app/features/img-export/components/ImageExportDialog.tsx
index 9470dd118..159198df7 100644
--- a/app/features/img-export/components/ImageExportDialog.tsx
+++ b/app/features/img-export/components/ImageExportDialog.tsx
@@ -45,23 +45,20 @@ const THEME_SELECTIONS = [
 ] as const;
 
 interface ImageExportDialogProps {
-	/** Button that opens the dialog, e.g. a `SendouButton` (its own `onPress` also runs, useful for lazy loading the graphic's data) */
+	/** Opens the dialog; its own `onPress` also runs (useful for lazy loading the graphic's data) */
 	trigger: React.ReactNode;
 	heading: string;
 	/** Name of the downloaded file without the extension */
 	filename: string;
 	/** Path the QR code links to, defaults to the current page */
 	qrCodePath?: string;
-	/** Extra settings controls specific to the use case */
 	settings?: React.ReactNode;
-	/** The graphic to preview and export */
 	children: React.ReactNode;
 }
 
 /**
- * Dialog for exporting a graphic component as a .png image. Renders the given graphic
- * as a preview with generic settings (color scheme, custom theme, QR code) and downloads
- * a screenshot of it via snapdom. Graphics render their QR code via {@link GraphicQrCodeContext}.
+ * Previews a graphic with generic settings (color scheme, custom theme, QR code) and downloads a
+ * snapdom screenshot of it as .png. Graphics render their QR code via {@link GraphicQrCodeContext}.
  */
 export function ImageExportDialog({
 	trigger,
@@ -110,11 +107,9 @@ function ImageExportDialogContent({
 
 	const qrCodeUrl = `${SENDOU_INK_BASE_URL}${qrCodePath ?? `${location.pathname}${location.search}`}`;
 
-	// snapdom re-downloads every image at export time rather than reusing what the preview
-	// already painted, and silently drops any that fails. Warming them while the preview sits
-	// idle keeps those fetches from racing the capture's own work for the main thread.
-	// Runs after every render because settings can mount images that were not there before
-	// (e.g. the build export's ability chunks); re-running once everything is cached is ~7ms.
+	// snapdom re-downloads every image at export and silently drops failures, so they are warmed
+	// while the preview idles. Runs after every render since settings can mount new images
+	// (e.g. ability chunks); re-running once cached is ~7ms.
 	React.useEffect(() => {
 		if (exportAction) return;
 
@@ -246,10 +241,7 @@ function canCopyPngToClipboard() {
 	return typeof ClipboardItem !== "undefined";
 }
 
-/**
- * Opens the share sheet when sharing is allowed (mobile) and the platform supports it,
- * otherwise downloads the image
- */
+/** Share sheet when allowed (mobile) and supported, otherwise a download. */
 async function saveImage(
 	blob: Blob,
 	filename: string,
diff --git a/app/features/img-export/components/SeasonSummaryGraphic.module.css b/app/features/img-export/components/SeasonSummaryGraphic.module.css
index 94de1337a..eead55125 100644
--- a/app/features/img-export/components/SeasonSummaryGraphic.module.css
+++ b/app/features/img-export/components/SeasonSummaryGraphic.module.css
@@ -1,7 +1,4 @@
-/*
-:where() keeps the box base at zero specificity so the single-class variants
-below win regardless of which CSS chunk loads last
-*/
+/* zero specificity so the single-class variants below always win */
 :where(.box) {
 	padding: var(--s-2) var(--s-3);
 	background-color: var(--graphic-row-bg);
diff --git a/app/features/img-export/components/SeasonSummaryGraphic.tsx b/app/features/img-export/components/SeasonSummaryGraphic.tsx
index 75409b066..4a462fd94 100644
--- a/app/features/img-export/components/SeasonSummaryGraphic.tsx
+++ b/app/features/img-export/components/SeasonSummaryGraphic.tsx
@@ -49,7 +49,7 @@ const CALENDAR_WEEK_LENGTH = 7;
 const CALENDAR_WEEK_MONTH_DAY_INDEX = 3;
 /** Monday and Friday, the only rows the calendar names */
 const CALENDAR_NAMED_WEEKDAY_INDICES = [0, 4];
-/** Without weapons the teammates box is alone next to the activity calendar, so it has room for more */
+/** Without weapons the teammates box is alone next to the calendar, so it has room for more */
 const TOP_MATES_COUNT_WITHOUT_WEAPONS = 6;
 
 export type SeasonSummaryGraphicActivity = "sq" | "tournament" | "both";
@@ -58,7 +58,7 @@ export interface SeasonSummaryGraphicBestSet {
 	opponentPlayers: GraphicPlayer[];
 	ownScore: number;
 	opponentScore: number;
-	/** Average SP of the opposing players at the time the set was played */
+	/** Average SP of the opponents when the set was played */
 	opponentSp: number;
 	/** Where the set was played e.g. "SendouQ" or a tournament name */
 	context: string;
@@ -72,7 +72,7 @@ export interface SeasonSummaryGraphicStats {
 	mapsWon: number;
 	mapsLost: number;
 	longestWinStreak: number;
-	/** Sets that went to a deciding map: how many of those were won */
+	/** Sets that went to a deciding map */
 	clutch?: { won: number; total: number };
 	soloRank?: number;
 	teamRank?: {
@@ -605,10 +605,7 @@ function CalendarWeekdays({ firstWeek }: { firstWeek: Date[] }) {
 	);
 }
 
-/**
- * The season's Monday to Sunday week columns. A season ending mid-week (its last hours can fall on the
- * next day depending on the time zone) would leave a ragged column, so an incomplete last week is left out.
- */
+/** Monday to Sunday week columns; an incomplete last week (a season ending mid-week) is left out. */
 function seasonWeeks({
 	seasonFirstDay,
 	seasonLastDay,
diff --git a/app/features/img-export/core/RunComps.ts b/app/features/img-export/core/RunComps.ts
index e88c8973d..60740cbd0 100644
--- a/app/features/img-export/core/RunComps.ts
+++ b/app/features/img-export/core/RunComps.ts
@@ -6,7 +6,7 @@ const TACTICOOLER_SPECIAL_WEAPON_ID = 15;
 const COMP_SIZE = 4;
 
 export interface CompObservation {
-	/** Identity of the player within the aggregated maps: user id when known, otherwise the ingested scoreboard name */
+	/** User id when known, otherwise the ingested scoreboard name */
 	playerKey: string;
 	weaponSplId: MainWeaponId;
 	/** Chronological index of the map the weapon was played in */
@@ -14,11 +14,8 @@ export interface CompObservation {
 }
 
 /**
- * Builds a team's weapon comp from per map weapon observations. Each player
- * contributes the weapon they played the most (ties broken by the most
- * recently played one). The comp is in weapon id order, except weapons with
- * Tacticooler as the special go last. When more than {@link COMP_SIZE}
- * players were observed, the ones that played the most maps make the comp.
+ * Each player contributes their most played weapon (ties: most recent). Weapon id order, Tacticooler
+ * weapons last. Over {@link COMP_SIZE} players, the ones with the most maps make the comp.
  */
 export function buildComp(observations: CompObservation[]): MainWeaponId[] {
 	const byPlayer = new Map<string, CompObservation[]>();
@@ -43,11 +40,8 @@ export function buildComp(observations: CompObservation[]): MainWeaponId[] {
 }
 
 /**
- * Converts one map's reported and ingested weapon rows of a team into comp
- * observations. Ingested rows that duplicate a reported weapon are dropped:
- * a row linked to a user that already reported, or an unlinked row whose
- * weapon a report already accounts for (a multiset, matching how the match
- * page timeline merges the two sources).
+ * One map's reported and ingested weapon rows as observations. Ingested rows duplicating a report
+ * are dropped (same user, or an unlinked row whose weapon a report already covers, as a multiset).
  */
 export function mapObservations({
 	mapOrder,
diff --git a/app/features/img-export/core/SeasonSummary.ts b/app/features/img-export/core/SeasonSummary.ts
index 568b77778..9458982d1 100644
--- a/app/features/img-export/core/SeasonSummary.ts
+++ b/app/features/img-export/core/SeasonSummary.ts
@@ -18,10 +18,7 @@ export interface SetScore {
 	opponentScore: number;
 }
 
-/**
- * Length of the longest run of consecutive set wins in the given
- * chronologically ordered list of sets.
- */
+/** Longest run of consecutive set wins; `sets` must be in chronological order. */
 export function longestWinStreak(sets: SetScore[]): number {
 	let longest = 0;
 	let current = 0;
@@ -38,10 +35,7 @@ export function longestWinStreak(sets: SetScore[]): number {
 	return longest;
 }
 
-/**
- * Win record in sets that went to a deciding map, i.e. the score margin was
- * exactly one (4-3 in SendouQ, 2-1/3-2 in tournaments).
- */
+/** Win record in sets decided by one map (4-3 in SendouQ, 2-1/3-2 in tournaments). */
 export function clutchRecord(sets: SetScore[]): { won: number; total: number } {
 	const decidingMapSets = sets.filter(
 		(set) => Math.abs(set.ownScore - set.opponentScore) === 1,
@@ -54,11 +48,7 @@ export function clutchRecord(sets: SetScore[]): { won: number; total: number } {
 	};
 }
 
-/**
- * Stage with the best winrate aggregated across modes. Stages with less than
- * a minimum threshold of maps played are excluded so a lucky 2-0 stage can't
- * win. Returns undefined when no stage passes the threshold.
- */
+/** Best winrate stage across modes; stages under the maps-played threshold are excluded so a lucky 2-0 can't win. */
 export function bestStage(
 	stages: Partial<
 		Record<
@@ -90,19 +80,15 @@ export function bestStage(
 }
 
 export interface TournamentRun {
-	/** Tournament tier, 1 = X (best) … 9 = C. Null when the tournament has no calculated tier (treated as below every tiered tournament). */
+	/** 1 = X (best) … 9 = C. Null (no calculated tier) ranks below every tiered tournament. */
 	tier: number | null;
 	placement: number;
 	teamsCount: number;
-	/** Average end of season SP of the players who placed in the tournament's top 8. Null when none of them had a calculated skill. */
+	/** Average end of season SP of the top 8 placers; null when none had a calculated skill. */
 	topEightAvgSp: number | null;
 }
 
-/**
- * Composite score for ranking a user's tournament runs of a season. The
- * tournament's tier dominates; within a tier both the user's placement quality
- * relative to the field size and the strength of that field contribute.
- */
+/** Ranks a season's tournament runs: tier dominates, then placement relative to field size and field strength. */
 export function tournamentRunScore(run: TournamentRun): number {
 	const tier = run.tier ?? UNTIERED_TOURNAMENT_TIER;
 
@@ -120,10 +106,7 @@ export function bestTournamentRun<T extends TournamentRun>(
 	return R.firstBy(runs, [tournamentRunScore, "desc"]);
 }
 
-/**
- * The user's most used weapons with their share of all reported weapon
- * occurrences, most used first.
- */
+/** Most used weapons with their share of all reported weapon occurrences, most used first. */
 export function topWeaponUsages(
 	reportedWeapons: Array<{ weaponSplId: MainWeaponId; count: number }>,
 ): Array<{ weaponSplId: MainWeaponId; usagePercentage: number }> {
@@ -139,15 +122,12 @@ export function topWeaponUsages(
 		}));
 }
 
-/** Whether the season has ended, a prerequisite for exporting its summary image. */
+/** Whether the season has ended. */
 export function isSeasonFinished(season: number, date = new Date()) {
 	return Seasons.allFinished(date).some((nth) => nth === season);
 }
 
-/**
- * Whether a season's summary image is exportable without the supporter perk:
- * only the latest finished season is, and only while no season is in progress.
- */
+/** Exportable without the supporter perk: only the latest finished season, and only while no season is in progress. */
 export function isSeasonExportableByAll(season: number, date = new Date()) {
 	return (
 		Seasons.current(date) === null && Seasons.allFinished(date)[0] === season
@@ -155,11 +135,8 @@ export function isSeasonExportableByAll(season: number, date = new Date()) {
 }
 
 /**
- * Whether the logged in user can export the season summary image from the
- * given profile. Only the profile owner can export, they must have
- * participated in the season and have a calculated (non-approximate) skill
- * for it. An ongoing season is never exportable. Supporters can export any of
- * their finished seasons, others only per {@link isSeasonExportableByAll}.
+ * Only the profile owner can export, with a non-approximate skill for a finished season. Supporters
+ * can export any finished season, others only per {@link isSeasonExportableByAll}.
  */
 export function canExportSeasonSummary({
 	loggedInUser,
diff --git a/app/features/img-upload/ImageRepository.server.ts b/app/features/img-upload/ImageRepository.server.ts
index 7e35ac0ce..69f889313 100644
--- a/app/features/img-upload/ImageRepository.server.ts
+++ b/app/features/img-upload/ImageRepository.server.ts
@@ -5,7 +5,7 @@ import { databaseTimestampNow } from "~/utils/dates";
 import { concatUserSubmittedImagePrefix } from "~/utils/kysely.server";
 import { IMAGES_TO_VALIDATE_AT_ONCE } from "./upload-constants";
 
-/** Finds an unvalidated image by ID with associated calendar event data */
+/** Unvalidated image with its calendar event data. */
 export function findById(id: number) {
 	return db
 		.selectFrom("UnvalidatedUserSubmittedImage")
@@ -19,7 +19,7 @@ export function findById(id: number) {
 		.executeTakeFirst();
 }
 
-/** Deletes an image and its associated art entry in a transaction */
+/** Deletes an image and its art entry. */
 export function deleteById(id: number) {
 	return db.transaction().execute(async (trx) => {
 		await trx.deleteFrom("Art").where("Art.imgId", "=", id).execute();
@@ -30,7 +30,7 @@ export function deleteById(id: number) {
 	});
 }
 
-/** Counts unvalidated art images for a specific author */
+/** Count of the author's unvalidated art images. */
 export async function countUnvalidatedArt(authorId: number) {
 	const result = await db
 		.selectFrom("UnvalidatedUserSubmittedImage")
@@ -85,7 +85,7 @@ const unvalidatedImagesBaseQuery = db
 		]),
 	);
 
-/** Counts all unvalidated images used in teams, art, or calendar events */
+/** Count of unvalidated images used in teams, art or calendar events. */
 export async function countAllUnvalidated() {
 	const result = await unvalidatedImagesBaseQuery
 		.select(({ fn }) => fn.countAll<number>().as("count"))
@@ -93,7 +93,7 @@ export async function countAllUnvalidated() {
 	return result.count;
 }
 
-/** Fetches unvalidated images for admin review with submitter info */
+/** Unvalidated images for admin review, with submitter info. */
 export function findAllUnvalidated() {
 	return unvalidatedImagesBaseQuery
 		.leftJoin(
@@ -113,11 +113,7 @@ export function findAllUnvalidated() {
 		.execute();
 }
 
-/**
- * Counts unvalidated images submitted by a user that are connected to a team, art, or calendar
- * event (i.e. excluding not-yet-connected orphans), so it can gate the SendouForm `image()` upload
- * path.
- */
+/** Count of the user's unvalidated images connected to a team, art or event (orphans excluded); gates `image()` uploads. */
 export async function countUnvalidatedBySubmitterUserId(userId: number) {
 	const result = await unvalidatedImagesBaseQuery
 		.select(({ fn }) => fn.countAll<number>().as("count"))
@@ -126,7 +122,7 @@ export async function countUnvalidatedBySubmitterUserId(userId: number) {
 	return result.count;
 }
 
-/** Marks an image as validated by setting the current timestamp */
+/** Marks an image as validated. */
 export function validateById(id: number) {
 	return db
 		.updateTable("UnvalidatedUserSubmittedImage")
@@ -135,9 +131,7 @@ export function validateById(id: number) {
 		.execute();
 }
 
-/**
- * Inserts an unvalidated image row without associating it with any owner. Returns the inserted row.
- */
+/** Inserts an unvalidated image row without an owner. Returns the inserted row. */
 export function insert(
 	args: TablesInsertable["UnvalidatedUserSubmittedImage"],
 	trx?: Transaction<DB>,
diff --git a/app/features/img-upload/image-bytes.server.ts b/app/features/img-upload/image-bytes.server.ts
index 3fb4715bd..9be02c18c 100644
--- a/app/features/img-upload/image-bytes.server.ts
+++ b/app/features/img-upload/image-bytes.server.ts
@@ -2,11 +2,7 @@ import invariant from "~/utils/invariant";
 
 export type ImageExtension = "webp" | "png" | "jpeg";
 
-/**
- * Decodes a base64 image data URL to a buffer, resolving the format from the buffer's own magic
- * bytes rather than trusting the client-declared mime type, and asserting it is one of
- * `allowedExtensions`.
- */
+/** Format is resolved from the magic bytes, not the client-declared mime type, and must be in `allowedExtensions`. */
 export function dataUrlToImageBuffer(
 	dataUrl: string,
 	allowedExtensions: ReadonlyArray<ImageExtension>,
diff --git a/app/features/img-upload/image-field.server.ts b/app/features/img-upload/image-field.server.ts
index 83eb42c74..7db1874f8 100644
--- a/app/features/img-upload/image-field.server.ts
+++ b/app/features/img-upload/image-field.server.ts
@@ -12,15 +12,9 @@ import { uploadStreamToS3 } from "./s3.server";
 import { MAX_UNVALIDATED_IMG_COUNT } from "./upload-constants";
 
 /**
- * Resolves a SendouForm `image` field value to the image id to store on the consuming FK column.
- *
- * - `null` → `null` (image removed / none)
- * - `EXISTING` → the unchanged `imgId` (no bytes are re-uploaded)
- * - `NEW` → decodes the base64 image, uploads it to S3 and inserts an unvalidated image row,
- *   auto-validating it for supporters (or always when `autoValidate` is set), then returns the
- *   new id.
- *
- * The consuming action is responsible for writing the returned value to its own FK column.
+ * Resolves a SendouForm `image` field value to the image id the caller stores on its FK column:
+ * `null` → `null`, `EXISTING` → the unchanged `imgId`, `NEW` → uploads to S3 and inserts an
+ * unvalidated image row (auto-validated for supporters or when `autoValidate` is set).
  */
 export async function imageFieldValueToImgId({
 	value,
@@ -29,7 +23,7 @@ export async function imageFieldValueToImgId({
 }: {
 	value: ImageFieldValue;
 	user: AuthenticatedUser;
-	/** Validate the image immediately, bypassing the moderator queue (e.g. trusted org logos). */
+	/** Bypass the moderator queue (e.g. trusted org logos). */
 	autoValidate?: boolean;
 }): Promise<number | null> {
 	if (!value) return null;
diff --git a/app/features/layout/LayoutDataProvider.tsx b/app/features/layout/LayoutDataProvider.tsx
index f3f217c3f..76f0806c4 100644
--- a/app/features/layout/LayoutDataProvider.tsx
+++ b/app/features/layout/LayoutDataProvider.tsx
@@ -27,10 +27,8 @@ const LayoutDataContext = React.createContext<LayoutDataContextValue>({
 });
 
 /**
- * Serves the parts of the app shell that go stale while a page sits open, from
- * the root loader first and from a polled resource route after. Polling instead
- * of revalidating means a page whose own loader is expensive (plus suggestions,
- * a tournament's brackets) is not refetched just to refresh the sidebar.
+ * App shell data that goes stale while a page sits open: from the root loader first, then a polled
+ * resource route, so pages with expensive loaders are not refetched just to refresh the sidebar.
  */
 export function LayoutDataProvider({
 	data,
@@ -45,8 +43,7 @@ export function LayoutDataProvider({
 		refresh,
 	} = useBackgroundResource<SerializeFrom<typeof loader>>(LAYOUT_DATA_ROUTE);
 
-	// read through a ref so a poll elsewhere in the app does not re-run the effect
-	// and restart the interval before it ever fires
+	// a ref so a poll elsewhere does not re-run the effect and restart the interval before it fires
 	const isLoadingRef = React.useRef(isLoading);
 	isLoadingRef.current = isLoading;
 
@@ -93,10 +90,7 @@ export function LayoutDataProvider({
 	);
 }
 
-/**
- * App shell data (sidebar, build commit), fresher than the root loader
- * whenever a poll has landed since the last root revalidation.
- */
+/** App shell data, fresher than the root loader whenever a poll has landed since. */
 export function useLayoutData() {
 	return React.useContext(LayoutDataContext);
 }
@@ -117,11 +111,7 @@ function useReloadOnStaleAuth({
 	}, [clientUserId, serverUserId]);
 }
 
-/**
- * Whichever of the two arrived last. The root loader reruns on every navigation
- * and the poll fires on its own schedule, so neither source is reliably the
- * newer one and both have to be watched for a change.
- */
+/** Whichever arrived last; neither the root loader nor the poll is reliably the newer one. */
 function useNewestOf(
 	rootData: RootLoaderData | undefined,
 	polledData: LayoutData | undefined,
diff --git a/app/features/layout/core/layout.server.ts b/app/features/layout/core/layout.server.ts
index b4dd08477..dc910bfd2 100644
--- a/app/features/layout/core/layout.server.ts
+++ b/app/features/layout/core/layout.server.ts
@@ -3,11 +3,8 @@ import { resolveSidebarData } from "~/features/sidebar/core/sidebar.server";
 import { GIT_COMMIT } from "~/utils/git-commit";
 
 /**
- * The parts of the app shell that go stale on their own while a page sits open.
- * Served both by the root loader and by the resource route `LayoutDataProvider`
- * polls, so the two payloads can't drift apart. Notifications are not part of
- * this: they live in their own resource route refetched when the server
- * publishes that they changed (see `NotificationsProvider`).
+ * App shell data that goes stale while a page sits open; shared by the root loader and the route
+ * `LayoutDataProvider` polls so they can't drift. Notifications have their own route (`NotificationsProvider`).
  */
 export async function resolveLayoutData(user: AuthenticatedUser | undefined) {
 	return {
diff --git a/app/features/layout/routes/api.layout.ts b/app/features/layout/routes/api.layout.ts
index bad2280be..d35ca11cd 100644
--- a/app/features/layout/routes/api.layout.ts
+++ b/app/features/layout/routes/api.layout.ts
@@ -1,11 +1,7 @@
 import { getUser } from "~/features/auth/core/user.server";
 import { resolveLayoutData } from "../core/layout.server";
 
-/**
- * The parts of the root loader that go stale on their own while a page sits
- * open. Polled by `LayoutDataProvider` so keeping them fresh does not mean
- * rerunning every loader of whatever route the user happens to be on.
- */
+/** Polled by `LayoutDataProvider` so refreshing the app shell doesn't rerun the current route's loaders. */
 export const loader = async () => {
 	return resolveLayoutData(getUser());
 };
diff --git a/app/features/leaderboards/LeaderboardRepository.server.ts b/app/features/leaderboards/LeaderboardRepository.server.ts
index ddd2f69db..092e0b26d 100644
--- a/app/features/leaderboards/LeaderboardRepository.server.ts
+++ b/app/features/leaderboards/LeaderboardRepository.server.ts
@@ -33,7 +33,7 @@ function addPowers<T extends { ordinal: number }>(entries: T[]) {
 	}));
 }
 
-/** Numbers the entries by placement. A skipped team keeps its spot in the order but takes no number, the one below it getting the number it would have had. */
+/** Numbers the entries by placement; a skipped team keeps its spot but no number, which passes to the one below. */
 function addPlacementRank<T extends { isSkipped: boolean }>(entries: T[]) {
 	let placementRank = 0;
 
@@ -121,7 +121,7 @@ export async function findTeamLeaderboardBySeason({
 	season: number;
 	onlyOneEntryPerUser: boolean;
 }) {
-	// skipping is about the season finale qualification which the all rosters leaderboard is not concerned with
+	// skipping concerns season finale qualification, not the all rosters leaderboard
 	const entries = addSkipped({
 		entries: await teamLeaderboardBySeasonQuery(season).execute(),
 		skippedIdentifiers: onlyOneEntryPerUser
diff --git a/app/features/leaderboards/core/leaderboards.server.test.ts b/app/features/leaderboards/core/leaderboards.server.test.ts
index b88f3472f..ae34a0097 100644
--- a/app/features/leaderboards/core/leaderboards.server.test.ts
+++ b/app/features/leaderboards/core/leaderboards.server.test.ts
@@ -10,11 +10,7 @@ import {
 
 const FIRST_TIED_RANK = DEFAULT_LEADERBOARD_MAX_SIZE - 2;
 
-/**
- * Leaderboard where five players are tied in SP across the shown-size cutoff:
- * indices 497–501 (0-based) all share placementRank 498, like players who
- * finished the season having played every match in the same stack do.
- */
+/** Leaderboard with five players tied across the shown-size cutoff: indices 497–501 share placementRank 498, like a stack that played every match together. */
 const leaderboardWithTieAcrossCutoff = () =>
 	Array.from({ length: DEFAULT_LEADERBOARD_MAX_SIZE + 2 }, (_, i) => {
 		const placementRank = i >= FIRST_TIED_RANK - 1 ? FIRST_TIED_RANK : i + 1;
diff --git a/app/features/leaderboards/core/leaderboards.server.ts b/app/features/leaderboards/core/leaderboards.server.ts
index 80dc80228..2c506a27d 100644
--- a/app/features/leaderboards/core/leaderboards.server.ts
+++ b/app/features/leaderboards/core/leaderboards.server.ts
@@ -69,7 +69,7 @@ export async function cachedTeamLeaderboard({
 	});
 }
 
-/** Clears both variants of a season's cached team leaderboard, so that a change to which teams are skipped shows without waiting for the cache to expire. */
+/** Clears both variants of a season's cached team leaderboard so a skip change shows without waiting for expiry. */
 export function clearCachedTeamLeaderboards(season: number) {
 	for (const onlyOneEntryPerUser of [true, false]) {
 		cache.delete(teamLeaderboardCacheKey({ season, onlyOneEntryPerUser }));
@@ -185,12 +185,7 @@ export function filterByWeaponCategory<
 	);
 }
 
-/**
- * The entries of the full user leaderboard that are visible on the leaderboard
- * page. Cut by placement rank instead of entry count so that players tied
- * across the cutoff are all shown; {@link ownEntryPeek} covers exactly the
- * entries this leaves out.
- */
+/** The user leaderboard entries the page shows, cut by placement rank (not count) so ties across the cutoff all show; {@link ownEntryPeek} covers what this leaves out. */
 export function shownUserLeaderboard(
 	leaderboard: UserLeaderboardWithAdditionsItem[],
 ) {
diff --git a/app/features/lfg/LFGRepository.server.test.ts b/app/features/lfg/LFGRepository.server.test.ts
index 678b6cda2..0b0123fd0 100644
--- a/app/features/lfg/LFGRepository.server.test.ts
+++ b/app/features/lfg/LFGRepository.server.test.ts
@@ -20,9 +20,8 @@ describe("LFGRepository.findAllPosts plus-tier visibility", () => {
 		});
 		expect(whileMember.map((post) => post.id)).toContain(postId);
 
-		// next monthly voting drops the author from the plus server: plusTier -> null.
-		// Their own post must remain visible to them, otherwise DELETE_POST / BUMP_POST
-		// (which resolve the post through findAllPosts) 404 and it can never be taken down.
+		// monthly voting drops the author from the plus server (plusTier -> null); their own post
+		// must stay visible or DELETE_POST / BUMP_POST (resolved through findAllPosts) 404 forever
 		const afterDrop = await LFGRepository.findAllPosts({
 			id: author.id,
 			plusTier: null,
diff --git a/app/features/lfg/core/timezone.ts b/app/features/lfg/core/timezone.ts
index 74ea77556..9bde62d50 100644
--- a/app/features/lfg/core/timezone.ts
+++ b/app/features/lfg/core/timezone.ts
@@ -1,5 +1,3 @@
-// timezone example is 'Asia/Tokyo'
-
 /** Hours between the local clock times of two timezones, wrapped to [-12, 12]. */
 export function hourDifferenceBetweenTimezones(
 	timezone1: string,
@@ -8,11 +6,7 @@ export function hourDifferenceBetweenTimezones(
 	return createTimezoneHourDifference()(timezone1, timezone2);
 }
 
-/**
- * Same as {@link hourDifferenceBetweenTimezones}, but resolving each timezone's
- * offset only once. Resolving an offset is expensive, so comparing many
- * timezones (filtering a list of posts, say) should share one instance.
- */
+/** {@link hourDifferenceBetweenTimezones} resolving each timezone's offset only once; resolving is expensive, so comparing many (filtering posts) should share one instance. */
 export function createTimezoneHourDifference() {
 	const offsets = new Map<string, number>();
 
@@ -38,19 +32,16 @@ export function createTimezoneHourDifference() {
 function getTimezoneOffset(timeZone: string) {
 	const date = new Date();
 
-	// Abuse the Intl API to get a local ISO 8601 string for a given time zone.
+	// Intl gives a local ISO 8601 string for the time zone
 	let iso = date
 		.toLocaleString("en-CA", { timeZone, hour12: false })
 		.replace(", ", "T");
 
-	// Include the milliseconds from the original timestamp
 	iso += `.${date.getMilliseconds().toString().padStart(3, "0")}`;
 
-	// Lie to the Date object constructor that it's a UTC time.
+	// parsed as if UTC
 	const lie = new Date(`${iso}Z`);
 
-	// Return the difference in timestamps, as minutes
-	// Positive values are West of GMT, opposite of ISO 8601
-	// this matches the output of `Date.getTimeZoneOffset`
+	// minutes, positive West of GMT (opposite of ISO 8601) like `Date.getTimezoneOffset`
 	return -(lie.getTime() - date.getTime()) / 60 / 1000;
 }
diff --git a/app/features/live-streams/LiveStreamRepository.server.ts b/app/features/live-streams/LiveStreamRepository.server.ts
index 819c3f21d..56deb8265 100644
--- a/app/features/live-streams/LiveStreamRepository.server.ts
+++ b/app/features/live-streams/LiveStreamRepository.server.ts
@@ -11,11 +11,7 @@ export function replaceAll(streams: Omit<Tables["LiveStream"], "id">[]) {
 	});
 }
 
-/**
- * Adds the given accounts as streamers of their tournament. Returns the ids of the
- * rows actually inserted, in insertion order — an account already streaming that
- * tournament is skipped and so has no id among them.
- */
+/** Adds the accounts as streamers of their tournament, returning the inserted ids in order; an account already streaming it is skipped. */
 export function insertTournamentStreamers(
 	rows: Omit<Tables["TournamentStreamer"], "id">[],
 ) {
diff --git a/app/features/map-list-generator/core/MapList.test.ts b/app/features/map-list-generator/core/MapList.test.ts
index 85818db5f..6fb02b81a 100644
--- a/app/features/map-list-generator/core/MapList.test.ts
+++ b/app/features/map-list-generator/core/MapList.test.ts
@@ -318,10 +318,8 @@ describe("MapList.generate()", () => {
 		});
 
 		test("keeps cycling other modes across sets when a must-include pattern is set", () => {
-			// A single generator drives every bracket round. With a `[SZ]`
-			// must-include pattern the non-SZ slots should keep advancing through
-			// the mode order across rounds instead of replaying the order's prefix
-			// every set, otherwise modes in the order's tail (here RM) are starved.
+			// one generator drives every round: with a `[SZ]` must-include the non-SZ slots must keep
+			// advancing through the mode order instead of replaying its prefix, or the tail (RM) starves
 			const gen = MapList.generate({
 				mapPool: ALL_MODES_TEST_MAP_POOL,
 				modeOrder: ["SZ", "TC", "CB", "RM", "TW"],
@@ -338,11 +336,9 @@ describe("MapList.generate()", () => {
 		});
 
 		test("keeps cycling other modes across sets when a positional pattern is set", () => {
-			// With a `*SZ*` pattern and Bo3 sets the two ANY slots are filled from
-			// the non-SZ modes (TC, RM, CB). Because the cycle offset advances by the
-			// full set size (3) instead of the slots actually consumed, every round
-			// resolves the ANY slots to the same modes and the remaining mode (here
-			// RM) never appears in the whole bracket.
+			// `*SZ*` Bo3: the two ANY slots come from TC, RM, CB. Guards against the cycle offset
+			// advancing by the set size (3) instead of consumed slots, which resolved the ANY slots
+			// to the same modes every round so RM never appeared in the whole bracket
 			const gen = MapList.generate({
 				mapPool: new MapPool({
 					TW: [],
diff --git a/app/features/map-list-generator/core/MapList.ts b/app/features/map-list-generator/core/MapList.ts
index 8f56fb4b1..74cf85c82 100644
--- a/app/features/map-list-generator/core/MapList.ts
+++ b/app/features/map-list-generator/core/MapList.ts
@@ -11,7 +11,7 @@ import type { MapPool } from "./map-pool";
 import type { ReadonlyMapPoolObject } from "./map-pool-serializer/types";
 
 interface GenerateNext {
-	/** How many maps to return? E.g. for a Bo5 set, amount should be 5 */
+	/** Maps to return, e.g. 5 for a Bo5. */
 	amount: number;
 	pattern?: string;
 }
@@ -19,23 +19,19 @@ interface GenerateNext {
 interface MaplistPattern {
 	mustInclude?: Array<{
 		mode: ModeShort;
-		/** Should the mode appear in the guaranteed to be played maps of a Best of set e.g. first 3 of a Bo5? */
+		/** Must appear among the guaranteed maps of a best of, e.g. first 3 of a Bo5. */
 		isGuaranteed: boolean;
 	}>;
 	pattern: Array<"ANY" | ModeShort>;
 }
 
-/**
- * Creates a unique key for a stage-mode combination.
- * @example
- * stageModeKey("SZ", 1); // "1-SZ"
- */
+/** Unique key of a mode-stage combination, e.g. `modeStageKey("SZ", 1)` gives `"SZ-1"`. */
 export function modeStageKey(mode: ModeShort, stageId: StageId): string {
 	return `${mode}-${stageId}`;
 }
 
 /**
- * Generates map lists that avoid repeating stages and optionally allows providing mode pattern.
+ * Generates map lists avoiding stage repeats, optionally following a mode pattern.
  *
  * @example
  * const generator = generate({ mapPool: new MapPool(pool) });
@@ -44,17 +40,16 @@ export function modeStageKey(mode: ModeShort, stageId: StageId): string {
  * const secondSet = generator.next({ amount: 3, pattern: "SZ*TC" }).value; // remembers stages used in firstSet
  */
 export function* generate(args: {
-	/** The map pool to use for generating map lists (MapPool class) */
 	mapPool: MapPool;
-	/** Should the function bias in favor of maps not played? E.g. maps 4 & 5 in a Bo5 format (not every team plays them). Should be true if generating for tournament with best of format. */
+	/** Bias towards maps not guaranteed to be played (e.g. maps 4 & 5 of a Bo5). True for best of formats. */
 	considerGuaranteed?: boolean;
-	/** Initial weights for specific stage-mode combinations. Key format: `${mode}-${stageId}` (generate via `MapList.stageModeKey`). Negative weights can be used to deprioritize certain maps. */
+	/** Initial weights keyed by `modeStageKey`. Negative weights deprioritize maps. */
 	initialWeights?: Map<string, number>;
-	/** Skip the ensureMinimumCandidates check that inflates weights to ensure half the pool is available. Useful when initial weights already define the desired selection. */
+	/** Skip inflating weights so half the pool is available, e.g. when initial weights already define the selection. */
 	skipEnsureMinimumCandidates?: boolean;
-	/** Fixed mode order — when set, skips the random shuffle and uses only this order. Intended for `resume`. */
+	/** Fixed mode order instead of a random shuffle. Intended for `resume`. */
 	modeOrder?: ModeShort[];
-	/** Initial weights for stages (mode-agnostic). Used by `resume` to carry over stage-level penalties from history. */
+	/** Mode-agnostic initial stage weights, how `resume` carries over stage-level penalties from history. */
 	initialStageWeights?: Map<StageId, number>;
 }): Generator<Array<ModeWithStage>, Array<ModeWithStage>, GenerateNext> {
 	if (args.mapPool.isEmpty()) {
@@ -141,11 +136,8 @@ export function* generate(args: {
 }
 
 /**
- * Returns a generator primed to continue map selection after the given history.
- *
- * Keeps the pool's mode order stable (rotated so the next-to-play mode is first)
- * and biases against already-played `(mode, stage)` pairs so they are not picked
- * again unless every option in that mode has already been played.
+ * Generator primed to continue after `history`: mode order kept stable (rotated so the next mode
+ * is first) and played `(mode, stage)` pairs avoided unless every option in that mode was played.
  *
  * @example
  * const generator = resume({ mapPool, history });
@@ -281,7 +273,7 @@ function selectStageWeighted({
 	});
 }
 
-/** Ensure that stage map pool has at least half the total options at the start of a round to avoid predictable replay order */
+/** At least half the pool must be available at the start of a round, or the replay order gets predictable. */
 function ensureMinimumCandidates({
 	mapPool,
 	stageWeights,
@@ -424,7 +416,7 @@ function modifyModeOrderByPattern(
 const validPatternParts = new Set(["*", ...modesShort] as const);
 
 /**
- * Parses a pattern string into structured pattern data for map list generation.
+ * Parses a mode pattern string.
  *
  * @example
  * unwrapOr(parsePattern("SZ*TC"), null); // { pattern: ["SZ", "ANY", "TC"] }
diff --git a/app/features/map-planner/components/Planner.tsx b/app/features/map-planner/components/Planner.tsx
index 8e01a4e60..15249bf39 100644
--- a/app/features/map-planner/components/Planner.tsx
+++ b/app/features/map-planner/components/Planner.tsx
@@ -258,8 +258,7 @@ export default function Planner() {
 		}) => {
 			if (!editor) return;
 
-			// tldraw image shapes reference an asset by id, so many copies of the
-			// same image on the canvas only take up memory once
+			// image shapes reference an asset by id, so copies of the same image only take up memory once
 			const assetId: TLAssetId = AssetRecordType.createId();
 
 			const srcWithOutline = imgOutlined ? `${src}?outline=red` : src;
@@ -372,7 +371,7 @@ export default function Planner() {
 			setRangesVisible(false);
 
 			const shapes = editor.getCurrentPageShapes();
-			// i dont think locked shapes can be deleted
+			// locked shapes can't be deleted
 			for (const value of shapes) {
 				editor.updateShape({ id: value.id, type: value.type, isLocked: false });
 			}
@@ -498,7 +497,7 @@ export default function Planner() {
 	);
 }
 
-// Wraps the style panel so it can be styled to sit below the header bar, which otherwise blocks clicks on it
+// styled to sit below the header bar, which otherwise blocks clicks on it
 function CustomStylePanel(props: TLUiStylePanelProps) {
 	return (
 		<div className={props.isMobile ? undefined : styles.stylePanel}>
@@ -822,8 +821,7 @@ function StageBackgroundSelector({
 	);
 }
 
-// when adding new language check from Tldraw codebase what is the matching
-// language in TRANSLATIONS constant, or default to english if none found
+// for a new language check tldraw's TRANSLATIONS constant for the matching one, default to english
 const ourLanguageToTldrawLanguageMap: Record<LanguageCode, string> = {
 	"es-US": "es",
 	"es-ES": "es",
diff --git a/app/features/map-planner/plans-global.css b/app/features/map-planner/plans-global.css
index 281d926ea..ec49a19ce 100644
--- a/app/features/map-planner/plans-global.css
+++ b/app/features/map-planner/plans-global.css
@@ -1,5 +1,3 @@
-/* Currently ignored by Biome, can be unignored when https://github.com/biomejs/biome/pull/3251 lands */
-
 /* https://github.com/tldraw/tldraw/blob/2352985e949d14270fc89dc60144239c37c8ff91/packages/tldraw/src/hooks/useStylesheet.ts */
 @import url("https://fonts.googleapis.com/css2?family=Caveat+Brush&family=Source+Code+Pro&family=Source+Sans+Pro&family=Crimson+Pro&display=block");
 @import url("@tldraw/tldraw/tldraw.css");
@@ -47,14 +45,14 @@ div {
 	box-shadow: none !important;
 }
 
-/* Hacky selector to hide sidebar, top nav and footer */
+/* hides sidebar, top nav and footer */
 body:has(.planner) nav,
 body:has(.planner) header,
 body:has(.planner) footer {
 	display: none !important;
 }
 
-/** Hacky selector to remove the help button on bottom left */
+/* removes the help button on bottom left */
 .tlui-help-menu {
 	display: none;
 }
diff --git a/app/features/match-page-test/routes/match-page-test.tsx b/app/features/match-page-test/routes/match-page-test.tsx
index 697aa7fd2..ce9f619b5 100644
--- a/app/features/match-page-test/routes/match-page-test.tsx
+++ b/app/features/match-page-test/routes/match-page-test.tsx
@@ -864,9 +864,8 @@ export default function MatchPageTestRoute() {
 }
 
 /**
- * Plays out a zones game second by second: the controlling side burns its
- * penalty before its count moves, and losing the zone after counting hands
- * the side a penalty to burn next time.
+ * Zones game second by second: the controlling side burns its penalty before its count moves,
+ * and losing the zone after counting hands it a penalty to burn next time.
  */
 function mockObjectiveEvents(): ObjectiveTimelineEvent[] {
 	const PHASES: Array<{ seconds: number; control: [boolean, boolean] }> = [
@@ -918,10 +917,7 @@ function mockObjectiveEvents(): ObjectiveTimelineEvent[] {
 	return events;
 }
 
-/**
- * Staggered respawn and special cycles per player over the same game as
- * `mockObjectiveEvents`, sampled at the same cadence.
- */
+/** Staggered respawn and special cycles per player over the `mockObjectiveEvents` game, same cadence. */
 function mockPlayerStatusSamples(): PlayerStatusTimelineSample[] {
 	const DURATION_SECONDS = 190;
 	const SAMPLE_EVERY_SECONDS = 2;
diff --git a/app/features/match-profile/MatchProfileRepository.server.ts b/app/features/match-profile/MatchProfileRepository.server.ts
index 98f701b5a..1624c4876 100644
--- a/app/features/match-profile/MatchProfileRepository.server.ts
+++ b/app/features/match-profile/MatchProfileRepository.server.ts
@@ -92,10 +92,7 @@ export async function updateOwnMatchProfile({
 	return { mapModePreferencesChanged, noScreenChanged };
 }
 
-/**
- * Preserves existing preferences for modes not included in the new submission.
- * So if they later want to play this mode again, the system remembers their maps.
- */
+/** Keeps preferences of modes left out of the submission, so their maps are remembered when the mode is played again. */
 export function mergeExcludedModePreferences(
 	newPool: UserMapModePreferences["pool"],
 	currentPool: UserMapModePreferences["pool"] | undefined,
diff --git a/app/features/mmr/SkillRepository.server.ts b/app/features/mmr/SkillRepository.server.ts
index bc911af5d..29a03b847 100644
--- a/app/features/mmr/SkillRepository.server.ts
+++ b/app/features/mmr/SkillRepository.server.ts
@@ -11,10 +11,7 @@ export type CurrentSkill = Pick<
 	"mu" | "sigma" | "matchesCount"
 >;
 
-/**
- * Season's latest skill of each given user, keyed by user id. Users without a skill
- * row that season are absent from the map.
- */
+/** Season's latest skill of each user, keyed by user id; users without one are absent. */
 export async function findCurrentUserSkills({
 	season,
 	userIds,
@@ -35,10 +32,7 @@ export async function findCurrentUserSkills({
 	);
 }
 
-/**
- * Season's latest skill of each given team, keyed by team identifier. Teams without a
- * skill row that season are absent from the map.
- */
+/** Season's latest skill of each team, keyed by identifier; teams without one are absent. */
 export async function findCurrentTeamSkills({
 	season,
 	identifiers,
@@ -64,9 +58,7 @@ export async function findCurrentTeamSkills({
 	);
 }
 
-/**
- * Ordinals of the season's latest skill of every user who has one, best first.
- */
+/** Ordinals of the season's latest skill of every user who has one, best first. */
 export async function findOrderedUserOrdinalsBySeason(season: number) {
 	return db
 		.selectFrom(latestSkillPerSeason({ season, by: "userId" }).as("latest"))
@@ -75,9 +67,7 @@ export async function findOrderedUserOrdinalsBySeason(season: number) {
 		.execute();
 }
 
-/**
- * Whether the season has any Skill rows.
- */
+/** Whether the season has any Skill rows. */
 export async function existsBySeason(season: number) {
 	const row = await db
 		.selectFrom("Skill")
@@ -89,10 +79,7 @@ export async function existsBySeason(season: number) {
 	return Boolean(row);
 }
 
-/**
- * Seeding skills of the given users for one seeding type, keyed by user id. Users without
- * a seeding skill of that type are absent from the map.
- */
+/** Seeding skills of the users for one seeding type, keyed by user id; users without one are absent. */
 export async function findSeedingSkills({
 	type,
 	userIds,
@@ -114,9 +101,7 @@ export async function findSeedingSkills({
 	return new Map<number, SeedingSkill>(rows.map((row) => [row.userId, row]));
 }
 
-/**
- * Adds a user's starting skill of a season.
- */
+/** Adds a user's starting skill of a season. */
 export async function addInitialSkill(
 	{
 		mu,
@@ -160,10 +145,7 @@ export async function findSeasonProgressionByUserId({
 		.execute();
 }
 
-/**
- * Days of the season the user played at least one set on, with whether they
- * played SendouQ, tournaments or both that day. Dates in `yyyy-MM-dd` format.
- */
+/** Days (`yyyy-MM-dd`) of the season the user played a set on, with whether it was SendouQ, tournaments or both. */
 export async function findSeasonActiveDaysByUserId({
 	userId,
 	season,
@@ -192,11 +174,7 @@ export async function findSeasonActiveDaysByUserId({
 	}));
 }
 
-/**
- * Ids of the season's latest Skill row of each given user or team. A grouped `max(id)`
- * over the `(season, userId/identifier)` index is a plain index range per value, where
- * a `row_number()` window would materialize and sort every row of those users first.
- */
+/** Ids of the season's latest Skill row per user or team. A grouped `max(id)` is an index range per value; a `row_number()` window would materialize and sort every row first. */
 function latestSkillIdsOfSeason(
 	season: number,
 	by: "userId" | "identifier",
@@ -210,11 +188,7 @@ function latestSkillIdsOfSeason(
 		.groupBy(`Skill.${by}`);
 }
 
-/**
- * User's Skill rows of a season that came from a set played, grouped by the day
- * it was played on (`yyyy-MM-dd`) in ascending order. Callers select what they
- * want aggregated per day.
- */
+/** User's Skill rows of a season from played sets, grouped by day (`yyyy-MM-dd`) ascending; callers select what to aggregate per day. */
 function seasonSkillsByDayQuery({
 	userId,
 	season,
diff --git a/app/features/mmr/components/SeasonSelect.tsx b/app/features/mmr/components/SeasonSelect.tsx
index 2fc7e4982..61faf8630 100644
--- a/app/features/mmr/components/SeasonSelect.tsx
+++ b/app/features/mmr/components/SeasonSelect.tsx
@@ -6,10 +6,8 @@ import {
 import * as Seasons from "~/features/mmr/core/Seasons";
 
 /**
- * Select for choosing one of the started seasons, grouped by the year the season started in.
- *
- * @param label - Localized word for "season", used both as the select's label and as the prefix of every season's name.
- * @param isSeasonDisabled - If given, seasons it returns `true` for can't be selected.
+ * Select of the started seasons, grouped by start year. `label` is the localized word for
+ * "season", used as the label and as each season name's prefix; `isSeasonDisabled` blocks the seasons it returns `true` for.
  */
 export function SeasonSelect({
 	label,
diff --git a/app/features/mmr/core/Seasons.ts b/app/features/mmr/core/Seasons.ts
index 77433530e..3bcfb94f1 100644
--- a/app/features/mmr/core/Seasons.ts
+++ b/app/features/mmr/core/Seasons.ts
@@ -2,27 +2,10 @@ import { addHours } from "date-fns";
 import { Config } from "~/config";
 import { IS_E2E_TEST_RUN } from "~/utils/e2e";
 
-/**
- * How long past a season's end its matches can still be resolved. A match can be
- * created up to the very end of the season and the stale match routine resolves
- * it 24h after creation, with up to an hour of scheduling lag on top.
- */
+/** How long past a season's end its matches can still resolve: 24h stale match routine after a buzzer-beater creation, plus up to an hour of scheduling lag. */
 const REPORTING_GRACE_HOURS = 25;
 
-/**
- * List of seasons with their respective start and end dates.
- *
- * Each season is represented as an object with the following properties:
- * - `nth`: The sequential number of the season (starting from 0).
- * - `starts`: The start date of the season as a `Date` object.
- * - `ends`: The end date of the season as a `Date` object.
- *
- * Note: The value is conditionally set based on the environment. In development mode,
- * the end date of the first season is set to a later date for testing purposes (ensures a season is always open).
- *
- * @example
- * console.log(Seasons.list[0].starts); // Logs the start date of the first season
- */
+/** Seasons (`nth` from 0) with their start and end dates. Outside production the list is a test set that keeps a season always open. */
 export const list =
 	// when we do pnpm run setup NODE_ENV is not set -> use test seasons
 	!process.env.NODE_ENV ||
@@ -113,16 +96,10 @@ export const list =
 				},
 			] as const);
 
-/**
- * Represents an individual item from the `Seasons.list` array.
- */
+/** An item of `Seasons.list`. */
 export type ListItem = (typeof list)[number];
 
-/**
- * Determines the current season relative to the provided date (defaults to now), or falls back to the previous season if no current season is found.
- *
- * @returns The current season if it exists; otherwise, the previous season.
- */
+/** The current season at `date` (default now), falling back to the previous one. */
 export function currentOrPrevious(date?: Date): ListItem | null {
 	const _currentSeason = current(date);
 	if (_currentSeason) return _currentSeason;
@@ -130,11 +107,7 @@ export function currentOrPrevious(date?: Date): ListItem | null {
 	return previous(date);
 }
 
-/**
- * Determines the previous season relative to the provided date (defaults to now).
- *
- * @returns The previous season if one exists.
- */
+/** The previous season relative to `date` (default now). */
 export function previous(date = new Date()): ListItem | null {
 	let latestPreviousSeason: ListItem | null = null;
 	for (const season of list) {
@@ -146,20 +119,12 @@ export function previous(date = new Date()): ListItem | null {
 
 let seasonEndedOverride = false;
 
-/**
- * Tests only: makes `current()` resolve to `null` as if every season had ended, so
- * tests can cover the season boundary without one having to actually pass. Only
- * "now" is affected, an explicitly given date still resolves to its real season.
- */
+/** Tests only: makes `current()` for "now" resolve to `null` as if every season had ended; an explicit date still resolves normally. */
 export function DANGEROUS_setSeasonEndedOverride(seasonEnded: boolean) {
 	seasonEndedOverride = seasonEnded;
 }
 
-/**
- * Determines the current ongoing season relative to the provided date (defaults to now).
- *
- * @returns The current season if one exists.
- */
+/** The ongoing season at `date` (default now), if any. */
 export function current(date?: Date): ListItem | null {
 	if (seasonEndedOverride && !date) return null;
 
@@ -174,11 +139,7 @@ export function current(date?: Date): ListItem | null {
 	return null;
 }
 
-/**
- * Determines the next upcoming season relative to the provided date (defaults to now).
- *
- * @returns The next season if one exists.
- */
+/** The next upcoming season relative to `date` (default now), if any. */
 export function next(date = new Date()): ListItem | null {
 	for (const season of list) {
 		if (date < season.starts) return season;
@@ -187,12 +148,7 @@ export function next(date = new Date()): ListItem | null {
 	return null;
 }
 
-/**
- * Retrieves the date range for a specific season based on its number.
- *
- * @returns An object containing the start and end dates of the specified season.
- * @throws {Error} If the season does not exist.
- */
+/** Start and end dates of season `nth`. @throws if the season does not exist. */
 export function nthToDateRange(nth: number) {
 	const seasonObject = list[nth];
 	if (!seasonObject) {
@@ -205,13 +161,7 @@ export function nthToDateRange(nth: number) {
 	};
 }
 
-/**
- * Retrieves the date range within which a season's results can land, i.e. the season
- * itself plus the grace period matches started at the buzzer are resolved within.
- *
- * @returns An object containing the start date of the specified season and the end of its reporting grace period.
- * @throws {Error} If the season does not exist.
- */
+/** The range a season's results can land in: the season plus the reporting grace period. @throws if the season does not exist. */
 export function nthToReportingDateRange(nth: number) {
 	const { starts, ends } = nthToDateRange(nth);
 
@@ -221,11 +171,7 @@ export function nthToReportingDateRange(nth: number) {
 	};
 }
 
-/**
- * Retrieves a list of season numbers that have started based on the provided date (defaults to now).
- *
- * @returns An array of season numbers in descending order (newest first). If no seasons have started, returns an array containing only `[0]`.
- */
+/** Numbers of seasons started by `date` (default now), newest first; `[0]` if none have. */
 export function allStarted(date = new Date()) {
 	const startedSeasons = list.filter((s) => date >= s.starts);
 	if (startedSeasons.length > 0) {
@@ -234,11 +180,7 @@ export function allStarted(date = new Date()) {
 
 	return [0];
 }
-/**
- * Retrieves a list of season numbers that have finished based on the provided date (defaults to now).
- *
- * @returns An array of season numbers in descending order. If no seasons have finished, returns an empty array.
- */
+/** Numbers of seasons finished by `date` (default now), newest first. */
 export function allFinished(date = new Date()) {
 	const finishedSeasons = list.filter((s) => date > s.ends);
 	return finishedSeasons.map((s) => s.nth).reverse();
diff --git a/app/features/mmr/mmr-utils.server.ts b/app/features/mmr/mmr-utils.server.ts
index 68527d426..376b6326d 100644
--- a/app/features/mmr/mmr-utils.server.ts
+++ b/app/features/mmr/mmr-utils.server.ts
@@ -8,13 +8,10 @@ type Rating = Pick<Tables["Skill"], "mu" | "sigma">;
 type RatingWithMatchesCount = { rating: Rating; matchesCount: number };
 
 /**
- * Loads the current ratings of the given users and teams for one season in two queries,
- * exposing them as synchronous lookups so that rating math can stay pure.
- *
- * Users and teams without a skill row that season resolve to the default rating. Asking
- * for anything that was not part of `userIds`/`identifiers` throws, as a silent default
- * rating would be indistinguishable from a real one. Note that `teamPlayerAverage` reads
- * the ratings of the identifier's members, so those users must be included in `userIds`.
+ * Loads the season's current ratings of the users and teams in two queries as synchronous lookups
+ * so rating math stays pure. Missing skill rows resolve to the default rating; asking for anything
+ * outside `userIds`/`identifiers` throws, as a silent default would pass for a real one.
+ * `teamPlayerAverage` reads the members' ratings, so those users must be in `userIds`.
  */
 export async function seasonRatings({
 	season,
@@ -77,11 +74,7 @@ export async function seasonRatings({
 	return { user, team, teamPlayerAverage };
 }
 
-/**
- * Loads the current seeding ratings of the given users for one seeding type in a single
- * query, exposing them as a synchronous lookup. Users without a seeding skill resolve to
- * the default rating.
- */
+/** Loads the users' seeding ratings of one type in a single query as a synchronous lookup; users without one resolve to the default rating. */
 export async function seedingRatings({
 	type,
 	userIds,
diff --git a/app/features/mmr/mmr-utils.ts b/app/features/mmr/mmr-utils.ts
index 3be3f606a..c470491b9 100644
--- a/app/features/mmr/mmr-utils.ts
+++ b/app/features/mmr/mmr-utils.ts
@@ -29,11 +29,9 @@ export function rate(teams: Team[], secondaryTeams?: [[Rating], [Rating]]) {
 	return openskillRate(teams, { tau: TAU, limitSigma: true });
 }
 
-// when ranking teams we rate the team against the actual team rating that it played against
-// as well as against the average ratings of the players on the team
-// then they get the bigger boost of the two (if won) or the smaller penalty of the two (if lost)
-// this is to avoid situations where teams might unexpectedly lose a huge amount of points
-// due to other team score not being accurate (not enough games played) to their perceived skill level
+// a team is rated against both the opposing team's rating and its players' average rating,
+// taking the bigger boost (won) or smaller penalty (lost), so an inaccurate team rating
+// (too few games) can't cost a huge amount of points
 function rateConservative(
 	teams: Team[],
 	secondaryTeams: [[Rating], [Rating]],
diff --git a/app/features/mmr/tiered.server.ts b/app/features/mmr/tiered.server.ts
index c942f2ea5..1f7350df7 100644
--- a/app/features/mmr/tiered.server.ts
+++ b/app/features/mmr/tiered.server.ts
@@ -86,8 +86,7 @@ function skillTierIntervals(
 	);
 	const hasLeviathan = points.length >= LEADERBOARD_MIN_ENTRIES_FOR_LEVIATHAN;
 	if (!hasLeviathan) {
-		// using all entries, no matter if they have enough to be on the leaderboard
-		// to create the tiers
+		// tiers from all entries, whether or not they have enough to be on the leaderboard
 		points = orderedPoints;
 	}
 
diff --git a/app/features/notifications/NotificationRepository.server.ts b/app/features/notifications/NotificationRepository.server.ts
index f479bf088..776bfefa1 100644
--- a/app/features/notifications/NotificationRepository.server.ts
+++ b/app/features/notifications/NotificationRepository.server.ts
@@ -78,15 +78,10 @@ export function findAllByType<T extends Notification["type"]>(type: T) {
 }
 
 /**
- * Marks the users' unseen notifications of the given type as seen, optionally
- * only those whose meta matches every given key/value pair. Used to clear the
- * unseen dot when the user addresses what the notification is about. Returns
- * the user ids whose rows actually changed.
- *
- * The correlated `exists` keeps this proportional to the users' own
- * notifications. A `notificationId in (select ...)` reads the same but makes
- * SQLite materialize every notification of the type (json_extract'ing each one)
- * before touching the user's rows, which is ~80x slower on a hot path.
+ * Marks the users' unseen notifications of the type (optionally only those whose meta matches
+ * every key/value) as seen, returning the user ids whose rows changed. The correlated `exists`
+ * keeps this proportional to the users' own notifications; `notificationId in (select ...)` makes
+ * SQLite materialize every notification of the type first, ~80x slower on a hot path.
  */
 export async function markAsSeenByType({
 	userIds,
@@ -130,11 +125,7 @@ export async function markAsSeenByType({
 	return R.unique(updated.map((row) => row.userId));
 }
 
-/**
- * Marks the actor's notifications as seen. Returns the actor's user id in an
- * array if any row actually changed (empty array otherwise), shaped for
- * passing straight to `ChatSystemMessage.notifyNotificationsChanged`.
- */
+/** Marks the actor's notifications as seen. Returns `[actorId]` if any row changed, else `[]`, shaped for `ChatSystemMessage.notifyNotificationsChanged`. */
 export async function markOwnAsSeen(notificationIds: number[]) {
 	const updated = await db
 		.updateTable("NotificationUser")
@@ -180,11 +171,7 @@ export function upsertOwnSubscription(subscription: NotificationSubscription) {
 		.execute();
 }
 
-/**
- * Finds the push subscriptions of the given notification's recipients who have
- * not seen it yet. Lets the push sender skip users who already addressed what
- * the notification is about during the delivery grace period.
- */
+/** Push subscriptions of the notification's recipients who have not seen it yet, so the push sender skips users who addressed it during the grace period. */
 export function findUnseenSubscriptionsByNotificationId(
 	notificationId: number,
 ) {
diff --git a/app/features/notifications/NotificationsProvider.tsx b/app/features/notifications/NotificationsProvider.tsx
index a1df743bf..15884ab39 100644
--- a/app/features/notifications/NotificationsProvider.tsx
+++ b/app/features/notifications/NotificationsProvider.tsx
@@ -24,13 +24,10 @@ const NotificationsContext = React.createContext<NotificationsContextValue>({
 });
 
 /**
- * Serves the notification peek (bell popover + unseen dot) and keeps it fresh
- * push-first: an initial fetch after mount (deliberately not part of any
- * loader, so notifications never delay a page), then a refetch whenever the
- * server publishes over the shared SSE connection that the user's
- * notifications changed server-side (new notification, marked seen, resolved
- * by an action elsewhere). Polling and refetch-on-activity heuristics only
- * kick in as a fallback while the event stream is down.
+ * Serves the notification peek (bell popover + unseen dot), push-first: an initial fetch after
+ * mount (not in any loader, so notifications never delay a page), then a refetch whenever the
+ * server publishes over SSE that they changed. Polling and refetch-on-activity are only the
+ * fallback while the event stream is down.
  */
 export function NotificationsProvider({
 	user,
@@ -93,12 +90,9 @@ export function useNotificationsData() {
 }
 
 /**
- * Without the event stream there is no ping when something the user did resolves
- * an unseen notification, so fall back to refetching after anything that may
- * have: a navigation (loaders mark notifications seen when the user views the
- * page a notification points at) or a settled action submission (actions mark
- * them seen when the user addresses the thing itself). Only fires while an
- * unseen notification exists, so it usually adds no server load even then.
+ * Without the event stream nothing pings when the user resolves an unseen notification, so refetch
+ * after anything that may have: a navigation (loaders mark seen) or a settled action (actions mark
+ * seen). Only fires while an unseen notification exists.
  */
 function useFallbackRefreshOnPotentialResolution({
 	enabled,
diff --git a/app/features/notifications/core/notify.server.ts b/app/features/notifications/core/notify.server.ts
index a2886933c..65cfc4b22 100644
--- a/app/features/notifications/core/notify.server.ts
+++ b/app/features/notifications/core/notify.server.ts
@@ -43,27 +43,19 @@ const NOTIFICATION_URGENCY: Record<Notification["type"], Urgency> = {
 	SCHEDULE_TEAM_REMINDER: "normal",
 };
 
-/** How long a push notification is held back before sending. Anything marking the notification as seen during this window (the user addressing what it is about, opening the notification list, `defaultSeenUserIds`) cancels the push for that user. */
+/** How long a push is held back; anything marking the notification seen meanwhile (addressing it, opening the list, `defaultSeenUserIds`) cancels it for that user. */
 export const PUSH_NOTIFICATION_GRACE_PERIOD_MS = 15 * 1000;
 
-/**
- * Create notifications both in the database and send push notifications to users (if enabled).
- *
- * Pushes go out after {@link PUSH_NOTIFICATION_GRACE_PERIOD_MS} and only to
- * users whose notification is still unseen at that point, so users who already
- * saw the event happen in-app are not pushed about it.
- */
+/** Creates notifications and sends pushes (if enabled) after {@link PUSH_NOTIFICATION_GRACE_PERIOD_MS}, only to users whose notification is still unseen by then. */
 export async function notify({
 	userIds,
 	notification,
 	defaultSeenUserIds,
 	skipPushGracePeriod,
 }: {
-	/** Array of user ids to notify */
 	userIds: Array<number>;
-	/** Array of user ids that should have the notification marked as seen by default */
+	/** User ids that get the notification already marked as seen */
 	defaultSeenUserIds?: Array<number>;
-	/** Notification to send (same for all users) */
 	notification: Notification;
 	/** Send push notifications right away and await them (used by the send-test-notification script) */
 	skipPushGracePeriod?: boolean;
@@ -159,14 +151,12 @@ export function clearSentNotificationsForTesting() {
 	sentNotifications.clear();
 }
 
-// deduplicates notifications as a failsafe & anti-abuse mechanism; entries
-// expire so a legitimately repeated identical notification (e.g. the same team
-// requesting a scrim again weeks later) still gets delivered
+// failsafe & anti-abuse dedupe; entries expire so a legitimately repeated identical
+// notification (the same team requesting a scrim again weeks later) still gets delivered
 function isNotificationAlreadySent(
 	notification: Notification,
 	userIds: Array<number>,
 ) {
-	// e2e tests should not be affected by this
 	if (IS_E2E_TEST_RUN) {
 		return false;
 	}
@@ -213,7 +203,7 @@ async function sendPushNotification({
 	} catch (err) {
 		if (!(err instanceof WebPushError)) {
 			logger.error("Failed to send push notification (unknown error)", err);
-			// if we get "Not Found" or "Gone" we should delete the subscription as it is expired or no longer valid
+			// "Not Found" / "Gone": the subscription is expired or no longer valid
 		} else if (err.statusCode === 404 || err.statusCode === 410) {
 			await NotificationRepository.deleteSubscriptionById(subscriptionId);
 		} else {
diff --git a/app/features/notifications/core/pushSubscription.ts b/app/features/notifications/core/pushSubscription.ts
index 4c1fc85fc..3b030fd55 100644
--- a/app/features/notifications/core/pushSubscription.ts
+++ b/app/features/notifications/core/pushSubscription.ts
@@ -11,12 +11,7 @@ export function isPushSupported() {
 	);
 }
 
-/**
- * Subscribes this browser to push notifications (reusing the existing
- * subscription if one is live) and syncs it to the server. Throws if
- * subscribing or the server sync fails, meaning the server might not know
- * where to deliver push notifications for this browser.
- */
+/** Subscribes this browser to push (reusing a live subscription) and syncs it to the server. Throws if either fails, meaning the server may not know where to deliver. */
 export async function subscribeToPush() {
 	const registration = await navigator.serviceWorker.register("/sw-2.js");
 	const subscription =
@@ -38,22 +33,13 @@ export async function subscribeToPush() {
 	}
 }
 
-/**
- * The live push subscription of this browser, or null when there is none
- * (never subscribed, expired, or revoked). Only call after hydration.
- */
+/** This browser's live push subscription, or null (never subscribed, expired, revoked). Only call after hydration. */
 export async function findPushSubscription() {
 	const registration = await navigator.serviceWorker.getRegistration();
 	return (await registration?.pushManager.getSubscription()) ?? null;
 }
 
-/**
- * Self-heals push delivery for a browser that has already opted in: if the
- * subscription expired, was revoked by the browser, or the server lost/deleted
- * its copy (e.g. after the push service returned 410 Gone), this resubscribes
- * and re-syncs so notifications keep arriving. Safe to call on every app
- * load; a failure is swallowed as the next load retries.
- */
+/** Self-heals push for an opted-in browser: resubscribes and re-syncs when the subscription expired, was revoked, or the server lost its copy (e.g. 410 Gone). Safe on every load; failures are swallowed. */
 export async function resyncPushSubscription() {
 	if (!isPushSupported() || Notification.permission !== "granted") return;
 
diff --git a/app/features/notifications/core/resolve.server.ts b/app/features/notifications/core/resolve.server.ts
index 1a2ce4987..0293ca476 100644
--- a/app/features/notifications/core/resolve.server.ts
+++ b/app/features/notifications/core/resolve.server.ts
@@ -12,11 +12,9 @@ type MetaFilter<T extends Notification["type"]> =
 	NotificationOfType<T> extends { meta: infer M } ? Partial<M> : undefined;
 
 /**
- * What resolves each notification type beyond opening the notification list.
- * `null` means nothing does: the notification is informational, or resolving it
- * would cost a query on a hot path for little gain (TO_ADDED_TO_TEAM,
- * TO_TEST_CREATED). Exhaustive on purpose, so a new notification type has to
- * pick a side, and only the types with a trigger can be resolved.
+ * What resolves each notification type beyond opening the list. `null`: nothing does, it is
+ * informational or resolving would cost a hot-path query for little gain (TO_ADDED_TO_TEAM,
+ * TO_TEST_CREATED). Exhaustive so a new type has to pick a side.
  */
 const RESOLUTION_TRIGGERS = {
 	SQ_ADDED_TO_GROUP: "visits a SendouQ group page (preparing/looking)",
@@ -61,12 +59,9 @@ type ResolvableNotificationType = {
 }[Notification["type"]];
 
 /**
- * Marks the users' unseen notifications of the given type as seen because they
- * addressed the thing the notification is about, so the unseen dot only shows
- * for notifications that still need the user's attention. Never throws; a
- * failed resolution only logs since the caller's action/loader matters more.
- *
- * See `RESOLUTION_TRIGGERS` for what resolves each type.
+ * Marks the users' unseen notifications of the type as seen because they addressed what it is
+ * about (see `RESOLUTION_TRIGGERS`). Never throws; a failure only logs since the caller's
+ * action/loader matters more.
  */
 export async function resolveNotifications<
 	T extends ResolvableNotificationType,
@@ -75,9 +70,7 @@ export async function resolveNotifications<
 	type,
 	meta,
 }: {
-	/** Users whose notifications got addressed */
 	userIds: Array<number>;
-	/** Notification type to resolve */
 	type: T;
 	/** Only notifications whose meta matches every given key/value pair are resolved (e.g. `{ tournamentId }`) */
 	meta?: MetaFilter<T>;
diff --git a/app/features/notifications/notifications-hooks.browser.test.tsx b/app/features/notifications/notifications-hooks.browser.test.tsx
index aca4523b7..a5c1fa6c1 100644
--- a/app/features/notifications/notifications-hooks.browser.test.tsx
+++ b/app/features/notifications/notifications-hooks.browser.test.tsx
@@ -21,12 +21,7 @@ const dotStatus = (screen: Awaited<ReturnType<typeof render>>) =>
 const createdAt = (offsetMs: number) =>
 	Math.floor((Date.now() + offsetMs) / 1000);
 
-/**
- * Runs the fake clock forward and lets React paint what the fired timers
- * changed. React schedules its render through a MessageChannel, which fake
- * timers do not control, so a message of our own posted afterwards is what
- * tells us the render already happened.
- */
+/** Runs the fake clock forward and lets React paint: renders go through a MessageChannel fake timers don't control, so a message of our own posted after signals the render happened. */
 const advanceTimers = async (ms: number) => {
 	await vi.advanceTimersByTimeAsync(ms);
 
diff --git a/app/features/notifications/notifications-hooks.ts b/app/features/notifications/notifications-hooks.ts
index 95a006949..a59a6e89e 100644
--- a/app/features/notifications/notifications-hooks.ts
+++ b/app/features/notifications/notifications-hooks.ts
@@ -47,14 +47,11 @@ export function useMarkNotificationsAsSeen(unseenIds: number[]) {
 const UNSEEN_DOT_GRACE_MS = 10_000;
 
 /**
- * Whether the bell should show its unseen dot. An unseen notification born
- * while the session is already open only counts once it has stayed unseen past
- * a short grace period: one about something the user is already on their way
- * to (e.g. a SendouQ match that just started, with the redirect to the match
- * page a second away) resolves itself right after, and the dot flashing for
- * it would be false signal. Notifications predating the session show the dot
- * right away — anything that was going to resolve them (a loader of the page
- * being landed on) already ran before the first notifications fetch.
+ * Whether the bell shows its unseen dot. A notification born during the session only counts once
+ * unseen past a short grace period: one about something the user is already headed to (a SendouQ
+ * match that just started, redirect a second away) resolves itself right after and the dot would
+ * flash for nothing. Ones predating the session show right away — whatever would resolve them
+ * already ran before the first fetch.
  */
 export function useShowUnseenDot(
 	notifications: Array<{ createdAt: number; seen: number }> | undefined,
@@ -92,12 +89,7 @@ export function useShowUnseenDot(
 	return showDot;
 }
 
-/**
- * Ids of the notifications to show an unseen dot for, keeping the dot for as
- * long as the list stays open. Opening the list marks its notifications as
- * seen right away so the bell stops claiming there is something new, and this
- * keeps the reader from losing track of which ones those were.
- */
+/** Ids to show an unseen dot for while the list stays open: opening marks them seen right away, and this keeps the reader from losing track of which were new. */
 export function useStickyUnseenIds(
 	notifications: Array<{ id: number; seen: number }>,
 ) {
@@ -116,7 +108,6 @@ export function useStickyUnseenIds(
 				newUnseenIds.add(id);
 			}
 
-			// optimize render by not updating state if nothing changed
 			if (newUnseenIds.size === prevUnseenIds.size) return prevUnseenIds;
 
 			return newUnseenIds;
diff --git a/app/features/notifications/routes/api.notifications.ts b/app/features/notifications/routes/api.notifications.ts
index d179ace68..6861f6b3b 100644
--- a/app/features/notifications/routes/api.notifications.ts
+++ b/app/features/notifications/routes/api.notifications.ts
@@ -2,11 +2,7 @@ import { getUser } from "~/features/auth/core/user.server";
 import * as NotificationRepository from "../NotificationRepository.server";
 import { NOTIFICATIONS } from "../notifications-contants";
 
-/**
- * The notification peek shown in the bell popover. Fetched by
- * `NotificationsProvider` whenever an event announces that the user's notifications
- * changed, instead of being polled with the rest of the app shell data.
- */
+/** The bell popover's notification peek, fetched by `NotificationsProvider` whenever an event says the user's notifications changed. */
 export const loader = async () => {
 	const user = getUser();
 
diff --git a/app/features/object-damage-calculator/calculator-constants.ts b/app/features/object-damage-calculator/calculator-constants.ts
index ec2061d54..4697a304d 100644
--- a/app/features/object-damage-calculator/calculator-constants.ts
+++ b/app/features/object-damage-calculator/calculator-constants.ts
@@ -34,11 +34,7 @@ type ReceiverTranslation =
 	| { key: string }
 	| { weaponKey: string; suffixKey: string };
 
-/**
- * Maps each damage receiver to the i18n key(s) describing the object it represents. Some
- * receivers are a plain weapon/mode name, others combine a weapon name with a suffix (e.g.
- * "<weapon> Canopy"). Consumed via {@link translateDamageReceiver}.
- */
+/** i18n key(s) per damage receiver: a plain weapon/mode name or a weapon name plus a suffix ("<weapon> Canopy"). */
 const damageReceiverTranslations: Record<DamageReceiver, ReceiverTranslation> =
 	{
 		Chariot: { key: "weapons:SPECIAL_12" },
@@ -99,10 +95,7 @@ const damageReceiverTranslations: Record<DamageReceiver, ReceiverTranslation> =
 		},
 	};
 
-/**
- * Resolves the localized display name of a damage receiver using the given i18next `t` function.
- * The `weapons`, `analyzer` and `game-misc` namespaces must be available to the caller.
- */
+/** Localized name of a damage receiver; needs the `weapons`, `analyzer` and `game-misc` namespaces. */
 export function translateDamageReceiver<Ns extends Namespace>(
 	t: TFunction<Ns>,
 	receiver: DamageReceiver,
@@ -116,11 +109,7 @@ export function translateDamageReceiver<Ns extends Namespace>(
 	});
 }
 
-/**
- * The suffix-only localized label of a damage receiver (e.g. "Shield", "Weak Point"), or `null`
- * when the receiver is a plain weapon/mode name with no suffix. Used to disambiguate the parts of
- * a multi-part object (e.g. Big Bubbler's shield vs. weak point) without repeating the weapon name.
- */
+/** Suffix-only label ("Shield", "Weak Point") to tell apart the parts of a multi-part object, or `null`. */
 export function damageReceiverSuffix<Ns extends Namespace>(
 	t: TFunction<Ns>,
 	receiver: DamageReceiver,
diff --git a/app/features/object-damage-calculator/core/objectDamage.test.ts b/app/features/object-damage-calculator/core/objectDamage.test.ts
index 8566d73d2..dd37b5a3b 100644
--- a/app/features/object-damage-calculator/core/objectDamage.test.ts
+++ b/app/features/object-damage-calculator/core/objectDamage.test.ts
@@ -54,8 +54,7 @@ function calculate({
 }
 
 describe("calculateDamage()", () => {
-	// the function throws if weapon resolves to more than one set of damage rates
-	// so this test goes through all of them to make sure they all work
+	// the function throws if a weapon resolves to more than one set of damage rates
 	test("Every weapon can calculate damage", () => {
 		for (const mainWeaponId of mainWeaponIds) {
 			const analyzed = buildStats({
@@ -164,7 +163,7 @@ describe("calculateDamage()", () => {
 		[5010, "NORMAL_MAX", 34, 31],
 		// Tenta Brella
 		[6010, "NORMAL_MAX", 4, 4],
-		// // Tri-Stringer
+		// Tri-Stringer
 		[7010, "NORMAL_MAX", 3, 3],
 		// REEF-LUX
 		[7020, "NORMAL_MIN", 8, 7],
diff --git a/app/features/object-damage-calculator/core/objectDamage.ts b/app/features/object-damage-calculator/core/objectDamage.ts
index e7a23e7ad..3cb853cf3 100644
--- a/app/features/object-damage-calculator/core/objectDamage.ts
+++ b/app/features/object-damage-calculator/core/objectDamage.ts
@@ -77,8 +77,7 @@ function resolveRelevantKey({
 	if (actualKeys.length === 1) return actualKeys[0];
 
 	for (const [weaponType, weaponIds, damageType, key] of damagePriorities) {
-		// handle alt kits e.g. Splatteshot might have id 10 but Tentatek Splattershot has id 11
-		// but in the context of this function they are one and the same
+		// alt kits (e.g. Tentatek Splattershot) share their base kit's damage
 		const normalizedWeaponId =
 			weapon.type === "MAIN" ? weaponIdToBaseWeaponId(weapon.id) : weapon.id;
 
@@ -290,8 +289,7 @@ export function calculateDamage({
 							const otherMultiplier =
 								multipliers[toCombine.combineWith][receiver];
 
-							// calculate "made up" multiplier that is taking the
-							// weighted average of the two multipliers
+							// "made up" multiplier: weighted average of the two
 							return (
 								(normalMultiplier * actualDamage() +
 									otherMultiplier * otherDamage()) /
diff --git a/app/features/params/components/ParamComparisonDialog.tsx b/app/features/params/components/ParamComparisonDialog.tsx
index cbb43ab0e..4d36f6ae2 100644
--- a/app/features/params/components/ParamComparisonDialog.tsx
+++ b/app/features/params/components/ParamComparisonDialog.tsx
@@ -10,11 +10,7 @@ import type {
 import styles from "./ParamComparisonDialog.module.css";
 import { WeaponParamImage } from "./WeaponParamsTable";
 
-/**
- * Modal with a simple horizontal bar chart comparing one parameter's numeric value across the
- * currently visible weapons. Bars are scaled relative to the largest absolute value so weapons can
- * be compared at a glance.
- */
+/** Horizontal bar chart of one parameter across the visible weapons, scaled to the largest absolute value. */
 export function ParamComparisonDialog({
 	kind,
 	label,
diff --git a/app/features/params/components/WeaponParamsTable.tsx b/app/features/params/components/WeaponParamsTable.tsx
index e21fe7a10..ec0b25e77 100644
--- a/app/features/params/components/WeaponParamsTable.tsx
+++ b/app/features/params/components/WeaponParamsTable.tsx
@@ -66,8 +66,6 @@ export function WeaponParamImage({
 	);
 }
 
-// The display name and (English) url slug of a weapon, resolved from the right `weapons`
-// translation key for the table's kind.
 function useWeaponParamNaming(kind: WeaponParamKind) {
 	const { t } = useTranslation(["weapons"]);
 
@@ -147,8 +145,7 @@ export function WeaponParamsTable({
 		});
 	};
 
-	// Bars are only drawn for plain numbers, so string-valued (or array/object) params and hidden
-	// weapons are skipped here. The compare button shows up only when at least two weapons remain.
+	// bars only for plain numbers; compare button needs at least two weapons left
 	const comparisonEntries = (
 		getValue: (weaponId: number) => number | string | undefined,
 	) =>
diff --git a/app/features/params/components/WeaponPatchHistory.tsx b/app/features/params/components/WeaponPatchHistory.tsx
index 8101f153f..1ce823532 100644
--- a/app/features/params/components/WeaponPatchHistory.tsx
+++ b/app/features/params/components/WeaponPatchHistory.tsx
@@ -67,11 +67,7 @@ export function WeaponPatchHistory({ patches }: { patches: WeaponPatch[] }) {
 	);
 }
 
-/**
- * Patch history of a main weapon shown one kit at a time: the selected kit's main weapon, sub
- * weapon and special weapon changes are grouped under dividers within the same patch column. Sub
- * and special weapon changes can be toggled off.
- */
+/** Patch history one kit at a time, main/sub/special changes under dividers in the same column. */
 export function WeaponPatchHistoryByKit({
 	kits,
 	defaultWeaponId,
@@ -279,7 +275,7 @@ function ChangeBadge({ change }: { change: PatchChange }) {
 
 	const isSpecialPoints = change.category === SPECIAL_POINTS_PARAM_KEY;
 	const isDamageMultiplier = change.category === DAMAGE_MULTIPLIER_PARAM_KEY;
-	// Damage falloff curves serialize to long "damage @ distance" lists that need their own line.
+	// falloff curves serialize to long "damage @ distance" lists
 	const isWideValue =
 		typeof change.from === "string" && change.from.includes("@");
 
@@ -322,11 +318,7 @@ function ChangeBadge({ change }: { change: PatchChange }) {
 	);
 }
 
-/**
- * An incoming damage multiplier change: a set of attacking weapons whose shared damage rate against
- * the page's sub or special weapon changed. Shows the attacking weapons' icons (with a suffix for
- * multi-part objects, e.g. a Big Bubbler's shield vs. weak point) and the from→to rate.
- */
+/** Attacking weapons' icons (suffixed for multi-part objects, e.g. Big Bubbler shield vs. weak point) and the from→to rate. */
 function IncomingChangeBadge({
 	change,
 	attackers,
diff --git a/app/features/params/core/WeaponParams.ts b/app/features/params/core/WeaponParams.ts
index dfcf8ec82..928ea56ac 100644
--- a/app/features/params/core/WeaponParams.ts
+++ b/app/features/params/core/WeaponParams.ts
@@ -29,11 +29,7 @@ import type {
 } from "../weapon-params-types";
 import { classifyParamChange } from "./param-directions";
 
-/**
- * Shape of the committed `all-version-*-params.json` data files: a map of weapon id to its raw
- * per-version params, the ordered list of tracked game versions, and (weapons only) special
- * points history.
- */
+/** Shape of the committed `all-version-*-params.json` files. */
 export interface AllVersionParams {
 	metadata: { versions: string[] };
 	weapons: Record<string, Record<string, Record<string, unknown>>>;
@@ -73,10 +69,7 @@ function isDistanceDamageBreakpoint(
 	);
 }
 
-/**
- * Whether `value` is a damage falloff curve: an array of {@link DistanceDamageBreakpoint}, with
- * each entry possibly being a nested array of breakpoints (e.g. fizzy bomb bounces).
- */
+/** Damage falloff curve: {@link DistanceDamageBreakpoint}s, possibly nested (e.g. fizzy bomb bounces). */
 function isDistanceDamageArray(
 	value: unknown[],
 ): value is Array<DistanceDamageBreakpoint | DistanceDamageBreakpoint[]> {
@@ -92,11 +85,7 @@ function isDistanceDamageArray(
 	);
 }
 
-/**
- * Serializes a damage falloff curve into a compact `"<damage> @ <distance>"` string (damage
- * scaled to displayed HP, i.e. divided by 10) so its per-version changes flow through the same
- * scalar param pipeline as plain values. Nested breakpoint arrays are flattened.
- */
+/** Falloff curve as `"<damage> @ <distance>"` (damage / 10 = displayed HP) so it flows through the scalar param pipeline. */
 function formatDistanceDamageArray(
 	value: Array<DistanceDamageBreakpoint | DistanceDamageBreakpoint[]>,
 ): string {
@@ -121,10 +110,8 @@ function flattenScalarParams(
 		if (typeof value === "number" || typeof value === "string") {
 			result.push([fullKey, value]);
 		} else if (Array.isArray(value)) {
-			// Damage falloff curves and arrays of plain numbers/strings (e.g.
-			// SplashSpawnParam.ForceSpawnNearestAddNumArray) are kept as a single joined string so
-			// their per-version changes still show up. Other arrays of objects are too structured
-			// to represent this way and are skipped.
+			// falloff curves and arrays of primitives become one joined string so their changes still
+			// show up; other arrays of objects are skipped
 			if (isDistanceDamageArray(value)) {
 				result.push([fullKey, formatDistanceDamageArray(value)]);
 			} else if (
@@ -146,10 +133,7 @@ function flattenScalarParams(
 	return result;
 }
 
-/**
- * Parses a single weapon's raw per-version params into the {@link ParsedWeaponParams} shape: each
- * parameter's current value plus its tracked history, grouped by category.
- */
+/** Raw per-version params of one weapon → {@link ParsedWeaponParams} (current value + history, by category). */
 export function parse(
 	weaponId: number,
 	rawParams: Record<string, Record<string, unknown>>,
@@ -214,10 +198,8 @@ export function parse(
 }
 
 /**
- * Parses the params of every given weapon id from a static all-version params data file, keyed by
- * weapon id (as a string). Ids with no entry in the data are skipped. `toDataKey` maps a weapon id
- * to the id its params are stored under — main weapons share params with their base weapon, while
- * subs and specials use their own id (the default identity mapping).
+ * Parses every given weapon id from an all-version data file, keyed by id string; ids with no data are
+ * skipped. `toDataKey` maps an id to the id its params are stored under (main weapons → base weapon).
  */
 export function parseMany<Id extends number>(
 	ids: readonly Id[],
@@ -236,10 +218,7 @@ export function parseMany<Id extends number>(
 	return result;
 }
 
-/**
- * Collects every distinct `${category}.${key}` parameter present across the given weapons, sorted
- * by category then key, for use as the comparison table's row definitions.
- */
+/** Every distinct `${category}.${key}` across the weapons, sorted, for the comparison table rows. */
 export function allParamKeys(
 	weaponParams: Record<string, ParsedWeaponParams>,
 ): ParamDefinition[] {
@@ -274,10 +253,7 @@ function getWeaponCategory(weaponId: MainWeaponId) {
 	);
 }
 
-/**
- * Returns the base main weapon ids of the given weapon's category, used as the columns its params
- * are compared against. A non-base weapon is kept first, followed by the other base weapons.
- */
+/** Base main weapon ids of the weapon's category (comparison columns); a non-base weapon is kept first. */
 export function categoryWeaponIds(weaponId: MainWeaponId): MainWeaponId[] {
 	const category = getWeaponCategory(weaponId);
 	if (!category) {
@@ -296,11 +272,7 @@ export function categoryWeaponIds(weaponId: MainWeaponId): MainWeaponId[] {
 	return [weaponId, ...baseWeapons.filter((id) => id !== currentWeaponBaseId)];
 }
 
-/**
- * Returns the main weapon ids that are kit siblings of the given weapon, i.e. they share
- * the same base weapon (e.g. a weapon and its alternate kit) but excluding cosmetic alt
- * skins. The returned list includes the given weapon itself.
- */
+/** Main weapon ids sharing the base weapon (alternate kits, not alt skins), including the weapon itself. */
 export function kitSiblingIds(weaponId: MainWeaponId): MainWeaponId[] {
 	const baseId = weaponIdToBaseWeaponId(weaponId);
 	return mainWeaponIds.filter(
@@ -344,10 +316,8 @@ function isMoreInformativeMultiplier(
 }
 
 /**
- * Collects the damage multiplier history of every damage rate row that applies to the given
- * weapon, reduced to a single entry per object target. A weapon can map to several rows (e.g.
- * different attacks) that share the same target; the most informative one (longest tracked
- * history, then highest current rate) is kept. Entries are ordered like {@link DAMAGE_RECEIVERS}.
+ * Damage multiplier history per object target, keeping the most informative row (longest history,
+ * then highest rate) when several attacks share a target. Ordered like {@link DAMAGE_RECEIVERS}.
  */
 export function damageMultipliersForWeapon(
 	rows: Record<string, DamageRateHistoryRow>,
@@ -391,11 +361,8 @@ function attackerGroupKey(attackers: IncomingDamageAttackers): string {
 }
 
 /**
- * Collects, for the given sub or special weapon (which must itself be a damageable object), the
- * history of every *other* weapon's damage multiplier against it. Each entry is one group of
- * attacking weapons that shared a rate change against one of the weapon's receiver targets; per
- * (attacker group, target) the most informative entry (longest history, then highest rate) is
- * kept. Entries are ordered like {@link DAMAGE_RECEIVERS}, then by attacker group.
+ * For a damageable sub/special: every other weapon's damage multiplier history against it, one entry
+ * per (attacker group, target) keeping the most informative. Ordered like {@link DAMAGE_RECEIVERS}.
  */
 export function incomingDamageMultipliersForWeapon(
 	rows: Record<string, DamageRateHistoryRow>,
@@ -461,8 +428,7 @@ function changesFromHistory(
 		const { version, value: from } = history[i];
 		const to = i < history.length - 1 ? history[i + 1].value : current;
 
-		// A recorded value is the value *before* a change, so the change took effect at the
-		// next tracked game version.
+		// a recorded value is the value *before* a change, so it took effect at the next version
 		const recordedIndex = versionIndex.get(version);
 		if (recordedIndex === undefined) continue;
 		const patchVersion = versions[recordedIndex + 1];
@@ -474,13 +440,7 @@ function changesFromHistory(
 	return result;
 }
 
-/**
- * Groups every tracked parameter change of a single weapon by the game version (patch) that
- * introduced it. Optionally folds the weapon's special points history into the same grouping.
- *
- * Within each patch the changes are sorted with special points first, then alphabetically by
- * category and key.
- */
+/** Every tracked change of one weapon grouped by the patch that introduced it, optionally with special points. */
 function computeWeaponPatchChanges(
 	parsed: ParsedWeaponParams,
 	versions: string[],
@@ -528,7 +488,7 @@ function computeWeaponPatchChanges(
 			versions,
 			versionIndex,
 		)) {
-			// Fewer special points needed means the special charges faster.
+			// fewer points = charges faster
 			const kind = from === to ? "neutral" : to < from ? "buff" : "nerf";
 			push(patchVersion, {
 				category: SPECIAL_POINTS_PARAM_KEY,
@@ -549,7 +509,6 @@ function computeWeaponPatchChanges(
 			versions,
 			versionIndex,
 		)) {
-			// A higher damage rate means the weapon deals more damage to the object.
 			const kind = from === to ? "neutral" : to > from ? "buff" : "nerf";
 			push(patchVersion, {
 				category: DAMAGE_MULTIPLIER_PARAM_KEY,
@@ -569,8 +528,7 @@ function computeWeaponPatchChanges(
 			versions,
 			versionIndex,
 		)) {
-			// A higher incoming damage rate means the object takes more damage, i.e. a nerf to the
-			// sub or special weapon being defended (the inverse of an outgoing damage multiplier).
+			// higher incoming rate = the sub/special takes more damage = nerf
 			const kind = from === to ? "neutral" : to > from ? "nerf" : "buff";
 			push(patchVersion, {
 				category: INCOMING_DAMAGE_MULTIPLIER_PARAM_KEY,
@@ -586,8 +544,7 @@ function computeWeaponPatchChanges(
 
 	for (const changes of byVersion.values()) {
 		changes.sort((a, b) => {
-			// Special points first (ordered by kit), then outgoing damage multipliers, then
-			// incoming damage multipliers, then regular params by category and key.
+			// special points, outgoing multipliers, incoming multipliers, then params by category and key
 			const rank = (change: PatchChange) =>
 				change.category === SPECIAL_POINTS_PARAM_KEY
 					? 0
@@ -620,12 +577,7 @@ function computeWeaponPatchChanges(
 	return byVersion;
 }
 
-/**
- * Assembles per-version change maps into the descending-by-version patch history, attaching each
- * tracked game version's release date and skipping versions with no changes. When several maps are
- * given (e.g. a kit's main, sub and special weapon changes) their changes are concatenated in the
- * order the maps are passed, keeping each map's own within-version ordering.
- */
+/** Change maps → descending patch history with release dates, skipping empty versions; maps concatenate in order. */
 function changeMapsToPatches(
 	maps: Array<Map<string, PatchChange[]>>,
 	versions: string[],
@@ -642,11 +594,7 @@ function changeMapsToPatches(
 		.reverse();
 }
 
-/**
- * Builds the descending-by-version patch history of a single weapon, attaching each tracked
- * game version's release date and skipping versions with no tracked balance changes. Special
- * points changes are only folded in for main weapons (pass their history as `specialPoints`).
- */
+/** Descending patch history of one weapon. Pass `specialPoints` for main weapons to fold those changes in. */
 export function patchHistory(
 	parsed: ParsedWeaponParams | undefined,
 	versions: string[],
@@ -671,11 +619,7 @@ export function patchHistory(
 	);
 }
 
-/**
- * Builds a patch history per kit of a main weapon, folding the (shared) main weapon changes
- * together with the kit's own special points, sub weapon and special weapon changes. Every change
- * is tagged with its `source` so the patch history can group a column under a divider per weapon.
- */
+/** Patch history per kit: shared main weapon changes + the kit's special points, sub and special. Changes are tagged by `source`. */
 export function kitPatchHistories({
 	mainParsed,
 	versions,
diff --git a/app/features/params/core/param-directions.ts b/app/features/params/core/param-directions.ts
index 8789b8cfb..a093c65bb 100644
--- a/app/features/params/core/param-directions.ts
+++ b/app/features/params/core/param-directions.ts
@@ -1,31 +1,22 @@
-/**
- * Whether a higher value is better ("higher") or worse ("lower") for the player who owns
- * the weapon. `null` means the direction is unknown / context-dependent.
- */
+/** Whether a higher value is better or worse for the weapon's owner; `null` = unknown / context-dependent. */
 type ParamDirection = "higher" | "lower" | null;
 
-/**
- * How a value change between two patches affected the weapon: a `"buff"` made it stronger,
- * a `"nerf"` made it weaker, and `"neutral"` is either an unclassified parameter or a change
- * whose impact direction we don't track.
- */
+/** `"neutral"` = unclassified parameter or a change whose direction isn't tracked. */
 export type ParamChangeKind = "buff" | "nerf" | "neutral";
 
 /**
- * Ordered substring rules describing whether a higher value of a parameter is good for its
- * weapon. The first rule whose `match` is a substring of the full `${category}.${key}` wins,
- * so narrower exceptions are listed before broader rules (e.g. `ReceiveDamage` before
- * `Damage`). Parameters matching no rule are treated as having an unknown direction.
+ * First rule whose `match` is a substring of `${category}.${key}` wins, so narrower exceptions go
+ * before broader rules (`ReceiveDamage` before `Damage`). No match = unknown direction.
  */
 const PARAM_DIRECTION_RULES: Array<{
 	match: string;
 	betterWhenHigher: boolean;
 }> = [
-	// Taking less damage is good, so these override the broader "Damage" rule below.
+	// overrides the broader "Damage" rule below
 	{ match: "ReceiveDamage", betterWhenHigher: false },
 	{ match: "AttackedDamageRate", betterWhenHigher: false },
 
-	// Lower is better: less ink, faster recovery, tighter spread, shorter delays.
+	// lower is better
 	{ match: "InkConsume", betterWhenHigher: false },
 	{ match: "InkRecoverStop", betterWhenHigher: false },
 	{ match: "DegSwerve", betterWhenHigher: false },
@@ -38,7 +29,7 @@ const PARAM_DIRECTION_RULES: Array<{
 	{ match: "NakedFrame", betterWhenHigher: false },
 	{ match: "Dash_ChargeCancelableFrame", betterWhenHigher: false },
 
-	// Higher is better: more damage, durability, mobility, paint, range, uptime.
+	// higher is better
 	{ match: "Damage", betterWhenHigher: true },
 	{ match: "CanopyHP", betterWhenHigher: true },
 	{ match: "ArmorHP", betterWhenHigher: true },
@@ -59,7 +50,6 @@ const PARAM_DIRECTION_RULES: Array<{
 	{ match: "PowerUpFrame", betterWhenHigher: true },
 	{ match: "KnockBackParam.Distance", betterWhenHigher: true },
 
-	// Longer-lasting effects and uptime are buffs.
 	{ match: "SpecialTotalFrame", betterWhenHigher: true },
 	{ match: "SpecialDurationFrame", betterWhenHigher: true },
 	{ match: "MarkingFrame", betterWhenHigher: true },
@@ -70,11 +60,6 @@ const PARAM_DIRECTION_RULES: Array<{
 	{ match: ".High", betterWhenHigher: true },
 ];
 
-/**
- * Returns whether a higher value of the given parameter benefits the weapon's owner, using
- * substring matching against `${category}.${key}`. Returns `null` when the parameter is not
- * recognized as clearly directional.
- */
 function getParamDirection(category: string, key: string): ParamDirection {
 	const fullKey = `${category}.${key}`;
 
@@ -87,14 +72,9 @@ function getParamDirection(category: string, key: string): ParamDirection {
 	return null;
 }
 
-/** Matches a single `"<damage> @ <distance>"` breakpoint of a serialized damage falloff curve. */
 const DAMAGE_BREAKPOINT_PATTERN = /^\s*([\d.]+)\s*@\s*([\d.]+)\s*$/;
 
-/**
- * Parses a serialized damage falloff curve (see `formatDistanceDamageArray`) back into its
- * breakpoints. Returns `null` for any other string (enums, primitive-array blobs), which are
- * treated as non-directional.
- */
+/** Inverse of `formatDistanceDamageArray`; `null` for any other string (enums, primitive-array blobs). */
 function parseDamageCurve(
 	value: number | string,
 ): Array<{ damage: number; distance: number }> | null {
@@ -113,11 +93,8 @@ function parseDamageCurve(
 }
 
 /**
- * Classifies a change between two damage falloff curves by comparing them breakpoint by
- * breakpoint. Both more damage and more reach (a higher distance at which a damage tier still
- * applies) count as improvements, so a curve where every change improves is a buff, every change
- * worsens is a nerf, and a mix (or curves of differing shape) is neutral. Returns `null` when the
- * values are not both damage curves, so the caller falls back to scalar comparison.
+ * Breakpoint by breakpoint; more damage and more reach both count as improvements. All improve = buff,
+ * all worsen = nerf, mixed or differing shape = neutral. `null` when not both curves.
  */
 function classifyDamageCurveChange(
 	direction: ParamDirection,
@@ -153,11 +130,8 @@ function classifyDamageCurveChange(
 }
 
 /**
- * Classifies a parameter value change between two patches as a buff, a nerf, or neutral.
- *
- * Damage falloff curves are compared breakpoint by breakpoint (see
- * {@link classifyDamageCurveChange}). Neutral is returned for other non-numeric values, unchanged
- * values, or parameters whose impact direction is unknown (see {@link getParamDirection}).
+ * Buff, nerf or neutral. Falloff curves go through {@link classifyDamageCurveChange}; other non-numeric,
+ * unchanged or unknown-direction ({@link getParamDirection}) values are neutral.
  */
 export function classifyParamChange(
 	category: string,
diff --git a/app/features/params/weapon-params-constants.ts b/app/features/params/weapon-params-constants.ts
index 6fafc80fb..103ee7e0a 100644
--- a/app/features/params/weapon-params-constants.ts
+++ b/app/features/params/weapon-params-constants.ts
@@ -1,31 +1,19 @@
 import type { DamageReceiver } from "~/features/object-damage-calculator/calculator-types";
 
-/**
- * Sentinel `category` used for the special points entry in patch change data, since special
- * points are not a regular weapon parameter. The matching `key` is also this value.
- */
+/** Sentinel `category` (and `key`) of special points patch changes, which are not a regular param. */
 export const SPECIAL_POINTS_PARAM_KEY = "__specialPoints__";
 
-/**
- * Sentinel `category` used for damage multiplier (damage rate vs objects) entries in patch
- * change data. The `key` of such a change holds the damage receiver target instead.
- */
+/** Sentinel `category` of damage multiplier (rate vs objects) patch changes; `key` holds the receiver target. */
 export const DAMAGE_MULTIPLIER_PARAM_KEY = "__damageMultiplier__";
 
 /**
- * Sentinel `category` used for incoming damage multiplier entries in patch change data: a change
- * to some *other* weapon's damage rate against the page's sub or special weapon (which is itself a
- * damageable object). The `key` holds the damage receiver target, and `attackers` holds the
- * weapons whose rate changed.
+ * Sentinel `category` of incoming damage multiplier patch changes (another weapon's rate against the
+ * page's damageable sub/special); `key` holds the receiver target, `attackers` the weapons.
  */
 export const INCOMING_DAMAGE_MULTIPLIER_PARAM_KEY =
 	"__incomingDamageMultiplier__";
 
-/**
- * Maps a sub or special weapon to the object {@link DAMAGE_RECEIVERS} target(s) that represent it,
- * so the patch history can surface changes to other weapons' damage rates *against* the kit's sub
- * or special. Only weapons that exist as a damageable object are listed.
- */
+/** Sub/special weapon → the {@link DAMAGE_RECEIVERS} target(s) representing it. Only damageable weapons are listed. */
 export const INCOMING_DAMAGE_RECEIVERS: Record<
 	"sub" | "special",
 	Record<number, readonly DamageReceiver[]>
diff --git a/app/features/params/weapon-params-types.ts b/app/features/params/weapon-params-types.ts
index b156e204f..e85754653 100644
--- a/app/features/params/weapon-params-types.ts
+++ b/app/features/params/weapon-params-types.ts
@@ -16,7 +16,6 @@ export interface ParamValueWithHistory {
 	history: Array<{ version: string; value: number | string }>;
 }
 
-/** Which set of weapons a params page compares: main weapons, sub weapons or special weapons. */
 export type WeaponParamKind = "main" | "sub" | "special";
 
 const WEAPON_PARAM_KIND_KEY_PREFIX: Record<WeaponParamKind, string> = {
@@ -54,33 +53,21 @@ export interface SpecialPointWithHistory {
 	history: Array<{ version: string; value: number }>;
 }
 
-/**
- * History of a weapon's damage multiplier against a single object (a {@link DAMAGE_RECEIVERS}
- * target), surfaced only in the patch history. `target` is the receiver key used by the object
- * damage calculator.
- */
+/** Damage multiplier history against one object; `target` is a {@link DAMAGE_RECEIVERS} key. Patch history only. */
 export interface DamageMultiplierWithHistory {
 	target: string;
 	current: number;
 	history: Array<{ version: string; value: number }>;
 }
 
-/**
- * The set of weapons whose damage rate against an object changed together. Carried by an incoming
- * damage multiplier {@link PatchChange} so the badge can show the attacking weapons' icons.
- */
+/** Weapons whose damage rate against an object changed together, so the {@link PatchChange} badge can show their icons. */
 export interface IncomingDamageAttackers {
 	mainWeaponIds: MainWeaponId[];
 	subWeaponIds: SubWeaponId[];
 	specialWeaponIds: SpecialWeaponId[];
 }
 
-/**
- * History of some attacking weapons' shared damage multiplier against a single object
- * ({@link DamageMultiplierWithHistory} from the defender's perspective): the page's sub or special
- * weapon is the object being damaged. `target` is the receiver key used by the object damage
- * calculator.
- */
+/** {@link DamageMultiplierWithHistory} from the defender's perspective: the page's sub/special is the object damaged. */
 export interface IncomingDamageMultiplierWithHistory {
 	target: string;
 	attackers: IncomingDamageAttackers;
@@ -94,14 +81,11 @@ export interface PatchChange {
 	from: number | string;
 	to: number | string;
 	kind: ParamChangeKind;
-	/** The specific kit a special points change belongs to. Only set for special points. */
+	/** Only set for special points changes. */
 	weaponId?: MainWeaponId;
-	/**
-	 * Which weapon of a kit the change belongs to. Used by the per-kit patch history to group a
-	 * column's changes under a divider per weapon. Only set for kit patch histories.
-	 */
+	/** Which weapon of the kit the change belongs to. Only set for kit patch histories. */
 	source?: WeaponParamKind;
-	/** The weapons whose rate changed. Only set for incoming damage multiplier changes. */
+	/** Only set for incoming damage multiplier changes. */
 	attackers?: IncomingDamageAttackers;
 }
 
@@ -111,11 +95,7 @@ export interface WeaponPatch {
 	changes: PatchChange[];
 }
 
-/**
- * Patch history of a single main weapon kit, folding the main weapon's changes together with its
- * sub and special weapon's changes. Each {@link PatchChange} carries a `source` so the changes can
- * be grouped per weapon within a patch.
- */
+/** Patch history of one kit: main + sub + special changes, each {@link PatchChange} tagged with its `source`. */
 export interface KitPatchHistory {
 	weaponId: MainWeaponId;
 	subWeaponId: SubWeaponId;
diff --git a/app/features/plus-suggestions/PlusSuggestionRepository.server.ts b/app/features/plus-suggestions/PlusSuggestionRepository.server.ts
index fc578c7dc..4a4e3521f 100644
--- a/app/features/plus-suggestions/PlusSuggestionRepository.server.ts
+++ b/app/features/plus-suggestions/PlusSuggestionRepository.server.ts
@@ -49,8 +49,7 @@ export async function findAllByMonth(args: MonthYear & { tier?: number }) {
 		.$narrowType<{ author: NotNull; suggested: NotNull }>()
 		.execute();
 
-	// filter out suggestions that were made in the time period
-	// between voting ending and people gaining access from the leaderboard
+	// drops suggestions made between voting ending and people gaining access from the leaderboard
 	const rows = allRows.filter(
 		(r) => !r.suggestedPlusTier || r.suggestedPlusTier > r.tier,
 	);
@@ -157,8 +156,7 @@ export async function findMonthSummary(
 		if (row.suggestedPlusTier && row.suggestedPlusTier <= row.tier) continue;
 		if (!isPlusTier(row.tier)) continue;
 
-		// rows are in creation order, so the first row of a suggestion is the one
-		// that started it and every later row is a follow up comment
+		// rows are in creation order: the first row of a suggestion started it, later ones are comments
 		const key = `${row.tier}-${row.suggestedId}`;
 		if (seenSuggestions.has(key)) continue;
 		seenSuggestions.add(key);
@@ -211,7 +209,6 @@ export function deleteWithCommentsBySuggestedUserId({
 		.execute();
 }
 
-/** Plus tier the suggested user already has, if any. */
 // the first entry is the suggestion itself; deleting it deletes the whole
 // suggestion which the author may only do while it has no comments
 function entryPermissions({
@@ -239,6 +236,7 @@ function entryPermissions({
 	};
 }
 
+/** Plus tier the suggested user already has, if any. */
 function suggestedPlusTier(eb: ExpressionBuilder<DB, "PlusSuggestion">) {
 	return eb
 		.selectFrom("PlusTier")
diff --git a/app/features/plus-suggestions/routes/plus.suggestions.comment.$tier.$userId.tsx b/app/features/plus-suggestions/routes/plus.suggestions.comment.$tier.$userId.tsx
index 0f6647372..f7b845c2c 100644
--- a/app/features/plus-suggestions/routes/plus.suggestions.comment.$tier.$userId.tsx
+++ b/app/features/plus-suggestions/routes/plus.suggestions.comment.$tier.$userId.tsx
@@ -28,8 +28,7 @@ export default function PlusCommentModalPage() {
 		return <Redirect to={plusSuggestionPage()} />;
 	}
 
-	// the parent only loads one tier's suggestions, so a link that arrived without
-	// the matching tier search param (an old bookmark) is sent through it first
+	// the parent only loads one tier, so a link missing the tier param (an old bookmark) is redirected
 	if (data.tier !== tierSuggestedTo) {
 		return (
 			<Redirect
diff --git a/app/features/plus-voting/PlusVotingRepository.server.ts b/app/features/plus-voting/PlusVotingRepository.server.ts
index ac338c8ba..00ba36d2f 100644
--- a/app/features/plus-voting/PlusVotingRepository.server.ts
+++ b/app/features/plus-voting/PlusVotingRepository.server.ts
@@ -32,8 +32,7 @@ type ResultsByMonthYearQueryReturnType = InferResult<
 >;
 
 export async function findAllPlusTiersFromLatestVoting() {
-	// resolving month & year separately first allows SQLite to push the
-	// filtering down into the PlusVotingResult view's aggregation
+	// resolving month & year first lets SQLite push the filter into the PlusVotingResult view
 	const latestVoting = await db
 		.selectFrom("PlusVote")
 		.select(["PlusVote.year", "PlusVote.month"])
@@ -152,8 +151,7 @@ export async function findAllUsersForVoting(loggedInUser: {
 		tier: loggedInUser.plusTier,
 	});
 
-	// the suggestions page does not render bios, so they are not part of a
-	// suggestion and are looked up for the voting page separately
+	// bios are not part of a suggestion (the suggestions page does not render them)
 	const suggestedUserBios = await findBiosByUserIds(
 		suggestedUsers.map((suggestion) => suggestion.suggested.id),
 	);
diff --git a/app/features/plus-voting/actions/plus.voting.server.ts b/app/features/plus-voting/actions/plus.voting.server.ts
index 658b604bc..917c75645 100644
--- a/app/features/plus-voting/actions/plus.voting.server.ts
+++ b/app/features/plus-voting/actions/plus.voting.server.ts
@@ -32,8 +32,7 @@ export const action: ActionFunction = async ({ request }) => {
 		plusTier: user.plusTier,
 	});
 
-	// this should not be needed but makes the voting a bit more resilient
-	// if there is a bug that causes some user to show up twice, or some user to show up who should not be included
+	// resilience against a bug listing a user twice or one who should not be included
 	const seen = new Set<number>();
 	const filteredVotes = data.votes.filter((vote) => {
 		if (seen.has(vote.votedId)) {
diff --git a/app/features/plus-voting/core/voting-time.ts b/app/features/plus-voting/core/voting-time.ts
index 719b31267..a1085620c 100644
--- a/app/features/plus-voting/core/voting-time.ts
+++ b/app/features/plus-voting/core/voting-time.ts
@@ -2,7 +2,7 @@ import { Config } from "~/config";
 import * as Seasons from "../../mmr/core/Seasons";
 import type { MonthYear } from "./types";
 
-/** In local development voting is always open so that the voting page can be tested outside a voting window. */
+/** Lets the voting page be tested outside a voting window. */
 const VOTING_ALWAYS_OPEN =
 	process.env.NODE_ENV === "development" && !Config.prodMode;
 
@@ -61,22 +61,14 @@ export function seasonToVotingRange(season: Seasons.ListItem) {
 	return { startDate, endDate };
 }
 
-/**
- * Whether votes can be cast right now. Unlike {@link isVotingActive}, which also decides when
- * suggesting is locked, this is always true in local development so the voting page can be
- * tested outside an actual voting window.
- */
+/** Whether votes can be cast; unlike {@link isVotingActive} (which also locks suggesting) always true in local dev. */
 export function isVotingOpen() {
 	return VOTING_ALWAYS_OPEN || isVotingActive();
 }
 
 let votingActiveOverride = false;
 
-/**
- * Tests only: makes {@link isVotingActive} (and thus {@link isVotingOpen}) resolve to
- * true as if a voting window was ongoing, so tests can cover voting without a real
- * window having to be open.
- */
+/** Tests only: fakes an ongoing voting window for {@link isVotingActive}. */
 export function DANGEROUS_setVotingActiveOverride(votingActive: boolean) {
 	votingActiveOverride = votingActive;
 }
diff --git a/app/features/scanner-ingest/ScannerIngestRepository.server.ts b/app/features/scanner-ingest/ScannerIngestRepository.server.ts
index 7e9cbbe5a..dbd6c1250 100644
--- a/app/features/scanner-ingest/ScannerIngestRepository.server.ts
+++ b/app/features/scanner-ingest/ScannerIngestRepository.server.ts
@@ -16,11 +16,7 @@ import * as Scoreboards from "./core/Scoreboards";
 const opponentOneId = sql<number>`"TournamentMatch"."opponentOne" ->> '$.id'`;
 const opponentTwoId = sql<number>`"TournamentMatch"."opponentTwo" ->> '$.id'`;
 
-/**
- * How far a stored match's playedAt may sit from an incoming one and still
- * be loaded as a merge candidate (content contradictions are checked by
- * Matches.isSameMatch; this only bounds the query).
- */
+/** Max playedAt distance for a stored match to load as a merge candidate; only bounds the query, Matches.isSameMatch checks content. */
 const MERGE_CANDIDATE_PLAYED_AT_WINDOW_DAYS = 1;
 /** How recently a playedAt-less stored match must have been created to be a candidate. */
 const MERGE_CANDIDATE_CREATED_AT_WINDOW_DAYS = 7;
@@ -44,11 +40,7 @@ export function gamesPlayedByUserInTournament(params: {
 	return tournamentGames(params);
 }
 
-/**
- * Returns the games a user played in any tournament since the given
- * database timestamp, in chronological order — tournament candidates for
- * content-based context resolution (Scoreboards.resolveContext).
- */
+/** Games a user played in any tournament since the timestamp, chronological — candidates for Scoreboards.resolveContext. */
 export function gamesPlayedByUserSince(params: {
 	userId: number;
 	/** database timestamp (seconds) */
@@ -57,11 +49,7 @@ export function gamesPlayedByUserSince(params: {
 	return tournamentGames(params);
 }
 
-/**
- * Returns the games of a tournament's casted sets (currently streamed ones
- * plus the cast history), in chronological order — the candidate set for
- * cast footage, whose submitter is staff rather than a player of the games.
- */
+/** Games of a tournament's casted sets (streamed now plus cast history), chronological — candidates for cast footage, whose submitter is staff. */
 export async function castedGamesInTournament(tournamentId: number) {
 	const tournament = await db
 		.selectFrom("Tournament")
@@ -85,30 +73,17 @@ export async function castedGamesInTournament(tournamentId: number) {
 	return tournamentGames({ tournamentId, tournamentMatchIds });
 }
 
-/**
- * Returns the reported games of one tournament match, in chronological
- * order — the candidate set for a live send, which carries no sequence of
- * its own to anchor on and so must not see the rest of the tournament.
- */
+/** Reported games of one tournament match, chronological — candidates for a live send, which has no sequence to anchor on and must not see the rest of the tournament. */
 export function gamesInTournamentMatch(tournamentMatchId: number) {
 	return tournamentGames({ tournamentMatchIds: [tournamentMatchId] });
 }
 
-/**
- * Returns a SendouQ match's reported games, in map order. The match's
- * pre-generated unplayed maps are left out: only a reported game is a link
- * target, so a match sent before its game's report stays unlinked (and gets
- * linked by a later resend instead).
- */
+/** A SendouQ match's reported games in map order. Unplayed maps are left out: a scan sent before its game's report stays unlinked until a resend. */
 export function gamesInGroupMatch(groupMatchId: number) {
 	return sendouqGames({ groupMatchId });
 }
 
-/**
- * Returns the reported games of SendouQ matches a user played in since the
- * given database timestamp, in chronological order — SendouQ candidates for
- * content-based context resolution (Scoreboards.resolveContext).
- */
+/** Reported SendouQ games a user played since the timestamp, chronological — candidates for Scoreboards.resolveContext. */
 export function sendouqGamesPlayedByUserSince(params: {
 	userId: number;
 	/** database timestamp (seconds) */
@@ -118,12 +93,9 @@ export function sendouqGamesPlayedByUserSince(params: {
 }
 
 /**
- * The tournament match the user was (probably) playing at the given
- * wall-clock time: their team is in a match whose `startedAt` is close
- * enough before `at`. When several qualify the one that started most
- * recently before `at` wins — a later round of the same event is still
- * within the window, and taking it would scope an earlier set's games out
- * of reach.
+ * The tournament match the user was probably playing at `at`: their team's match whose
+ * `startedAt` is close enough before it. The most recently started wins — a later round of the
+ * same event is still within the window and would scope an earlier set's games out of reach.
  */
 export async function tournamentActivityAt({
 	userId,
@@ -173,11 +145,9 @@ export async function tournamentActivityAt({
 }
 
 /**
- * The SendouQ match the user was (probably) playing at the given wall-clock
- * time: a group they are a member of is in a non-canceled match created
- * close enough before `at`. When several qualify the one created most
- * recently before `at` wins — queueing again right after a set still falls
- * within the window, and the newer match is not the one that was played.
+ * The SendouQ match the user was probably playing at `at`: their group's non-canceled match
+ * created close enough before it. The most recently created wins — queueing again right after
+ * a set still falls within the window.
  */
 export async function groupMatchIdAt({
 	userId,
@@ -231,12 +201,7 @@ export async function groupMatchIdAt({
 	return row?.id ?? null;
 }
 
-/**
- * Tournaments running a match around the given wall-clock time that the
- * user helps run: they authored the event, are on its staff (organizer or
- * streamer), or hold an admin/organizer/streamer role in its organization.
- * The candidate contexts for cast footage.
- */
+/** Tournaments with a match around `at` the user helps run (author, organizer/streamer staff, or org admin/organizer/streamer) — candidate contexts for cast footage. */
 export async function staffTournamentIdsAt({
 	userId,
 	at,
@@ -308,10 +273,7 @@ export async function staffTournamentIdsAt({
 	return rows.map((row) => row.tournamentId);
 }
 
-/**
- * Returns a tournament match's ingested scoreboards with their 0-based map
- * indexes, each derived from the game's linked ingested matches.
- */
+/** A tournament match's ingested scoreboards with 0-based map indexes, derived from each game's linked ingests. */
 export async function findScoreboardsByTournamentMatchId(
 	tournamentMatchId: number,
 ) {
@@ -377,10 +339,7 @@ export async function findScoreboardsByTournamentMatchId(
 	});
 }
 
-/**
- * Returns a SendouQ match's ingested scoreboards with their 0-based map
- * indexes, each derived from the map's linked ingested matches.
- */
+/** A SendouQ match's ingested scoreboards with 0-based map indexes, derived from each map's linked ingests. */
 export async function findScoreboardsByGroupMatchId(groupMatchId: number) {
 	const rows = await db
 		.selectFrom("IngestedMatchLink")
@@ -441,15 +400,12 @@ export async function findScoreboardsByGroupMatchId(groupMatchId: number) {
 }
 
 /**
- * Stores ingested matches, merging partials: a match that
- * `Matches.isSameMatch` recognizes as an already stored one (same POV user
- * scope) enriches that row instead of inserting. Identical resends are
- * no-ops via the content hash. The resolved context is stamped onto the
- * rows as tournamentIdHint/groupMatchIdHint (existing hints win; missing
- * ones are backfilled even on no-op resends).
+ * Stores ingested matches, merging partials: one `Matches.isSameMatch` recognizes (same POV user
+ * scope) enriches the stored row instead of inserting; identical resends are no-ops via the
+ * content hash. The resolved context is stamped as tournamentIdHint/groupMatchIdHint (existing
+ * hints win, missing ones backfilled even on no-op resends).
  *
- * @returns counts plus the post-merge rows (a partial arriving after an
- * earlier richer send links downstream with the merged, fuller data)
+ * @returns counts plus the post-merge rows, so a partial after a richer send links with the fuller data
  */
 export async function addOrMergeMatches({
 	povUserId,
@@ -490,11 +446,9 @@ export async function addOrMergeMatches({
 }
 
 /**
- * Links ingested matches to the game results they were matched to. A row
- * links to at most one game (re-sends are no-ops); one game may collect
- * links from many rows (each POV's scan of it). When the row's POV player
- * is known, their weapon is reported as a regular ReportedWeapon, unless
- * the user already has one for that game.
+ * Links ingested matches to their matched game results. A row links to at most one game (re-sends
+ * are no-ops); a game collects links from many rows (each POV's scan). A known POV player's
+ * weapon is reported as a regular ReportedWeapon unless they already have one for that game.
  *
  * @returns count of newly created links
  */
@@ -637,11 +591,7 @@ async function backfillHints(
 		.execute();
 }
 
-/**
- * The stored match the incoming one describes the same game as, if any:
- * rows in the same POV user scope, near in play time (or recent when either
- * side has none), content-checked by Matches.isSameMatch.
- */
+/** The stored match describing the same game, if any: same POV user scope, near in play time (or recent when either has none), content-checked by Matches.isSameMatch. */
 async function findMergeCandidate(
 	trx: Transaction<DB>,
 	{
@@ -708,11 +658,9 @@ function newestFirst<T extends { createdAt: number }>(a: T[], b: T[]): T[] {
 }
 
 /**
- * Orders activity candidates by how well their start explains a scan taken
- * at `atSeconds`: the one that started most recently at or before it, and
- * only when none did, the nearest one starting after (the window's clock-skew
- * allowance). Ordering by start alone would prefer whatever started last,
- * which for an event running back-to-back rounds is the wrong set.
+ * Orders candidates by how well their start explains a scan at `atSeconds`: most recent start at
+ * or before it, else the nearest after (clock-skew allowance). Start alone would prefer whatever
+ * started last, the wrong set for back-to-back rounds.
  */
 function startedNearestBefore(
 	column: "TournamentMatch.startedAt" | "GroupMatch.createdAt",
@@ -1001,10 +949,7 @@ async function groupRosters(groupIds: number[]) {
 	return result;
 }
 
-/**
- * The winner-first player names of each game's earliest linked ingested
- * match, keyed by the given link target column's value.
- */
+/** Winner-first player names of each game's earliest linked ingest, keyed by the link target column's value. */
 async function linkedPlayerNamesByTarget(
 	column: "tournamentMatchGameResultId" | "groupMatchMapId",
 	targetIds: number[],
diff --git a/app/features/scanner-ingest/actions/scanner-ingest.server.ts b/app/features/scanner-ingest/actions/scanner-ingest.server.ts
index 0846bc33b..9b98f0d5f 100644
--- a/app/features/scanner-ingest/actions/scanner-ingest.server.ts
+++ b/app/features/scanner-ingest/actions/scanner-ingest.server.ts
@@ -15,10 +15,7 @@ import {
 	ingestBodySchema,
 } from "../scanner-ingest-schemas";
 
-/**
- * How far back the POV user's reported games are considered as content-
- * resolution candidates
- */
+/** How far back the POV user's reported games are content-resolution candidates */
 const CONTENT_RESOLUTION_WINDOW_DAYS = 365;
 
 export const action: ActionFunction = async ({ request }) => {
@@ -139,17 +136,12 @@ interface IngestContextCandidate {
 }
 
 /**
- * Resolves the context (tournament or SendouQ match) a request's matches
- * belong to.
- *
- * The user's activity around the time the matches were played is the strong
- * signal: the SendouQ match resp. tournament match of theirs running then
- * (for cast footage, the casted sets of tournaments the submitter helps
- * run as author/organizer/streamer). Candidates are scored by how many
- * matches would link to their games; a candidate is kept even when nothing links
- * yet (a live minimap-only match still gets its hint). With no activity,
- * the matches' content decides: the mode+stage sequence plus roster sides
- * is near-unique in a user's reported-game history.
+ * Resolves the context (tournament or SendouQ match) a request's matches belong to. The user's
+ * activity around play time is the strong signal: their match running then (for cast footage,
+ * the casted sets of tournaments they help run). Candidates are scored by how many matches would
+ * link, but kept even when nothing links yet (a live minimap-only match still gets its hint).
+ * Without activity the content decides: mode+stage sequence plus roster sides is near-unique in
+ * a user's history.
  */
 async function resolveIngestContext({
 	matches,
@@ -295,21 +287,14 @@ function countAttachableMatches(matches: ScannerMatch[]): number {
 	return matches.filter((match) => match.winner !== null).length;
 }
 
-/**
- * A results-screen POV seat disproves the cast flag — casts never see a
- * results screen — so a misflagged read still resolves through the sender's
- * own activity.
- */
+/** A results-screen POV seat disproves the cast flag (casts never see one), so a misflagged read still resolves through the sender's activity. */
 function withoutDisprovenCast(match: ScannerMatch): ScannerMatch {
 	if (!match.cast || match.pov === null) return match;
 
 	return { ...match, cast: false };
 }
 
-/**
- * The wall-clock time the request's matches were (probably) played: the
- * latest match's playedAt, falling back to "now".
- */
+/** When the request's matches were probably played: the latest playedAt, else "now". */
 function anchorTime(matches: ScannerMatch[]): number {
 	const playedAts = matches
 		.map((match) => match.playedAt)
diff --git a/app/features/scanner-ingest/core/Matches.ts b/app/features/scanner-ingest/core/Matches.ts
index d357a8e0c..5ab13c041 100644
--- a/app/features/scanner-ingest/core/Matches.ts
+++ b/app/features/scanner-ingest/core/Matches.ts
@@ -1,8 +1,4 @@
-/**
- * Pure logic for stored scanner matches: canonical serialization (hashing),
- * deciding whether two partial ScannerMatches describe the same game, and
- * merging a newly ingested partial into a stored one.
- */
+/** Pure logic for stored scanner matches: canonical serialization (hashing), same-game identity of two partials, and merging a partial into a stored one. */
 import type {
 	ScannerMatch,
 	ScannerMatchObjective,
@@ -12,11 +8,7 @@ import type {
 } from "~/features/scanner/core/scanner-match";
 import { inGameNameWithoutDiscriminator } from "~/utils/strings";
 
-/**
- * Replay codes are random enough that two different games share almost no
- * positions; this many differing characters still reads as OCR jitter of
- * the same code, at or above it as a different game.
- */
+/** Replay codes of different games share almost no positions; fewer differing characters than this is OCR jitter of the same code. */
 const REPLAY_CODE_MAX_OCR_ERRORS = 3;
 
 /** Two reads of one game land within this of each other (clock skew, retries). */
@@ -32,11 +24,7 @@ const MIN_WEAPON_SLOTS_READ = 7;
 
 const PLAYERS_PER_TEAM = 4;
 
-/**
- * Rebuilds a match with a fixed key order so `JSON.stringify` of the result
- * is stable regardless of how the input was constructed — the hashing and
- * change-detection representation.
- */
+/** Rebuilds a match with a fixed key order so `JSON.stringify` is stable — the hashing and change-detection representation. */
 export function canonicalMatch(match: ScannerMatch): ScannerMatch {
 	return {
 		startsAt: match.startsAt,
@@ -68,11 +56,9 @@ export function canonicalMatch(match: ScannerMatch): ScannerMatch {
 }
 
 /**
- * Whether two (possibly partial) matches describe the same game. Callers
- * pre-scope candidates to the same tournament + POV user; this checks the
- * contents: contradicting mode/stage/replay-code/play-time rules identity
- * out, then a matching replay code, close play times, or an aligning roster
- * (names, or weapons when names are unread) rules it in.
+ * Whether two (possibly partial) matches describe the same game; callers pre-scope to the same
+ * tournament + POV user. Contradicting mode/stage/replay-code/play-time rules identity out; then a
+ * matching replay code, close play times, or an aligning roster (names, else weapons) rules it in.
  */
 export function isSameMatch(a: ScannerMatch, b: ScannerMatch): boolean {
 	if (a.mode !== null && b.mode !== null && a.mode !== b.mode) return false;
@@ -105,12 +91,9 @@ export function isSameMatch(a: ScannerMatch, b: ScannerMatch): boolean {
 }
 
 /**
- * Merges a newly ingested partial into the stored match: the incoming teams
- * are first aligned to the stored orientation (a scoreboard match's teams[0]
- * is the winner side while a minimap match's is alpha), then every field
- * fills stored nulls, stored values winning on conflict (mirroring the
- * scoreboard attachment's first-ingest-wins). `changed` is false when the
- * merge added nothing, so callers can skip the write.
+ * Merges an ingested partial into the stored match: incoming teams are aligned to the stored
+ * orientation (a scoreboard match's teams[0] is the winner, a minimap match's is alpha), then
+ * every field fills stored nulls, stored values winning. `changed` is false when nothing was added.
  */
 export function mergeMatches(
 	existing: ScannerMatch,
@@ -205,10 +188,7 @@ function canonicalPlayer(player: ScannerMatchPlayer): ScannerMatchPlayer {
 	};
 }
 
-/**
- * Positions at which two replay codes differ; null when either is unread.
- * A length mismatch counts every position of the longer code.
- */
+/** Positions at which two replay codes differ (a length mismatch counts every position of the longer); null when either is unread. */
 function replayCodeDiff(a: string | null, b: string | null): number | null {
 	if (a === null || b === null) return null;
 	const longer = Math.max(a.length, b.length);
@@ -227,10 +207,7 @@ interface Alignment {
 	weaponOverlap: number;
 }
 
-/**
- * How `b`'s teams best map onto `a`'s: as-is or sides swapped, scored by
- * name and weapon overlap. Ties keep "straight".
- */
+/** How `b`'s teams best map onto `a`'s (as-is or swapped), scored by name and weapon overlap. Ties keep "straight". */
 function bestAlignment(a: ScannerMatch, b: ScannerMatch): Alignment {
 	const straight = pairScore(a, b.teams[0], b.teams[1]);
 	const swapped = pairScore(a, b.teams[1], b.teams[0]);
@@ -333,12 +310,7 @@ function mergeScorePair(
 	return [existing[0] ?? incoming[0], existing[1] ?? incoming[1]];
 }
 
-/**
- * Merge one team's rows: each stored row takes its incoming counterpart —
- * matched by readable name, then by a weapon unique among the unmatched,
- * then by position — field-wise with stored values winning. Incoming rows
- * no stored row claimed append while the team stays ≤4.
- */
+/** Merges one team's rows: each stored row takes its counterpart (by name, then a unique weapon, then position), stored values winning; unclaimed incoming rows append while the team stays ≤4. */
 function mergeTeam(
 	existing: ScannerMatchTeam,
 	incoming: ScannerMatchTeam,
diff --git a/app/features/scanner-ingest/core/Scoreboards.ts b/app/features/scanner-ingest/core/Scoreboards.ts
index 14dae73ec..61e3a8522 100644
--- a/app/features/scanner-ingest/core/Scoreboards.ts
+++ b/app/features/scanner-ingest/core/Scoreboards.ts
@@ -16,31 +16,20 @@ import * as Matches from "./Matches";
 /** Lobby header value scoreboards of tournament/SendouQ games are expected to have. */
 const TOURNAMENT_LOBBY = "PRIVATE";
 
-/**
- * How many of the 8 player rows must carry the same readable name in the
- * same position for a match to count as a re-detection of a game's
- * already linked scoreboard (allows a couple of OCR misreads).
- */
+/** Of 8 player rows, how many must share name and position for a match to count as a re-detection (tolerates a couple of OCR misreads). */
 const MIN_LINKED_DUPLICATE_NAME_MATCHES = 6;
 
 /** How many players on the winning (first) resp. losing side of a scoreboard. */
 const PLAYERS_PER_TEAM = 4;
 
-/**
- * How many matches must align with one context's games for content
- * resolution to trust it. A single game's (mode, stage, sides) is common
- * across a user's history; two already carry order.
- */
+/** Matches that must align with one context's games before content resolution trusts it: one (mode, stage, sides) is common across a user's history, two carry order. */
 const MIN_RESOLVED_SCOREBOARDS = 2;
 
 /**
- * How far a scan's play time may sit from a game's report for the two to
- * still be the same game. Reporting follows the game by minutes, so this is
- * mostly headroom for a slow reporter and for the scan's clock (the client's
- * own) — while staying far inside the gap between two plays of one map. A
- * scan that lands outside every candidate stays unlinked rather than
- * guessing: an unlinked scan keeps its hint and can be re-sent, a wrongly
- * linked one silently puts strangers on a match page.
+ * Max distance between a scan's play time and a game's report for them to be the same game:
+ * headroom for a slow reporter and the client's clock, still far inside the gap between two
+ * plays of one map. Outside every candidate the scan stays unlinked (re-sendable) rather than
+ * silently putting strangers on a match page.
  */
 const PLAYED_AT_TOLERANCE_MS = 30 * 60 * 1000;
 
@@ -73,18 +62,9 @@ export interface IngestableGame {
 	winnerInGameNames: string[];
 	/** known in-game names of the losing team's roster, the side fallback for reads without a POV seat */
 	loserInGameNames: string[];
-	/**
-	 * database timestamp of the game's own report — both the chronological
-	 * ordering key across matches and what a scan's play time is measured
-	 * against to tell two plays of one map apart
-	 */
+	/** timestamp of the game's report: the chronological key and what a scan's play time is measured against */
 	playedAt: number;
-	/**
-	 * player names (winner-first, in scoreboard row order) of an already
-	 * linked ingested match of the game; null when the game has none yet.
-	 * Lets matching skip taken games across requests while recognizing
-	 * re-detections of the same scoreboard.
-	 */
+	/** winner-first row-order names of an already linked ingest of the game, null when none; lets matching skip taken games yet recognize re-detections */
 	linkedPlayerNames: string[] | null;
 }
 
@@ -107,12 +87,9 @@ export function contextKey(context: IngestContext): string {
 }
 
 /**
- * Resolves which context (tournament or SendouQ match) a request's matches
- * belong to from their content alone: the candidate games (the POV user's
- * reported games) are grouped by context and each context is scored by how
- * many matches `matchedGames` aligns with its games — the same mode+stage
- * sequence walk and roster-side validation that decides what would actually
- * be linked.
+ * Resolves which context (tournament or SendouQ match) a request's matches belong to from content
+ * alone: the POV user's reported games are grouped by context and each is scored by how many
+ * matches `matchedGames` aligns with its games.
  */
 export function resolveContext({
 	matches,
@@ -148,32 +125,21 @@ export function resolveContext({
 }
 
 /**
- * Matches ingested matches against a context's games, deciding which game
- * result each match should link to.
+ * Decides which game result each ingested match links to.
  *
- * Only matches whose winner is known with two full teams qualify (a
- * minimap-only match can never link — its winner and stats are unread).
- * Matches and games are both walked in chronological order: each match is
- * assigned to a not-yet-assigned game with the same mode and stage whose
- * sides agree with what is known. Among those, a match carrying a wall clock
- * takes the game reported nearest it (and none at all when every candidate
- * is further off than `PLAYED_AT_TOLERANCE_MS`); a match without one — a VoD
- * read, whose times are offsets into a video — takes the next in sequence,
- * which is what the chronological walk is for.
+ * Only matches with a known winner and two full teams qualify (minimap-only reads never link).
+ * Matches and games are walked chronologically: each match takes an unassigned game of the same
+ * mode+stage whose sides agree with what is known. A match with a wall clock takes the game
+ * reported nearest it (none beyond `PLAYED_AT_TOLERANCE_MS`); a VoD read (video offsets only)
+ * takes the next in sequence.
  *
- * The POV seat decides the sides where it can: the sender is the POV player,
- * so which of the game's rosters they belong to pins the scan's sides to the
- * game's teams — OCR'd names are too
- * unreliable to overrule it. Only when no seat can decide (cast footage, no
- * POV read) do the known in-game names arbitrate the sides. Matches from
- * other lobbies, with unreadable mode/stage or duplicated detections of the
- * same game are skipped.
+ * The sender is the POV player, so the roster they sit in pins the scan's sides — OCR'd names
+ * are too unreliable to overrule it. Only without a POV seat (cast footage) do in-game names
+ * arbitrate. Other lobbies, unreadable mode/stage and duplicate detections are skipped.
  *
- * One session's matches may arrive over many requests (one per game), so
- * games another ingest already linked to are skipped — unless the incoming
- * match is a re-detection of the linked one, which is matched to the same
- * game so re-sends stay idempotent and another POV's scan of the same game
- * lands on it too.
+ * Matches arrive over many requests, so games already linked are skipped — unless the incoming
+ * match is a re-detection of the linked one, which lands on the same game so re-sends stay
+ * idempotent and another POV's scan joins it.
  */
 export function matchedGames({
 	matches,
@@ -229,38 +195,23 @@ export interface IngestedScoreboardPlayer {
 	userId?: number;
 }
 
-/**
- * The scoreboard of a game derived from its linked ingested matches — the
- * shape match pages render. Derived at read time, not stored.
- */
+/** A game's scoreboard derived from its linked ingested matches, the shape match pages render. Derived at read time, not stored. */
 export interface IngestedScoreboardData {
 	/** game scores [winner, loser] (0-100; a knockout's winner is 100) */
 	scores: [number | null, number | null];
 	/** in scoreboard order: rows 0-3 winning team, rows 4-7 losing team */
 	players: IngestedScoreboardPlayer[];
-	/**
-	 * objective-counter progress of the game, per-team values [winner, loser]
-	 * and sample `t` in seconds since the game's first read (the source video
-	 * the raw values are offsets into is not stored). Absent when no counter
-	 * was read.
-	 */
+	/** objective-counter progress, per-team values [winner, loser], `t` in seconds since the game's first read (the source video is not stored). Absent when no counter was read. */
 	objective?: ScannerMatchObjective;
-	/**
-	 * per-player special/death samples, teams winner-first and `t` rebased
-	 * onto the same origin as `objective` so both chart on one axis. Absent
-	 * when the icon strip was never read.
-	 */
+	/** per-player special/death samples, teams winner-first, `t` on the same origin as `objective`. Absent when the icon strip was never read. */
 	playerStatus?: ScannerMatchPlayerStatus;
 }
 
 /**
- * Derives a game's scoreboard from its linked ingested matches: the earliest
- * link is the base and later ones enrich it (first-ingest-wins field-wise,
- * via Matches.mergeMatches), the merged match is projected winner-first, and
- * every linked POV seat attributes its player row to the POV user.
- *
- * `winnerTeamId`/`loserTeamId` are the game result's sides (tournament team
- * or SendouQ group ids), stamped onto the rows for the reader.
+ * Derives a game's scoreboard from its linked ingests: earliest link is the base, later ones
+ * enrich it field-wise (Matches.mergeMatches), projected winner-first, with every linked POV seat
+ * attributing its row to the POV user. `winnerTeamId`/`loserTeamId` are the result's sides
+ * (tournament team or SendouQ group ids) stamped onto the rows.
  */
 export function deriveScoreboardData({
 	linked,
@@ -307,21 +258,13 @@ export function deriveScoreboardData({
 	};
 }
 
-/**
- * A match's players winner-first in scoreboard row order (unread names as
- * empty strings), or null when the match has no such view — the
- * `linkedPlayerNames` a game's already linked ingest contributes.
- */
+/** A match's players winner-first in row order (unread names as ""), or null without such a view — a game's `linkedPlayerNames`. */
 export function winnerFirstPlayerNames(match: ScannerMatch): string[] | null {
 	const view = winnerFirstView(match, 0);
 	return view ? view.players.map((player) => player.name.trim()) : null;
 }
 
-/**
- * A match's players in linked-scoreboard order — winning team's rows first —
- * with unread names as empty strings. Null when the match can't link: its
- * winner is unknown or either team wasn't fully seen.
- */
+/** Winner-first row view of a match (unread names as ""). Null when it can't link: unknown winner or a team not fully seen. */
 interface WinnerFirstView {
 	lobby: ScannerLobby | null;
 	mode: ModeShort | null;
@@ -403,11 +346,7 @@ function winnerFirstView(
 	};
 }
 
-/**
- * The shared `t` origin of a match's progress series: the earliest counter
- * or status read, so both rebase onto one axis and stay aligned without
- * the source video.
- */
+/** Shared `t` origin of a match's progress series: the earliest counter or status read. */
 function firstProgressT(match: ScannerMatch): number {
 	const ts = [
 		...(match.objective?.samples ?? []).map((sample) => sample.t),
@@ -416,12 +355,7 @@ function firstProgressT(match: ScannerMatch): number {
 	return ts.length > 0 ? Math.min(...ts) : 0;
 }
 
-/**
- * Puts a match's counter samples in derived-scoreboard shape: per-team
- * values winner-first like `scores` and `players`, and `t` rebased to the
- * game's first progress read so the samples stay meaningful without the
- * source video.
- */
+/** Counter samples winner-first with `t` rebased to the game's first progress read. */
 function winnerFirstObjective(
 	objective: ScannerMatchObjective | null,
 	winner: 0 | 1,
@@ -466,11 +400,9 @@ function winnerFirstPlayerStatus(
 }
 
 /**
- * Attributes each linked match's POV seat to its POV user on the merged
- * rows: the seat's read name picks the row (unique name match), falling
- * back to the seat's own winner-first position when the names don't
- * contradict. A row already attributed, or a user already present, is left
- * alone (first link wins).
+ * Attributes each linked POV seat to its user on the merged rows: unique name match picks the
+ * row, else the seat's own winner-first position when names don't contradict. Already attributed
+ * rows and already present users are left alone (first link wins).
  */
 function attributePovUsers(
 	players: IngestedScoreboardPlayer[],
@@ -511,12 +443,7 @@ function attributionIndex(
 	return fallbackIndex;
 }
 
-/**
- * Drops re-detections of the same game within one request: same mode and
- * stage with enough player rows carrying the same readable name in the same
- * position — the same OCR-jitter tolerance as the cross-request duplicate
- * check (isLinkedDuplicate).
- */
+/** Drops re-detections of the same game within one request, with the same OCR-jitter tolerance as isLinkedDuplicate. */
 function dedupeViews(sorted: IndexedView[]): IndexedView[] {
 	const result: IndexedView[] = [];
 
@@ -537,14 +464,9 @@ function dedupeViews(sorted: IndexedView[]): IndexedView[] {
 }
 
 /**
- * The index of the game `view` should link to, or null when none fits. Only
- * games from `from` on are considered, so two scans of one request never
- * take the same game and the sequence stays ordered.
- *
- * A scan that knows when it was played takes the candidate reported nearest
- * that moment, which keeps two plays of one map apart — they sit minutes
- * from their own report and a session apart from each other. One that does
- * not takes the next candidate in sequence.
+ * Index of the game `view` links to, or null. Only games from `from` on are considered so two
+ * scans of one request never take the same game. A scan with a play time takes the candidate
+ * reported nearest it (keeps two plays of one map apart); one without takes the next in sequence.
  */
 function pickGame(
 	view: IndexedView,
@@ -569,11 +491,7 @@ function pickGame(
 	return best?.index ?? null;
 }
 
-/**
- * Whether a game is a candidate for a scan at all: the same map, and sides
- * that do not contradict — an already linked game only through being a
- * re-detection of the scan already on it.
- */
+/** Same map and non-contradicting sides; an already linked game only as a re-detection of the scan on it. */
 function canLink(
 	view: WinnerFirstView,
 	game: IngestableGame,
@@ -591,11 +509,8 @@ function canLink(
 }
 
 /**
- * Whether the POV seat's side in the scan agrees with the sender's side in
- * the game: the sender is the POV player, so the roster their user id sits
- * in says whether their seat should be on the winning rows. Null when the
- * check cannot decide — no POV seat read, no sender, or the sender in
- * neither roster (cast footage) — leaving the sides to the name fallback.
+ * Whether the POV seat's side agrees with the roster the sender sits in. Null when undecidable
+ * (no POV seat, no sender, or sender in neither roster — cast footage), leaving it to the name fallback.
  */
 function povSideAgreement(
 	view: WinnerFirstView,
@@ -611,11 +526,8 @@ function povSideAgreement(
 }
 
 /**
- * The side fallback for reads no POV seat can pin (cast footage above all):
- * the winning rows should overlap the game winner's in-game names at least
- * as well as the losing team's (and vice versa). A contradiction means the
- * match belongs to some other game. No overlap at all (e.g. no in-game
- * names set) counts as a pass.
+ * Side fallback when no POV seat can pin (cast footage): winning rows must overlap the winner's
+ * in-game names at least as well as the loser's, and vice versa. No overlap at all passes.
  */
 function sidesMatchKnownPlayers(view: WinnerFirstView, game: IngestableGame) {
 	const winnerSide = view.players
@@ -641,12 +553,7 @@ function nameOverlap(names: string[], knownNames: string[]) {
 	return names.filter((name) => name && known.has(name)).length;
 }
 
-/**
- * Checks whether a match is a re-detection of a game's already linked
- * scoreboard: enough player rows carry the same readable name in the same
- * position. Positional comparison keeps two games between the same eight
- * players apart — their row orders and sides practically always differ.
- */
+/** Re-detection check: enough rows share name and position. Positional so two games between the same eight players stay apart. */
 function isLinkedDuplicate(view: WinnerFirstView, linkedPlayerNames: string[]) {
 	const matches = view.players.filter((player, i) => {
 		const name = Matches.normalizeInGameName(player.name);
diff --git a/app/features/scanner-ingest/core/VodMatches.test.ts b/app/features/scanner-ingest/core/VodMatches.test.ts
index 50adb8b08..f8075a4f5 100644
--- a/app/features/scanner-ingest/core/VodMatches.test.ts
+++ b/app/features/scanner-ingest/core/VodMatches.test.ts
@@ -65,9 +65,8 @@ describe("prefillVodMatches", () => {
 	});
 
 	test("accepts the `ingest` search param the scanner VoD tab sends", () => {
-		// what the scanner VoD tab's "Add VoD" button puts in the URL
-		// (~/features/scanner/components/sendou-upload.ts): a { type?, matches }
-		// payload in the compressed `ingest` param
+		// the { type?, matches } payload the scanner VoD tab's "Add VoD" button puts in the
+		// compressed `ingest` param (~/features/scanner/components/sendou-upload.ts)
 		const href = vodsNewSearchParams.href("/vods/new", {
 			ingest: { type: "CAST", matches: [testMatch()] },
 		});
diff --git a/app/features/scanner-ingest/core/VodMatches.ts b/app/features/scanner-ingest/core/VodMatches.ts
index 95d01a8dd..ae4538ee5 100644
--- a/app/features/scanner-ingest/core/VodMatches.ts
+++ b/app/features/scanner-ingest/core/VodMatches.ts
@@ -14,11 +14,7 @@ export interface PrefillVodMatch {
 	povWeapon: MainWeaponId | null;
 }
 
-/**
- * Turns the per-match rows a scanner VoD scan sends into prefill data for the
- * /vods/new form. The rows already carry sendou ids (validated by
- * ingestVodPrefillSchema); this only renames fields into the form's shape.
- */
+/** Turns a scanner VoD scan's per-match rows (sendou ids, validated by ingestVodPrefillSchema) into /vods/new prefill data; only renames fields. */
 export function prefillVodMatches(
 	matches: IngestVodMatchInput[],
 ): PrefillVodMatch[] {
diff --git a/app/features/scanner-ingest/scanner-ingest-schemas.ts b/app/features/scanner-ingest/scanner-ingest-schemas.ts
index 6c4605ff6..bf0de4d44 100644
--- a/app/features/scanner-ingest/scanner-ingest-schemas.ts
+++ b/app/features/scanner-ingest/scanner-ingest-schemas.ts
@@ -3,12 +3,7 @@ import { scannerMatchSchema } from "~/features/scanner/scanner-schemas";
 
 const MAX_MATCHES_PER_REQUEST = 50;
 
-/**
- * The ScannerMatch shape comes from the producer
- * (~/features/scanner/scanner-schemas — the single source of truth for the
- * scanner domain); this module only adds the ingest-specific envelope. The
- * POV user is always the session user, never client-supplied.
- */
+/** The ScannerMatch shape comes from ~/features/scanner/scanner-schemas; this only adds the ingest envelope. The POV user is always the session user, never client-supplied. */
 export const ingestBodySchema = v.object({
 	matches: v.pipe(
 		v.array(scannerMatchSchema),
@@ -28,10 +23,6 @@ export interface IngestResponse {
 	linkedGamesCount: number;
 	/** per request match (by its index in the body's `matches`), the match it linked to */
 	linkedMatches: Array<{ matchIndex: number; link: IngestedMatchLink }>;
-	/**
-	 * whether the request's matches were resolved to a tournament or SendouQ
-	 * match. A match that stayed unlinked despite one is waiting for its game
-	 * to be reported, so resending it later can still link it.
-	 */
+	/** whether the matches resolved to a tournament or SendouQ match; one unlinked despite that waits for its game's report, so a resend can still link it */
 	contextResolved: boolean;
 }
diff --git a/app/features/scanner-ingest/scanner-ingest-vod-schemas.ts b/app/features/scanner-ingest/scanner-ingest-vod-schemas.ts
index e9c9a1b49..d3ba95109 100644
--- a/app/features/scanner-ingest/scanner-ingest-vod-schemas.ts
+++ b/app/features/scanner-ingest/scanner-ingest-vod-schemas.ts
@@ -12,31 +12,20 @@ const ingestVodMatchSchema = v.object({
 	startsAt: v.pipe(v.number(), v.integer(), v.minValue(0)),
 	/** null when no source read it */
 	mode: v.nullable(modeShortSchema),
-	/**
-	 * true when `mode` is the scanner's fabricated PoC default (SZ) rather
-	 * than a real read. Currently informational only — assumed modes are
-	 * still stored, since casted footage never exposes the mode.
-	 */
+	/** true when `mode` is the scanner's fabricated default (SZ), not a read. Informational only: assumed modes are still stored, casted footage never exposes the mode. */
 	modeAssumed: v.optional(v.boolean()),
 	/** null when no source read it */
 	stage: v.nullable(stageIdSchema),
 	/** sendou main-weapon ids; null for a slot that never read */
 	weapons: v.pipe(v.array(v.nullable(mainWeaponIdSchema)), v.maxLength(16)),
-	/**
-	 * the POV player's weapon, prefilling a non-CAST VoD's single weapon
-	 * select. Absent when no scoreboard identified the POV seat (or it read
-	 * no weapon) — including on casted footage, which has no POV.
-	 */
+	/** the POV player's weapon, prefilling a non-CAST VoD's weapon select. Absent when no scoreboard identified the POV seat or its weapon (casted footage has no POV). */
 	povWeapon: v.optional(mainWeaponIdSchema),
 });
 
 /**
- * The scanner VoD tab's "Add VoD" button packs this into /vods/new's
- * `ingest` search param (an `SP.json` param, compressed by the search-params
- * module) to prefill the form: the detected match rows, minus the submission
- * fields (YouTube URL, title, date) the user fills in the form. `type` is
- * sent only when the scan auto-detected it (spectator map screens → CAST);
- * absent means the form's default.
+ * What the scanner VoD tab's "Add VoD" button packs into /vods/new's `ingest` search param (a
+ * compressed `SP.json` param) to prefill the form: the detected match rows minus the submission
+ * fields. `type` is sent only when auto-detected (spectator map screens → CAST).
  */
 export const ingestVodPrefillSchema = v.object({
 	type: v.optional(v.picklist(videoMatchTypes)),
diff --git a/app/features/scanner-ingest/tests/harness.ts b/app/features/scanner-ingest/tests/harness.ts
index 084d58a69..521713471 100644
--- a/app/features/scanner-ingest/tests/harness.ts
+++ b/app/features/scanner-ingest/tests/harness.ts
@@ -1,8 +1,4 @@
-/**
- * Everything the ingest scenario cases need: world builders (arrange), the
- * ingest wrapper (act), page-loader wrappers and row fetchers (assert).
- * Cases import only from here, plus vitest. See README.md for the design.
- */
+/** Everything ingest scenario cases need: world builders (arrange), ingest wrapper (act), page-loader wrappers and row fetchers (assert). See README.md. */
 import { addHours, addMinutes, subDays, subMinutes } from "date-fns";
 import * as R from "remeda";
 import { afterAll, beforeAll } from "vitest";
@@ -62,18 +58,11 @@ export interface ScannableGame {
 	stage: StageId;
 	/** chronological position among the world's games, spacing reads apart */
 	order: number;
-	/**
-	 * wall-clock ms the game was reported, for cases whose read has to sit on
-	 * the world's real timeline rather than the default "now + order" spacing
-	 */
+	/** wall-clock ms the game was reported, for reads that must sit on the world's real timeline rather than "now + order" */
 	playedAt?: number;
 	winnerNames: string[];
 	loserNames: string[];
-	/**
-	 * each player's weapon, keyed by name. Worlds keep this stable per player
-	 * so two games between different opponents never read as the same match.
-	 * Reads fall back to `WEAPONS` by row for games built outside a world.
-	 */
+	/** each player's weapon by name, stable per player so two games against different opponents never read as the same match; falls back to `WEAPONS` by row */
 	weaponFor?: (name: string) => MainWeaponId;
 }
 
@@ -86,11 +75,7 @@ export interface ScannedOptions extends Partial<ScannerMatch> {
 	partial?: boolean;
 }
 
-/**
- * Forces the scanner gate open for the whole suite (fallback for
- * `import.meta.env` not carrying the config's `test.env`), restoring the
- * original value afterwards. Call at the top of the test file.
- */
+/** Forces the scanner gate open for the suite (`import.meta.env` may not carry the config's `test.env`), restoring it afterwards. Call at the top of the test file. */
 export function setupScannerGate() {
 	let original: boolean;
 	beforeAll(() => {
@@ -113,12 +98,7 @@ export async function withScannerDisabled(fn: () => Promise<void>) {
 	}
 }
 
-/**
- * 8 users with deterministic in-game names (`Alpha1#1111`, …) and a SendouQ
- * match between them. The match starts unreported; `conclude()` plays it out
- * the way the teams report it (alpha sweeps), making its maps linkable, and
- * returns the refreshed map rows.
- */
+/** 8 users with deterministic in-game names (`Alpha1#1111`, …) and an unreported SendouQ match between them; `conclude()` plays it out (alpha sweeps), making its maps linkable, and returns the refreshed map rows. */
 export async function sendouqWorld(
 	options: {
 		createdAt?: Date;
@@ -176,14 +156,10 @@ export async function sendouqWorld(
 }
 
 /**
- * A played single-elimination tournament: `teams` rosters of 4 users, all
- * with deterministic in-game names (`T1P1#1111`, …), played out through
- * `playedOut` the way `TournamentFactory.createPlayed` plays brackets.
- * Match/game timestamps are staggered into the recent past in play order, so
- * activity resolution and chronological walks see an unambiguous timeline.
- * Creating a world clears the tournament data caches: SQLite ids restart
- * after the db wipe, so a previous test's entries could otherwise serve
- * stale data for a reused id.
+ * A played single-elimination tournament of `teams` 4-user rosters with deterministic in-game
+ * names (`T1P1#1111`, …). Timestamps are staggered into the recent past in play order so activity
+ * resolution sees an unambiguous timeline. Clears the tournament data caches: SQLite ids restart
+ * after the db wipe, so a previous test's entries could serve stale data for a reused id.
  */
 export async function tournamentWorld(
 	options: { teams?: number; playedOut?: number } = {},
@@ -285,10 +261,7 @@ export async function tournamentWorld(
 	};
 }
 
-/**
- * Another SendouQ match between a world's same players, made at `createdAt` —
- * the later queueing an earlier match's read must not be captured by.
- */
+/** Another SendouQ match between a world's same players at `createdAt` — the later queueing an earlier match's read must not be captured by. */
 export function anotherSendouqMatch(
 	world: {
 		alphaUsers: Array<{ id: number }>;
@@ -313,11 +286,9 @@ export function createUser(inGameName?: string) {
 }
 
 /**
- * Derives a full `ScannerMatch` from a sendou.ink game so mode/stage/rosters
- * line up by construction; options spell out a case's deviation. The default
- * read is winner-first with the POV on seat 0 of the winning team, played
- * when the game says it was — or, for games that carry no time of their own,
- * "now" offset by `order` so multi-read requests stay chronological.
+ * A full `ScannerMatch` derived from a game so mode/stage/rosters line up; options spell out a
+ * case's deviation. Default read is winner-first, POV on winning seat 0, played when the game
+ * says — or "now" offset by `order` for games without a time, so multi-read requests stay chronological.
  */
 export function scannedGame(
 	game: ScannableGame,
@@ -462,12 +433,7 @@ function groupMatchMaps(matchId: number) {
 		.execute();
 }
 
-/**
- * Backdates the set's reported maps so they look played minutes apart ending
- * at `reportedThrough`, rather than all inside the same test second.
- * Production reports a map as it finishes, and matching leans on that spacing
- * to tell two plays of one map apart.
- */
+/** Backdates the set's map reports minutes apart ending at `reportedThrough`: matching leans on that spacing to tell two plays of one map apart. */
 async function stampMapReports(matchId: number, reportedThrough: Date) {
 	const reported = (await groupMatchMaps(matchId)).filter(
 		(map) => map.winnerGroupId !== null,
@@ -525,10 +491,8 @@ async function concludeGroupMatch(matchId: number) {
 }
 
 /**
- * Backdates match `startedAt`s and game result `createdAt`s into the recent
- * past, staggered in play order: everything production stamps within the
- * same test second becomes an unambiguous timeline, so "latest match" and
- * game order come out the same on every run.
+ * Backdates match `startedAt`s and result `createdAt`s into the recent past, staggered in play
+ * order, so "latest match" and game order come out the same on every run.
  *
  * @returns each set's `startedAt`, keyed by match id
  */
diff --git a/app/features/scanner/capture/sampler.ts b/app/features/scanner/capture/sampler.ts
index 5edf78718..cfd439227 100644
--- a/app/features/scanner/capture/sampler.ts
+++ b/app/features/scanner/capture/sampler.ts
@@ -1,7 +1,6 @@
 /**
  * Capture layer: OBS Virtual Camera in via getUserMedia, frames out as
- * ImageBitmaps at a low sample rate. The interface downstream is just
- * (bitmap, t) — a WHIP/MediaMTX transport can replace this file later.
+ * ImageBitmaps at a low sample rate. Downstream sees only (bitmap, t).
  */
 
 export async function openVirtualCamera(
@@ -25,14 +24,13 @@ export async function listVideoInputs(): Promise<MediaDeviceInfo[]> {
 export type FrameHandler = (bitmap: ImageBitmap, t: number) => void;
 
 /**
- * Sample frames from a playing video element at ~fps. The clock is a
+ * Samples frames from a playing video element at ~fps. The clock is a
  * setInterval in a dedicated worker (ticker.worker.ts): rAF and
- * requestVideoFrameCallback pause entirely in hidden tabs, but worker timers
- * keep firing and the camera stream keeps decoding, so capture continues
- * while the user is in another tab or window. Timestamps come from
- * performance.now() (monotonic, which the timeline's merge windows rely on)
- * rather than mediaTime, which Firefox never advances for MediaStream-backed
- * videos anyway. Returns a stop function.
+ * requestVideoFrameCallback pause in hidden tabs, but worker timers keep
+ * firing, so capture continues in another tab. Timestamps come from
+ * performance.now() (monotonic, which the merge windows rely on) rather than
+ * mediaTime, which Firefox never advances for MediaStream-backed videos.
+ * Returns a stop function.
  */
 export function startSampler(
 	video: HTMLVideoElement,
diff --git a/app/features/scanner/capture/ticker.worker.ts b/app/features/scanner/capture/ticker.worker.ts
index 7d4f4af42..135194d4a 100644
--- a/app/features/scanner/capture/ticker.worker.ts
+++ b/app/features/scanner/capture/ticker.worker.ts
@@ -1,8 +1,7 @@
 /**
- * Interval clock for the frame sampler. Lives in a worker because worker
- * timers keep firing while the tab is hidden, unlike main-thread rAF /
- * requestVideoFrameCallback / throttled setInterval. Receives the interval
- * in ms, then posts a tick forever.
+ * Interval clock for the frame sampler, in a worker because worker timers keep
+ * firing while the tab is hidden (unlike rAF / requestVideoFrameCallback /
+ * throttled setInterval). Receives the interval in ms, then posts ticks forever.
  */
 self.onmessage = (e: MessageEvent<number>) => {
 	setInterval(() => self.postMessage(0), e.data);
diff --git a/app/features/scanner/capture/vod-frames.ts b/app/features/scanner/capture/vod-frames.ts
index 564b1883f..66e8d7796 100644
--- a/app/features/scanner/capture/vod-frames.ts
+++ b/app/features/scanner/capture/vod-frames.ts
@@ -1,11 +1,9 @@
 /**
  * VoD scan entry points. The primary path probes whether WebCodecs (via
- * mediabunny) can decode the file — if so, the analyzer workers each demux
- * and decode their own time slice of it (worker/analyzer.worker.ts) and no
- * frames cross the main thread at all. When the container/codec can't be
- * read that way, the fallback seek-steps a <video> element, which handles
- * anything the browser can play at the cost of per-seek latency; its stride
- * is supplied per step so the caller can widen it over calm footage.
+ * mediabunny) can decode the file — then the analyzer workers each decode
+ * their own time slice and no frames cross the main thread. Otherwise the
+ * fallback seek-steps a <video> element (anything the browser can play, at
+ * per-seek latency); its stride is supplied per step so it can widen over calm footage.
  */
 import { ALL_FORMATS, BlobSource, Input } from "mediabunny";
 
@@ -16,9 +14,7 @@ interface VodFrame {
 	t: number;
 }
 
-/**
- * Whether mediabunny + WebCodecs can decode `file`, and its duration if so.
- */
+/** Whether mediabunny + WebCodecs can decode `file`, and its duration if so. */
 export async function probeWebCodecs(
 	file: File,
 ): Promise<{ duration: number } | null> {
@@ -40,9 +36,8 @@ export async function probeWebCodecs(
 }
 
 /**
- * Open a seek-stepping scan over `video` (which must already have the file
- * loaded; metadata is awaited here). `nextStrideS` is consulted after every
- * yielded frame, so analysis feedback can adjust the step on the fly.
+ * Opens a seek-stepping scan over `video` (file already loaded; metadata is
+ * awaited here). `nextStrideS` is consulted after every yielded frame.
  */
 export async function openSeekScan(
 	video: HTMLVideoElement,
diff --git a/app/features/scanner/components/AbilityGrid.tsx b/app/features/scanner/components/AbilityGrid.tsx
index da46d9c9e..829aefd77 100644
--- a/app/features/scanner/components/AbilityGrid.tsx
+++ b/app/features/scanner/components/AbilityGrid.tsx
@@ -1,7 +1,4 @@
-/**
- * Gear-ability grid (3 rows: head/clothes/shoes, each [main, sub, sub, sub])
- * shared by the death card and the scoreboard player popover.
- */
+/** Gear-ability grid (head/clothes/shoes rows of [main, sub, sub, sub]) shared by death card and player popover. */
 
 import { Button } from "react-aria-components";
 import { Ability } from "~/components/Ability";
@@ -33,10 +30,7 @@ export function AbilityGrid({
 	);
 }
 
-/**
- * Click-to-toggle popover showing a player's ability grid; the trigger is
- * the head-main ability icon.
- */
+/** Click-to-toggle popover showing a player's ability grid; the head-main icon is the trigger. */
 export function AbilityPopover({
 	abilities,
 }: {
diff --git a/app/features/scanner/components/EventCard.tsx b/app/features/scanner/components/EventCard.tsx
index 17249adad..475f80e2e 100644
--- a/app/features/scanner/components/EventCard.tsx
+++ b/app/features/scanner/components/EventCard.tsx
@@ -1,10 +1,9 @@
 /**
- * Single dispatch point from a detected event to its card component, shared
- * by the live feed and the VoD feed. Frames are loaded lazily through
- * `getFrame` (IndexedDB keeps them out of the listed records); the Inspect
- * action (open the frame in the screenshot page in a new browser tab, so
- * the running scan is left undisturbed) is derived from it here so pages
- * don't duplicate the wiring.
+ * Single dispatch point from a detected event to its card, shared by the live
+ * and VoD feeds. Frames load lazily through `getFrame` (IndexedDB keeps them
+ * out of the listed records); the Inspect action (open the frame in the
+ * screenshot page in a new tab, leaving the running scan undisturbed) is
+ * derived from it here.
  */
 
 import clsx from "clsx";
diff --git a/app/features/scanner/components/EventsSummary.tsx b/app/features/scanner/components/EventsSummary.tsx
index 9496df694..0478c13b6 100644
--- a/app/features/scanner/components/EventsSummary.tsx
+++ b/app/features/scanner/components/EventsSummary.tsx
@@ -1,8 +1,6 @@
 /**
- * One light line summarizing raw detections as per-type counts, with a
- * toggle for their event card feed. Callers pass only events not covered
- * by a match card — a fallback for detections not yet grouped, hidden
- * entirely once everything lives in a match.
+ * One light line summarizing raw detections as per-type counts, with a toggle
+ * for their card feed. Callers pass only events not covered by a match card.
  */
 
 import * as R from "remeda";
diff --git a/app/features/scanner/components/FrameThumb.tsx b/app/features/scanner/components/FrameThumb.tsx
index 6d1e3baac..aba4fa96d 100644
--- a/app/features/scanner/components/FrameThumb.tsx
+++ b/app/features/scanner/components/FrameThumb.tsx
@@ -1,8 +1,7 @@
 /**
- * Analyzed-frame preview in an event card's meta row. Clicking it opens the
- * frame big in a dialog — the exact lossless frame once its lazy loader
- * resolves, the thumbnail as a stand-in until then. The frame actions
- * (Inspect, Save fixture) live under the dialog image.
+ * Analyzed-frame preview in an event card's meta row; clicking opens the
+ * frame big in a dialog (the exact lossless frame once its lazy loader
+ * resolves, the thumbnail until then) with the Inspect / Save fixture actions.
  */
 
 import { ExternalLink, FlaskConical } from "lucide-react";
diff --git a/app/features/scanner/components/LivePage.tsx b/app/features/scanner/components/LivePage.tsx
index 9b960ae99..812c680ae 100644
--- a/app/features/scanner/components/LivePage.tsx
+++ b/app/features/scanner/components/LivePage.tsx
@@ -65,21 +65,15 @@ import { thumbnailFromBlob } from "./thumbnail";
 const SAMPLE_FPS = 2;
 
 /**
- * A slow parse (a browsed battle-log entry, a CJK splash-tag name) can
- * occupy the worker for seconds to tens of seconds; buffering the frames
- * sampled meanwhile (analyzed late, VoD-style) keeps what happened during
- * the stall from being missed. 24 frames hold ~12s at full density; past
- * that the backlog is decimated toward even spacing over the whole stall
- * (worker/frame-queue.ts) instead of dropping its oldest frames, so a
- * results screen mid-stall survives as a few frames.
+ * A slow parse (a browsed battle-log entry, a CJK splash-tag name) can occupy
+ * the worker for seconds to tens of seconds; buffering the frames sampled
+ * meanwhile keeps the stall from being missed. 24 frames hold ~12s at full
+ * density; past that the backlog is decimated toward even spacing over the
+ * stall (worker/frame-queue.ts) so a results screen mid-stall survives.
  */
 const FRAME_QUEUE_LIMIT = 24;
 
-/**
- * How often a running capture rechecks whether a match sendou.ink could not
- * link yet is due for another attempt (the backoff itself lives in
- * sendou-ingest.ts).
- */
+/** How often a running capture rechecks unlinked matches for a retry (backoff in sendou-ingest.ts). */
 const UNLINKED_RETRY_TICK_MS = 15_000;
 
 /** The scan knows the on-screen sides only, not who is playing. */
@@ -131,9 +125,8 @@ export function LivePage({
 		Array<(built: BuiltMatch<StoredEvent>) => boolean>
 	>([]);
 
-	// every saved event asks for a refresh, ~2-3 a second during a match;
-	// requests landing while one runs coalesce into a single trailing pass so
-	// the store read + feed render never pile up on the main thread
+	// every saved event asks for a refresh, ~2-3 a second during a match; requests
+	// landing while one runs coalesce into a single trailing pass
 	const refreshStateRef = useRef({ running: false, queued: false });
 	const refreshFeed = useCallback(() => {
 		const state = refreshStateRef.current;
@@ -147,9 +140,8 @@ export function LivePage({
 				do {
 					state.queued = false;
 					const events = await listEvents();
-					// objective reads grouped into a known non-SZ match slipped past
-					// the live block (e.g. the mode read arrived after them) — delete
-					// them
+					// objective reads grouped into a known non-SZ match slipped past the live
+					// block (e.g. the mode read arrived after them) — delete them
 					const invalid = new Set(
 						invalidObjectiveEvents(buildScannerMatches(events)),
 					);
@@ -184,11 +176,7 @@ export function LivePage({
 		};
 	}, [refreshFeed]);
 
-	/**
-	 * Sends the matches `include` selects; serialized so sends never overlap.
-	 * A send requested while one is in flight runs right after it instead of
-	 * being dropped.
-	 */
+	/** Sends the matches `include` selects; serialized so sends never overlap (a send requested mid-flight runs right after). */
 	const send = async (
 		include: (built: BuiltMatch<StoredEvent>) => boolean,
 		{ manual = false } = {},
@@ -323,10 +311,9 @@ export function LivePage({
 			stopRef.current = startSampler(video, SAMPLE_FPS, (bitmap, t) => {
 				clientRef.current?.analyze(bitmap, t);
 			});
-			// a match sent the moment its scoreboard closed usually beats the
-			// players to reporting the game, so sendou.ink had nothing to link
-			// it to; give those another go while the capture runs — along with
-			// any closed match whose close-send never got attempted
+			// a match sent the moment its scoreboard closed usually beats the players to
+			// reporting it, so sendou.ink had nothing to link to; retry those while the
+			// capture runs, along with closed matches whose close-send was never attempted
 			retryTimerRef.current ??= setInterval(() => {
 				if (liveSendRef.current) {
 					void send(
@@ -480,10 +467,9 @@ export function LivePage({
 						renderMatch={(built, justFormed) => {
 							const id = built.sources[0]!.id!;
 							const skipReason = skipReasons.get(built);
-							// counter reads render as one timeline chart, not a card each --
-							// from the builder's samples, whose sides are team-stable (raw
-							// reads follow the specced player on casts); a non-SZ match's
-							// reads (objective null) are never shown
+							// counter reads render as one timeline chart, not a card each, from the
+							// builder's samples, whose sides are team-stable (raw reads follow the
+							// specced player on casts); a non-SZ match's reads (objective null) are hidden
 							const objectiveEvents = (
 								built.match.objective?.samples ?? []
 							).map((sample) => ({ t: sample.t, data: sample }));
@@ -633,10 +619,8 @@ function LiveMenu({
 
 /**
  * A closed match whose send was never attempted: a match-close send can be
- * skipped (it queues behind an in-flight send now, but a page reload also
- * loses the queue), so the retry tick flushes these. Sources sit at
- * "queued"/no status until a send marks them; sent/unlinked/failed matches
- * follow their own paths.
+ * skipped (a page reload loses the queue), so the retry tick flushes these.
+ * Sent/unlinked/failed matches follow their own paths.
  */
 function unsentClosedMatches(built: BuiltMatch<StoredEvent>): boolean {
 	return (
diff --git a/app/features/scanner/components/MatchCard.tsx b/app/features/scanner/components/MatchCard.tsx
index 49f77114e..dbe9dc617 100644
--- a/app/features/scanner/components/MatchCard.tsx
+++ b/app/features/scanner/components/MatchCard.tsx
@@ -1,8 +1,7 @@
 /**
- * Glanceable card for one ScannerMatch in the live feed: stage banner
- * background, mode + stage, score, team weapons, and the match's /ingest
- * status. Expanding the card reveals the source event cards below it,
- * so the raw per-event view stays one click away.
+ * Glanceable card for one ScannerMatch in the live feed: stage banner, mode +
+ * stage, score, team weapons and /ingest status. Expanding reveals the source
+ * event cards below it.
  */
 
 import clsx from "clsx";
@@ -39,8 +38,8 @@ const UNKNOWN_MAIN_ABILITIES: AbilityWithUnknown[] = [
 
 /**
  * Where each main sits on the half-moon under the weapon. A positive CSS
- * rotation swings the arc's downward offset to the *left*, so the angles
- * descend to read head, clothes, shoes left to right.
+ * rotation swings the arc's offset to the *left*, so angles descend to read
+ * head, clothes, shoes left to right.
  */
 const ABILITY_ARC_ANGLES = ["44deg", "0deg", "-44deg"];
 
@@ -76,10 +75,7 @@ export function MatchCard({
 	onSend?: () => void;
 	/** still being played: no closing scoreboard yet and the scan is running */
 	live?: boolean;
-	/**
-	 * the newest match, still being formulated (no result yet) — shows an
-	 * "in progress" chip in the score slot; at most one card should get this
-	 */
+	/** the newest match, still being formulated — shows an "in progress" chip; at most one card */
 	inProgress?: boolean;
 	/** set = ingestSkipReasons held the match back from /ingest */
 	skipReason?: IngestSkipReason;
@@ -243,10 +239,9 @@ function Score({
 
 /**
  * `teams` order is winner-first on a scoreboard-closed match, so it flips
- * between the games of one feed. The card instead keeps the scan's own
- * side (alpha) left and the enemy (bravo) right for every match, so the
- * scores and weapons of consecutive games line up; footage with no POV
- * seat read (casts) keeps `teams` order.
+ * between games. The card keeps the scan's own side (alpha) left and the
+ * enemy right for every match so consecutive games line up; footage with no
+ * POV seat read (casts) keeps `teams` order.
  */
 function displayOrder(match: ScannerMatch): [0 | 1, 0 | 1] {
 	return match.pov?.team === 1 ? [1, 0] : [0, 1];
@@ -259,9 +254,8 @@ function winnerClass(match: ScannerMatch, team: 0 | 1): string | undefined {
 
 /**
  * A 100 only happens on a knockout, shown the way players say it. A knockout's
- * loser gets no score of its own, so the objective counter's last read stands
- * in — parenthesized, since the scan read it off the video and may have lost
- * sight of the counter before the game ended.
+ * loser gets no score, so the objective counter's last read stands in —
+ * parenthesized, since the scan may have lost sight of the counter early.
  */
 function scoreLabel(
 	score: number | null,
@@ -322,10 +316,7 @@ function TeamWeapons({ match }: { match: ScannerMatch }) {
 	);
 }
 
-/**
- * The three gear mains of a build, or null when the scan read none of them —
- * a partially read build keeps its unknown slots.
- */
+/** The three gear mains of a build, or null when none were read; partial builds keep unknown slots. */
 function mainAbilities(
 	player: ScannerMatchPlayer,
 ): AbilityWithUnknown[] | null {
diff --git a/app/features/scanner/components/MatchLobbyTabs.tsx b/app/features/scanner/components/MatchLobbyTabs.tsx
index d2053e15c..a60a5d12b 100644
--- a/app/features/scanner/components/MatchLobbyTabs.tsx
+++ b/app/features/scanner/components/MatchLobbyTabs.tsx
@@ -1,9 +1,7 @@
 /**
- * Lobby tabs over the match feed: private battles (the games /ingest cares
- * about) split from X Battles and everything else, so a scan that picked up
- * ranked play between tournament sets stays readable. Sets are a private
- * battle concept — consecutive games between the same two teams — so only
- * that tab gets set dividers, and set numbers are assigned within the tab.
+ * Lobby tabs over the match feed: private battles (what /ingest cares about)
+ * split from X Battles and everything else. Sets are a private battle concept,
+ * so only that tab gets set dividers, numbered within the tab.
  */
 
 import { Fragment, useEffect, useRef } from "react";
@@ -84,10 +82,9 @@ function lobbyGroup(lobby: ScannerLobby | null): LobbyGroup {
 }
 
 /**
- * Keys of the matches that showed up since the previous render — the ones a
- * scan just formed. A list arriving whole (the live feed loaded from storage,
- * a saved VoD opened) is not "just formed": every card would animate in at
- * once for something the user did not watch happen.
+ * Keys of the matches that showed up since the previous render. A list
+ * arriving whole (feed loaded from storage, a saved VoD opened) is not "just
+ * formed": every card would animate in for something the user did not watch.
  */
 function useJustFormedKeys(keys: React.Key[]): ReadonlySet<React.Key> {
 	const seenRef = useRef<Set<React.Key> | null>(null);
diff --git a/app/features/scanner/components/MetaChips.tsx b/app/features/scanner/components/MetaChips.tsx
index 17a06bf46..0354755a3 100644
--- a/app/features/scanner/components/MetaChips.tsx
+++ b/app/features/scanner/components/MetaChips.tsx
@@ -1,7 +1,6 @@
 /**
- * The pill group every event card's meta row opens with: video timestamp,
- * detection confidence and the event type, kept tight together so the free-form
- * detail text that follows reads as a separate group.
+ * The pill group every event card's meta row opens with (video timestamp,
+ * confidence, event type), kept tight so the detail text after reads as its own group.
  */
 
 import { Clock, Gauge } from "lucide-react";
diff --git a/app/features/scanner/components/ScannerChrome.tsx b/app/features/scanner/components/ScannerChrome.tsx
index 9f2c3a9c2..eb3db91ab 100644
--- a/app/features/scanner/components/ScannerChrome.tsx
+++ b/app/features/scanner/components/ScannerChrome.tsx
@@ -1,7 +1,6 @@
 /**
- * Page chrome shared by the scanner's live, VoD and screenshot pages: the
- * controls row and its status pill, the preview/feed split and the file
- * dropzone the VoD and screenshot pages both start from.
+ * Page chrome shared by the live, VoD and screenshot pages: the controls row
+ * with its status pill, the preview/feed split and the file dropzone.
  */
 
 import clsx from "clsx";
diff --git a/app/features/scanner/components/ScreenshotPage.module.css b/app/features/scanner/components/ScreenshotPage.module.css
index 8ef78af63..5f04fdfd4 100644
--- a/app/features/scanner/components/ScreenshotPage.module.css
+++ b/app/features/scanner/components/ScreenshotPage.module.css
@@ -9,8 +9,6 @@
 	}
 }
 
-/* ---- per-detector gate results ---- */
-
 .gateList {
 	display: grid;
 	grid-template-columns: repeat(3, max-content) 1fr;
@@ -64,8 +62,6 @@
 	font-size: var(--font-2xs);
 }
 
-/* ---- fired detector's parse detail ---- */
-
 .detail {
 	display: flex;
 	flex-direction: column;
@@ -167,8 +163,6 @@
 	}
 }
 
-/* ---- per-row parse inspector ---- */
-
 .inspector {
 	width: 100%;
 	border-collapse: collapse;
diff --git a/app/features/scanner/components/VodPage.tsx b/app/features/scanner/components/VodPage.tsx
index 68464c319..ee17e9292 100644
--- a/app/features/scanner/components/VodPage.tsx
+++ b/app/features/scanner/components/VodPage.tsx
@@ -1,17 +1,12 @@
 /**
- * VoD tab: load a video file and scan it for scoreboard matches as fast as
- * decoding allows — no real-time playback. On the primary (WebCodecs) path
- * the file's duration is split into one contiguous slice per analyzer
- * worker and each worker demuxes, decodes, schedules and analyzes its slice
- * by itself (worker/analyzer.worker.ts): no frames cross the main thread,
- * scheduling state is exact per slice, and calm stretches are skimmed by
- * keyframe hops instead of decoded frame-by-frame. The seek fallback drives
- * a <video> element through a single worker, widening its stride over calm
- * footage. Each match can be opened in the screenshot page with the exact
- * frame that was analyzed.
- *
- * Completed scans are persisted to IndexedDB keyed by file name
- * (store/vods.ts); the default view lists them for reinspection.
+ * VoD tab: load a video file and scan it as fast as decoding allows — no
+ * real-time playback. On the primary (WebCodecs) path the duration is split
+ * into one contiguous slice per analyzer worker and each worker demuxes,
+ * decodes, schedules and analyzes its slice itself (worker/analyzer.worker.ts):
+ * no frames cross the main thread and calm stretches are skimmed by keyframe
+ * hops. The seek fallback drives a <video> element through a single worker,
+ * widening its stride over calm footage. Completed scans are persisted to
+ * IndexedDB keyed by file name (store/vods.ts) and listed for reinspection.
  */
 import clsx from "clsx";
 import { Download, FileText, Send, Trash2, Video } from "lucide-react";
@@ -88,9 +83,8 @@ const SCANNER_TEAM_LABELS = ["Alpha", "Bravo"] as const;
 /** seek-fallback stride while the worker reports activity */
 const SEEK_ACTIVE_STRIDE_S = 0.25;
 /**
- * seek-fallback stride over calm footage (nothing detected for a while, no
- * match open) — small enough that the screens that can start activity from
- * dead air (results ~10s, match intro ~7s) still get sampled
+ * seek-fallback stride over calm footage — small enough that the screens that
+ * start activity from dead air (results ~10s, match intro ~7s) still get sampled
  */
 const SEEK_CALM_STRIDE_S = 2.5;
 
@@ -99,8 +93,8 @@ type Status = "idle" | "scanning" | "done" | "error";
 interface VodMatch {
 	event: DetectedEvent<FixtureData>;
 	/**
-	 * render identity — inherited when a better read replaces the event, so
-	 * match cards keyed on it don't remount (replaying the enter animation)
+	 * render identity, inherited when a better read replaces the event so match
+	 * cards keyed on it don't remount (replaying the enter animation)
 	 */
 	key: number;
 	thumbnail?: string;
@@ -190,9 +184,8 @@ export function VodPage({
 			!groupedEvents.has(m.event) && m.event.type !== STRIP_WEAPONS_EVENT_TYPE,
 	);
 
-	// "Send results" sends the whole scan in one go, so its outcome maps
-	// onto every ingestable card; a partial failure (some chunks sent, some
-	// not) can't be attributed per match — the bulk status text covers it
+	// "Send results" sends the whole scan in one go, so its outcome maps onto
+	// every ingestable card; a partial failure can't be attributed per match
 	const bulkSend: SendStatus | undefined =
 		resultsSend?.state === "sending"
 			? { state: "sending", at: 0 }
@@ -207,8 +200,7 @@ export function VodPage({
 	const upload =
 		status === "done" ? sendouUpload(matches.map((m) => m.event)) : null;
 
-	// "Send results" — the /ingest counterpart of live sending: the
-	// scan's ingestable ScannerMatches POSTed in one go
+	// "Send results": the scan's ingestable ScannerMatches POSTed to /ingest in one go
 	const resultsMatchCount =
 		status === "done" ? countIngestableMatches(matches.map((m) => m.event)) : 0;
 
@@ -238,8 +230,7 @@ export function VodPage({
 			links: report.links,
 		};
 		setResultsSend({ state: "done", ...outcome });
-		// the scan is saved under its file name, so its send outcome can be
-		// restored when the VoD is reopened
+		// saved under its file name so the send outcome is restored when the VoD is reopened
 		if (fileName) {
 			await saveVodResultsSend(fileName, outcome);
 			await refreshVods();
@@ -734,10 +725,9 @@ export function VodPage({
 								ingestableBuilt.indexOf(built),
 							);
 							const send = skipReason ? undefined : bulkSend;
-							// counter reads render as one timeline chart, not a card each --
-							// from the builder's samples, whose sides are team-stable (raw
-							// reads follow the specced player on casts); a non-SZ match's
-							// reads (objective null) are never shown
+							// counter reads render as one timeline chart, not a card each, from the
+							// builder's samples, whose sides are team-stable (raw reads follow the
+							// specced player on casts); a non-SZ match's reads (objective null) are hidden
 							const objectiveEvents = (
 								built.match.objective?.samples ?? []
 							).map((sample) => ({ t: sample.t, data: sample }));
diff --git a/app/features/scanner/components/dedupe-events.ts b/app/features/scanner/components/dedupe-events.ts
index f968d93a8..c08f27071 100644
--- a/app/features/scanner/components/dedupe-events.ts
+++ b/app/features/scanner/components/dedupe-events.ts
@@ -1,11 +1,9 @@
 /**
- * Display-side cleanup for a match card's source event list: a long map-open
- * can fragment into several minimap events (the timeline's merge window
- * tracks a drifting `t`, and VoD results arrive out of order), so a minimap
- * that shows nothing new versus the previous one is pure noise. Names are
- * ignored in the comparison — OCR wobbles on them while the actual content
- * (stage, weapons, ability reads) is unchanged. Stored events are untouched;
- * this only filters what gets rendered.
+ * Display-side cleanup for a match card's source events: a long map-open can
+ * fragment into several minimap events (the merge window tracks a drifting
+ * `t`, VoD results arrive out of order), so a minimap showing nothing new
+ * versus the previous one is noise. Names are ignored (OCR wobbles on them).
+ * Stored events are untouched; this only filters what is rendered.
  */
 
 import { isDeepEqual, omit } from "remeda";
diff --git a/app/features/scanner/components/events-csv.ts b/app/features/scanner/components/events-csv.ts
index 3586ff4f1..956b668b7 100644
--- a/app/features/scanner/components/events-csv.ts
+++ b/app/features/scanner/components/events-csv.ts
@@ -1,9 +1,7 @@
 /**
- * Flatten detected events into a single CSV for download. One row per event;
- * the event types share columns where they overlap (lobby/mode/stage,
- * weapon/name/abilities) and a scoreboard's eight player rows — or the
- * minimap's teammates+enemies, or the objective HUD's icon strip — are packed
- * into one cell, matching the compact per-event view of the live feed.
+ * Flattens detected events into one CSV. One row per event; types share
+ * columns where they overlap, and a scoreboard's eight player rows (or the
+ * minimap's cards, or the objective HUD's icon strip) pack into one cell.
  */
 
 import type { MainWeaponId } from "~/modules/in-game-lists/types";
diff --git a/app/features/scanner/components/fixture-export.ts b/app/features/scanner/components/fixture-export.ts
index 484af5c48..16bb24554 100644
--- a/app/features/scanner/components/fixture-export.ts
+++ b/app/features/scanner/components/fixture-export.ts
@@ -1,7 +1,6 @@
 /**
- * "Save as fixture": download the raw captured frame as PNG plus an
- * expected.json prefilled from the detector's own output, so labeling a new
- * fixture is review-and-correct instead of data entry.
+ * "Save as fixture": downloads the raw captured frame as PNG plus an
+ * expected.json prefilled from the detector's output, so labeling is review-and-correct.
  */
 
 import {
@@ -250,10 +249,7 @@ function buildExpectedJson(
 	)}\n`;
 }
 
-/**
- * expected.json alone, for a frame the user already has on disk (Screenshot
- * page). Null data produces the negative-fixture form.
- */
+/** expected.json alone, for a frame already on disk (Screenshot page). Null data = negative-fixture form. */
 export function downloadExpectedJson(
 	data: FixtureData | null,
 	eventType?: string,
@@ -266,10 +262,7 @@ export function downloadExpectedJson(
 	);
 }
 
-/**
- * Fixture export for a live detection: the stored PNG is the byte-exact
- * frame the detector analyzed, paired with that event's own parse output.
- */
+/** Fixture export for a live detection: the stored PNG is the byte-exact analyzed frame plus its parse output. */
 export function saveFixtureFromEvent(
 	frame: Blob,
 	data: FixtureData,
diff --git a/app/features/scanner/components/format.ts b/app/features/scanner/components/format.ts
index 0c5a23699..f991969f1 100644
--- a/app/features/scanner/components/format.ts
+++ b/app/features/scanner/components/format.ts
@@ -15,19 +15,13 @@ export function formatClock(seconds: number): string {
 	return `${m}:${String(s).padStart(2, "0")}`;
 }
 
-/**
- * Locale-aware time-of-day formatter for detection timestamps (epoch ms)
- * shown in scanner cards, in place of a raw `toLocaleTimeString()` call.
- */
+/** Locale-aware time-of-day formatter for detection timestamps (epoch ms). */
 export function useEventTimeFormatter(): (ms: number) => string {
 	const { formatter } = useDateTimeFormat({ timeStyle: "medium" });
 	return (ms: number) => formatter.format(new Date(ms));
 }
 
-/**
- * Locale-aware date+time formatter for absolute timestamps (epoch ms), e.g.
- * a saved VoD's scan time, in place of a raw `toLocaleString()` call.
- */
+/** Locale-aware date+time formatter for absolute timestamps (epoch ms), e.g. a VoD's scan time. */
 export function useEventDateTimeFormatter(): (ms: number) => string {
 	const { formatter } = useDateTimeFormat({
 		dateStyle: "medium",
diff --git a/app/features/scanner/components/labels.ts b/app/features/scanner/components/labels.ts
index 2d0148be9..ccac5d83b 100644
--- a/app/features/scanner/components/labels.ts
+++ b/app/features/scanner/components/labels.ts
@@ -1,8 +1,7 @@
 /**
  * English display labels for the ids scanner events carry. UI-only: events and
- * detectors speak sendou ids (§ scanner-types.ts); these helpers turn them back
- * into human-readable names for cards, CSV export, and the fixture
- * exporter's informational *Label fields.
+ * detectors speak sendou ids; these turn them back into names for cards, CSV
+ * export and the fixture exporter's informational *Label fields.
  */
 
 import type {
diff --git a/app/features/scanner/components/player-status-view.ts b/app/features/scanner/components/player-status-view.ts
index 70ecfa390..a02213104 100644
--- a/app/features/scanner/components/player-status-view.ts
+++ b/app/features/scanner/components/player-status-view.ts
@@ -1,7 +1,4 @@
-/**
- * Prop derivation for rendering a ScannerMatch's status samples with the
- * shared <PlayerStatusTimeline />, used by the Live and VoD tabs.
- */
+/** Prop derivation for rendering a ScannerMatch's status samples with the shared <PlayerStatusTimeline />. */
 import type { PlayerStatusTimelineTeam } from "~/components/PlayerStatusTimeline";
 import type { ScannerMatch } from "../core/scanner-match";
 
diff --git a/app/features/scanner/components/sendou-ingest.ts b/app/features/scanner/components/sendou-ingest.ts
index 1ed445a26..55373e490 100644
--- a/app/features/scanner/components/sendou-ingest.ts
+++ b/app/features/scanner/components/sendou-ingest.ts
@@ -1,16 +1,13 @@
 /**
- * Browser client for sendou.ink's /ingest. The scanner pages run inside
- * sendou.ink itself, so requests are same-origin: the session cookie rides
- * along automatically and the logged-in user comes from the root loader
- * (useUser) instead of an identity probe. sendou.ink authenticates the
- * session user and resolves the tournament/match server-side.
- *
- * The unit of accounting is one ScannerMatch (core/match-builder.ts) —
- * every source event's IndexedDB record tracks its outcome (the `send`
- * status the feed cards display) — while the unit of transport is a request
- * of up to `MAX_MATCHES_PER_REQUEST` of them. Resends are safe: sendou.ink
- * dedupes matches by content hash, merges partials, and scoreboards
- * first-ingest-wins.
+ * Browser client for sendou.ink's /ingest. The scanner runs inside sendou.ink,
+ * so requests are same-origin: the session cookie rides along and the
+ * logged-in user comes from the root loader (useUser); the server resolves
+ * the tournament/match. The unit of accounting is one ScannerMatch
+ * (core/match-builder.ts) — every source event's IndexedDB record tracks its
+ * outcome (the `send` status the feed cards display) — while the unit of
+ * transport is a request of up to `MAX_MATCHES_PER_REQUEST`. Resends are
+ * safe: sendou.ink dedupes by content hash, merges partials, and scoreboards
+ * are first-ingest-wins.
  */
 
 import * as R from "remeda";
@@ -34,10 +31,9 @@ const INGEST_URL = "/ingest";
 const MAX_MATCHES_PER_REQUEST = 50;
 
 /**
- * How long after each unlinked send to try again. A live send usually beats
- * the players to reporting the game, so the first attempts find nothing to
- * link to; these delays cover the reporting lag without hammering. Running
- * out of them gives up — the capture ending still makes one last attempt.
+ * Retry delays after each unlinked send: a live send usually beats the players
+ * to reporting the game, so the first attempts find nothing to link to. Running
+ * out gives up — the capture ending still makes one last attempt.
  */
 const UNLINKED_RETRY_DELAYS_MS = [30_000, 2 * 60_000, 5 * 60_000];
 
@@ -54,17 +50,14 @@ export interface SendResult {
 /**
  * Builds the stored events into matches, POSTs the ingestable ones `include`
  * selects, and records the outcome on every source event's `send` status
- * (calling `onStatus` after each request's store writes so the feed can
- * refresh).
+ * (calling `onStatus` after each request's store writes).
  *
- * Matches go out as few requests as the server cap allows rather than one
- * apiece: sendou.ink resolves a whole request at once, so a request carrying
- * several matches anchors on their mode+stage sequence instead of guessing a
- * set from one match's timestamp. A live send is a single match either way;
- * catching up on a session's backlog is where it counts. One request resolves
- * to one context, so a backlog spanning two of them links the larger and
- * leaves the rest "unlinked" — the retry then carries only those, and they
- * resolve to their own context.
+ * Matches go out in as few requests as the server cap allows: sendou.ink
+ * resolves a whole request at once, so several matches anchor on their
+ * mode+stage sequence instead of one match's timestamp — this is what makes
+ * catching up on a session's backlog work. One request resolves to one
+ * context, so a backlog spanning two links the larger and leaves the rest
+ * "unlinked"; the retry carries only those, which then resolve on their own.
  */
 export async function sendMatches({
 	events,
@@ -97,10 +90,9 @@ export async function sendMatches({
 				const link = response.linkedMatches?.find(
 					(linked) => linked.matchIndex === matchIndex,
 				)?.link;
-				// stored but not linked, and sendou.ink knows which tournament or
-				// SendouQ match this is: the game is just not reported yet, so a
-				// later resend can still land it. Without a context there is nothing
-				// to wait for and the match is as done as it will get.
+				// stored but not linked while sendou.ink knows the tournament/SendouQ
+				// match: the game is just not reported yet, so a later resend can still
+				// land it. Without a context there is nothing to wait for.
 				const unlinked = !link && response.contextResolved;
 				await updateEventsSend(idsPerMatch[matchIndex]!, {
 					state: unlinked ? "unlinked" : "sent",
@@ -138,14 +130,11 @@ export interface VodResultsSendReport {
 }
 
 /**
- * One-go sender for the VoD tab's "Send results": builds a completed
- * scan's events into matches and POSTs as many per request as the server
- * cap allows — usually the whole scan in one request, so sendou.ink's
- * content-based tournament resolution sees the full match sequence (its
- * mode+stage order plus roster sides is near-unique in the user's history).
- * No per-event status bookkeeping — VoD events don't live in the live feed
- * store. Resending is safe (server-side dedupe/merge), so a partial failure
- * can simply be retried whole.
+ * One-go sender for the VoD tab's "Send results": POSTs as many matches per
+ * request as the server cap allows — usually the whole scan, so sendou.ink's
+ * content-based tournament resolution sees the full match sequence. No
+ * per-event status bookkeeping (VoD events don't live in the live feed store);
+ * resending is safe, so a partial failure is simply retried whole.
  */
 export async function sendVodResults(
 	events: readonly DetectedEvent[],
@@ -191,9 +180,9 @@ export function matchContaining(
 }
 
 /**
- * The single send status a match displays, folded from its source events:
- * an in-flight send wins, then a failure, then success, then queued. Within
- * a state the most recent change is shown.
+ * The single send status a match displays, folded from its source events: an
+ * in-flight send wins, then failure, then success, then queued; within a
+ * state the most recent change is shown.
  */
 export function aggregateSendStatus(
 	sources: readonly StoredEvent[],
@@ -223,10 +212,7 @@ export function unsentMatches(built: BuiltMatch<StoredEvent>): boolean {
 	);
 }
 
-/**
- * Match selector: matches sendou.ink stored without a game to link them to,
- * whose next attempt is due. Exhausting the backoff stops the retries.
- */
+/** Match selector: matches stored without a game to link to, whose next retry is due. */
 export function retryableUnlinkedMatches(
 	built: BuiltMatch<StoredEvent>,
 ): boolean {
@@ -267,10 +253,9 @@ async function postIngestMatches(
 }
 
 /**
- * Live sending marks events "queued" as they arrive; ones the match builder
- * later leaves out (non-private match, older than the fallback window) would
- * sit "queued" forever. Once a match boundary has passed them they can
- * never join a future match, so clear their status back to "not sent".
+ * Live sending marks events "queued" as they arrive; ones the builder later
+ * leaves out (non-private match, older than the fallback window) would sit
+ * "queued" forever, so once a match boundary has passed them clear the status.
  */
 async function clearOrphanedQueued(
 	events: readonly StoredEvent[],
diff --git a/app/features/scanner/components/sendou-upload.ts b/app/features/scanner/components/sendou-upload.ts
index 9ace0e1cf..32f800683 100644
--- a/app/features/scanner/components/sendou-upload.ts
+++ b/app/features/scanner/components/sendou-upload.ts
@@ -1,16 +1,11 @@
 /**
- * "Upload to sendou.ink" link for a fully processed VoD: the detected events
- * are built into ScannerMatches (core/match-builder.ts), projected onto the
- * slim per-match rows the `ingest` search param of sendou.ink's /vods/new
- * form carries (an `SP.json` param the search-params module compresses),
- * which prefills a new VoD from them (the user adds the YouTube
- * URL/title/date and fixes any misreads before submitting).
- *
- * The VoD type is auto-detected: footage containing the casted 8-player
- * spectator map screen is a CAST VoD; anything else leaves the form's default
- * type untouched. A match without a mode read prefills the form's SZ default,
- * flagged `modeAssumed` — the fabricated default lives here, not on
- * ScannerMatch.
+ * "Upload to sendou.ink" link for a fully processed VoD: the events are built
+ * into ScannerMatches and projected onto the slim per-match rows the `ingest`
+ * search param of /vods/new carries (an `SP.json` param), which prefills a
+ * new VoD (the user adds URL/title/date and fixes misreads). Footage with the
+ * casted 8-player spectator map screen is a CAST VoD; anything else keeps the
+ * form's default type. A match without a mode read prefills the SZ default,
+ * flagged `modeAssumed` — the fabricated default lives here, not on ScannerMatch.
  */
 import type {
 	IngestVodMatchInput,
@@ -24,10 +19,9 @@ import { buildScannerMatches } from "../core/match-builder";
 import type { ScannerMatch } from "../core/scanner-match";
 
 /**
- * GET query params ride the request line, and servers/proxies commonly cap
- * that around 8-16 KB. A VoD long enough to blow past this needs a POST
- * flow, which /vods/new doesn't offer yet — surface that instead of
- * emitting a URL the server would reject with an opaque error.
+ * Servers/proxies commonly cap the request line around 8-16 KB; a VoD long
+ * enough to blow past this needs a POST flow /vods/new doesn't offer yet, so
+ * surface that instead of emitting a URL the server rejects opaquely.
  */
 const MAX_URL_LENGTH = 8000;
 
diff --git a/app/features/scanner/core/ability-harvest.ts b/app/features/scanner/core/ability-harvest.ts
index d6e632700..fbe33a5cc 100644
--- a/app/features/scanner/core/ability-harvest.ts
+++ b/app/features/scanner/core/ability-harvest.ts
@@ -1,10 +1,8 @@
 /**
- * Connect death events to scoreboard players: a death overlay shows the
- * killer's splash-tag name, weapon, and full gear-ability grid, so every
- * death in a match reveals one enemy player's build. Deaths are attributed
- * to the next scoreboard-type event in the timeline (a match's deaths
- * always precede its results screen), and matched to a player row by name
- * and weapon id.
+ * Connects death events to scoreboard players: a death overlay shows the
+ * killer's splash-tag name, weapon and full gear-ability grid, so every death
+ * reveals one enemy build. Deaths are attributed to the next scoreboard-type
+ * event in the timeline and matched to a player row by name and weapon id.
  */
 
 import type {
@@ -36,10 +34,9 @@ interface BuildRead {
 }
 
 /**
- * Match a build read to a player row. Both signals are OCR output, so
- * neither is trusted alone unless it is unambiguous: a combined name+weapon
- * hit wins, then a unique name hit, then a unique weapon hit (two players on
- * the same weapon with a misread name stay unattributed).
+ * Matches a build read to a player row. Both signals are OCR output, so a
+ * combined name+weapon hit wins, then a unique name hit, then a unique weapon
+ * hit (two players on the same weapon with a misread name stay unattributed).
  */
 function matchPlayer(
 	players: readonly HarvestablePlayer[],
@@ -63,10 +60,7 @@ function matchPlayer(
 	return null;
 }
 
-/**
- * Harvest the builds one match's death events reveal: each death with a
- * readable ability grid is attributed to a scoreboard player row.
- */
+/** Harvests the builds a match's deaths reveal, attributed to scoreboard player rows. */
 export function harvestAbilities(
 	players: readonly HarvestablePlayer[],
 	deaths: readonly DeathData[],
@@ -80,10 +74,7 @@ export function harvestAbilities(
 	return abilities;
 }
 
-/**
- * A death as a build read: scoreboard rows carry main-weapon ids, so a
- * sub/special kill credit says nothing about which main the killer holds.
- */
+/** A death as a build read: a sub/special kill credit says nothing about the killer's main. */
 function deathRead(death: DeathData): BuildRead {
 	return {
 		name: death.name,
@@ -95,11 +86,9 @@ function deathRead(death: DeathData): BuildRead {
 }
 
 /**
- * Harvest the gear mains one side's minimap cards reveal: a card shows the
- * three mains only, and is attributed to a player row the way a death is —
- * refusing an ambiguous read rather than guessing a seat. Cards come and go
- * across a match's frames (cross-outs, absent slots), so each gear slot
- * keeps the first badge that identified it.
+ * Harvests the gear mains one side's minimap cards reveal (three mains only),
+ * attributed like a death — refusing ambiguous reads. Cards come and go across
+ * frames (cross-outs, absent slots), so each slot keeps its first badge.
  */
 export function harvestCardMains(
 	players: readonly HarvestablePlayer[],
@@ -134,9 +123,8 @@ function betterRead(
 }
 
 /**
- * For each scoreboard/replay event, harvest abilities from the death events
- * since the previous scoreboard. Keyed by event object identity; events
- * without any attributed death are absent from the result.
+ * Per scoreboard/replay event, the abilities harvested from the deaths since the
+ * previous scoreboard; keyed by event identity, absent when none attributed.
  */
 export function connectAbilities(
 	events: readonly DetectedEvent[],
diff --git a/app/features/scanner/core/canonical.ts b/app/features/scanner/core/canonical.ts
index 058302dfc..d14a44db7 100644
--- a/app/features/scanner/core/canonical.ts
+++ b/app/features/scanner/core/canonical.ts
@@ -1,8 +1,4 @@
-/**
- * Pure constants/types shared by UI and pipeline. No OpenCV dependency —
- * the main-thread bundle must not pull in the WASM module (that lives in
- * the worker).
- */
+/** Pure constants/types shared by UI and pipeline; no OpenCV dependency, so the main bundle never pulls in the WASM. */
 export const CANONICAL_WIDTH = 1920;
 export const CANONICAL_HEIGHT = 1080;
 
diff --git a/app/features/scanner/core/cv.ts b/app/features/scanner/core/cv.ts
index eece3a248..a831c0036 100644
--- a/app/features/scanner/core/cv.ts
+++ b/app/features/scanner/core/cv.ts
@@ -1,13 +1,9 @@
 /**
- * OpenCV.js singleton loader. Works in Node, browser main thread, and workers —
- * the UMD bundle embeds its WASM, so no asset paths are involved.
- *
- * Everything in core/ obtains the cv namespace through getCV(); callers must
- * await loadOpenCV() once at startup (worker bootstrap, test setup, tool entry).
- *
- * Gotcha of this build (5.0.0-release.1): `.data` and `.clone()` are broken
- * on ROI views — `view.copyTo(freshMat)` before pixel access. Views are fine
- * as inputs to cv calls.
+ * OpenCV.js singleton loader for Node, browser main thread and workers (the
+ * UMD bundle embeds its WASM). core/ obtains the namespace through getCV();
+ * callers await loadOpenCV() once at startup. Gotcha of this build
+ * (5.0.0-release.1): `.data` and `.clone()` are broken on ROI views —
+ * `view.copyTo(freshMat)` before pixel access. Views are fine as cv inputs.
  */
 import cvModule from "@techstark/opencv-js";
 
@@ -22,12 +18,10 @@ export function loadOpenCV(): Promise<CV> {
 	if (loading) return loading;
 	const attempt = (async () => {
 		// The package is patched (patches/@techstark__opencv-js…) to export
-		// { cvReadyPromise } instead of the bare ready-promise: a thenable (or
-		// default-wrapped thenable) module.exports leaks `then` through
-		// vite-node's CJS namespace proxy and crashes every Node-side import.
-		// Depending on bundler interop we see the wrapper (possibly nested
-		// under `default`) or, in bundles that took the UMD's non-CJS branch,
-		// the promise itself.
+		// { cvReadyPromise } instead of the bare ready-promise: a thenable
+		// module.exports leaks `then` through vite-node's CJS namespace proxy and
+		// crashes every Node-side import. Depending on bundler interop we see the
+		// wrapper (possibly under `default`) or, via the UMD's non-CJS branch, the promise.
 		const raw = cvModule as {
 			cvReadyPromise?: unknown;
 			default?: { cvReadyPromise?: unknown };
diff --git a/app/features/scanner/core/detectors/death/abilities.ts b/app/features/scanner/core/detectors/death/abilities.ts
index 8b5815b61..e067db393 100644
--- a/app/features/scanner/core/detectors/death/abilities.ts
+++ b/app/features/scanner/core/detectors/death/abilities.ts
@@ -1,13 +1,9 @@
 /**
- * Ability badge templates for the death-screen gear panel.
- *
- * Committed icon assets (assets/cv/abilities/) are bare icon art with
- * alpha; on screen each sits centered on a near-black circular badge
- * filling a known fraction of the slot. Templates composite the art onto a
- * black square at that fraction, then resize to the candidate badge sizes —
- * shaped like weapon templates so matchWeapon's NCC + ink-coverage scoring
- * (see weapons.ts) applies directly. Mains (⌀~68) and subs (⌀~48) use
- * different art fractions, so each role gets its own template set.
+ * Ability badge templates for the death-screen gear panel: the bare icon art
+ * (assets/cv/abilities/) is composited onto a near-black square at the on-screen
+ * art fraction and resized to candidate badge sizes, shaped like weapon templates
+ * so matchWeapon's scoring applies. Mains (⌀~68) and subs (⌀~48) use different
+ * art fractions, hence separate template sets.
  */
 import { getCV } from "../../cv";
 import type { FrameData } from "../../image";
@@ -29,10 +25,8 @@ export interface AbilityTemplates {
 }
 
 /**
- * Exported for the calibration tooling's art-ratio sweeps and for other
- * screens' badge sets (scoreboard-own builds its sizes/threshold here).
- * inkThreshold must match the one passed to matchWeapon, or the coverage
- * ratio compares mismatched ink counts.
+ * Also used by calibration art-ratio sweeps and scoreboard-own's badge set.
+ * inkThreshold must match the one passed to matchWeapon or coverage ratios mismatch.
  */
 export function buildAbilityRole(
 	icons: { id: string; image: FrameData }[],
@@ -42,8 +36,7 @@ export function buildAbilityRole(
 ): WeaponTemplate[] {
 	const cv = getCV();
 	return icons.map(({ id, image }) => {
-		// composite the icon art over the badge black, padded so the art
-		// occupies artRatio of the square (as it does of the badge on screen)
+		// pad so the art occupies artRatio of the square, as it does of the badge on screen
 		const side = Math.round(image.width / artRatio);
 		const offset = Math.floor((side - image.width) / 2);
 		const padded = new cv.Mat(
diff --git a/app/features/scanner/core/detectors/death/index.ts b/app/features/scanner/core/detectors/death/index.ts
index ad7db86e8..c58e3f0f2 100644
--- a/app/features/scanner/core/detectors/death/index.ts
+++ b/app/features/scanner/core/detectors/death/index.ts
@@ -1,15 +1,11 @@
 /**
- * DeathDetector: parses the death cam overlay — "Splatted by <weapon>!"
- * text, the killer's gear abilities (3 rows x [main, sub, sub, sub]), and
- * the killer's name from the tilted splash tag.
- *
- * Weapon reads primarily as OCR text matched against per-language message
- * templates (localized-messages.ts); the constant line doubles as a
- * parse-time confirmation (else a lookalike gate hit emits nothing). Falls
- * back to template-matching the burst weapon icon when the WIPEOUT banner
- * covers the text, then to a candidate-lattice re-rank for low-fidelity
- * captures, then to icon/text corroboration when neither is decisive alone
- * (steps 2c/2d).
+ * DeathDetector: parses the death cam overlay — "Splatted by <weapon>!" text,
+ * the killer's gear abilities (3 rows x [main, sub, sub, sub]) and the name on
+ * the tilted splash tag. Weapon reads as OCR text against per-language message
+ * templates (the constant line doubles as confirmation, else a lookalike gate
+ * hit emits nothing), falling back to the burst weapon icon (WIPEOUT banner
+ * covers the text), a candidate-lattice re-rank (low-fidelity captures), then
+ * icon/text corroboration (steps 2c/2d).
  */
 import type {
 	AbilityWithUnknown,
@@ -69,17 +65,11 @@ import {
 } from "./weapon-names";
 
 export interface DeathData {
-	/**
-	 * the killer's weapon id — a sendou main/sub/special weapon id, unique
-	 * only within its kind (`weaponType` disambiguates); null if unreadable
-	 */
+	/** sendou main/sub/special weapon id, unique only within its kind (`weaponType`); null if unreadable */
 	weaponId: MainWeaponId | SubWeaponId | SpecialWeaponId | null;
-	/** which kind of weapon got the splat; null when the weapon is unreadable */
+	/** null when the weapon is unreadable */
 	weaponType: WeaponType | null;
-	/**
-	 * killer's gear abilities, [head, clothes, shoes] rows of [main, sub...]
-	 * ability ids; rows carry as many sub entries as the gear has slots (1-3)
-	 */
+	/** [head, clothes, shoes] rows of [main, sub...]; rows carry as many subs as the gear has slots (1-3) */
 	abilities: AbilityWithUnknown[][];
 	/** killer's splash-tag name; null if unreadable */
 	name: string | null;
@@ -90,10 +80,8 @@ export const DEATH_EVENT_TYPE = "Death";
 /** The constant message line must read back at least this well to emit. */
 const LINE1_MIN_SCORE = 0.5;
 /**
- * A Latin template's constant line reading at least this well settles the
- * language and the (expensive) JA line reads are skipped. Fixture-measured:
- * Latin-language frames read their template at 0.889+, while JA frames'
- * best Latin-template score is 0.222.
+ * A Latin constant line reading this well skips the expensive JA line reads.
+ * Fixtures: Latin frames read their template at 0.889+, JA frames' best Latin score is 0.222.
  */
 const LATIN_DECISIVE_SCORE = 0.85;
 /** Snapped weapon reading below this is reported as null (kept in debug). */
@@ -101,55 +89,42 @@ const WEAPON_MIN_SCORE = 0.55;
 /** Burst-icon fallback match below this is ignored (kept in debug). */
 const BURST_ICON_MIN_SCORE = 0.52;
 /**
- * Candidate-lattice re-rank acceptance (rankByRead — its scores sit well
- * below the plain-snap scale; see text.ts). On the 720p-upscaled JP
- * frames that motivated it, correct picks score 0.25-0.47 with a margin
- * of 0.056+ over the nearest other weapon, while wrong picks margin
- * <= 0.03 — the margin, not the score, is the discriminator.
+ * Lattice re-rank acceptance (rankByRead scores sit well below plain-snap scale).
+ * On 720p-upscaled JP frames correct picks score 0.25-0.47 with margin 0.056+
+ * over the next weapon, wrong picks margin <= 0.03 — the margin discriminates.
  */
 const LATTICE_MIN_SCORE = 0.22;
 const LATTICE_MIN_MARGIN = 0.05;
 /**
- * Burst-icon corroboration: below the decisive threshold the icon alone
- * can't be trusted, but when the garbled text *independently* ranks the
- * icon's weapon at (or within EPS of) its own top, the two weak signals
- * agree out of ~350 candidates and the weapon is accepted. Floor sits at
- * the weakest corroborated fixture positive (Splat Dualies at 0.33).
+ * Burst-icon corroboration: a non-decisive icon is accepted when the garbled
+ * text independently ranks its weapon at (within EPS of) the top of ~350
+ * candidates. Floor = weakest corroborated fixture positive (Splat Dualies 0.33).
  */
 const BURST_ICON_CORROBORATE_MIN_SCORE = 0.3;
 const CORROBORATE_EPS = 0.02;
 const TAG_NAME_BIN_THRESHOLD = 160;
 /**
- * The text-color refinement band is absolute closeness (255 - distance) to
- * the estimated text color, so its threshold is tight by construction:
- * 215 keeps pixels within 40 of the text color — glyph cores — while art
- * highlights that leak past the banner-median band sit further away.
+ * Refinement band is closeness (255 - distance) to the text color: 215 keeps
+ * pixels within 40 (glyph cores) and drops art highlights that leak past the banner band.
  */
 const TAG_NAME_REFINE_BIN_THRESHOLD = 215;
 /** Don't trust a text-color estimate taken from fewer ink pixels. */
 const TAG_NAME_REFINE_MIN_INK = 200;
 /**
- * Split-banner detection: some banners paint the name band in two flat
- * hues (diagonal splits). Any single background estimate turns the other
- * half into one huge "ink" blob that border-clearing deletes together
- * with the glyphs standing on it, so when a second quantized color bin
- * both covers a real share of the band and sits far from the first, a
- * third read candidate measures distance from the *nearest* of the two.
- * The share floor keeps the text color itself (or sparse art) from being
- * mistaken for a second background, which would erase the glyphs.
+ * Split banners paint the name band in two hues; a single background estimate
+ * makes the other half one huge ink blob that border-clearing deletes along with
+ * its glyphs. A second color bin with a real share, far from the first, adds a
+ * read candidate measuring distance from the nearest hue. The share floor keeps
+ * the text color itself from counting as a background.
  */
 const TAG_SPLIT_MIN_FRACTION = 0.15;
 const TAG_SPLIT_MIN_CHANNEL_DISTANCE = 40;
 
 /**
- * The splash-tag read dominates parse cost — a CJK name OCRs against the
- * full name atlas for tens of seconds, 90%+ of a slow death parse — and
- * the same killer's tag recurs pixel-identical, both across the frames of
- * one death's parse streak and across their later kills. Reads are
- * memoized on a small downscaled signature of the leveled tag band:
- * VoD-measured mean abs diffs are ≤1 between reads of one killer's tag
- * (even across different deaths) and ≥95 between different killers, so
- * the threshold has a wide margin on both sides.
+ * The tag read dominates parse cost (a CJK name OCRs for tens of seconds) and a
+ * killer's tag recurs pixel-identical across frames and later kills, so reads
+ * are memoized on a downscaled signature of the leveled band. VoD-measured mean
+ * abs diff: ≤1 for the same killer, ≥95 between killers.
  */
 const TAG_MEMO_WIDTH = 48;
 const TAG_MEMO_HEIGHT = 12;
@@ -178,9 +153,8 @@ function isJaTemplate(t: DeathMessageTemplate): boolean {
 }
 
 /**
- * The weapon-line strings a template can show: that language's localized
- * names plus every canonical English name (localized-messages omits names
- * identical to English), wrapped in the template's constant pre/post text.
+ * Weapon-line strings a template can show: the language's localized names plus
+ * every canonical English name (identical ones are omitted from localized-messages).
  */
 const templateCandidates = new Map<DeathMessageTemplate, WeaponCandidate[]>();
 function candidatesFor(template: DeathMessageTemplate): WeaponCandidate[] {
@@ -218,8 +192,7 @@ export function createDeathDetector(
 	): GlyphSet | null => (set ? scaleGlyphSet(set, height / set.height) : null);
 
 	const weaponGlyphs = scaled(resources.deathWeaponGlyphs, WEAPON_TEXT_HEIGHT);
-	// JA glyphs match at native scale: the atlas mixes fixture crops with
-	// per-face renders already sized to the on-screen condensed text
+	// JA atlas is already sized to the on-screen condensed text, so no scaling
 	const jaGlyphs = resources.deathWeaponJaGlyphs ?? null;
 	const tagNameGlyphs = scaled(
 		resources.deathTagNameGlyphs,
@@ -366,15 +339,11 @@ export function createDeathDetector(
 	}
 
 	/**
-	 * Dominant colors of `inner`: most frequent quantized colors (5 bits/
-	 * channel), clustered by proximity (else a hue straddling a quantization
-	 * boundary under-reports, split across neighbor bins), each refined to
-	 * its per-channel median with its share of the band. A second background
-	 * estimator besides medianColor — neither wins everywhere (whole-image
-	 * medians blend distinct populations into a color nobody has; the bin
-	 * vote loses to a flat art blob out-voting a textured banner's true
-	 * color) — so both are tried and the better read kept. The runner-up
-	 * cluster feeds the split-banner candidate (see TAG_SPLIT_MIN_FRACTION).
+	 * Most frequent quantized colors (5 bits/channel), clustered by proximity so a
+	 * hue straddling a bin boundary isn't split, each refined to its median.
+	 * Second background estimator besides medianColor: neither wins everywhere
+	 * (medians blend populations; the bin vote loses to flat art blobs), so both
+	 * reads are tried. The runner-up feeds the split-banner candidate.
 	 */
 	function dominantColors(
 		inner: Mat,
@@ -435,12 +404,9 @@ export function createDeathDetector(
 	}
 
 	/**
-	 * Text-ness map: per-pixel max-channel distance from the nearest of
-	 * `colors` (one for solid banners, two hues for a split banner). Uses
-	 * distance from banner color rather than a fixed brightness/polarity
-	 * since text/banner colors vary per player (e.g. pink text on a
-	 * light-blue banner has near-zero luminance contrast). `invert` flips to
-	 * *closeness* for the text-color refinement pass.
+	 * Per-pixel max-channel distance from the nearest of `colors` (two for a split
+	 * banner). Distance rather than brightness since text/banner colors vary per
+	 * player (pink on light blue has ~zero luminance contrast). `invert` = closeness.
 	 */
 	function distanceBand(
 		inner: Mat,
@@ -467,11 +433,9 @@ export function createDeathDetector(
 	}
 
 	/**
-	 * Zero ink components touching the band border. Busy banner art also
-	 * differs from the median banner color but continues past the name
-	 * band's edges, while the name sits inside it (fixture extremes: dakuten
-	 * at y=3, descender 2px above bottom) — left in place an edge blob
-	 * merges into a glyph and corrupts the read.
+	 * Zero ink components touching the border: banner art continues past the band
+	 * edges while the name sits inside (fixture extremes: dakuten at y=3, descender
+	 * 2px above bottom), and an edge blob merged into a glyph corrupts the read.
 	 */
 	function clearBorderBlobs(band: Mat, threshold: number): void {
 		const bin = new cv.Mat();
@@ -518,11 +482,8 @@ export function createDeathDetector(
 		const confidences: number[] = [];
 
 		// 1. read both burst lines and find the language template whose constant
-		// line reads back best — a gate hit matching none is a lookalike.
-		// Latin templates read the standard line boxes with the Latin atlas;
-		// JA templates read the swapped-width JA boxes (weapon line 1 wide,
-		// constant line 2 narrow — see rois.ts) with the JA atlas, so the two
-		// scripts never compete inside one glyph set.
+		// line reads best; a gate hit matching none is a lookalike. Latin and JA
+		// templates use separate boxes (rois.ts) and atlases so the scripts never compete.
 		let line1: RecognizedText | null = null;
 		let line2: RecognizedText | null = null;
 		let jaWeaponLine: RecognizedText | null = null;
@@ -550,10 +511,7 @@ export function createDeathDetector(
 					template = t;
 				}
 			}
-			// the JA line reads cost ~2x the Latin ones (condensed-kana atlas),
-			// so they only run when no Latin template already owns the frame:
-			// measured constant-line scores separate cleanly (Latin frames read
-			// their template at 0.889+, JA frames' best Latin score is <= 0.222)
+			// JA line reads cost ~2x, so they only run when no Latin template owns the frame
 			if (jaGlyphs && line1Score < LATIN_DECISIVE_SCORE) {
 				jaWeaponLine = readLine(JA_WEAPON_LINE_ROI, jaGlyphs);
 				jaConstLine = readLine(JA_CONST_LINE_ROI, jaGlyphs);
@@ -605,11 +563,9 @@ export function createDeathDetector(
 			}
 		}
 
-		// 2b. text can be unreadable while the burst's weapon icon is intact
-		// (the WIPEOUT banner covers the weapon name line), so fall back to
-		// matching the icon against the main-weapon set at burst size. Only a
-		// decisive match is trusted: fixture positives score 0.55+ while the
-		// best off-target frame (icon displaced by a rainmaker line) hits 0.48.
+		// 2b. the WIPEOUT banner can cover the text while the burst icon stays intact:
+		// match it against the main-weapon set. Fixture positives score 0.55+, best
+		// off-target frame (icon displaced by a rainmaker line) 0.48.
 		let burstIcon: WeaponMatch | null = null;
 		if (weapon === null && burstWeapons) {
 			const crop = cropRoi(rgb, BURST_ICON_ROI);
@@ -622,11 +578,8 @@ export function createDeathDetector(
 			if (entry) accept(entry, burstIcon.score);
 		}
 
-		// 2c. low-fidelity captures (720p upscaled to canonical) garble the
-		// per-segment top-1 read enough that the plain snap stays under
-		// WEAPON_MIN_SCORE, while the correct glyphs sit at rank 2-3 of the
-		// segments' candidate lists. Re-rank through those lists (rankByRead)
-		// and accept the top weapon when it clears the field decisively.
+		// 2c. 720p-upscaled captures garble the top-1 read below WEAPON_MIN_SCORE while
+		// the correct glyphs sit at rank 2-3 per segment: re-rank through those lists
 		let latticeTop: {
 			entry: WeaponEntry;
 			score: number;
@@ -645,8 +598,7 @@ export function createDeathDetector(
 				(c) => c.text,
 			);
 			const top = latticeRanked[0]!;
-			// margin vs the nearest *other* weapon: the same weapon rides both
-			// its localized and English candidate lines
+			// margin vs the nearest *other* weapon: a weapon has both localized and English lines
 			const runner = latticeRanked.find(
 				(r) => r.entry.entry !== top.entry.entry,
 			);
@@ -663,10 +615,8 @@ export function createDeathDetector(
 			}
 		}
 
-		// 2d. neither signal is decisive alone, but if the burst icon's main
-		// weapon is also the text's best guess (plain or lattice ranking,
-		// within EPS of that ranking's top), the independent agreement is
-		// decisive together.
+		// 2d. neither signal decisive alone, but icon weapon == text's best guess
+		// (plain or lattice, within EPS of the top) is decisive together
 		if (
 			weapon === null &&
 			burstIcon &&
@@ -690,8 +640,7 @@ export function createDeathDetector(
 		}
 		if (weaponGlyphs && template) confidences.push(weaponScore);
 
-		// 3. ability grid; rows carry 1-3 sub circles (left-aligned, as many
-		// as the gear has slots), so a sub box without badge ink ends the row
+		// 3. ability grid; rows carry 1-3 left-aligned sub circles, so a sub box without badge ink ends the row
 		const abilityRows: AbilityWithUnknown[][] = [];
 		const abilityDebug: (WeaponMatch | null)[][] = [];
 		if (abilities) {
@@ -732,11 +681,9 @@ export function createDeathDetector(
 			}
 		}
 
-		// 4. splash-tag name: read against the estimated banner color, then
-		// (since busy banner art also differs from that estimate and can
-		// survive as fake glyphs) against closeness to the text color
-		// estimated from pass 1's ink; whichever reads back more confidently
-		// wins. Both background estimators (dominantColors) run the same way.
+		// 4. splash-tag name: read against the banner color, then (busy art survives
+		// that as fake glyphs) against closeness to the text color estimated from
+		// pass 1's ink; the more confident read wins. Same for each background estimator.
 		let name: string | null = null;
 		let nameConfidence = 0;
 		let nameRaw = "";
@@ -805,11 +752,9 @@ export function createDeathDetector(
 				) {
 					candidates.push([dominant, second.color]);
 				}
-				// an empty read never beats one with glyphs (an estimate landing on
-				// the text color blanks the band, and recognizeText scores a
-				// segment-less band confidence 1); near-tied confidences resolve to
-				// the longer read, since confidence is the *min* char score and
-				// erasing most of the name can still read the survivors immaculately
+				// an empty read never beats one with glyphs (a blanked band scores confidence 1);
+				// near ties go to the longer read since confidence is the *min* char score
+				// and erasing most of a name can still read the survivors immaculately
 				const NEAR_TIE = 0.03;
 				const beats = (
 					a: { parsed: { name: string; confidence: number } },
@@ -896,15 +841,11 @@ export function createDeathDetector(
 		];
 	}
 
-	// the death cam's animated background flickers the gate; after a
-	// sufficient read the 4s rearm hold stays inside the timeline's 8s
-	// Death merge window, so every parse it skips would merge anyway.
-	// sufficientConfidence sits just under the measured clean-read floor
-	// (fixtures 0.750-0.825, confirmed scan events 0.751+); the refine and
-	// stagnation overrides cap what a parse can cost when a dirty read
-	// never reaches it, and the tag memo keeps the streak's repeat parses
-	// off the expensive name read (a first-sight CJK name runs tens of
-	// seconds; repeats must not)
+	// the animated background flickers the gate; the 4s rearm hold stays inside
+	// the timeline's 8s Death merge window so every skipped parse would merge anyway.
+	// sufficientConfidence sits just under the clean-read floor (fixtures
+	// 0.750-0.825, scan events 0.751+); refine/stagnation overrides cap the cost
+	// of a dirty read that never reaches it
 	return {
 		id: "death",
 		refineIntervalS: 0.5,
diff --git a/app/features/scanner/core/detectors/death/rois.ts b/app/features/scanner/core/detectors/death/rois.ts
index c76a3afd1..164b706d1 100644
--- a/app/features/scanner/core/detectors/death/rois.ts
+++ b/app/features/scanner/core/detectors/death/rois.ts
@@ -1,15 +1,10 @@
 /**
- * ALL death-screen ROI coordinates, in canonical 1920x1080 space.
- * Calibrated against the death/ fixtures via scripts/scanner/dump-crops.ts,
- * HoughCircles measurement, and bright-row profiling.
- *
- * The death cam overlays three fixed elements on live gameplay: a dark
- * camo "splat burst" top-center (two-line "Splatted by" / "<weapon>!"
- * message); the killer's gear panel bottom-left (three gear rows, each
- * with one main-ability circle ⌀~68 plus three sub circles ⌀~48,
- * divided by dashed lines); and the killer's splash tag bottom-right,
- * tilted, name in large type. Probes sit in the overlays' opaque-dark
- * parts (everything but the tag banner sits over the live scene).
+ * Death-screen ROIs in canonical 1920x1080 space, calibrated against the death/
+ * fixtures (scripts/scanner/dump-crops.ts, HoughCircles, bright-row profiling).
+ * The overlay has three fixed elements over live gameplay: the dark camo splat
+ * burst top-center (two-line message), the killer's gear panel bottom-left
+ * (3 rows: main circle ⌀~68 + three sub circles ⌀~48) and the tilted splash tag
+ * bottom-right. Probes sit in the overlays' opaque-dark parts.
  */
 import type { Roi } from "../../canonical";
 
@@ -26,19 +21,15 @@ export const SPLAT_TEXT_BIN_THRESHOLD = 190;
 export const WEAPON_TEXT_HEIGHT = 34;
 
 /**
- * Non-Latin weaponLine=1 langs (JA: "<weapon> で" / "やられた！") swap line
- * widths: variable name gets the full-width box, the short constant line
- * gets a narrow one. Both boxes run taller than Latin: kana overshoot the
- * cap band both sides (JP line spans y=359..401 vs Latin's y=362 start).
+ * weaponLine=1 langs (JA: "<weapon> で" / "やられた！") swap line widths; boxes
+ * run taller than Latin since kana overshoot the cap band (JP y=359..401 vs 362).
  */
 export const JA_WEAPON_LINE_ROI: Roi = { x: 640, y: 354, w: 640, h: 62 };
 export const JA_CONST_LINE_ROI: Roi = { x: 790, y: 412, w: 340, h: 54 };
 
 /**
- * Killer's weapon icon, upright above the message text (~110px art;
- * specials render team-tinted, unmatched). Templates at
- * BURST_ICON_TEMPLATE_SIZES. A "Lost the Rainmaker!" style line shifts
- * the icon out of this box; the text read handles those.
+ * Killer's weapon icon above the message (~110px art; specials render
+ * team-tinted, unmatched). A "Lost the Rainmaker!" line shifts it out of the box.
  */
 export const BURST_ICON_ROI: Roi = { x: 785, y: 230, w: 190, h: 140 };
 export const BURST_ICON_TEMPLATE_SIZES = [116, 124, 132] as const;
@@ -52,10 +43,7 @@ const ABILITY_MAIN_YS = [696, 795, 887] as const;
 export const ABILITY_SUB_XS = [578, 630, 682] as const;
 const ABILITY_SUB_YS = [702, 797, 888] as const;
 
-/**
- * Search boxes around each circle; heights double as the size filter
- * (matchTemplate skips templates taller than the ROI).
- */
+/** Search boxes around each circle; heights double as the size filter (matchTemplate skips taller templates). */
 export function abilityMainRoi(row: number): Roi {
 	const cy = ABILITY_MAIN_YS[row]!;
 	return { x: ABILITY_MAIN_X - 38, y: cy - 38, w: 76, h: 76 };
@@ -71,48 +59,32 @@ export function abilitySubRoi(row: number, slot: number): Roi {
 export const ABILITY_MAIN_SIZES = [64, 68, 72] as const;
 export const ABILITY_SUB_SIZES = [44, 48, 52] as const;
 
-/**
- * Icon art diameter as fraction of circle box: mains peak 1.0, subs 0.92
- * — badges draw art nearly edge-to-edge, ring contributes ~nothing.
- */
+/** Icon art diameter as fraction of the circle box; badges draw art nearly edge-to-edge. */
 export const ABILITY_MAIN_ART_RATIO = 1.0;
 export const ABILITY_SUB_ART_RATIO = 0.92;
 
-/**
- * Ink threshold: badge near-black, icon art saturated-bright; panel is
- * slightly translucent so a bright scene can ghost through — kept above that.
- */
+/** Badge near-black, art bright; kept above what a bright scene ghosts through the translucent panel. */
 export const ABILITY_INK_THRESHOLD = 90;
 
 /**
- * A gear row carries only as many sub circles as gear slots (1-3); an
- * absent slot shows bare panel. Bright pixels (max channel >
- * ABILITY_INK_THRESHOLD) separate cases: absent measures 0, every real
- * badge measures 403+ even at the dimmest 720p capture.
+ * Rows carry 1-3 sub circles; absent slots show bare panel. Bright pixel count
+ * (max channel > ABILITY_INK_THRESHOLD): absent = 0, real badge 403+ even at dim 720p.
  */
 export const ABILITY_SLOT_MIN_INK = 200;
 
-/**
- * Splash tag name band. Tag renders tilted (baseline rises right by
- * TAG_TILT_DEG); crop TAG_NAME_OUTER, rotate level, read TAG_NAME_INNER
- * relative to the rotated crop.
- */
+/** Splash tag: crop TAG_NAME_OUTER, rotate level by TAG_TILT_DEG, read TAG_NAME_INNER in the rotated crop. */
 export const TAG_TILT_DEG = 3.0;
 export const TAG_NAME_OUTER: Roi = { x: 1130, y: 770, w: 650, h: 140 };
 /**
- * Name band inside the rotated crop. Top edge must clear kana dakuten
- * (old y=34 clipped them, misreading こ for ご); y=21 splits the title
- * line above (ends outer y=17) with margin.
+ * Top edge must clear kana dakuten (y=34 clipped them, misreading こ for ご) yet stay below the title
+ * line (ends y=17).
  */
 export const TAG_NAME_INNER: Roi = { x: 20, y: 21, w: 610, h: 87 };
 
 /** Tight cap height of the tag name text (atlas nominal height). */
 export const TAG_NAME_TEXT_HEIGHT = 46;
 
-/**
- * Gate probes: burst camo is dark left/right of the text line and below
- * the weapon line; gear panel is dark right of the sub circles.
- */
+/** Gate probes: burst camo dark around the text lines; gear panel dark right of the sub circles. */
 export const GATE_BURST_PROBES: readonly Roi[] = [
 	{ x: 750, y: 376, w: 36, h: 22 },
 	{ x: 1134, y: 376, w: 36, h: 22 },
@@ -129,11 +101,9 @@ export const GATE_TEXT_MIN_MAX = 210;
 export const GATE_TEXT_MAX_FRACTION = 0.35;
 
 /**
- * Dark probes + white text also match the scoreboard screens, so the gate
- * additionally requires bright icon art at all three main-ability centers
- * (max RGB channel, not grayscale — saturated art can be gray-dark yet
- * bright in max-channel). Death fixtures measure 244+, closest non-death
- * row 184.
+ * Dark probes + white text also match scoreboards, so the gate also needs bright
+ * art at all three main-ability centers (max RGB channel, not grayscale: saturated
+ * art can be gray-dark). Death fixtures 244+, closest non-death 184.
  */
 export function gateAbilityProbe(row: number): Roi {
 	return {
diff --git a/app/features/scanner/core/detectors/map-start/index.ts b/app/features/scanner/core/detectors/map-start/index.ts
index 2fbb18912..3b074b45d 100644
--- a/app/features/scanner/core/detectors/map-start/index.ts
+++ b/app/features/scanner/core/detectors/map-start/index.ts
@@ -1,18 +1,11 @@
 /**
- * MapStartDetector: parses the match-intro splash — the mode title on the
- * black center splat and the stage name bottom-right, both snapped to the
- * localized closed sets (core/localized.ts) and reported under canonical
- * English names.
- *
- * The mode title wraps to two lines for longer names ("Splat" / "Zones"),
- * so parse finds text lines inside MODE_BLOCK_ROI by row projection, OCRs
- * each band, and snaps the joined reading. The constant "MODE" label
- * doubles as a parse-time confirmation (else a lookalike gate hit emits
- * nothing). The splash sits on live gameplay, so bright stages leak
- * background past the text edges: the title block is masked to near-dark
- * for line finding only (raw crop OCRs better); the stage line reads its
- * min channel (drops blue-tinted water gray keeps) under several
- * binarizations, keeping the best-snapping one (see rois.ts).
+ * MapStartDetector: parses the match-intro splash — mode title on the black
+ * center splat and stage name bottom-right, snapped to the localized closed sets
+ * (core/localized.ts). The title wraps to two lines, so parse finds line bands
+ * by row projection and snaps the joined reading; the constant "MODE" label is
+ * the parse-time confirmation. Bright stages leak background past text edges:
+ * the title block is masked to near-dark for line finding only (raw crop OCRs
+ * better) and the stage line reads its min channel under several binarizations.
  */
 import type { ModeShort, StageId } from "~/modules/in-game-lists/types";
 import { getCV, type Mat, minMaxLoc } from "../../cv";
@@ -103,10 +96,9 @@ function findLineBands(binary: Mat): LineBand[] {
 			if (data[y * cols + x]! > 0) counts[y]!++;
 		}
 	}
-	// dual threshold: a band needs rows above a cutoff scaled to the
-	// strongest row (background leaking past the splat's rim puts a
-	// scene-dependent noise floor under every row), then extends over a
-	// fixed floor so antialiased glyph tops/bottoms stay inside the band
+	// dual threshold: band core scaled to the strongest row (background leak sets a
+	// scene-dependent noise floor), then extended over a fixed floor to keep
+	// antialiased glyph tops/bottoms inside
 	const core = Math.max(
 		LINE_MIN_ROW_PIXELS,
 		LINE_ROW_FRACTION * Math.max(...counts),
@@ -139,10 +131,7 @@ function findLineBands(binary: Mat): LineBand[] {
 	return merged.filter((b) => b.y1 - b.y0 >= LINE_MIN_HEIGHT);
 }
 
-/**
- * Trim a line band to its text columns (on the masked binary), so the raw
- * OCR crop excludes the background the wide block picks up at its edges.
- */
+/** Trim a line band to its text columns so the raw OCR crop excludes edge background. */
 function bandExtent(
 	binary: Mat,
 	band: LineBand,
@@ -201,9 +190,8 @@ export function createMapStartDetector(
 			whiteFraction > GATE_TEXT_MIN_FRACTION &&
 			whiteFraction < GATE_TEXT_MAX_FRACTION;
 
-		// the label-to-title gap core is solid ink on this screen: it must be
-		// near-totally dark (the scoreboards' pills aren't) and carry no bright
-		// pixels (the death burst's "Splatted by" line crosses it)
+		// label-to-title gap is solid ink here: near-totally dark (scoreboard pills
+		// aren't) with no bright pixels (death's "Splatted by" line crosses it)
 		const band = copyRoi(gray, GATE_INK_BAND);
 		const bandPixels = band.rows * band.cols;
 		const bandBright = new cv.Mat();
@@ -256,10 +244,8 @@ export function createMapStartDetector(
 		let modeReading = "";
 		if (modeGlyphs) {
 			const block = copyRoi(gray, MODE_BLOCK_ROI);
-			// find line bands on the masked block (bright background rows would
-			// merge/invent bands) but OCR the raw crop (masking clips strokes and
-			// costs accuracy); each band is trimmed to its text columns (also
-			// from the mask) since the full-width block picks up background junk
+			// find bands on the masked block (bright background merges/invents bands)
+			// but OCR the raw crop (masking clips strokes)
 			const masked = maskNearDark(block, BLOCK_MASK_RADIUS);
 			const binary = new cv.Mat();
 			cv.threshold(masked, binary, TEXT_BIN_THRESHOLD, 255, cv.THRESH_BINARY);
@@ -297,10 +283,8 @@ export function createMapStartDetector(
 			}
 		}
 
-		// 3. stage name. Backdrop is live gameplay (dark water on one stage,
-		// a bright floor on another), so no single binarization works
-		// everywhere: read the near-dark-masked crop plus the raw crop at a
-		// few rising thresholds, and keep whichever snaps best.
+		// 3. stage name over live gameplay: no single binarization works everywhere,
+		// so try the masked crop plus raw crop at rising thresholds, keep the best snap
 		let stage: StageId | null = null;
 		let stageScore = 0;
 		let stageReading = "";
@@ -337,9 +321,8 @@ export function createMapStartDetector(
 			{
 				type: MAP_START_EVENT_TYPE,
 				t,
-				// mean like every other detector: a clean mode read must survive an
-				// unreadable stage (map-start is the only mode source for VoD matches),
-				// not be zeroed by it
+				// mean, so a clean mode read survives an unreadable stage (map-start is
+				// the only mode source for VoD matches)
 				confidence: (modeScore + stageScore) / 2,
 				data: { mode, stage },
 				debug: {
@@ -354,8 +337,7 @@ export function createMapStartDetector(
 		];
 	}
 
-	// just under the measured clean-read floor (fixtures 0.795-0.864,
-	// confirmed scan events 0.854-1.0)
+	// just under the clean-read floor (fixtures 0.795-0.864, scan events 0.854-1.0)
 	return {
 		id: "map-start",
 		sufficientConfidence: 0.79,
diff --git a/app/features/scanner/core/detectors/map-start/rois.ts b/app/features/scanner/core/detectors/map-start/rois.ts
index da4ccbba2..b15edb9be 100644
--- a/app/features/scanner/core/detectors/map-start/rois.ts
+++ b/app/features/scanner/core/detectors/map-start/rois.ts
@@ -1,28 +1,18 @@
 /**
- * ALL map-start ROI coordinates, in canonical 1920x1080 space.
- * Calibrated against the map-start/ fixtures via row/column profiling.
- *
- * The match-intro splash overlays live gameplay: a black ink splat
- * top-center with the constant "MODE" label (~48px caps), the mode title
- * (~76px BlitzBold, up to two lines), and an objective subtitle; the
- * stage name bottom-right (~40px); and eight players' splash tags along
- * the left/right edges.
+ * Map-start ROIs in canonical 1920x1080 space, calibrated against the map-start/
+ * fixtures. The intro splash overlays gameplay: black splat top-center with the
+ * "MODE" label (~48px), mode title (~76px, up to two lines) and objective
+ * subtitle; stage name bottom-right (~40px); splash tags along both edges.
  */
 import type { Roi } from "../../canonical";
 
-/**
- * The constant "MODE" label (white caps centered x=960), kept tight
- * inside the label's black pill (x≈825-1110): on bright stages
- * (Mahi-Mahi) a wider crop picks up background that garbles the read.
- */
+/** "MODE" label, kept tight inside its black pill (x≈825-1110): a wider crop picks up background on bright stages. */
 export const MODE_LABEL_ROI: Roi = { x: 850, y: 268, w: 220, h: 62 };
 export const MODE_LABEL_TEXT_HEIGHT = 48;
 
 /**
- * Mode title block below the label, one or two lines (parse finds lines
- * by row projection, not fixed positions). Ends above the objective
- * subtitle (~y678); wide enough for the longest title ("Herrschaft" /
- * "Spetterzone" ~660px) — at 520 wide the German H/t clipped ("lerrschaf").
+ * Mode title block, 1-2 lines found by row projection. Ends above the objective
+ * subtitle (~y678); 680 wide fits "Herrschaft"/"Spetterzone" (~660px, clipped at 520).
  */
 export const MODE_BLOCK_ROI: Roi = { x: 620, y: 380, w: 680, h: 285 };
 export const MODE_TEXT_HEIGHT = 76;
@@ -30,9 +20,8 @@ export const MODE_TEXT_HEIGHT = 76;
 /** A block row is text when it has at least this many bright pixels... */
 export const LINE_MIN_ROW_PIXELS = 40;
 /**
- * ...and at least this fraction of the block's strongest row: background
- * leak past the splat rim sets a scene-dependent floor (Robo ROM-en's
- * bright mall merged title + junk into one 227px band without this).
+ * ...and this fraction of the strongest row: background leak sets a scene-dependent floor (Robo
+ * ROM-en merged title + junk into one band without it).
  */
 export const LINE_ROW_FRACTION = 0.25;
 /** Text rows closer than this merge into one line band. */
@@ -48,29 +37,25 @@ export const STAGE_TEXT_HEIGHT = 40;
 export const TEXT_BIN_THRESHOLD = 190;
 
 /**
- * Bright-background suppression (light stages like Mahi-Mahi: water ~200
- * gray, docks 230+): text counts only near a near-black pixel (title
- * borders splat ink, stage name has a drop shadow). Radius must exceed
- * stroke half-width or it eats glyph cores: ~12 for the title, ~6 for
- * the stage line.
+ * Bright-background suppression (Mahi-Mahi water ~200, docks 230+): text counts
+ * only near a near-black pixel (splat ink / drop shadow). Radius must exceed
+ * stroke half-width or it eats glyph cores.
  */
 export const MASK_DARK_MAX = 70;
 export const BLOCK_MASK_RADIUS = 12;
 export const STAGE_MASK_RADIUS = 6;
 /**
- * Stage line also reads the per-pixel min channel at a higher threshold
- * (blue water drops via its low red channel, white glyphs stay near 255).
- * When the mask fails on an all-bright backdrop (Robo ROM-en's mall
- * floor), parse tries the raw crop at these thresholds and keeps the best.
+ * Stage line reads the min channel at a higher threshold (blue water drops via
+ * its red channel). When the mask fails on an all-bright backdrop (Robo ROM-en),
+ * the raw crop is tried at these thresholds.
  */
 export const STAGE_BIN_THRESHOLD = 210;
 export const STAGE_RAW_BIN_THRESHOLDS: readonly number[] = [225, 235, 245];
 
 /**
- * Gate probes: splat ink flanking the "MODE" label and before the title,
- * on spots verified solid across fixtures (mean ≤8, well above ink yet
- * under the dark scoreboard pills ~51+). Flanking pair sits outside x
- * 838-1082, past the widest label text ("Kampfart", "Vechtstijl").
+ * Gate probes on splat ink flanking the label and before the title (fixture
+ * mean ≤8; scoreboard pills ~51+). Flanking pair sits past the widest label
+ * text ("Kampfart", "Vechtstijl").
  */
 export const GATE_DARK_PROBES: readonly Roi[] = [
 	{ x: 780, y: 280, w: 30, h: 20 },
@@ -81,9 +66,8 @@ export const GATE_DARK_PROBES: readonly Roi[] = [
 export const GATE_DARK_MAX_MEAN = 45;
 
 /**
- * Core of the label-to-title gap is solid splat ink: near-total darkness,
- * zero bright pixels. Death's "Splatted by" line runs through here
- * (bright fraction 0.17+); scoreboard pills only reach ~0.83 dark.
+ * Label-to-title gap is solid ink; death's "Splatted by" line crosses it (bright 0.17+), scoreboard
+ * pills only ~0.83 dark.
  */
 export const GATE_INK_BAND: Roi = { x: 840, y: 350, w: 230, h: 36 };
 export const GATE_INK_BAND_MAX_BRIGHT = 0.005;
@@ -91,7 +75,6 @@ export const GATE_INK_BAND_MIN_DARK = 0.95;
 
 /** MODE_LABEL_ROI must contain near-white pixels... */
 export const GATE_TEXT_MIN_MAX = 210;
-/** ...at a text fill fraction: "MODE" fills ~0.25 of the tight ROI, while
- * stray white on the other screens stays under ~0.13. */
+/** ...at a text fill fraction: "MODE" fills ~0.25, stray white elsewhere stays under ~0.13. */
 export const GATE_TEXT_MIN_FRACTION = 0.05;
 export const GATE_TEXT_MAX_FRACTION = 0.35;
diff --git a/app/features/scanner/core/detectors/minimap/abilities.ts b/app/features/scanner/core/detectors/minimap/abilities.ts
index c4b27d5ae..1cf6c7b46 100644
--- a/app/features/scanner/core/detectors/minimap/abilities.ts
+++ b/app/features/scanner/core/detectors/minimap/abilities.ts
@@ -1,8 +1,4 @@
-/**
- * Ability badge templates at the minimap cards' badge size (⌀~44 on both
- * the own cards and the enemy panel; one role, mains only — the cards show
- * no sub-ability slots). Built via the death panel's badge compositor.
- */
+/** Ability badge templates at the minimap cards' badge size (⌀~44, mains only: cards show no subs). */
 import type { FrameData } from "../../image";
 import { buildAbilityRole } from "../death/abilities";
 import type { WeaponTemplate } from "../scoreboard/weapons";
diff --git a/app/features/scanner/core/detectors/minimap/index.ts b/app/features/scanner/core/detectors/minimap/index.ts
index f40c4adb0..3b0e6dcda 100644
--- a/app/features/scanner/core/detectors/minimap/index.ts
+++ b/app/features/scanner/core/detectors/minimap/index.ts
@@ -1,25 +1,16 @@
 /**
- * MinimapDetector: parses the in-match map overlay (opened with X) — the
- * own-team callout cards (name, main weapon, the three main-ability
- * badges), the enemy panel rows (weapon, abilities; the game shows no
- * enemy names) — plus the stage, matched from the drawn map (stage.ts).
- * The goal is the most complete read of every card/row; map control is
- * deliberately not reported.
- *
- * Two per-player screen states are reported (`dead`, `specialReady` — the
- * match builder merges them into the death/special timeline alongside the
- * icon-strip PlayerStatus reads) and steer the reads themselves:
- * - a respawning player's card is struck through with a large team-color
- *   X that covers the name and badges (own cards also lose the weapon;
- *   enemy rows keep theirs — the X spares the row's weapon icon). Reading
- *   through the X yields garbage, so an occlusion probe skips the covered
- *   fields and reports them null;
- * - a charged special swaps the card/row background for a light camo
- *   pattern; weapons are full-color icon art matched against art-cropped
- *   template sets composited for the surface actually behind them — bg-40
- *   for the translucent dark cards/rows, bg-150 for the camo (dark
- *   templates anti-correlate there) — so a corner-brightness probe picks
- *   the template set, ink threshold, and score floor per card.
+ * MinimapDetector: parses the in-match map overlay (X) — own-team callout cards
+ * (name, main weapon, three main-ability badges), enemy panel rows (weapon,
+ * abilities; no enemy names) and the stage matched from the drawn map
+ * (stage.ts). Map control is deliberately not reported. Two per-player states
+ * (`dead`, `specialReady`) feed the match builder's timeline and steer the reads:
+ * - a respawning player's card is struck through with a team-color X covering
+ *   name and badges (enemy rows keep their weapon icon); an occlusion probe
+ *   skips covered fields and reports them null;
+ * - a charged special swaps the background for light camo; weapons match
+ *   against template sets composited for the surface behind them (bg-40 dark,
+ *   bg-150 camo — dark templates anti-correlate there), so a corner-brightness
+ *   probe picks template set, ink threshold and score floor per card.
  */
 
 import type {
@@ -95,10 +86,7 @@ export interface MinimapTeammate {
 	name: string | null;
 	/** sendou main-weapon id; null when unreadable/covered */
 	weaponId: MainWeaponId | null;
-	/**
-	 * the card's three main abilities, [head, clothes, shoes] (null per
-	 * unreadable badge); empty when a respawn cross-out sits over the badges
-	 */
+	/** [head, clothes, shoes] main abilities (null per unreadable badge); empty when crossed out */
 	abilities: (AbilityWithUnknown | null)[];
 	/** struck through with the respawn cross-out at the read */
 	dead: boolean;
@@ -107,10 +95,7 @@ export interface MinimapTeammate {
 }
 
 export interface MinimapEnemy {
-	/**
-	 * the POV overlay shows no enemy names (always null there); the
-	 * spectator screen does, so spectator rows carry them
-	 */
+	/** always null on the POV overlay; the spectator screen shows enemy names */
 	name: string | null;
 	/** readable even on struck rows: the cross-out spares the weapon icon */
 	weaponId: MainWeaponId | null;
@@ -122,18 +107,11 @@ export interface MinimapEnemy {
 }
 
 export interface MinimapData {
-	/**
-	 * sendou stage id, matched from the drawn map against the planner
-	 * renders (stage.ts); null when no stage matched confidently or the
-	 * planner signatures were not loaded. The mode is not identifiable this
-	 * way (see stage.ts) and is left to the mode-bearing detectors.
-	 */
+	/** matched from the drawn map (stage.ts); null when unconfident or planner signatures not loaded */
 	stage: StageId | null;
 	/**
-	 * true when the frame is a casted stream's 8-player spectator map screen
-	 * rather than the POV overlay: the alpha (left) column is reported as
-	 * teammates (d-pad slots up/right/down/left) and the bravo (right)
-	 * column as enemy rows — with names, which this screen shows
+	 * casted 8-player spectator screen rather than the POV overlay: alpha (left)
+	 * column reported as teammates, bravo (right) as enemy rows, both with names
 	 */
 	spectator: boolean;
 	/** own-team callout cards; a slot missing from the frame is omitted */
@@ -141,10 +119,9 @@ export interface MinimapData {
 	/** enemy panel rows, top to bottom */
 	enemies: MinimapEnemy[];
 	/**
-	 * mean team-ink RGB per side sampled from the sub-weapon tiles
-	 * ([teammates/alpha, enemies/bravo]); null when too little saturated
-	 * ink. Anchors the objective counter's color-tracked sides to `teams`
-	 * order on casted footage, which never shows a results screen.
+	 * mean team-ink RGB per side from the sub-weapon tiles ([alpha, bravo]); null
+	 * on too little ink. Anchors the objective counter's sides to `teams` order on
+	 * casted footage, which never shows a results screen.
 	 */
 	teamColors: [InkRgb | null, InkRgb | null];
 }
@@ -152,11 +129,9 @@ export interface MinimapData {
 export const MINIMAP_EVENT_TYPE = "Minimap";
 
 /**
- * Timeline content guard: minimap frames inside the merge window collapse
- * only while every card/row keeps its dead/special state, so each flip a
- * map-open catches (a respawn, a special charged or spent) stays its own
- * event. Names, weapons and badges are not compared — OCR wobble on an
- * unchanged screen is still the same state.
+ * Timeline content guard: frames in the merge window collapse only while every
+ * card/row keeps its dead/special state, so each flip stays its own event.
+ * Names/weapons/badges are not compared (OCR wobble is still the same state).
  */
 export function sameMinimapStatusData(a: unknown, b: unknown): boolean {
 	const da = a as MinimapData;
@@ -179,13 +154,10 @@ export function sameMinimapStatusData(a: unknown, b: unknown): boolean {
 const ABILITY_MIN_SCORE = 0.45;
 
 /**
- * Light-camo (special-charged) probe: the dimmer of the two 8x8 top
- * corners of the weapon box, its brightness and saturation. Camo
- * backgrounds brighten both corners (140-165) and are gray-green
- * unsaturated; on a dark card at least one corner stays dark even when
- * avatar bleed or a cross-out stroke lights up the other, and a bright
- * scene bleeding through the card lights both but stays colored (see
- * SPECIAL_READY_MAX_CORNER_SATURATION).
+ * Light-camo probe: brightness and saturation of the dimmer 8x8 top corner of
+ * the weapon box. Camo brightens both corners (140-165) and is unsaturated; a
+ * dark card keeps one corner dark despite bleed or a cross-out stroke, and
+ * scene bleed lights both but stays colored.
  */
 function minTopCorner(
 	gray: Mat,
@@ -331,11 +303,8 @@ export function createMinimapDetector(
 	}
 
 	/**
-	 * Weapon icon match against the composite set for the surface behind
-	 * it: light templates on the camo surface, dark templates on a dark
-	 * card — and on a bright-bleed surface (see
-	 * WEAPON_BLEED_MIN_CORNER_MEAN) both sets, better score wins, since
-	 * neither composite matches scene bleed exactly.
+	 * Weapon match against the composite set for the surface behind it; on a
+	 * bright-bleed surface (WEAPON_BLEED_MIN_CORNER_MEAN) both sets, better wins.
 	 */
 	function matchSurfaceWeapon(
 		rgb: Mat,
@@ -378,10 +347,8 @@ export function createMinimapDetector(
 	}
 
 	/**
-	 * Near-tied weapon icons whose kits differ by sub (plain vs Custom
-	 * Dualie Squelchers): let the card/row's team-tinted sub tile break the
-	 * tie. Shape-only matching survives the tint, the camo surface, and a
-	 * cross-out stroke clipping the tile.
+	 * Near-tied icons whose kits differ by sub (plain vs Custom Dualie Squelchers):
+	 * the sub tile breaks the tie; shape-only matching survives tint, camo and cross-out.
 	 */
 	function resolveTieBySubTile(
 		rgb: Mat,
@@ -408,11 +375,7 @@ export function createMinimapDetector(
 		return best;
 	}
 
-	/**
-	 * The spectator screen's 8-card grid doesn't share the overlay's ROIs
-	 * (running the overlay parse against it reads phantom cards), so it gets
-	 * its own card loop: same fields per card, both columns carry names.
-	 */
+	/** The spectator 8-card grid has its own ROIs (the overlay parse reads phantom cards on it). */
 	function parseSpectator(
 		frame: Mat,
 		gray: Mat,
@@ -456,8 +419,7 @@ export function createMinimapDetector(
 				let weapon: WeaponMatch | null = null;
 				const badgeDebug: (WeaponMatch | null)[] = [];
 				let abilities: (AbilityWithUnknown | null)[] = [];
-				// the spectator cross-out sits clear of the weapon ROI (like
-				// overlay enemy rows), so the weapon stays readable when struck
+				// the spectator cross-out sits clear of the weapon ROI, so it stays readable when struck
 				weapon = matchSurfaceWeapon(
 					rgb,
 					layout.weapon,
@@ -686,8 +648,7 @@ export function createMinimapDetector(
 			const occluded =
 				crossFraction >= CROSS_MIN_FRACTION && crossLap >= CROSS_MIN_LAPLACIAN;
 
-			// light camo rows: pick the template variant by the weapon box's
-			// corner brightness and raise the ink threshold past that background
+			// light camo rows: pick template variant by corner brightness, raise ink threshold past it
 			const corner = minTopCorner(gray, hsv, weaponRoi);
 			const cornerMin = corner.mean;
 			const lightSurface =
@@ -769,16 +730,12 @@ export function createMinimapDetector(
 		];
 	}
 
-	// sufficientConfidence sits just under the lowest confirmed scan read
-	// (fixtures 0.746-0.800; confirmed scan events reach down to 0.699), so
-	// nearly every real overlay suppresses after one parse. Reads below it
-	// would fall back to stagnation, but a map-open's confidence keeps
-	// fluctuating upward, resetting the stagnation counter — on the live
-	// capture that ran the ~4s browser parse over and over until the worker
-	// starved the frame queue and whole match stretches were never analyzed
-	// (2026-08-23 Mincemeat: the last 95s of counter reads lost). The rearm
-	// cooldown covers the overlay's flicker the same way death's does: a
-	// gate blink otherwise clears the suppression and re-runs the parse.
+	// sufficientConfidence sits just under the lowest confirmed scan read (fixtures
+	// 0.746-0.800, scan events down to 0.699) so nearly every overlay suppresses
+	// after one parse; stagnation can't be relied on since a map-open's confidence
+	// keeps fluctuating upward, which once re-ran the ~4s parse until the worker
+	// starved the frame queue (2026-08-23 Mincemeat: last 95s of counter reads
+	// lost). The rearm cooldown covers gate flicker like death's does.
 	return {
 		id: "minimap",
 		refineIntervalS: 0.4,
diff --git a/app/features/scanner/core/detectors/minimap/rois.ts b/app/features/scanner/core/detectors/minimap/rois.ts
index 6cb02af83..4b88f3c47 100644
--- a/app/features/scanner/core/detectors/minimap/rois.ts
+++ b/app/features/scanner/core/detectors/minimap/rois.ts
@@ -1,15 +1,10 @@
 /**
- * ALL minimap ROI coordinates, in canonical 1920x1080 space. Calibrated
- * against the minimap/ fixtures via scripts/scanner/dump-crops.ts plus template
- * relocation sweeps (badges sit on an exact 48px pitch, pinning origins).
- *
- * The in-match map overlay (X) draws over gaussian-blurred gameplay: four
- * own-team cards (POV player bottom-left) and an enemy panel top-right,
- * each with weapon icon art, sub/special tiles, three ability badges
- * (⌀~44); a respawning player is struck through with a team-color X, and
- * a charged special swaps the card background for gray-green camo.
- * Constant chrome (close disc, Spawn Point pill) gates on shape since the
- * pill label is localized.
+ * Minimap ROIs in canonical 1920x1080 space, calibrated against the minimap/
+ * fixtures (dump-crops.ts plus relocation sweeps; badges sit on an exact 48px
+ * pitch). The overlay draws over blurred gameplay: four own-team cards and an
+ * enemy panel top-right, each with weapon art, sub/special tiles and three
+ * badges (⌀~44); respawning = team-color X, charged special = gray-green camo.
+ * Chrome (close disc, Spawn Point pill) gates on shape since the label is localized.
  */
 import type { Roi } from "../../canonical";
 
@@ -32,8 +27,8 @@ export interface CardLayout {
 }
 
 /**
- * Right card = left shifted +1352px (verified only on the struck fixture).
- * Self card differs: avatar leftmost, larger name inset, no d-pad.
+ * Right card = left +1352px (verified only on the struck fixture). Self card: avatar leftmost,
+ * larger name inset, no d-pad.
  */
 export const CARD_LAYOUTS: readonly CardLayout[] = [
 	{
@@ -108,10 +103,7 @@ export function badgeRoi(cx: number, cy: number): Roi {
 export const BADGE_TEMPLATE_SIZES = [38, 42, 46] as const;
 /** Badge art fills the circle like the death panel's mains. */
 export const BADGE_ART_RATIO = 1.0;
-/**
- * Badge ink threshold: near-black circles vs the enemy panel's translucent
- * pink bleed (~150-180 in corners) — a constant penalty, ranking intact.
- */
+/** Near-black circles vs the enemy panel's pink bleed (~150-180 in corners): a constant penalty, ranking intact. */
 export const MINIMAP_ABILITY_INK_THRESHOLD = 90;
 
 /** BlitzMain caps measure 28-29px on every card (self included). */
@@ -123,27 +115,20 @@ export const CROSS_SATURATION_MIN = 110;
 export const CROSS_VALUE_MIN = 110;
 export const CROSS_MIN_FRACTION = 0.08;
 /**
- * A saturated probe alone is not a cross-out: the fully-rendered POV map
- * screen draws bright team ink through the translucent cards/panel
- * (attested phantom fractions 0.61-0.65 on the Um'ami fixture with
- * everyone alive). The X stroke is crisp UI while the bleed is softened by
- * the surface — mean |Laplacian| over the probe separates them (struck
- * >=98 vs bleed <=34; the floor only gates the fraction, clean cards read
- * up to ~62 of crisp line art at fraction ~0).
+ * Saturation alone is not a cross-out: the POV map screen bleeds team ink
+ * through the cards (phantom fractions 0.61-0.65 on Um'ami, everyone alive).
+ * The X is crisp while bleed is softened: mean |Laplacian| struck >=98 vs bleed
+ * <=34 (clean cards read up to ~62 of line art at fraction ~0).
  */
 export const CROSS_MIN_LAPLACIAN = 65;
 
-/**
- * Weapon templates built with cropToArt (54px card box needs padding
- * trimmed to fit larger icons — Splatana Stamper unmatchable otherwise).
- * Dark surfaces match a bg-40 composite, special-ready camo a bg-150 one.
- */
-/**
- * Sub-tile silhouettes matched shape-only (specials.ts): survives team
- * tint/camo/cross-out, used to split near-tied main-weapon icons.
- */
+/** Sub-tile silhouettes matched shape-only (specials.ts) to split near-tied main-weapon icons. */
 export const SUB_TILE_TEMPLATE_SIZES = [24, 27, 30, 33, 36] as const;
 
+/**
+ * Weapon templates built with cropToArt (the 54px box can't fit Splatana
+ * Stamper's padding). Dark surfaces match a bg-40 composite, camo a bg-150 one.
+ */
 export const CARD_WEAPON_BACKGROUND = 40;
 export const SPECIAL_READY_BACKGROUND = 150;
 export const MINIMAP_WEAPON_TEMPLATE_SIZES = [
@@ -152,47 +137,33 @@ export const MINIMAP_WEAPON_TEMPLATE_SIZES = [
 export const MINIMAP_WEAPON_INK_THRESHOLD = CARD_WEAPON_BACKGROUND + 50;
 export const SPECIAL_READY_INK_THRESHOLD = SPECIAL_READY_BACKGROUND + 50;
 /**
- * Corner mean above this = special-ready camo (measures 140-165); a dark
- * card keeps at least one top corner <=90 despite avatar/cross-out bleed.
- * The fully-rendered POV map screen can push a clean card's corners past
- * the mean floor (attested 136.7 on the Um'ami fixture vs true camo
- * >=139.9), so the camo call also requires the dimmer corner to be
- * unsaturated like the gray-green camo — attested camo <=53 vs bright
- * scene bleed >=67 (the dimmer corner, because a cross-out stroke can
- * saturate the brighter one on a struck camo row). Margins are THIN on
- * both probes — re-measure before moving either.
+ * Corner mean above this = camo (140-165; dark cards keep a corner <=90). The
+ * POV map screen can push a clean card to 136.7 (Um'ami) vs true camo >=139.9,
+ * so the dimmer corner must also be unsaturated: camo <=53 vs bleed >=67 (dimmer
+ * corner because a cross-out stroke can saturate the brighter one). Margins are
+ * THIN on both probes — re-measure before moving either.
  */
 export const SPECIAL_READY_MIN_CORNER_MEAN = 120;
 export const SPECIAL_READY_MAX_CORNER_SATURATION = 60;
-/**
- * Camo surfaces score systematically lower (blob pattern depresses NCC):
- * 0.45-0.61 on correct matches vs 0.77+ on dark surfaces.
- */
+/** Camo depresses NCC: correct matches 0.45-0.61 vs 0.77+ on dark surfaces. */
 export const WEAPON_MIN_SCORE = 0.55;
 export const SPECIAL_READY_WEAPON_MIN_SCORE = 0.42;
 
 /**
- * A non-camo card whose dimmer corner still reads this bright sits on
- * scene bleed (the fully-rendered POV map screen lights the translucent
- * surfaces to ~95-137): neither composite matches such a surface exactly,
- * so both template sets are tried and the better score wins, under the
- * camo floor — bleed depresses NCC the same way (attested true matches
- * 0.55-0.66 there, and the E-liter card wins as the light set's 0.611
- * over the dark set's misranked 0.599 — THIN, re-measure before touching).
- * Dark cards (corners <=77 attested) keep the plain dark match.
+ * A non-camo card this bright sits on scene bleed (POV map screen lights
+ * surfaces to ~95-137): both template sets are tried under the camo floor since
+ * bleed depresses NCC too (true matches 0.55-0.66; E-liter wins as light 0.611
+ * over misranked dark 0.599 — THIN, re-measure before touching). Dark cards
+ * (corners <=77) keep the plain dark match.
  */
 export const WEAPON_BLEED_MIN_CORNER_MEAN = 90;
 
-/**
- * Overlay is crisp over a blurred scene: mean |Laplacian| over the name
- * band/weapon box separates a drawn element from see-through background.
- */
+/** Overlay is crisp over a blurred scene: mean |Laplacian| separates drawn elements from background. */
 export const PRESENCE_MIN_LAPLACIAN = 8;
 
 /**
  * Close-button gate: white ✕ on a dark disc (center (110,92) ±4px). Bright
- * probes trace the crossing point + four arms, dark probes sit in the
- * cardinal gaps — a plain bright blob misses the arms and fails.
+ * probes trace crossing + arms, dark probes the cardinal gaps, so a blob fails.
  */
 export const GATE_CLOSE_X_BRIGHT: readonly Roi[] = [
 	{ x: 104, y: 88, w: 12, h: 10 },
@@ -224,11 +195,9 @@ export const GATE_DARK_MAX_MEAN = 85;
 export const GATE_BRIGHT_MIN_MAX = 210;
 
 /**
- * Spectator-variant gate: casted streams show the 8-player spectator
- * screen and often cover the overlay gate's corner chrome, so this gates
- * on the rarely-covered X jump-button disc beside the 8th card
- * (bottom-right, center (1424,712) ±4px). Measured margins: bright>=249 /
- * dark<=65 against the shared 210/85 thresholds.
+ * Spectator gate: casts often cover the overlay's corner chrome, so gate on the
+ * X jump-button disc beside the 8th card (center (1424,712) ±4px). Measured
+ * bright>=249 / dark<=65 against the shared 210/85 thresholds.
  */
 export const GATE_SPECTATOR_X_BRIGHT: readonly Roi[] = [
 	{ x: 1418, y: 706, w: 12, h: 12 },
@@ -245,10 +214,9 @@ export const GATE_SPECTATOR_X_DARK: readonly Roi[] = [
 ];
 
 /**
- * Spectator card grid: four cards per column, 120px row pitch, right =
- * left +1348px. Left column is alpha team, right is bravo (reported as
- * enemy rows). Mirrors the overlay's card layout; no struck/special-ready
- * fixture attested yet, so those probes reuse overlay thresholds untuned.
+ * Spectator grid: four cards per column, 120px pitch, right = left +1348px;
+ * left is alpha, right bravo. No struck/special-ready fixture attested yet, so
+ * those probes reuse overlay thresholds untuned.
  */
 export const SPECTATOR_SLOTS: readonly CardSlot[] = [
 	"up",
@@ -277,8 +245,5 @@ export function spectatorCardLayout(
 	};
 }
 
-/**
- * Spectator names tried at both heights, more confident read wins: blur
- * across captures moves the best fit between 29 and 30 per card.
- */
+/** Both heights tried, more confident wins: capture blur moves the best fit between 29 and 30. */
 export const SPECTATOR_NAME_TEXT_HEIGHTS = [29, 30] as const;
diff --git a/app/features/scanner/core/detectors/minimap/stage.ts b/app/features/scanner/core/detectors/minimap/stage.ts
index ace2d744d..1fa4b1dd9 100644
--- a/app/features/scanner/core/detectors/minimap/stage.ts
+++ b/app/features/scanner/core/detectors/minimap/stage.ts
@@ -1,19 +1,11 @@
 /**
- * Stage identification for the minimap overlay by matching the drawn map
- * against sendou.ink planner renders (assets/cv/planner/, one PNG per
- * stage x mode, packed as a signature atlas).
- *
- * The map is drawn sharp over blurred gameplay, so a Laplacian edge mask
- * isolates it; dropping saturated (team-ink) edges leaves a structural,
- * ink-invariant signature. Downscaling+blurring also absorbs the POV (map
- * fills screen) vs spectator (map smaller, centered) scale/offset
- * difference, letting one atlas serve both via a translation search.
- *
- * Stage separates cleanly this way (NCC leads the next stage by
- * ~0.17-0.26). Mode does NOT — the objective marker is the only per-mode
- * difference and ink-invariance strips it — so the atlas keeps all five
- * renders per stage and reports only the winning tile's stage; mode comes
- * from map-start/scoreboard header instead.
+ * Minimap stage identification against sendou.ink planner renders
+ * (assets/cv/planner/, one per stage x mode, packed as a signature atlas). The
+ * map is drawn sharp over blurred gameplay, so a Laplacian edge mask minus
+ * saturated (team-ink) edges gives an ink-invariant signature; downscale+blur
+ * absorbs the POV vs spectator scale difference so one atlas serves both via a
+ * translation search. Stage separates cleanly (NCC lead ~0.17-0.26); mode does
+ * NOT (ink-invariance strips the objective marker), so only the stage is reported.
  */
 import type { StageId } from "~/modules/in-game-lists/types";
 import { getCV, type Mat } from "../../cv";
@@ -50,10 +42,8 @@ export interface StageMatch {
 }
 
 /**
- * Ink-invariant structural signature of a canonical-normalized RGBA frame:
- * downscaled, blurred, unit-L2-normalized float mask of the non-ink render
- * edges. Shared by the build tool and the runtime matcher so the atlas and
- * the live frame are computed identically.
+ * Ink-invariant signature of a canonical RGBA frame: downscaled, blurred,
+ * unit-L2 mask of non-ink edges. Shared by the atlas build tool and the matcher.
  */
 export function plannerSignature(frame: Mat): Float32Array {
 	const cv = getCV();
@@ -145,11 +135,7 @@ function bestNcc(a: Float32Array, b: Float32Array): number {
 	return best;
 }
 
-/**
- * Identify the stage of a minimap frame's signature against the planner
- * atlas. Returns null when no stage matches confidently (score floor) or two
- * stages are too close to call (margin floor) — e.g. a stage not in the set.
- */
+/** Stage of a minimap signature; null under the score floor or when two stages are too close to call. */
 export function matchStage(
 	sig: Float32Array,
 	planners: readonly PlannerStage[],
@@ -191,11 +177,7 @@ export interface PlannerManifest {
 	keys: string[];
 }
 
-/**
- * Slice the packed signature atlas (grayscale uint8 tiles) back into
- * unit-normalized PlannerStage signatures. Mirrors loadGlyphSet's atlas
- * convention; the build tool writes the atlas + manifest.
- */
+/** Slice the packed atlas (grayscale uint8 tiles) into unit-normalized signatures; mirrors loadGlyphSet. */
 export function loadPlannerStages(
 	atlas: FrameData,
 	manifest: PlannerManifest,
diff --git a/app/features/scanner/core/detectors/objective/index.ts b/app/features/scanner/core/detectors/objective/index.ts
index 82fd5ac64..98d6b904b 100644
--- a/app/features/scanner/core/detectors/objective/index.ts
+++ b/app/features/scanner/core/detectors/objective/index.ts
@@ -1,25 +1,13 @@
 /**
- * ObjectiveDetector: parses the ranked in-match counter overlay top-center —
- * each team's count plate, the penalty pill under it, which team is in
- * control (controlling team's plate keeps its saturated team-color fill;
- * otherwise near-black fill with digits in the team's ink color — see
- * rois.ts), and the M:SS match timer above the plates.
- *
- * Digits are read as the trailing digit run (banner.ts) under several
- * channel extractions — team-color ink on a black plate needs the
- * brightest channel (dark blue ink is near-black in luminance), ink on a
- * team-color fill needs the darkest channel — every extraction is tried at
- * each threshold/size and the best-scoring read wins. A gate hit with no
- * readable count on either side emits nothing (lookalike frame).
- *
- * `ObjectiveData` is a discriminated union on `mode`; only SZ exists so
- * far. Identifying mode from the badge between the plates awaits TC/RM/CB
- * fixtures.
- *
- * Every successful counter read additionally emits a PlayerStatus event
- * (player-status.ts) parsed off the per-player icon strip of the same
- * frame — the counter parse carries the lookalike rejection for both, and
- * the shared timer value pairs the two events downstream.
+ * ObjectiveDetector: parses the ranked counter overlay top-center — count plates,
+ * penalty pills, control (the controlling plate keeps its team-color fill, the
+ * other is near-black with digits in team ink) and the M:SS timer. Digits read
+ * as the trailing digit run (banner.ts) under several channel extractions (ink
+ * on black needs the brightest channel, ink on a team fill the darkest); best
+ * read wins. No readable count on either side = lookalike, emits nothing.
+ * `ObjectiveData` is discriminated on `mode`; only SZ exists until TC/RM/CB
+ * fixtures. Each read also emits a PlayerStatus event (player-status.ts) off
+ * the same frame, paired downstream by the shared timer value.
  */
 import { getCV, type Mat, minMaxLoc } from "../../cv";
 import {
@@ -81,11 +69,7 @@ export type ObjectiveData = SplatZonesObjectiveData;
 
 export interface SplatZonesObjectiveData {
 	mode: "SZ";
-	/**
-	 * seconds shown on the match timer above the plates ("3:35" = 215);
-	 * null = unreadable. Counts down in regulation; the overtime display is
-	 * unattested so far.
-	 */
+	/** match timer seconds ("3:35" = 215); null = unreadable. Overtime display unattested so far. */
 	time: number | null;
 	/** displayed count per team, [alpha, bravo]; null = unreadable */
 	score: [number | null, number | null];
@@ -94,11 +78,9 @@ export interface SplatZonesObjectiveData {
 	/** which team currently holds the zone (team-color plate fill) */
 	control: [boolean, boolean];
 	/**
-	 * mean team-ink RGB per side, sampled off the plate (the team-color
-	 * fill while in control, the digit ink otherwise — one of the two is
-	 * always drawn in the team's color); null when too little saturated
-	 * ink was found. The stable team identity for casted footage, where
-	 * the plates follow the specced player's side instead of alpha/bravo.
+	 * mean team-ink RGB per side off the plate (fill in control, digit ink
+	 * otherwise); null on too little ink. The stable team identity on casted
+	 * footage, where plates follow the specced player's side.
 	 */
 	teamColor: [InkRgb | null, InkRgb | null];
 }
@@ -109,11 +91,9 @@ export const OBJECTIVE_EVENT_TYPE = "Objective";
 const CHECK_INTERVAL_SECONDS = 1;
 
 /**
- * Timeline content guard: consecutive counter reads merge only when they
- * show the same state, so every actual tick/penalty/control change becomes
- * its own event. `time` is deliberately not compared — the timer ticks
- * every second, so comparing it would keep any two reads from ever merging
- * — and neither is `teamColor`, whose raw pixel means jitter per frame.
+ * Timeline content guard: reads merge only with the same state so every tick/
+ * penalty/control change is its own event. `time` (ticks every second) and
+ * `teamColor` (pixel means jitter) are deliberately not compared.
  */
 export function sameObjectiveData(a: unknown, b: unknown): boolean {
 	const da = a as ObjectiveData;
@@ -142,8 +122,7 @@ export function createObjectiveDetector(
 ): Detector<ObjectiveData | PlayerStatusData | StripWeaponsData> {
 	const cv = getCV();
 	let lastStatus: { layout: PlayerStatusLayout; t: number } | undefined;
-	// primed so the very first counter read samples — short matches and
-	// single-frame runs (fixtures) get evidence too
+	// primed so the very first read samples (short matches, single-frame fixtures)
 	let readsSinceWeaponSample = STRIP_WEAPON_SAMPLE_INTERVAL;
 
 	const scoreSets: GlyphSet[] = resources.paintDigits
@@ -211,11 +190,7 @@ export function createObjectiveDetector(
 		return { pass: passed === checks.length, score: passed / checks.length };
 	}
 
-	/**
-	 * Best trailing-digit read of the band across channel extractions,
-	 * thresholds, and glyph sizes (see module header for why one pass
-	 * cannot cover both plate styles).
-	 */
+	/** Best trailing-digit read across channel extractions, thresholds and glyph sizes. */
 	function readScore(frame: Mat, gray: Mat, roi: Roi): BannerScoreRead {
 		let best: BannerScoreRead = {
 			value: null,
@@ -236,9 +211,8 @@ export function createObjectiveDetector(
 						spaceGap: Number.POSITIVE_INFINITY,
 						minCharScore: 0.3,
 					});
-					// the band holds nothing but the count, so a leading digit
-					// blurred below the extension floor voids the read instead of
-					// truncating it (see SCORE_EXTEND_MIN_CONF)
+					// the band holds only the count, so a leading digit under the
+					// extension floor voids the read instead of truncating it
 					const read = trailingDigitRun(raw, set, {
 						extendMinScore: SCORE_EXTEND_MIN_CONF,
 						rejectTruncated: true,
@@ -252,12 +226,9 @@ export function createObjectiveDetector(
 	}
 
 	/**
-	 * The match timer's M:SS over TIMER_DIGIT_ROI: white digits on the
-	 * near-black box the gate already anchored on. The colon's two dots stack
-	 * to well under the digit height floor, so a valid read is exactly three
-	 * full-height digits — the minute, then the two second digits. Each glyph
-	 * size is tried (the digits render bigger on upscaled 720p footage) and
-	 * the valid read with the most confident digits wins.
+	 * M:SS timer: the colon's dots fall under the digit height floor, so a valid
+	 * read is exactly three full-height digits. Each glyph size is tried (digits
+	 * render bigger on upscaled 720p) and the most confident valid read wins.
 	 */
 	function readTimer(gray: Mat): { value: number | null; reading: string } {
 		const band = copyRoi(gray, TIMER_DIGIT_ROI);
@@ -320,11 +291,7 @@ export function createObjectiveDetector(
 		return trailingDigitRun(raw, penaltySet);
 	}
 
-	/**
-	 * Control: the plate's fill (sampled over the probe strip) is the
-	 * saturated team-color style instead of the near-black fill shown while
-	 * not in control (see CONTROL_PLATE_MIN_SATURATION in rois.ts).
-	 */
+	/** Plate fill over the probe strip; saturated = team-color style = in control (CONTROL_PLATE_MIN_SATURATION). */
 	function plateFill(
 		frame: Mat,
 		side: 0 | 1,
@@ -365,8 +332,7 @@ export function createObjectiveDetector(
 					score.value !== null &&
 					fill.saturation >= CONTROL_PLATE_MIN_SATURATION,
 				fill,
-				// the fill while in control, the digit ink otherwise — both
-				// ROIs together always cover whichever carries the team color
+				// both ROIs together always cover whichever carries the team color
 				teamColor: meanInkColor(frame, [
 					SCORE_ROIS[side],
 					PLATE_PROBE_ROIS[side],
@@ -389,9 +355,8 @@ export function createObjectiveDetector(
 		);
 		lastStatus = { layout: playerStatus.data.layout, t };
 
-		// sampled slot-identity evidence for the strip → scoreboard-row
-		// assignment; every read would re-measure fixed identities at full
-		// template-sweep cost
+		// sampled slot-identity evidence for the strip → scoreboard-row assignment;
+		// identities are fixed so every read would re-measure at full sweep cost
 		let stripWeapons: DetectedEvent<StripWeaponsData> | null = null;
 		readsSinceWeaponSample++;
 		if (
@@ -412,9 +377,8 @@ export function createObjectiveDetector(
 			...(side.penalty?.value != null ? [side.penalty.confidence] : []),
 		]);
 		return [
-			// the icon-strip statuses ride along with every counter read: the
-			// count confirmation above is the shared lookalike rejection, and
-			// the shared timer value is what pairs the two events downstream
+			// the strip statuses ride along with every counter read; the shared
+			// timer value pairs the two events downstream
 			{
 				type: OBJECTIVE_EVENT_TYPE,
 				t,
diff --git a/app/features/scanner/core/detectors/objective/player-status.ts b/app/features/scanner/core/detectors/objective/player-status.ts
index 357d83074..0348f5065 100644
--- a/app/features/scanner/core/detectors/objective/player-status.ts
+++ b/app/features/scanner/core/detectors/objective/player-status.ts
@@ -1,27 +1,17 @@
 /**
- * PlayerStatus: the per-player state read off the eight squid/octo icons
- * flanking the match timer, emitted by the ObjectiveDetector alongside each
- * Objective read (same frame, same `time`, so callers can pair the two).
- *
- * Per slot, three pixel-class fractions decide the state (rois.ts documents
- * the calibration): an alive icon's body is saturated team ink; holding
- * special washes the body into a bright pale glow that PULSES — bright
- * frames light the shoulder probe past the glow floor, trough frames only
- * read as pale — and a splatted icon is an unsaturated grey/dark X with
- * none of the three. Three strip geometries exist, named by which side
- * sits at the packed pitch: "even", "narrow-right" (the casted spectator
- * HUD's usual arrangement — S3 POV footage draws it too) and its mirror
- * "narrow-left" (whose right column nearly coincides with even's). White
- * camera badges under the right team prove a broadcast outright, but
- * broadcasts can hide them while keeping their geometry, so a badge-less
- * frame picks whichever geometry reads more decisively (bodies far from
- * the dead threshold on either side) instead of assuming even — with two
- * positional refinements: a decisive slot-comb win proves badge-less
- * narrow-left outright, and a history-less near-tie stays with
- * narrow-right (see pickLayout). The spectator wash glow is pale, so on
- * the narrow layouts only the unsaturated glow fraction counts toward
- * ready (and against dead) — saturated backdrop leaking over a dead
- * icon's shoulder cannot fake or suppress a state.
+ * PlayerStatus: per-player state off the eight squid/octo icons flanking the
+ * timer, emitted alongside each Objective read (same frame, same `time`).
+ * Three pixel-class fractions decide a slot (calibration in rois.ts): alive =
+ * saturated team-ink body; special held = bright pale wash that PULSES (bright
+ * frames light the shoulder probe, trough frames only read pale); splatted =
+ * unsaturated grey X with none of the three. Three geometries, named by which
+ * side sits at the packed pitch: "even", "narrow-right" (usual spectator HUD;
+ * S3 POV draws it too) and "narrow-left" (right column nearly coincides with
+ * even's). Camera badges prove a broadcast, but broadcasts can hide them, so a
+ * badge-less frame picks the geometry reading more decisively, with a slot-comb
+ * win proving narrow-left and a history-less near-tie staying narrow-right
+ * (pickLayout). On narrow layouts only the unsaturated glow counts toward ready
+ * so saturated backdrop leaks cannot fake or suppress a state.
  */
 import type { Mat } from "../../cv";
 import { copyRoi, type Roi } from "../../image";
@@ -78,38 +68,26 @@ export type PlayerStatusFlags = [boolean, boolean, boolean, boolean];
 export type PlayerStatusLayout = "even" | "narrow-right" | "narrow-left";
 
 export interface PlayerStatusData {
-	/**
-	 * seconds shown on the match timer at the read, same value as the
-	 * Objective event from the same frame — the key for pairing the two
-	 */
+	/** match timer seconds, same as the paired Objective event's */
 	time: number | null;
 	/** special held per slot, [left team, right team], slots left-to-right */
 	special: [PlayerStatusFlags, PlayerStatusFlags];
 	/** splatted per slot, same arrangement */
 	dead: [PlayerStatusFlags, PlayerStatusFlags];
 	/**
-	 * which icon-strip geometry the frame showed, named by which side's
-	 * icons sit at the packed ~76px pitch ("even" = both sides at the wide
-	 * ~99px pitch). Pure geometry, never footage type: S3 first-person POV
-	 * footage draws both narrow arrangements in steady state (the
-	 * 2026-08-11 Um'ami VoD measures identical to narrow-right, the
-	 * 2026-08-22 Sendou VoD to narrow-left), so only `cast` is broadcast
-	 * evidence
+	 * strip geometry, named by which side sits at the packed ~76px pitch ("even"
+	 * = both at ~99px). Pure geometry, never footage type: S3 POV draws both
+	 * narrow arrangements (2026-08-11 Um'ami VoD = narrow-right, 2026-08-22
+	 * Sendou VoD = narrow-left), so only `cast` is broadcast evidence
 	 */
 	layout: PlayerStatusLayout;
-	/**
-	 * true when the white camera badges proved a casted spectator HUD on
-	 * this frame; null otherwise — badge absence proves nothing (broadcasts
-	 * can hide them while keeping the geometry), so this never reads false
-	 */
+	/** true when camera badges proved a cast; never false since badge absence proves nothing */
 	cast: true | null;
 }
 
 /**
- * Timeline content guard: reads merge only while every slot state matches,
- * so each death/respawn/special flip becomes its own event. `time` is not
- * compared (it ticks every second) and neither is `layout` (a camera-style
- * change with identical states is the same state).
+ * Timeline content guard: reads merge only while every slot state matches.
+ * `time` (ticks every second) and `layout` (same states = same state) are not compared.
  */
 export function samePlayerStatusData(a: unknown, b: unknown): boolean {
 	const da = a as PlayerStatusData;
@@ -134,13 +112,10 @@ interface SlotRead {
 }
 
 /**
- * Parse the icon strip of a frame the objective gate already anchored as
- * the in-match counter HUD. Callers emit the event only alongside a
- * successful Objective read — the counter parse carries the lookalike
- * rejection for both. `prevLayout` is the layout of the caller's previous
- * read (sticky: a badge-less frame only switches geometry when the other
- * layout wins the decisiveness score by a clear margin — the footage type
- * does not flip frame to frame, but a busy scene can nudge the score).
+ * Parse the icon strip of a frame the objective gate anchored; emitted only
+ * alongside a successful Objective read (its lookalike rejection covers both).
+ * `prevLayout` is sticky: a badge-less frame only switches geometry on a clear
+ * decisiveness margin, since a busy scene can nudge the score.
  */
 export function parsePlayerStatus(
 	frame: Mat,
@@ -235,16 +210,12 @@ const ALL_LAYOUTS: readonly PlayerStatusLayout[] = [
 ];
 
 /**
- * Which layouts a badge-less frame may flip to from an established one on
- * score alone. The narrow-left right column nearly coincides with even's,
- * so decisiveness cannot tell those two apart — and a wrong even pick on
- * broadcast footage self-heals (the next badge frame proves the
- * arrangement) while a wrong narrow-left pick on POV footage never would
- * (POV footage shows no badges). So on score alone narrow-left is only
- * reachable via badges or from an established narrow-right (the specced
- * POV switching teams mid-game, attested in the AREA CUP VoD's badge-less
- * overhead stretches); a fresh history-less frame may still open on
- * narrow-left through the left-column gate (see pickLayout).
+ * Layouts a badge-less frame may flip to on score alone. Decisiveness cannot
+ * tell even from narrow-left (right columns coincide); a wrong even pick on a
+ * broadcast self-heals at the next badge frame while a wrong narrow-left on POV
+ * never would, so narrow-left is only reachable via badges or from an
+ * established narrow-right (specced POV switching teams, AREA CUP VoD). A fresh
+ * frame may still open narrow-left through the left-column gate (pickLayout).
  */
 const SCORED_FLIPS: Record<PlayerStatusLayout, readonly PlayerStatusLayout[]> =
 	{
@@ -254,35 +225,22 @@ const SCORED_FLIPS: Record<PlayerStatusLayout, readonly PlayerStatusLayout[]> =
 	};
 
 /**
- * Camera badges prove a broadcast arrangement outright (each arrangement
- * has its own badge columns). Badge-less frames are NOT proven even —
- * broadcasts can hide the badges while keeping their icon geometry — so
- * the candidate geometries are scored and the one whose body reads land
- * decisively on either side of the dead threshold wins. A mispicked
- * geometry puts outer-slot boxes between icons or on backdrop, which reads
- * mid-range ink — exactly what the score punishes; boxes on featureless
- * dark backdrop still read "decisively dead" though, so a busy scene can
- * nudge a frame's score across — the sticky margin keeps a single noisy
- * frame from flipping an established layout, and SCORED_FLIPS keeps the
- * even/narrow-left false friends from ever trading places without badge
- * proof.
- *
- * Three decisions decisiveness cannot make on its own:
- * - Badge-less narrow-left (attested in the sendou-triton VoD) scores
- *   below narrow-right even on true narrow-left frames, so a decisive
- *   slot-comb win (see combContrast) overrides everything but badges —
- *   comb evidence is positional and cannot confuse the even/narrow-left
- *   false friends because only their differing left columns can produce a
- *   decisive lead.
- * - A history-less even-vs-narrow-right near-tie (busy backdrops mis-rank
- *   broadcast footage): the fresh pick stays narrow-right unless it reads
- *   under the floor or even leads decisively (STATUS_FRESH_* in rois.ts).
- * - Steady-state badge-less narrow-left POV footage over pale backdrops
- *   (the 2026-08-22 Sendou POV VoD) drowns the comb — gaps read as
- *   iconness — so a fresh narrow-left pick may also come from the left
- *   column, the only one where narrow-left and even differ, winning the
- *   per-side decisiveness outright, with a readable rival left comb as
- *   the veto (STATUS_FRESH_NARROW_LEFT_* in rois.ts).
+ * Badges prove an arrangement outright. Badge-less frames are NOT proven even,
+ * so geometries are scored by how decisively body reads land on either side of
+ * the dead threshold: a mispicked geometry puts outer boxes on backdrop, which
+ * reads mid-range ink. Featureless dark backdrop still reads "decisively dead",
+ * so the sticky margin stops one noisy frame flipping an established layout and
+ * SCORED_FLIPS keeps the even/narrow-left false friends from trading places.
+ * Three decisions decisiveness cannot make alone:
+ * - badge-less narrow-left (sendou-triton VoD) scores below narrow-right even
+ *   when true, so a decisive slot-comb win (combContrast) overrides all but
+ *   badges — positional, so only the differing left columns can lead;
+ * - a history-less even-vs-narrow-right near-tie stays narrow-right unless it
+ *   reads under the floor or even leads decisively (STATUS_FRESH_*);
+ * - badge-less narrow-left POV over pale backdrops (2026-08-22 Sendou VoD)
+ *   drowns the comb, so a fresh narrow-left pick may also come from the left
+ *   column winning decisiveness, vetoed by a readable rival left comb
+ *   (STATUS_FRESH_NARROW_LEFT_*).
  */
 function pickLayout(
 	frame: Mat,
@@ -323,13 +281,9 @@ function pickLayout(
 		return { layout: "narrow-left", scores };
 	}
 	if (prevLayout) {
-		// flips away from narrow-right additionally need positional
-		// corroboration: S3 POV footage draws that geometry, but while the
-		// POV player is dead the strip shrinks toward the timer and those
-		// transient frames spike the challenger decisiveness past the sticky
-		// margin (the 2026-08-11 POV VoD locked into narrow-left that way) —
-		// a real arrangement change moves the slot comb with it, a shrink
-		// does not
+		// flips away from narrow-right also need comb corroboration: on S3 POV the
+		// strip shrinks toward the timer while the POV player is dead, spiking the
+		// challenger past the sticky margin (2026-08-11 VoD locked into narrow-left)
 		const challengers = SCORED_FLIPS[prevLayout].filter(
 			(layout) =>
 				prevLayout !== "narrow-right" ||
@@ -388,20 +342,13 @@ function sideDecisiveness(reads: SlotRead[]): number {
 }
 
 /**
- * State from the pixel-class fractions, with a confidence scaled by the
- * distance to the nearest decision boundary (1 at twice the threshold / at
- * zero). On the narrow layouts a ready icon is always the wash, which
- * replaces the body's team ink — an ink-heavy body there means the bright
- * read is backdrop leaking past the icon edge, not a held special, unless
- * the body also reads strongly pale (the graded STATUS_READY_*WASH*
- * guards) — and the wash glow is pale, so only the
- * unsaturated glow fraction counts (a saturated bright leak, like sky over
- * a dead icon's shoulder, is not a wash — see STATUS_GLOW_MAX_SPREAD).
- * A pale backdrop can still light a DEAD icon's shoulder past the ready
- * floor (the grey X passes every ink guard), so narrow-layout ready reads
- * additionally need the wash's pale body — and for the same reason the
- * dead read there ignores the shoulder and trusts the body classes alone
- * (see STATUS_READY_MIN_WASH_BODY_PALE / STATUS_DEAD_MAX_SHOULDER_GLOW).
+ * State from the class fractions; confidence scales with distance to the
+ * nearest boundary (1 at twice the threshold / at zero). On narrow layouts the
+ * wash replaces the body's ink, so an ink-heavy body means backdrop leak unless
+ * strongly pale too (graded STATUS_READY_*WASH* guards), and only unsaturated
+ * glow counts (STATUS_GLOW_MAX_SPREAD). A pale backdrop can still light a DEAD
+ * icon's shoulder, so narrow ready reads also need the wash's pale body and the
+ * narrow dead read trusts the body classes alone.
  */
 function classifySlot(
 	bodyInk: number,
@@ -488,15 +435,10 @@ function classFractions(
 }
 
 /**
- * Slot-comb contrast per layout and side: mean iconness (ink-or-pale
- * column fraction over the strip's body band) at the layout's slot centers
- * minus the mean at its between-slot gap midpoints, maximized over a small
- * global shift. Icon bodies concentrate iconness at true centers while the
- * V-notches between kites drop it, so a rigid comb at the wrong pitch
- * cannot score all four slots at once — positional evidence orthogonal to
- * body decisiveness, strong enough to prove the badge-less narrow-left
- * arrangement (see STATUS_NARROW_LEFT_COMB_* in rois.ts) and to veto the
- * false-friend fresh narrow-left pick off its left half.
+ * Slot-comb contrast per layout and side: mean iconness (ink-or-pale column
+ * fraction) at slot centers minus at gap midpoints, maximized over a small
+ * shift. A rigid comb at the wrong pitch cannot score all four slots at once:
+ * positional evidence orthogonal to body decisiveness (STATUS_NARROW_LEFT_COMB_*).
  */
 function combScores(frame: Mat): Record<PlayerStatusLayout, [number, number]> {
 	const profiles = STATUS_COMB_SIDE_SPANS.map(([x0, x1]) =>
diff --git a/app/features/scanner/core/detectors/objective/rois.ts b/app/features/scanner/core/detectors/objective/rois.ts
index df3033ff6..e2c1f9e5d 100644
--- a/app/features/scanner/core/detectors/objective/rois.ts
+++ b/app/features/scanner/core/detectors/objective/rois.ts
@@ -1,16 +1,10 @@
 /**
- * ALL objective-counter ROI coordinates, in canonical 1920x1080 space.
- * Calibrated against the objective/ fixtures (pixel maps over the
- * top-center band). Layout is only roughly mirror-symmetric around x=960
- * (widest digit run "100" measures x816..888 left, x1039..1112 right), so
- * score/plate-probe ROIs are measured per side, not mirrored.
- *
- * One counter plate per team flanks the mode's objective badge under the
- * timer strip: small localized label line over big BlitzBold count
- * digits (~41px). The controlling team's plate fills team-color; a
- * non-controlling team (or both while neutral) is near-black with digits
- * in team ink — the fill swap, not digit values, identifies control. A
- * penalty adds a dark pill under the plate with a white "+N" (~29px).
+ * Objective-counter ROIs in canonical 1920x1080 space, calibrated against the
+ * objective/ fixtures. Layout is only roughly mirror-symmetric around x=960
+ * ("100" spans x816..888 left, x1039..1112 right), so score/plate ROIs are
+ * measured per side. Each plate: localized label over BlitzBold count digits
+ * (~41px); the controlling plate fills team-color, otherwise near-black with
+ * team-ink digits. A penalty adds a dark pill with white "+N" (~29px).
  */
 import { CANONICAL_WIDTH, type Roi } from "../../canonical";
 
@@ -19,41 +13,29 @@ function mirrorRoi(roi: Roi): Roi {
 	return { ...roi, x: CANONICAL_WIDTH - roi.x - roi.w };
 }
 
-/**
- * Count digit band inside the plate below the label line. Wide enough
- * for the full "100" run each side (x816..888 left, x1039..1112 right),
- * clear of the plate rims (edge glow against a bright scene reads as ink).
- */
+/** Count digit band, wide enough for "100" and clear of the plate rims (edge glow reads as ink). */
 export const SCORE_ROIS: readonly [Roi, Roi] = [
 	{ x: 810, y: 156, w: 90, h: 46 },
 	{ x: 1034, y: 156, w: 84, h: 46 },
 ];
 
-/**
- * Penalty "+N" band inside the pill. The pill measures x 826..920,
- * y 218..256 under the left plate; the band leaves the rounded ends out.
- */
+/** Penalty "+N" band inside the pill (x 826..920, y 218..256 left), rounded ends left out. */
 export const PENALTY_ROIS: readonly [Roi, Roi] = (() => {
 	const left: Roi = { x: 832, y: 220, w: 82, h: 36 };
 	return [left, mirrorRoi(left)];
 })();
 
 /**
- * Plate-fill probe strips inside each plate's LEFT rim, clear of the
- * widest digit run (right strip isn't mirrored since that digit run
- * reaches x1112). Both plate styles are a flat fill there (team color in
- * control, near-black otherwise), so the gate accepts flatness (std)
- * alone — fill brightness spans near-black to bright yellow.
+ * Plate-fill probes inside each plate's LEFT rim, clear of the widest digit run
+ * (not mirrored: the right run reaches x1112). Both styles are a flat fill there,
+ * so the gate accepts flatness (std) alone since brightness spans black to yellow.
  */
 export const PLATE_PROBE_ROIS: readonly [Roi, Roi] = [
 	{ x: 800, y: 162, w: 10, h: 30 },
 	{ x: 1021, y: 162, w: 10, h: 30 },
 ];
 
-/**
- * Penalty-pill presence probes at the pill's rounded ends, clear of the
- * widest "+100": translucent fill reads mid-dark and flat over any scene.
- */
+/** Pill presence probes at the rounded ends, clear of "+100": translucent fill reads mid-dark and flat. */
 export const PENALTY_PROBE_ROIS: readonly [[Roi, Roi], [Roi, Roi]] = (() => {
 	const leftPill: [Roi, Roi] = [
 		{ x: 828, y: 226, w: 8, h: 24 },
@@ -67,14 +49,10 @@ export const GATE_PLATE_MAX_STD = 30;
 export const GATE_SCORE_MIN_MAX_BRIGHTNESS = 200;
 
 /**
- * Gate anchor: the match timer above the plates — white M:SS digits in a
- * near-black box only the in-match HUD draws. In-match HUD reads <=32 on
- * each dark probe; other screens light one past this ceiling — the closest
- * lookalike is the replay-browser header, whose black stage tag reaches
- * under the side probes when the stage name is long ("Banlieue Balibot"
- * reads ~48 there). Turf War and the death cam (one centered pill) also
- * show a timer — there the plate probes and no-readable-count parse
- * confirmation carry the rejection.
+ * Gate anchor: the timer's white M:SS in a near-black box. In-match HUD reads
+ * <=32 on each dark probe; closest lookalike is the replay-browser header's
+ * stage tag ("Banlieue Balibot" ~48). Turf War and the death cam also show a
+ * timer; the plate probes and no-readable-count rejection handle those.
  */
 export const TIMER_DIGIT_ROI: Roi = { x: 908, y: 54, w: 100, h: 40 };
 export const TIMER_DARK_PROBES: readonly Roi[] = [
@@ -86,37 +64,26 @@ export const GATE_TIMER_MAX_MEAN = 40;
 export const GATE_TIMER_MIN_MAX_BRIGHTNESS = 240;
 
 /**
- * Timer's white M:SS digits measure 34px on native 1080p footage; upscaled
- * 720p captures draw them at ~40px. Every height is tried and the best
- * valid read wins — the wrong-scale set scores well under a clean read's
- * confidence. The colon's dots stack under the digit height floor at
- * either size, so a plain height filter drops the colon.
+ * Timer digits are 34px on native 1080p, ~40px on upscaled 720p; both tried,
+ * best valid read wins. The colon's dots fall under the height floor at either size.
  */
 export const TIMER_TEXT_HEIGHTS = [34, 40] as const;
 export const TIMER_BIN_THRESHOLD = 160;
 export const TIMER_DIGIT_MIN_CONF = 0.75;
 export const TIMER_DIGIT_MIN_HEIGHT_RATIO = 0.82;
 
-/**
- * Count digits measure ~40-44px across attested plates; both scaled sets
- * are tried, best trailing read wins (banner's settled/mid-pop pattern).
- */
+/** Count digits measure ~40-44px across attested plates; best trailing read wins. */
 export const SCORE_TEXT_HEIGHTS = [40, 44] as const;
 export const PENALTY_TEXT_HEIGHT = 29;
 
-/**
- * Binarization thresholds vary with plate style (team-ink ~200+ on ~45
- * black; white ~250 on team fills up to ~130 gray) — each read keeps its best.
- */
+/** Thresholds per plate style (team ink ~200+ on ~45 black; white ~250 on fills up to ~130). */
 export const SCORE_BIN_THRESHOLDS = [160, 190] as const;
 
 /**
- * Extension floor for count digits joining a run anchored by a confident
- * one: white digits on a bright control fill blur into the plate on
- * compressed cast footage, eroding a leading digit to 0.64-0.76 while its
- * neighbor still clears the main floor ("50" read as trailing "0" — the
- * Splat World Series lime plates). Noise chars on the same plates matched
- * digit templates at up to 0.66 but never alongside an anchor digit.
+ * Extension floor for digits joining a confidently anchored run: compressed
+ * cast footage erodes a leading white digit on a bright fill to 0.64-0.76 ("50"
+ * read as "0", Splat World Series lime plates); noise reached 0.66 but never
+ * alongside an anchor digit.
  */
 export const SCORE_EXTEND_MIN_CONF = 0.6;
 
@@ -125,53 +92,29 @@ export const PENALTY_BIN_THRESHOLD = 170;
 export const PENALTY_PROBE_MAX_MEAN = 165;
 export const PENALTY_PROBE_MAX_STD = 30;
 
-/**
- * Control = plate fill is team-color style (measured over the probe
- * strip): even dark inks (deep blue ~130 spread at ~50 brightness) stay
- * saturated, while a non-controlling/neutral plate is unsaturated
- * (attested fills >=112 vs <=19).
- */
+/** Control = saturated plate fill: even deep blue keeps ~130 spread; attested fills >=112 vs <=19. */
 export const CONTROL_PLATE_MIN_SATURATION = 60;
 
-// ---- player-status icon strips (the PlayerStatus event) ----
+// Player-status icon strips: eight squid/octo icons flank the timer (alive =
+// team-ink body, special held = pale wash, splatted = grey X). Three geometries
+// named by which side sits at the packed pitch: "even" draws small icons at
+// ~99px on both sides; the spectator HUD draws bigger icons (gauge digits
+// top-RIGHT, camera badges below) at per-side pitches (~98 left vs ~76 right =
+// "narrow-right"). Nothing is mirror-symmetric (even inner icons sit 108px left
+// / 130px right of center), so centers are measured per side. Spectator icons
+// ride ~20px left of their badge centers; the outer-right center sits past the
+// measured icon (~1313) because splat X's lean into inked backdrop on the left
+// while alive bodies extend right (dead <=0.16 vs alive >=0.33 at 1320).
 //
-// Eight per-player squid/octo icons flank the timer. An alive icon's body
-// is drawn in team ink; holding special washes the upper body out into a
-// bright pale glow; a splatted player's icon turns an unsaturated grey/dark
-// X'd shape. Three geometries share the band, named by which side sits at
-// the packed pitch. "even" draws small icons at a ~99px pitch on both
-// sides; the casted spectator HUD draws bigger icons (gauge digits hanging
-// over each icon's top-RIGHT and white camera-button badges below) at
-// per-side pitches — slot centers are measured per side off the fixtures;
-// no geometry is mirror-symmetric (even inner icons sit 108px left /
-// 130px right of screen center) and the spectator sides don't share a
-// pitch (~98 left vs ~76 right = "narrow-right"). Spectator icons ride
-// their badge columns ~20px left of each badge center; the outer-right
-// center sits a few px past the measured icon (~1313) because splat X's
-// there lean into inked backdrop on their left while alive bodies extend
-// right (attested dead <=0.16 vs alive >=0.33 at 1320).
-//
-// The spectator strip additionally MIRRORS its pitches when the broadcast
-// specs a player on the other team (attested mid-game in the AREA CUP
-// VoD): the narrow ~76 pitch swaps to the left column and the wide ~97
-// pitch to the right, badges and all — the "narrow-left" layout. Its
-// right column lands within a few px of the even right column, so a
-// mirrored frame scores deceptively well as even; narrow-left's own
-// geometry must be a scored candidate (and badge-probed) or the left
-// column misreads ready/dead. S3 POV footage draws the badge-less narrow
-// arrangements in steady state too (the whole 2026-08-22 Sendou POV VoD
-// measures narrow-left, both alive and death-cam frames — vs the
-// 2026-08-11 POV VoD's narrow-right), so narrow-left is also a fresh
-// badge-less pick (STATUS_FRESH_NARROW_LEFT_*) — and no geometry implies
-// a footage type; only the badges prove a broadcast (PlayerStatusData's
-// `cast`).
-//
-// Broadcasts can hide the camera badges while keeping their icon geometry
-// (attested in the AREA CUP VoD), so badge absence alone cannot pick the
-// even layout — player-status.ts scores the geometries and keeps the one
-// whose body reads sit decisively on either side of the dead threshold; a
-// mispicked layout puts outer-slot boxes between icons and flickers
-// phantom deaths on the outermost players.
+// The spectator strip MIRRORS its pitches when the broadcast specs the other
+// team (AREA CUP VoD): "narrow-left", badges and all. Its right column lands
+// within px of even's, so it must be its own scored, badge-probed candidate or
+// the left column misreads. S3 POV draws both badge-less narrow arrangements
+// in steady state (2026-08-22 Sendou VoD = narrow-left, 2026-08-11 =
+// narrow-right), so no geometry implies a footage type; only badges prove a
+// broadcast (`cast`). Broadcasts can also hide badges while keeping geometry
+// (AREA CUP VoD), so player-status.ts scores the geometries by body-read
+// decisiveness; a mispicked layout flickers phantom deaths on the outer players.
 
 /** Per-side slot center x's, slots left-to-right. */
 export const STATUS_SLOT_CENTERS_EVEN: readonly [
@@ -197,73 +140,52 @@ export const STATUS_SLOT_CENTERS_NARROW_LEFT: readonly [
 ];
 
 /**
- * Shoulder probe: the icon's upper-left body, clear of the weapon
- * silhouette (drawn center/lower), the spectator gauge digits (hanging
- * top-right) and the even layout's sub/special trinkets (bottom). The
- * special-ready glow is
- * detected here. Boxes are relative to a slot center.
+ * Shoulder probe (special-ready glow): upper-left body, clear of the weapon
+ * silhouette, spectator gauge digits (top-right) and even trinkets (bottom).
+ * Relative to a slot center.
  */
 export const STATUS_SHOULDER_BOX_EVEN = { dx: -30, y: 38, w: 24, h: 20 };
 export const STATUS_SHOULDER_BOX_NARROW = { dx: -30, y: 35, w: 24, h: 30 };
 
 /**
- * Body probe: the widest band of the icon that dodges the spectator camera
- * badges below (y>=100) and the even layout's coin trinkets (y>=95). Team ink
- * presence here separates alive icons from the grey/dark splatted ones.
- * Sized to cover most of the icon: a slimmer box left alive icons whose
- * body is largely weapon silhouette/badges reading ink 0.24 while stage
- * ink bleeding around a translucent dead icon read 0.23 (AREA CUP VoD) —
- * this footprint separates them at 0.26 vs 0.20.
+ * Body probe (team ink = alive): widest band dodging camera badges (y>=100) and
+ * even coin trinkets (y>=95). A slimmer box read alive 0.24 vs dead bleed 0.23
+ * (AREA CUP VoD); this footprint separates them at 0.26 vs 0.20.
  */
 export const STATUS_BODY_BOX_EVEN = { dx: -40, y: 40, w: 80, h: 50 };
 export const STATUS_BODY_BOX_NARROW = { dx: -40, y: 45, w: 80, h: 50 };
 
-/**
- * An ink pixel: saturated and bright enough to be team color. The value
- * floor keeps dark saturated stage backdrops (deep blue arena walls behind
- * the translucent dead icons measure v<=90) from counting as ink.
- */
+/** Ink pixel: saturated and bright; the value floor excludes dark saturated backdrops (blue walls v<=90). */
 export const STATUS_INK_MIN_SPREAD = 70;
 export const STATUS_INK_MIN_VALUE = 105;
 
 /**
- * A glow pixel of the special-ready wash. 225 splits the attested ready
- * shoulders (fractions >=0.40) from the brightest alive team color —
- * even-layout lime peaks between 215 and 225 (glow fraction 0.97 at 215,
- * 0.00 at 225).
+ * Glow pixel: 225 splits ready shoulders (>=0.40) from the brightest alive ink (even lime: 0.97 at
+ * 215, 0.00 at 225).
  */
 export const STATUS_GLOW_MIN_VALUE = 225;
 
 /**
- * Narrow-layout glow must also be UNSATURATED: the spectator wash is pale
- * even at its brightest, while backdrop leaking past an icon edge is
- * colored — bright sky over a dead icon's shoulder reads glow 0.30 raw but
- * 0.00 under this cap (sky spread >130), and the lilac/pink washes sit at
- * spread 70-90 (attested capped fractions 0.46-0.61 vs raw 0.46-0.62).
- * Even-layout ready icons light up IN team color (attested glow 0.94 fully
- * saturated), so the cap applies to the narrow layouts only, like the
- * wash-ink guard.
+ * Narrow-layout glow must be UNSATURATED: the wash is pale while backdrop leak
+ * is colored (sky over a dead shoulder: 0.30 raw, 0.00 capped, spread >130;
+ * lilac/pink washes spread 70-90, capped 0.46-0.61). Even ready icons light IN
+ * team color (glow 0.94 saturated), so narrow layouts only.
  */
 export const STATUS_GLOW_MAX_SPREAD = 90;
 
 /**
- * A pale pixel: bright but unsaturated, the ready wash across its whole
- * pulse cycle. The wash PULSES — its trough dims below the glow floor
- * (~190-220) while staying pale, so a trough frame reads no ink and no
- * glow; without the pale class it is indistinguishable from a splat.
+ * Pale pixel: bright but unsaturated. The wash PULSES, dimming below the glow
+ * floor (~190-220) at its trough; without this class a trough frame reads as a splat.
  */
 export const STATUS_PALE_MIN_VALUE = 185;
 export const STATUS_PALE_MAX_SPREAD = 70;
 
 /**
- * Splatted: body ink under the floor (attested dead <=0.20 vs alive
- * >=0.26 with the current body box) with the body-pale guard keeping the
- * wash out across its whole pulse cycle (wash pale >=0.22 vs dead <=0.15 —
- * the 0.15 is a dead icon under the 2026-08-22 VoD's skylight backdrop).
- * Even-layout reads add the shoulder-glow guard against the bright
- * team-color ready flash (glow >=0.40 vs dead <=0.03); on the narrow
- * layouts the same probe reads backdrop leaking past a shrunken X's shoulder at 0.26-0.35,
- * over any usable ceiling, so there only the body classes decide.
+ * Splatted: body ink under the floor (dead <=0.20 vs alive >=0.26) and the
+ * body-pale guard keeping the wash out across its pulse (wash >=0.22 vs dead
+ * <=0.15 under the 2026-08-22 VoD's skylight). Even reads add the shoulder-glow
+ * guard (ready >=0.40 vs dead <=0.03); on narrow layouts backdrop leak past a
+ * shrunken X reads 0.26-0.35 there, so only the body classes decide.
  */
 export const STATUS_DEAD_MAX_BODY_INK = 0.23;
 export const STATUS_DEAD_MAX_SHOULDER_GLOW = 0.2;
@@ -273,101 +195,67 @@ export const STATUS_DEAD_MAX_BODY_PALE = 0.15;
 export const STATUS_READY_MIN_SHOULDER_GLOW = 0.25;
 
 /**
- * Special ready off the body when the shoulder misses the wash (pulse
- * trough, or wash dimmed on compressed footage): pale-dominant body
- * (attested ready >=0.31 — the AREA CUP narrow-left wash after a respawn — vs
- * alive <=0.25 — plain alive bodies show some pale from weapon-silhouette
- * whites).
+ * Ready off the body when the shoulder misses the wash (trough, compressed
+ * footage): ready >=0.31 (AREA CUP after a respawn) vs alive <=0.25 (silhouette whites).
  */
 export const STATUS_READY_MIN_BODY_PALE = 0.3;
 
 /**
- * Narrow-layout ready guard: the spectator wash REPLACES the body's team
- * ink, so an ink-heavy body proves a bright shoulder/pale read is backdrop
- * leaking past the icon edge — the spectator overhead view draws a
- * badge-less strip whose left column sits ~12px off the narrow-right
- * centers, sliding the probes onto pale buildings and the team-color lead
- * banner (attested leaks read body ink >=0.44). The guard is graded: clean
- * washes read ink <=0.28, and the attested inky washes (stage ink bleeding
- * around the washed icon, 0.316/0.344) still show a strongly pale body
- * (>=0.399) — while the S3 POV Um'ami backdrop leak that faked a star read
- * ink 0.36 with pale only 0.269, so the mid band demands the pale
- * corroboration. Even-layout ready icons instead light up IN team color
- * (attested ink up to 0.68), so the guard applies to the narrow layouts
- * only. Margins are THIN (true ink 0.344 vs
- * hard ceiling 0.4; true pale 0.399 vs floor 0.35) — re-measure before
- * moving any of the three.
+ * Narrow-layout ready guard: the wash REPLACES body ink, so an ink-heavy body
+ * means backdrop leak (the overhead view's left column sits ~12px off, sliding
+ * probes onto pale buildings / the lead banner: ink >=0.44). Graded: clean
+ * washes ink <=0.28; inky washes (0.316/0.344) still read strongly pale
+ * (>=0.399) while the Um'ami POV leak read ink 0.36 / pale 0.269. Even ready
+ * icons light IN team color (ink up to 0.68), so narrow only. Margins are THIN
+ * (ink 0.344 vs 0.4; pale 0.399 vs 0.35) — re-measure before moving any.
  */
 export const STATUS_READY_WASH_MAX_BODY_INK = 0.4;
 export const STATUS_READY_CLEAN_WASH_MAX_BODY_INK = 0.3;
 export const STATUS_READY_INKY_WASH_MIN_BODY_PALE = 0.35;
 
 /**
- * Narrow-layout ready reads also need a minimally pale body: the wash
- * surface always paints the body probe pale (every attested spectator wash
- * reads >=0.22, bright phase and trough alike), while a splatted icon
- * with a bright backdrop leaking over its shoulder shows none (leaks on
- * the 2026-08-22 POV VoD's skylight/glass backdrops lit the shoulder
- * 0.26-0.35 past the ready floor over grey X bodies reading pale <=0.15).
- * The washed-ink guards cannot catch this — a dead body is ink-poor by
- * nature. Even-layout ready icons light in team color, so even reads
- * skip it.
+ * Narrow ready reads also need a minimally pale body: every attested wash reads
+ * >=0.22 (bright and trough) while a dead icon under skylight leak (2026-08-22
+ * VoD: shoulder 0.26-0.35) reads pale <=0.15 — a dead body is ink-poor, so the
+ * ink guards cannot catch it. Even reads skip this.
  */
 export const STATUS_READY_MIN_WASH_BODY_PALE = 0.2;
 
 /**
- * Layout scoring (see player-status.ts): per-slot decisiveness is the
- * body-ink distance from the dead threshold, capped so one saturated slot
- * cannot carry a misaligned geometry. The sticky margin is what the
- * non-established layout must win the score by before a badge-less frame
- * switches an established geometry.
+ * Layout scoring: per-slot decisiveness is body-ink distance from the dead
+ * threshold, capped so one saturated slot cannot carry a misaligned geometry.
+ * Sticky margin: what a challenger must win by to switch an established layout.
  */
 export const STATUS_LAYOUT_SCORE_CAP = 0.3;
 export const STATUS_LAYOUT_STICKY_MARGIN = 0.04;
 
 /**
- * History-less badge-less picks prefer narrow-right: every attested
- * badge-less strip draws a narrow geometry (an even strip on badge-less
- * footage is barely attested), and decisiveness alone mis-ranks busy
- * backdrops — the sendou-triton match-start frame scores even 0.278 /
- * narrow-right 0.273 yet is narrow-right. Even wins a fresh pick only
- * when the narrow-right geometry reads poorly (below the floor — the S2
- * POV fixture reads narrow-right at 0.198 vs attested narrow-right
- * footage >=0.212) or even beats it by a decisive lead (attested
- * narrow-right frames mis-lead even by at most 0.036).
+ * Fresh badge-less picks prefer narrow-right (badge-less even is barely
+ * attested; busy backdrops mis-rank: sendou-triton match-start scores even
+ * 0.278 / narrow-right 0.273 yet is narrow-right). Even wins only when
+ * narrow-right reads under the floor (S2 POV fixture 0.198 vs true >=0.212) or
+ * leads decisively (true narrow-right mis-leads even by at most 0.036).
  */
 export const STATUS_FRESH_NARROW_RIGHT_MIN_DECISIVENESS = 0.21;
 export const STATUS_FRESH_EVEN_MIN_LEAD = 0.05;
 
 /**
- * Fresh badge-less NARROW-LEFT pick (see pickLayout): S3 POV footage can
- * draw the badge-less narrow-left arrangement in steady state (attested
- * across the 2026-08-22 Sendou POV VoD — icon centers measured on the
- * narrow-left pitches within ~10px), and its pale backdrops drown the
- * slot comb (gaps read as iconness), so the comb-decisive gate cannot
- * claim these frames. Instead a fresh narrow-left pick needs the LEFT
- * column — the only column where narrow-left and its even false friend
- * differ — to win decisively: attested true narrow-left frames lead the
- * rival left decisiveness by >=0.046 while every attested
- * narrow-right/even frame that also wins the overall score leads by
- * <=0.001. One false friend survives that cut (the S2 POV fixture, left
- * lead 0.052 from boxes landing on featureless backdrop) but its left
- * comb is strong at the rival pitch (even 0.326 / narrow-right 0.325 vs
- * <=0.220 on every attested narrow-left frame), so a readable rival left
- * comb vetoes.
+ * Fresh badge-less NARROW-LEFT pick (pickLayout): S3 POV draws it in steady
+ * state (2026-08-22 Sendou VoD, centers within ~10px) over pale backdrops that
+ * drown the comb, so the LEFT column — the only one differing from even — must
+ * win decisively: true frames lead by >=0.046, rival winners by <=0.001. The S2
+ * POV fixture survives that (lead 0.052 off featureless backdrop) but its left
+ * comb is strong at the rival pitch (0.326/0.325 vs <=0.220 on true frames), so
+ * a readable rival left comb vetoes.
  */
 export const STATUS_FRESH_NARROW_LEFT_MIN_LEFT_LEAD = 0.025;
 export const STATUS_FRESH_NARROW_LEFT_RIVAL_COMB_VETO = 0.3;
 
 /**
- * Slot-comb contrast (see combContrast in player-status.ts): mean iconness
- * at a layout's slot centers minus mean at its between-slot gaps, maximized
- * over a small global shift. Rigid comb positions expose the arrangement's
- * pitch — the badge-less narrow-left strip scores 0.81 while narrow-right
- * reads it at -0.07 (sendou-triton MakoMart) — so a decisive comb win
- * proves the narrow-left arrangement even though its right column nearly
- * coincides with even's. Both gates are needed: the worst attested false
- * narrow-left comb is 0.44 total (lead-banner frame) with a 0.24 lead.
+ * Slot-comb contrast (combContrast): a rigid comb exposes the pitch — badge-less
+ * narrow-left scores 0.81 while narrow-right reads it at -0.07 (sendou-triton
+ * MakoMart), so a decisive win proves narrow-left despite the shared right
+ * column. Both gates needed: worst false narrow-left comb is 0.44 with a 0.24 lead.
  */
 export const STATUS_COMB_BAND_Y = 35;
 export const STATUS_COMB_BAND_H = 61;
@@ -385,52 +273,32 @@ export const STATUS_NARROW_LEFT_COMB_MIN = 0.5;
 export const STATUS_NARROW_LEFT_COMB_LEAD = 0.25;
 
 /**
- * Sticky flips away from an established narrow-right layout also need
- * comb corroboration (challenger comb past this floor AND leading
- * narrow-right's comb by STATUS_NARROW_LEFT_COMB_LEAD): S3 POV footage
- * draws that geometry, but while the POV player is dead the whole strip
- * shrinks toward the timer (~0.77 scale, left column landing near the
- * narrow-left pitches), and those transient frames spike the narrow-left
- * decisiveness past the sticky margin — the 2026-08-11 Um'ami POV VoD
- * locked 107 of 136 reads into narrow-left that way. Attested true
- * narrow-left stretches comb 0.41-0.81 with >=0.31 lead over
- * narrow-right; the worst POV-footage narrow-left comb is 0.20 with a
- * negative lead.
+ * Sticky flips away from narrow-right need comb corroboration (past this floor
+ * AND leading by STATUS_NARROW_LEFT_COMB_LEAD): while the S3 POV player is dead
+ * the strip shrinks ~0.77 toward the timer, landing near narrow-left pitches
+ * (2026-08-11 Um'ami VoD locked 107 of 136 reads that way). True narrow-left
+ * combs 0.41-0.81 with >=0.31 lead; worst POV false comb 0.20, negative lead.
  */
 export const STATUS_STICKY_FLIP_COMB_MIN = 0.3;
 
-/**
- * An established layout only carries forward across reads this close in
- * time — in-match reads land ~1s apart, while a longer silence means a new
- * match (possibly new footage type) and the next frame picks fresh.
- */
+/** Layout carries forward only across reads this close (~1s apart in-match); longer means a new match. */
 export const STATUS_LAYOUT_STICKY_MAX_GAP_S = 30;
 
-// ---- strip weapon-icon evidence (the StripWeapons event) ----
-//
-// Each slot draws the player's weapon render over its squid plate; the
-// match builder aggregates sampled per-slot candidate rankings across a
-// match to solve the strip-slot → scoreboard-row assignment
-// (strip-weapons.ts). Calibrated on the sendou-triton VoD (narrow-right
-// geometry on 720p footage upscaled to canonical space).
+// Strip weapon-icon evidence (strip-weapons.ts), calibrated on the sendou-triton
+// VoD (narrow-right, 720p upscaled to canonical).
 
 /**
- * Weapon search window relative to a slot center: generous enough to hold
- * the render at any strip geometry (the render measures ~65px on the
- * narrow strips, smaller on even) without swallowing a neighbor slot's art.
+ * Search window per slot center: holds the render at any geometry (~65px on narrow strips) without
+ * a neighbor's art.
  */
 export const STRIP_WEAPON_BOX = { dx: -50, y: 20, w: 100, h: 100 };
 
-/**
- * Template render heights to try inside the window; the attested narrow
- * strips draw renders at ~55-70px depending on the weapon's aspect.
- */
+/** Narrow strips draw renders at ~55-70px depending on the weapon's aspect. */
 export const STRIP_WEAPON_TEMPLATE_SIZES = [44, 52, 60, 68, 76] as const;
 
 /**
- * The flat grey the knocked-out plate pixels become and templates are
- * composited over — mid-grey, so both dark barrels and white bodies keep
- * contrast against it.
+ * Knocked-out plate pixels and template backgrounds: mid-grey so dark barrels and white bodies both
+ * keep contrast.
  */
 export const STRIP_WEAPON_TEMPLATE_BACKGROUND = 90;
 
@@ -438,40 +306,27 @@ export const STRIP_WEAPON_TEMPLATE_BACKGROUND = 90;
 export const STRIP_WEAPON_INK_THRESHOLD = 140;
 
 /**
- * A plate pixel: saturated and bright (the plate is drawn in team ink),
- * within the hue band of the region's modal saturated hue. The spread and
- * value floors sit under the modal-vote floors (+15 in strip-weapons.ts)
- * so the knockout reaches the plate's dimmer edge pixels the vote skips.
+ * Plate pixel: saturated, bright, near the region's modal saturated hue. Floors
+ * sit under the modal-vote floors (+15 in strip-weapons.ts) to reach dimmer edge pixels.
  */
 export const STRIP_WEAPON_KNOCKOUT_MIN_SPREAD = 55;
 export const STRIP_WEAPON_KNOCKOUT_MIN_VALUE = 90;
 export const STRIP_WEAPON_MAX_PLATE_HUE_DIST = 30;
 
-/**
- * Candidates kept per slot: single reads only rank the true weapon top-1
- * about half the time on attested footage, but it lands in the top 8 in
- * enough reads for the cross-match aggregate to decide.
- */
+/** Single reads rank the true weapon top-1 about half the time, but top-8 often enough for the aggregate. */
 export const STRIP_WEAPON_TOP_K = 8;
 
 /**
- * Every Nth successful counter read samples the strip weapons: identities
- * are fixed per match, ~1 read/s makes ~20 samples over a short match —
- * attested to assign correctly — and the full-atlas NCC sweep is too
- * heavy to run on every read.
+ * Every Nth counter read samples strip weapons: ~20 samples over a short match assign correctly;
+ * the sweep is too heavy per read.
  */
 export const STRIP_WEAPON_SAMPLE_INTERVAL = 5;
 
 /**
- * Broadcast discriminator (PlayerStatusData's `cast`): the spectator HUD
- * always draws white camera badges under the right team's icons; nothing
- * fixed sits there on POV footage. All four probes must read white
- * (bright AND unsaturated — bright sky is saturated cyan) to call the
- * frame cast. The narrow-left set covers that arrangement's wide right
- * badge pitch. The white floor sits in a wide attested gap: badge-bearing
- * frames read a min-probe fraction >=0.33 (the AREA CUP gauge-overlay
- * wash frame's slightly faded badge row) while every badge-less frame —
- * POV footage and badge-hidden broadcast stretches alike — reads <=0.004.
+ * Broadcast discriminator (`cast`): the spectator HUD draws white camera badges
+ * under the right team's icons. All four probes must read white (bright AND
+ * unsaturated — sky is saturated cyan). Badge frames read >=0.33 (AREA CUP faded
+ * row), every badge-less frame <=0.004.
  */
 export const STATUS_DPAD_PROBES_NARROW_RIGHT: readonly Roi[] = [
 	1105, 1180, 1256, 1332,
diff --git a/app/features/scanner/core/detectors/objective/strip-weapons.ts b/app/features/scanner/core/detectors/objective/strip-weapons.ts
index 672d71bde..8c71395ff 100644
--- a/app/features/scanner/core/detectors/objective/strip-weapons.ts
+++ b/app/features/scanner/core/detectors/objective/strip-weapons.ts
@@ -1,24 +1,13 @@
 /**
- * StripWeapons: per-slot weapon-icon evidence off the same icon strip the
- * PlayerStatus read classifies, emitted by the ObjectiveDetector on a
- * sampled cadence (identities are fixed for a match, so every read would be
- * waste). The results scoreboard re-sorts each team per game while the
- * strip keeps the lobby seating (attested in the sendou-triton VoD: strip
- * [Planetz, .52, Neo Splash, Snipewriter] vs scoreboard rows
- * [.52, Neo Splash, Snipewriter, Planetz]), so status samples cannot be
- * paired with scoreboard rows by position alone — the match builder
- * aggregates these candidate lists across the match and solves the
- * slot→row assignment against the scoreboard's weapons
- * (slot-row-assignment.ts).
- *
- * A slot's icon is the weapon render over a team-ink squid plate; the
- * plate (and scene bleeding through it — the plates are translucent) is
- * what drowns template matching, so saturated pixels near the plate's
- * modal hue are flattened to the template background before the NCC
- * ranking. One read's top-1 is only right about half the time on attested
- * footage — the value is in the aggregate, so the event carries a ranked
- * candidate list per slot. Splatted slots grey the render out and are
- * skipped rather than guessed.
+ * StripWeapons: per-slot weapon-icon evidence off the PlayerStatus icon strip,
+ * sampled by the ObjectiveDetector. The scoreboard re-sorts each team per game
+ * while the strip keeps lobby seating (sendou-triton VoD: strip [Planetz, .52,
+ * Neo Splash, Snipewriter] vs rows [.52, Neo Splash, Snipewriter, Planetz]), so
+ * the match builder aggregates these candidate lists to solve the slot→row
+ * assignment (slot-row-assignment.ts). The translucent team-ink squid plate
+ * drowns template matching, so pixels near its modal hue are flattened to the
+ * template background first. A single top-1 is right only about half the time,
+ * hence the ranked list per slot. Splatted slots grey out and are skipped.
  */
 import type { MainWeaponId } from "~/modules/in-game-lists/types";
 import { getCV, type Mat } from "../../cv";
@@ -52,19 +41,11 @@ export interface StripWeaponsData {
 	time: number | null;
 	/** the icon-strip geometry the paired PlayerStatus read picked */
 	layout: PlayerStatusLayout;
-	/**
-	 * ranked weapon candidates per slot, [left team, right team], slots
-	 * left-to-right as drawn; null = slot skipped (splatted icons grey the
-	 * weapon render out)
-	 */
+	/** ranked candidates per slot, [left team, right team], as drawn; null = splatted slot skipped */
 	slots: [(StripWeaponCandidate[] | null)[], (StripWeaponCandidate[] | null)[]];
 }
 
-/**
- * Match every alive slot's icon against the strip weapon templates.
- * `status` is the PlayerStatus read off the same frame — its layout picks
- * the slot centers and its dead flags pick which slots are worth reading.
- */
+/** Match every alive slot's icon; `status` (same frame) supplies slot centers and dead flags. */
 export function parseStripWeapons(
 	frame: Mat,
 	t: number,
@@ -85,9 +66,8 @@ export function parseStripWeapons(
 	return {
 		type: STRIP_WEAPONS_EVENT_TYPE,
 		t,
-		// raw NCC peaks on attested footage sit ~0.4-0.6 even for correct
-		// reads; the aggregate assignment carries the reliability, so the
-		// event's own confidence only reflects that something matched at all
+		// correct reads peak at only ~0.4-0.6 NCC; reliability lives in the aggregate,
+		// so this only reflects that something matched
 		confidence: scores.length > 0 ? Math.max(...scores) : 0,
 		data: {
 			time: status.time,
@@ -134,12 +114,7 @@ function matchSlot(
 	}));
 }
 
-/**
- * Flatten the squid plate out of the search region: the modal hue of the
- * region's saturated pixels is the plate's team ink, and every pixel near
- * that hue is replaced with the flat template background, leaving the
- * weapon render (grey/white bodies and off-hue accents) to carry the NCC.
- */
+/** Replace pixels near the modal saturated hue (the plate's team ink) with the flat template background. */
 function knockoutPlate(search: Mat): void {
 	const { data } = search;
 	const n = search.rows * search.cols;
diff --git a/app/features/scanner/core/detectors/registry.ts b/app/features/scanner/core/detectors/registry.ts
index 8ef957852..a12fbd021 100644
--- a/app/features/scanner/core/detectors/registry.ts
+++ b/app/features/scanner/core/detectors/registry.ts
@@ -1,8 +1,4 @@
-/**
- * The full detector registry — the single source of truth for "every
- * detector that runs on a frame". New event types get added here and are
- * picked up by the analyzer worker.
- */
+/** Every detector that runs on a frame; new event types register here. */
 
 import { createDeathDetector } from "./death/index";
 import { createMapStartDetector } from "./map-start/index";
@@ -24,11 +20,7 @@ import {
 import { createScoreboardOwnDetector } from "./scoreboard-own/index";
 import type { Detector } from "./types";
 
-/**
- * Event types whose data is the full 8-player scoreboard shape
- * (ScoreboardData): the results screen, the replay-browser detail, and the
- * scoreboard-battle-log detail.
- */
+/** Event types whose data is the full 8-player ScoreboardData shape. */
 export const SCOREBOARD_EVENT_TYPES: readonly string[] = [
 	SCOREBOARD_EVENT_TYPE,
 	SCOREBOARD_BATTLE_LOG_REPLAY_EVENT_TYPE,
diff --git a/app/features/scanner/core/detectors/scheduler.ts b/app/features/scanner/core/detectors/scheduler.ts
index f32460b12..ade301e51 100644
--- a/app/features/scanner/core/detectors/scheduler.ts
+++ b/app/features/scanner/core/detectors/scheduler.ts
@@ -31,30 +31,21 @@ export interface SchedulingInfo {
 }
 
 export interface SchedulerOptions {
-	/**
-	 * false = one-shot harness mode: every detector is due on every frame and
-	 * parses are never suppressed
-	 */
+	/** false = one-shot harness mode: every detector due every frame, never suppressed */
 	suppressSteadyFrames: boolean;
-	/** check cadence while a detector's gate is passing (per-detector
-	 * refineIntervalS overrides — for detectors whose parse is expensive
-	 * enough that the dense default multiplies real cost) */
+	/** check cadence while a gate is passing (per-detector refineIntervalS overrides) */
 	refineIntervalS: number;
-	/** check cadence while a detector's gate is failing (per-detector
-	 * searchIntervalS overrides) */
+	/** check cadence while a gate is failing (per-detector searchIntervalS overrides) */
 	searchIntervalS: number;
-	/** consecutive non-improving parses tolerated before suppression
-	 * (per-detector maxStagnantParses overrides) */
+	/** non-improving parses tolerated before suppression (per-detector maxStagnantParses overrides) */
 	maxStagnantParses: number;
 	/** seconds without improvement tolerated before suppression */
 	stagnantAfterS: number;
 	/** minimum confidence gain that counts as an improvement */
 	minImprovement: number;
 	/**
-	 * a gate signature cell moving more than this since the streak's last
-	 * parse means the screen's content changed and the streak resets
-	 * (measured on battle log browsing: static-screen noise ≤2 per cell,
-	 * entry flips ≥57)
+	 * a signature cell moving more than this since the streak's last parse
+	 * resets the streak (battle log browsing: static noise ≤2 per cell, entry flips ≥57)
 	 */
 	signatureTolerance: number;
 	/** seconds without any gate pass before the scan counts as calm */
@@ -72,8 +63,7 @@ const DEFAULT_SCHEDULER_OPTIONS: SchedulerOptions = {
 	refineIntervalS: 0.15,
 	searchIntervalS: 0.25,
 	maxStagnantParses: 6,
-	// give a screen ~3s to animate in and produce its best read, whatever
-	// the sampling cadence
+	// ~3s for a screen to animate in and produce its best read, whatever the cadence
 	stagnantAfterS: 3,
 	minImprovement: 0.001,
 	signatureTolerance: 12,
@@ -138,10 +128,7 @@ export class DetectorScheduler {
 		this.#matchOpenUntilT = Number.NEGATIVE_INFINITY;
 	}
 
-	/**
-	 * Earliest t at which any detector wants a check — frames before it can
-	 * skip analysis (and its canvas readback) entirely.
-	 */
+	/** Earliest t any detector wants a check; frames before it skip analysis and readback. */
 	nextDueT(): number {
 		let next = Number.POSITIVE_INFINITY;
 		for (const state of this.#states.values()) {
@@ -154,8 +141,7 @@ export class DetectorScheduler {
 	/** Detector ids that should gate the frame at `t`. */
 	dueDetectors(t: number): string[] {
 		if (t + RESET_TOLERANCE_S < this.#maxT) this.reset(t);
-		// the first frame seeds the activity clock so a fresh session is never
-		// instantly calm — it has to earn its quiet period first
+		// first frame seeds the activity clock so a fresh session is never instantly calm
 		if (this.#lastActivityT === Number.NEGATIVE_INFINITY) {
 			this.#lastActivityT = t;
 		}
@@ -222,8 +208,7 @@ export class DetectorScheduler {
 		this.#recordMatchState(t, events);
 		const state = this.#states.get(id);
 		if (!state || state.info.checkIntervalS !== undefined) return;
-		// no events counts as confidence 0: a false-firing gate on a static
-		// screen stagnates and gets suppressed just like a parsed one
+		// no events counts as confidence 0 so a false-firing gate on a static screen stagnates too
 		const confidence = events.reduce(
 			(max, e) => Math.max(max, e.confidence),
 			0,
@@ -274,11 +259,7 @@ export class DetectorScheduler {
 		}
 	}
 
-	/**
-	 * True when the footage at `t` is dead air as far as detection goes: no
-	 * gate has passed for quietAfterS and no match is open — the VoD scanner
-	 * may skim by keyframes instead of decoding densely.
-	 */
+	/** Dead air: no gate pass for quietAfterS and no open match, so the VoD scanner may skim keyframes. */
 	calm(t: number): boolean {
 		if (!this.#options.suppressSteadyFrames) return false;
 		return (
@@ -292,8 +273,7 @@ export class DetectorScheduler {
 		const { info } = state;
 		if (info.checkIntervalS !== undefined) return info.checkIntervalS;
 		const search = info.searchIntervalS ?? this.#options.searchIntervalS;
-		// while suppressed only the gate keeps running (to spot the screen
-		// changing), which the sparser search cadence covers
+		// while suppressed only the gate runs (to spot the screen changing); search cadence suffices
 		if (state.streak?.suppressed) return search;
 		if (!state.gatePassing) return search;
 		return info.refineIntervalS ?? this.#options.refineIntervalS;
diff --git a/app/features/scanner/core/detectors/scoreboard-battle-log-replay/code.ts b/app/features/scanner/core/detectors/scoreboard-battle-log-replay/code.ts
index 5213eb60c..622555474 100644
--- a/app/features/scanner/core/detectors/scoreboard-battle-log-replay/code.ts
+++ b/app/features/scanner/core/detectors/scoreboard-battle-log-replay/code.ts
@@ -1,8 +1,6 @@
 /**
- * Replay code recognition ("R6KE-DO64-3CXD-XVKL"): bright green text under
- * the team panels. Green on the dark background lands below the default
- * grayscale binarization threshold, so recognition runs on the green
- * channel, where the glyphs are near-white.
+ * Replay code recognition ("R6KE-DO64-3CXD-XVKL"): green text falls below the
+ * grayscale binarization threshold, so it runs on the green channel.
  */
 import { getCV, type Mat } from "../../cv";
 import {
@@ -14,12 +12,9 @@ import { cropRoi } from "../../image";
 import { REPLAY_CODE_ROI } from "./rois";
 
 /**
- * FOT-RowdyStd's 'Q' is a '0' bowl with a small tail below the baseline;
- * the bowl dominates template correlation, so a real Q ranks as '0' by a
- * hair. Like the P/p rule in scoreboard/names.ts, the segment geometry
- * decides what the templates cannot: a 0/O read whose ink reaches well
- * below the line's baseline (the median ink bottom of the other
- * alphanumerics) is a Q.
+ * FOT-RowdyStd's 'Q' is a '0' bowl with a tail, so a real Q ranks as '0' by a
+ * hair; like names.ts's P/p rule, a 0/O whose ink reaches well below the
+ * baseline (median ink bottom of the other chars) is a Q.
  */
 const Q_TWINS = new Set(["0", "O"]);
 const Q_DESCENT_MIN_PX = 4;
@@ -39,12 +34,9 @@ function resolveQsByDescent(raw: RecognizedText): string {
 }
 
 /**
- * On blurry captures a narrow 'L' template can edge out the true 'U' by a
- * hair. Segment geometry decides what templates can't: a U's right stroke
- * fills the segment's top-right quadrant, where an L has no ink (measured
- * 0.00-0.15 leak on true Ls vs 0.27+ on Us across fixtures). The margin only
- * skips confident reads and stays generous, since no true L on the fixtures
- * carries a 'U' candidate at all.
+ * On blurry captures 'L' can edge out a true 'U': a U's right stroke fills the
+ * top-right quadrant where an L has no ink (0.00-0.15 on true Ls vs 0.27+ on
+ * Us). The margin is generous since no fixture L carries a 'U' candidate at all.
  */
 const LU_SCORE_MARGIN = 0.12;
 const LU_INK_THRESHOLD = 150;
@@ -86,10 +78,7 @@ export interface ParsedReplayCode {
 
 const CODE_RE = /^[0-9A-Z]{4}(-[0-9A-Z]{4}){3}$/;
 
-/**
- * Restrict a glyph set to the characters codes can contain — a shallow
- * view over the same template mats, so dispose only the source set.
- */
+/** Glyph set restricted to code characters; a shallow view, so dispose only the source set. */
 export function codeCharsetOf(set: GlyphSet): GlyphSet {
 	const glyphs = set.glyphs.filter((g) => /^[0-9A-Z-]$/.test(g.char));
 	const widths = glyphs.map((g) => g.mat.cols).sort((a, b) => a - b);
@@ -121,9 +110,7 @@ export function parseReplayCode(rgb: Mat, glyphs: GlyphSet): ParsedReplayCode {
 	green.delete();
 
 	let text = resolveQsByDescent(resolved).toUpperCase();
-	// Dashes are thin and can drop out of segmentation (any subset of the
-	// three); the 16 alphanumerics are unambiguous on their own, so re-derive
-	// the grouping from them alone.
+	// thin dashes can drop out of segmentation; re-derive the grouping from the 16 alphanumerics
 	const compact = text.replaceAll("-", "");
 	if (/^[0-9A-Z]{16}$/.test(compact)) {
 		text = compact.replace(/(.{4})(?=.)/g, "$1-");
diff --git a/app/features/scanner/core/detectors/scoreboard-battle-log-replay/header.ts b/app/features/scanner/core/detectors/scoreboard-battle-log-replay/header.ts
index 95ac5dd66..79aa903c3 100644
--- a/app/features/scanner/core/detectors/scoreboard-battle-log-replay/header.ts
+++ b/app/features/scanner/core/detectors/scoreboard-battle-log-replay/header.ts
@@ -1,12 +1,7 @@
 /**
- * Replay-browser header parsing. Same black auto-sized tag style as the
- * live scoreboard header, but different content: the top line holds the
- * recording timestamp ("3/7/2026 22:28") followed by the stage, the bottom
- * line the lobby (bold) followed by the mode.
- *
- * The timestamp is locale-formatted and open-ended, so it is validated by
- * shape and kept as a raw string; stage and lobby+mode snap to the closed
- * sets shared with the live header.
+ * Replay-browser header: same tag style as the live header, top line timestamp
+ * ("3/7/2026 22:28") + stage, bottom line lobby + mode. The locale-formatted
+ * timestamp is validated by shape and kept raw; the rest snaps to closed sets.
  */
 import type { ModeShort, StageId } from "~/modules/in-game-lists/types";
 import type { ScannerLobby } from "../../../scanner-types";
@@ -36,33 +31,24 @@ export interface ParsedReplayHeader {
 const MIN_MATCH_SCORE = 0.62;
 
 /**
- * Lifted-blacks captures (720p streams upscaled and re-encoded) raise the
- * tag background to ~80-115 gray, above readTagBand's default dark ceiling,
- * so the tag-extent trim truncates the band to a sliver and the read comes
- * back empty. A band whose closed-set snap fails is re-read with this
- * ceiling; the retry is adopted only when it snaps at least as well.
+ * Lifted-blacks captures raise the tag background to ~80-115 gray, above
+ * readTagBand's default ceiling, truncating the band to a sliver. A failed snap
+ * is re-read with this ceiling and adopted only when it snaps at least as well.
  */
 const TAG_DARK_MAX_LIFTED = 120;
 
 /**
- * "3/7/2026 22:28" and friends; capture the rest of the line (the stage).
- * The console formats the date per locale — "7.3.2026" (de), "2026/3/7"
- * (ja) — so any . / - separated triple followed by a time is accepted.
- * Adjacent skinny time digits can read with a spurious gap on compressed
- * captures ("14:1 1"), so a lone space is tolerated between them and
- * stripped when the timestamp is assembled. Not left-anchored: the
- * battle log line leads with a rank icon on ranked lobbies, which reads as
- * a junk glyph before the date.
+ * Locale date ("3/7/2026", "7.3.2026", "2026/3/7") + time, rest = stage. A lone
+ * space between skinny time digits is tolerated ("14:1 1") and stripped. Not
+ * left-anchored: the battle log's rank icon reads as a junk glyph before the date.
  */
 const TIMESTAMP_RE =
 	/(\d{1,4}[./-]\d{1,2}[./-]\d{1,4})\s+(\d(?: ?\d)?: ?\d ?\d)\s*(.*)$/;
 
 /**
- * The date-to-time gap can also collapse entirely ("22/8/202620:37"), tried
- * only after the spaced form fails. The date's last component is lazy so the
- * time match decides where the fused run splits ("2026/3/720:28" is 7 +
- * 20:28, not 7202 + 0:28), and the time drops the spurious-gap tolerance —
- * with it, a lazy match could steal the year's last digit instead.
+ * Fused date-time ("22/8/202620:37"), tried after the spaced form. The date's
+ * last component is lazy so the time decides the split ("2026/3/720:28" = 7 +
+ * 20:28); no spurious-gap tolerance or a lazy match could steal a year digit.
  */
 const TIMESTAMP_FUSED_RE =
 	/(\d{1,4}[./-]\d{1,2}[./-]\d{1,4}?)(\d{1,2}:\d\d)\s*(.*)$/;
@@ -75,13 +61,9 @@ interface TopBandParse {
 }
 
 /**
- * In the BlitzMain glyphs the digit forms are near-identical to their letter
- * lookalikes (0/O, the 1/I/l/| bars), so a stage read can surface the digit
- * ("R0M-en") or the wrong bar ("WnrId") and burn an edit the snap threshold
- * cannot spare. Stage names are digit-free in every language (sole exception
- * carries a '9'), so digits and bars fold to letters before snapping — on
- * both the reading and the entry, so an entry's own 'I' ("Inkblot") lands in
- * the same folded space.
+ * BlitzMain digits are near-identical to letter lookalikes (0/O, 1/I/l/|), so a
+ * stage read like "R0M-en" burns an edit the snap cannot spare. Stage names are
+ * digit-free (sole exception carries a '9'), so both reading and entry fold.
  */
 function foldDigitLookalikes(s: string): string {
 	return s.replace(/0/g, "o").replace(/[1|I]/g, "l");
@@ -91,11 +73,8 @@ function parseTopBand(reading: string): TopBandParse {
 	let timestamp: string | null = null;
 	let stage: StageId | null = null;
 	let stageScore = 0;
-	// The top band reads with the BlitzMain name glyphs, where 1/I/l/| are
-	// identical bars ("I9:04"), O/o ride a hair off 0, and 8 can surface as
-	// S ("O9/OS/2Oo6"); in the digits-only timestamp every lookalike folds
-	// to its digit. Match on the normalized line, keep the stage part's
-	// original reading (the replacements are 1:1, so offsets line up).
+	// BlitzMain lookalikes ("I9:04", "O9/OS/2Oo6") fold to digits for the
+	// timestamp; the stage part keeps its original reading (1:1 replacements, offsets line up)
 	const normalized = reading
 		.replace(/[Il|]/g, "1")
 		.replace(/[Oo]/g, "0")
@@ -124,10 +103,7 @@ function parseTopBand(reading: string): TopBandParse {
 export interface ReplayHeaderBands {
 	top: Roi;
 	bottom: Roi;
-	/**
-	 * see TagBandOptions.tagLeadInMax; the battle log tags are not
-	 * left-anchored
-	 */
+	/** see TagBandOptions.tagLeadInMax; the battle log tags are not left-anchored */
 	tagLeadInMax?: number;
 	/** see TagBandOptions.tagColumnFraction; the battle log tags are tilted */
 	tagColumnFraction?: number;
diff --git a/app/features/scanner/core/detectors/scoreboard-battle-log-replay/index.ts b/app/features/scanner/core/detectors/scoreboard-battle-log-replay/index.ts
index 48f3dd43d..afbb567b8 100644
--- a/app/features/scanner/core/detectors/scoreboard-battle-log-replay/index.ts
+++ b/app/features/scanner/core/detectors/scoreboard-battle-log-replay/index.ts
@@ -1,13 +1,9 @@
 /**
- * ScoreboardBattleLogReplayDetector: parses the replay-browser detail
- * screen — the same match data as the live scoreboard (header, team scores,
- * 8 player rows) plus the recording timestamp and the replay code.
- *
- * Layout differs from the live scoreboard: the two team panels sit side by
- * side and the replay owner's team may be on either side, so the
- * VICTORY/DEFEAT panel tags are read to keep `players`/`matchScores`
- * ordered winners-first like the live event. Field parsing reuses the
- * scoreboard helpers with glyph sets rescaled to this screen's text sizes.
+ * ScoreboardBattleLogReplayDetector: parses the replay-browser detail screen —
+ * the live scoreboard's data plus recording timestamp and replay code. The two
+ * team panels sit side by side with the owner's team on either side, so the
+ * VICTORY/DEFEAT tags keep `players`/`matchScores` winners-first. Reuses the
+ * scoreboard helpers with glyph sets rescaled to this screen.
  */
 import { getCV, type Mat } from "../../cv";
 import { type GlyphSet, recognizeText, scaleGlyphSet } from "../../glyphs";
@@ -87,20 +83,15 @@ export const SCOREBOARD_BATTLE_LOG_REPLAY_EVENT_TYPE =
 const REPLAY_INK_THRESHOLD = 90;
 
 /**
- * White banner digits on saturated team color: applies to the "Score:"
- * banners AND the team totals — a green DEFEAT panel weighs in at ~184
- * on the green-heavy grayscale, above the default 150.
+ * White digits on team color ("Score:" banners and team totals): a green DEFEAT panel reads ~184
+ * gray, above the default 150.
  */
 const BANNER_BIN_THRESHOLD = 190;
 
 /** Canonical results the localized VICTORY/DEFEAT panel tags snap to. */
 type PanelResult = "VICTORY" | "DEFEAT";
 const RESULT_MIN_SCORE = 0.6;
-/**
- * The chunky outlined tag letters bridge at the default 150 on the
- * max-channel image; 190 keeps the cores separated (and drops the gray
- * gear/signal icons trailing the text).
- */
+/** Outlined tag letters bridge at 150 on max-channel; 190 keeps cores separated and drops trailing gray icons. */
 const RESULT_TAG_BIN_THRESHOLD = 190;
 
 interface PanelParse {
@@ -155,8 +146,7 @@ export function createScoreboardBattleLogReplayDetector(
 		resources.headerLineGlyphs,
 		HEADER_LINE_HEIGHT,
 	);
-	// Code and result tags render in FOT-RowdyStd — use the dedicated atlases
-	// when present; the BlitzMain-based fallbacks read them only roughly.
+	// code and result tags render in FOT-RowdyStd; the BlitzMain fallbacks read them only roughly
 	const resultGlyphs =
 		scaled(resources.replayResultGlyphs ?? null, RESULT_TAG_TEXT_HEIGHT) ??
 		scaled(resources.headerLineGlyphs, RESULT_TAG_TEXT_HEIGHT);
@@ -201,10 +191,8 @@ export function createScoreboardBattleLogReplayDetector(
 			suffixOk >= 7 &&
 			gapOk === 2 &&
 			codeFraction >= GATE_CODE_MIN_FRACTION;
-		// browsing flips between replays never drop this gate, so it
-		// fingerprints the content that always differs between two battles
-		// (recording timestamp band + replay code) plus the name columns —
-		// the scheduler re-arms suppression when the fingerprint moves
+		// browsing between replays never drops this gate, so fingerprint what
+		// differs between battles (timestamp, code, names) for the scheduler
 		const signature = pass ? contentSignature(gray) : undefined;
 		gray.delete();
 		return { pass, score, signature };
@@ -242,16 +230,12 @@ export function createScoreboardBattleLogReplayDetector(
 			nameGlyphs,
 		};
 		for (const cy of ROW_CENTERS) {
-			// A short team (e.g. a 7-player private battle) renders no pill for
-			// the unused bottom row — just near-black panel background where the
-			// flat probe expects the mid-gray pill (the gate's flatOk >= 7 already
-			// tolerates the missing row). Skip it: no phantom player.
+			// a short team (7-player private battle) renders no pill for the unused
+			// bottom row (gate's flatOk >= 7 tolerates it); skip it, no phantom player
 			const flat = meanBrightness(rgb, gateFlatProbe(cy, dx));
 			if (flat < GATE_FLAT_MIN_MEAN || flat > GATE_FLAT_MAX_MEAN) continue;
 
-			// replay rows render smaller (icons ~26px, inside the live template
-			// set's slide range) on a lighter panel; the paint number is
-			// left-aligned so the "p" suffix lands inside the ROI on short paints
+			// paint is left-aligned so the "p" suffix lands inside the ROI on short paints
 			const row = parseScoreboardRow(
 				gray,
 				rgb,
@@ -268,9 +252,8 @@ export function createScoreboardBattleLogReplayDetector(
 			rows.push(row.debug);
 		}
 
-		// The panel's point total is read only to recognize a knockout below
-		// (the count times five: only a knockout's full count reaches 500);
-		// it is never emitted as a score.
+		// the point total is read only to recognize a knockout below (only a
+		// knockout's full count reaches 500); never emitted as a score
 		let teamScore: ParsedNumber | null = null;
 		if (teamDigits) {
 			const crop = cropRoi(gray, teamScoreRoi(dx));
@@ -295,9 +278,8 @@ export function createScoreboardBattleLogReplayDetector(
 			}
 			crop.delete();
 			confidences.push(matchScore.confidence);
-			// No number under the floor + a full team count = the KNOCKOUT! burst
-			// sitting where the banner's score would be. Report the count it won at
-			// rather than a hole; an unreadable banner on a lesser total stays null.
+			// no number + a full team count = the KNOCKOUT! burst sits where the score
+			// would be; an unreadable banner on a lesser total stays null
 			if (
 				matchScore.value === null &&
 				teamScore?.value === FULL_COUNT_TEAM_SCORE
@@ -358,9 +340,8 @@ export function createScoreboardBattleLogReplayDetector(
 			PanelParse,
 		];
 
-		// Winners first. Trust a confident VICTORY/DEFEAT tag read; when the
-		// tags are inconclusive, the higher "Score:" banner marks the winner
-		// (the shown match score decides the game). Default to left otherwise.
+		// winners first: confident VICTORY/DEFEAT tag, else the higher "Score:"
+		// banner, else left
 		let swapped = false;
 		if (left.result !== null || right.result !== null) {
 			swapped = left.result === "DEFEAT" || right.result === "VICTORY";
@@ -448,9 +429,8 @@ export function createScoreboardBattleLogReplayDetector(
 		];
 	}
 
-	// no rearm cooldown — distinct replays browsed in quick succession are
-	// told apart by content. sufficientConfidence just under the measured
-	// clean-read floor (fixtures 0.808-0.890)
+	// no rearm cooldown: browsed replays are told apart by content signature.
+	// sufficientConfidence just under the clean-read floor (fixtures 0.808-0.890)
 	return {
 		id: "scoreboard-battle-log-replay",
 		sufficientConfidence: 0.8,
diff --git a/app/features/scanner/core/detectors/scoreboard-battle-log-replay/rois.ts b/app/features/scanner/core/detectors/scoreboard-battle-log-replay/rois.ts
index c1074bf2d..6aa24916f 100644
--- a/app/features/scanner/core/detectors/scoreboard-battle-log-replay/rois.ts
+++ b/app/features/scanner/core/detectors/scoreboard-battle-log-replay/rois.ts
@@ -1,15 +1,9 @@
 /**
- * ALL scoreboard-battle-log-replay ROI coordinates, in canonical 1920x1080
- * space. Calibrated against scoreboard-battle-log-replay/private-battle-
- * splat-zones-hagglefish via scripts/scanner/overlay-rois.ts and column-projection
- * measurement.
- *
- * The replay-browser detail screen shows two team panels SIDE BY SIDE
- * (right = left shifted by PANEL_DX), four gray pill rows each — mid-gray
- * (~61) with darker gaps (~23), unlike the live scoreboard's near-black
- * pills (~12). Below the panels: replay owner line + bright green replay
- * code; above: two "Score:" banners and the stage-photo header (line 1 =
- * timestamp + stage, line 2 = lobby + mode).
+ * Replay-browser ROIs in canonical 1920x1080 space, calibrated against the
+ * private-battle-splat-zones-hagglefish fixture. Two team panels SIDE BY SIDE
+ * (right = left + PANEL_DX), four mid-gray pill rows each (~61, gaps ~23; the
+ * live scoreboard's pills are ~12). Below: green replay code; above: two
+ * "Score:" banners and the header (timestamp + stage / lobby + mode).
  */
 import type { Roi } from "../../canonical";
 
@@ -22,65 +16,45 @@ export const PANEL_DX = 676;
 /** dx per panel: [left (index 0), right (index 1)]. */
 export const PANEL_XS = [0, PANEL_DX] as const;
 
-/**
- * Weapon icon search region — full pill height so the largest template
- * (64; icons render ~60-64px) fits with slide room (matchTemplate skips
- * taller templates).
- */
+/** Full pill height so the largest template (64; icons ~60-64px) fits with slide room. */
 export function weaponRoi(cy: number, dx: number): Roi {
 	return { x: 522 + dx, y: cy - 34, w: 96, h: 68 };
 }
 
 /**
- * Special-weapon icon on a black disc above the third stat counter (~25x29
- * art at x 1109-1134, y cy-29..cy). Only read to break near-tied weapon
- * matches with different specials; box stays inside the disc since the
- * mid-gray pill around it sits above matchSpecial's ink threshold.
+ * Special icon on a black disc above the third stat (~25x29 at x 1109-1134),
+ * only read to break near-tied weapons. Box stays inside the disc: the mid-gray
+ * pill sits above matchSpecial's ink threshold.
  */
 export function specialIconRoi(cy: number, dx: number): Roi {
 	return { x: 1104 + dx, y: cy - 32, w: 38, h: 33 };
 }
 
-/**
- * Player name text region (white, left-aligned; descenders reach cy+18).
- * Long names run into the paint column; parse paint first and trim at its
- * leftmost digit. Kept narrower than the first glyph to dodge weapon-icon bleed.
- */
+/** Name text (descenders reach cy+18); long names run into the paint column, trim at its leftmost digit. */
 export function nameRoi(cy: number, dx: number): Roi {
 	return { x: 620 + dx, y: cy - 16, w: 226, h: 37 };
 }
 
 /**
- * Paint digits, LEFT-aligned from x~843 (~18px pitch); the trailing "p"
- * moves with digit count, so short (3-digit) paints put it inside this
- * region — parseNumber's digit-only charset drops it.
+ * Paint digits, LEFT-aligned from x~843; the trailing "p" lands inside on 3-digit paints
+ * (digit-only charset drops it).
  */
 export function paintRoi(cy: number, dx: number): Roi {
 	return { x: 821 + dx, y: cy - 15, w: 88, h: 34 };
 }
 
-/**
- * Gate anchor over the "p" after the paint number. Since it's left-aligned,
- * "p" position tracks digit count (x 898-907 after 3 digits, 915-924
- * after 4) — the probe spans both.
- */
+/** Gate anchor over the paint "p", spanning both positions (x 898-907 after 3 digits, 915-924 after 4). */
 export function paintSuffixRoi(cy: number, dx: number): Roi {
 	return { x: 896 + dx, y: cy - 13, w: 31, h: 26 };
 }
 
-/**
- * Stat counter digits (zero-padded, "x" prefix excluded), cy+4..cy+23 —
- * the top edge must stay below the stat icons, which bleed ink above it.
- */
+/** Stat digits ("x" prefix excluded); top edge must stay below the stat icons' ink bleed. */
 export function statRoi(cy: number, dx: number, index: 0 | 1 | 2): Roi {
 	const x = [1000, 1057, 1114][index]!;
 	return { x: x + dx, y: cy + 3, w: 36, h: 24 };
 }
 
-/**
- * POV arrow: smaller replay-browser arrow on the pill's left edge (x
- * 487-530). Right edge stays short of the weapon-icon region (x 522+).
- */
+/** POV arrow on the pill's left edge (x 487-530), short of the weapon region (x 522+). */
 export function povArrowRoi(cy: number, dx: number): Roi {
 	return { x: 480 + dx, y: cy - 32, w: 54, h: 56 };
 }
@@ -101,23 +75,12 @@ export const MATCH_SCORE_ROIS: readonly [Roi, Roi] = [
 	{ x: 1620, y: 340, w: 130, h: 56 },
 ];
 
-/**
- * Header bands on the stage-photo banner: line 1 timestamp + stage tag,
- * line 2 lobby + mode. Tags size to their text; the header parser trims
- * each band to the tag extent.
- */
+/** Header bands: line 1 timestamp + stage, line 2 lobby + mode; the parser trims each to the tag extent. */
 export const HEADER_TOP_BAND: Roi = { x: 500, y: 68, w: 560, h: 46 };
-/**
- * Wide lobby tags push the mode tag right ("Anarchy Battle (Open)" +
- * "Rainmaker" ends x~1134), so the band runs past the longest observed pair.
- */
+/** Runs past the longest observed pair ("Anarchy Battle (Open)" + "Rainmaker" ends x~1134). */
 export const HEADER_BOTTOM_BAND: Roi = { x: 500, y: 124, w: 700, h: 58 };
 
-/**
- * Bright green replay code line ("XXXX-XXXX-XXXX-XXXX"), left-aligned
- * after the magnifier icon. Width tracks the glyphs, so a wide-letter
- * code can run past x=913 — box extends into the background to fit it.
- */
+/** Green replay code, left-aligned after the magnifier; a wide-letter code can run past x=913. */
 export const REPLAY_CODE_ROI: Roi = { x: 574, y: 960, w: 400, h: 38 };
 
 /** Gate probe: flat pill background strip between paint "p" and first stat "x" — mid-gray here, not near-black. */
@@ -138,7 +101,10 @@ export const GATE_FLAT_MAX_MEAN = 78;
 export const GATE_GAP_MAX_MEAN = 40;
 /** The paint "p" suffix region must contain bright pixels. */
 export const GATE_TEXT_MIN_MAX = 180;
-/** Replay-code color probe: fraction of REPLAY_CODE_ROI pixels that are green-ish (high G, low B) — unique to this screen. */
+/**
+ * Replay-code color probe: fraction of REPLAY_CODE_ROI pixels that are green-ish (high G, low B) —
+ * unique to this screen.
+ */
 export const GATE_CODE_GREEN_MIN = 140;
 export const GATE_CODE_BLUE_MAX = 90;
 export const GATE_CODE_MIN_FRACTION = 0.03;
diff --git a/app/features/scanner/core/detectors/scoreboard-battle-log/index.ts b/app/features/scanner/core/detectors/scoreboard-battle-log/index.ts
index b0236f4fa..785369dc3 100644
--- a/app/features/scanner/core/detectors/scoreboard-battle-log/index.ts
+++ b/app/features/scanner/core/detectors/scoreboard-battle-log/index.ts
@@ -1,14 +1,9 @@
 /**
- * ScoreboardBattleLogDetector: parses the Recent Battles detail screen
- * (battle log) — the same match data as the live scoreboard (header, team
- * scores, 8 player rows) plus the recording timestamp, but no replay code.
- *
- * The two team panels sit STACKED (observed winner on top, confirmed by the
- * VICTORY/DEFEAT tags) and the row text renders at the live scoreboard's
- * sizes, so field parsing reuses the scoreboard helpers with the shared
- * glyph sets unscaled — only the ROI geometry is this screen's own. The
- * header is the replay browser's (timestamp + stage / lobby + mode tags),
- * parsed with battle log bands.
+ * ScoreboardBattleLogDetector: parses the Recent Battles detail screen — the
+ * live scoreboard's data plus recording timestamp, no replay code. The panels
+ * sit STACKED (winner on top, confirmed by VICTORY/DEFEAT tags) with row text
+ * at live sizes, so the scoreboard helpers run with unscaled glyph sets; the
+ * header is the replay browser's, parsed with battle log bands.
  */
 import { getCV, type Mat } from "../../cv";
 import { type GlyphSet, recognizeText, scaleGlyphSet } from "../../glyphs";
@@ -76,20 +71,15 @@ export interface ScoreboardBattleLogData extends ScoreboardData {
 
 export const SCOREBOARD_BATTLE_LOG_EVENT_TYPE = "ScoreboardBattleLog";
 
-/**
- * White outlined team totals on the panel's saturated color band — a yellow
- * band grays at ~190, so binarize just above it (the digit cores are ~250).
- */
+/** White team totals on the color band: a yellow band grays at ~190, digit cores ~250. */
 const TEAM_SCORE_BIN_THRESHOLD = 205;
 
 /** Canonical results the localized VICTORY/DEFEAT panel tags snap to. */
 type PanelResult = "VICTORY" | "DEFEAT";
 const RESULT_MIN_SCORE = 0.6;
 /**
- * The tag letters render in the team's ink color on the gray stamp box
- * (~75 gray, trailing status icons ~120), so binarize the max-channel
- * image just above the icons — every ink color's brightest channel
- * clears this.
+ * Tag letters in team ink on the gray stamp (~75, trailing icons ~120): max-channel binarized just
+ * above the icons.
  */
 const RESULT_TAG_BIN_THRESHOLD = 140;
 
@@ -121,8 +111,7 @@ export function createScoreboardBattleLogDetector(
 		resources.headerLineGlyphs,
 		HEADER_LINE_HEIGHT,
 	);
-	// The tags render in FOT-RowdyStd — use the dedicated atlas when present;
-	// the BlitzMain-based fallback reads them only roughly.
+	// tags render in FOT-RowdyStd; the BlitzMain fallback reads them only roughly
 	const resultGlyphs =
 		scaled(resources.replayResultGlyphs ?? null, RESULT_TAG_TEXT_HEIGHT) ??
 		scaled(resources.headerLineGlyphs, RESULT_TAG_TEXT_HEIGHT);
@@ -175,10 +164,8 @@ export function createScoreboardBattleLogDetector(
 				colorOk / GATE_COLOR_PROBES.length) /
 			3;
 		const pass = darkOk >= 7 && suffixOk >= 7 && colorOk === 3;
-		// browsing flips between entries never drop this gate, so it
-		// fingerprints the content that always differs between two battles
-		// (recording timestamp + stage tag) plus the name column — the
-		// scheduler re-arms suppression when the fingerprint moves
+		// browsing between entries never drops this gate, so fingerprint what
+		// differs between battles (timestamp, stage, names) for the scheduler
 		const signature = pass ? contentSignature(gray) : undefined;
 		gray.delete();
 		return { pass, score, signature };
@@ -220,9 +207,8 @@ export function createScoreboardBattleLogDetector(
 			rows.push(row.debug);
 		}
 
-		// The panel's point total is read only to recognize a knockout (the
-		// count times five: only a knockout's full count reaches 500); it is
-		// never emitted as a score.
+		// the point total is read only to recognize a knockout (only a knockout's
+		// full count reaches 500); never emitted as a score
 		let teamScore: ParsedNumber | null = null;
 		if (teamDigits) {
 			const crop = cropRoi(gray, teamScoreRoi(dy));
@@ -370,10 +356,8 @@ export function createScoreboardBattleLogDetector(
 		];
 	}
 
-	// no rearm cooldown — distinct battles browsed in quick succession are
-	// told apart by content: the gate signature re-arms scheduler suppression
-	// and the timeline merges via sameScoreboardMatch (same as the replay
-	// browser)
+	// no rearm cooldown: browsed battles are told apart by the gate signature and
+	// the timeline merges via sameScoreboardMatch
 	return {
 		id: "scoreboard-battle-log",
 		sufficientConfidence: 0.8,
@@ -383,11 +367,9 @@ export function createScoreboardBattleLogDetector(
 }
 
 /**
- * Whether the winner sits in the bottom panel. A confident VICTORY/DEFEAT
- * tag decides (the distressed tag texture usually reads below the floor);
- * otherwise the panel totals are checked against the banner scores — the
- * total is the count times five, and only a knockout winner's reaches 500.
- * Default: winner on top, which every observed battle log screen shows.
+ * Whether the winner sits in the bottom panel: a confident VICTORY/DEFEAT tag
+ * (the distressed texture usually reads under the floor), else panel totals
+ * (count x5; only a knockout reaches 500) against the banner. Default top.
  */
 function decideSwapped(
 	top: PanelParse,
diff --git a/app/features/scanner/core/detectors/scoreboard-battle-log/rois.ts b/app/features/scanner/core/detectors/scoreboard-battle-log/rois.ts
index a56027bde..debb29ce8 100644
--- a/app/features/scanner/core/detectors/scoreboard-battle-log/rois.ts
+++ b/app/features/scanner/core/detectors/scoreboard-battle-log/rois.ts
@@ -1,15 +1,9 @@
 /**
- * ALL scoreboard-battle-log ROI coordinates, in canonical 1920x1080 space.
- * Calibrated against scoreboard-battle-log/private-battle-splat-zones-
- * makomart and x-battle-clam-blitz-lemuria via scripts/scanner/dump-crops.ts
- * and column-projection measurement.
- *
- * The Recent Battles detail screen shows two team panels STACKED (bottom =
- * top shifted by PANEL_DY), four near-black pill rows each on a dark panel
- * whose top band/border carry the team's ink color. Text sizes match the
- * live scoreboard (row glyphs reused unscaled, only columns differ). Above
- * the panels: split "Score:"/KNOCKOUT! banner and stage-photo header
- * (line 1 = timestamp + stage, line 2 = lobby + mode). No replay code line.
+ * Battle-log ROIs in canonical 1920x1080 space, calibrated against the
+ * private-battle-splat-zones-makomart and x-battle-clam-blitz-lemuria fixtures.
+ * Two panels STACKED (bottom = top + PANEL_DY), four near-black pill rows each,
+ * team ink on the top band. Text sizes match the live scoreboard. Above: split
+ * "Score:"/KNOCKOUT! banner and header (timestamp + stage / lobby + mode).
  */
 import type { Roi } from "../../canonical";
 
@@ -22,27 +16,20 @@ export const PANEL_DY = 366;
 /** dy per panel: [top (index 0), bottom (index 1)]. */
 export const PANEL_DYS = [0, PANEL_DY] as const;
 
-/**
- * Weapon icon search region — icons render at live-scoreboard sizes; 56px
- * height excludes larger replay-browser templates (matchTemplate skips them).
- */
+/** Icons at live-scoreboard sizes; 56px height excludes the larger replay-browser templates. */
 export function weaponRoi(cy: number): Roi {
 	return { x: 1040, y: cy - 28, w: 76, h: 56 };
 }
 
 /**
- * Special-weapon icon on the pill above the third stat counter (~x
- * 1645-1692, y cy-20..cy+2). Only read to break near-tied weapon matches
- * with different specials; bounded at cy+2 to keep counter digits out.
+ * Special icon above the third stat (~x 1645-1692), read only to break near-tied weapons; bounded
+ * at cy+2 to keep digits out.
  */
 export function specialIconRoi(cy: number): Roi {
 	return { x: 1642, y: cy - 24, w: 52, h: 26 };
 }
 
-/**
- * Player name text region (white, left-aligned x=1114). Long names run
- * into paint; parse paint first and trim at its leftmost digit.
- */
+/** Name text from x=1114; long names run into paint, trim at its leftmost digit. */
 export function nameRoi(cy: number): Roi {
 	return { x: 1110, y: cy - 14, w: 208, h: 32 };
 }
@@ -63,34 +50,24 @@ export function statRoi(cy: number, index: 0 | 1 | 2): Roi {
 	return { x, y: cy + 3, w: 30, h: 22 };
 }
 
-/**
- * POV arrow on the panel left of the pill (x 977-1024). Right edge stays
- * short of the pill's rounded cap (~x 1032).
- */
+/** POV arrow left of the pill (x 977-1024), short of the pill's rounded cap (~x 1032). */
 export function povArrowRoi(cy: number): Roi {
 	return { x: 968, y: cy - 32, w: 60, h: 62 };
 }
 
-/**
- * Team point totals ("500 p") on the colored top band, ending x=1704.
- * Only read to recognize a knockout (winner total 500), not the score.
- */
+/** Team totals ("500 p") ending x=1704, read only to recognize a knockout (500). */
 export function teamScoreRoi(dy: number): Roi {
 	return { x: 1614, y: 371 + dy, w: 96, h: 38 };
 }
 
-/**
- * VICTORY/DEFEAT tag on each panel's top band — confirms which panel won
- * (observed always the top one; letters render in team ink on gray stamp).
- */
+/** VICTORY/DEFEAT tag (team ink on gray stamp); observed winner always on top. */
 export function resultTagRoi(dy: number): Roi {
 	return { x: 990, y: 358 + dy, w: 215, h: 52 };
 }
 
 /**
- * The two sides of the "Score:" banner above the panels. Left follows the
- * localized label (from x~985), right ends x~1744. A knockout replaces
- * the winning side's value with the KNOCKOUT! burst.
+ * "Score:" banner sides: left follows the localized label (x~985), right ends x~1744; a knockout
+ * replaces the winner's value.
  */
 export const MATCH_SCORE_ROIS: readonly [Roi, Roi] = [
 	{ x: 985, y: 278, w: 265, h: 40 },
@@ -98,11 +75,9 @@ export const MATCH_SCORE_ROIS: readonly [Roi, Roi] = [
 ];
 
 /**
- * Header bands on the stage-photo banner. Line 1: timestamp + stage tag
- * (rank icon on ranked lobbies shifts the left edge); line 2: lobby
- * (bold, x=809) + mode. Bands hug the tag rows tightly since the photo
- * below has bright pixels that would ink glyph bottoms; readTagBand scans
- * for the tag start (HEADER_TAG_LEAD_IN_MAX) instead of anchoring an edge.
+ * Header bands: timestamp + stage (a rank icon shifts the left edge on ranked
+ * lobbies), lobby + mode. Bands hug the tags since the photo below inks glyph
+ * bottoms; readTagBand scans for the tag start (HEADER_TAG_LEAD_IN_MAX).
  */
 export const HEADER_TOP_BAND: Roi = { x: 800, y: 74, w: 668, h: 32 };
 export const HEADER_BOTTOM_BAND: Roi = { x: 800, y: 122, w: 728, h: 46 };
@@ -110,19 +85,14 @@ export const HEADER_TAG_LEAD_IN_MAX = 40;
 /** see TagBandOptions.tagColumnFraction — the tags are subtly tilted */
 export const HEADER_TAG_COLUMN_FRACTION = 0.75;
 
-/**
- * Gate probe: strip between paint "p" (ends 1413) and first stat "x"
- * (starts 1517) is always empty pill background (near-black ~20).
- */
+/** Strip between paint "p" (ends 1413) and first stat "x" (starts 1517): empty pill background (~20). */
 export function gateDarkProbe(cy: number): Roi {
 	return { x: 1422, y: cy - 10, w: 78, h: 20 };
 }
 
 /**
- * Ink-color probes discriminate against two lookalike results screens:
- * panels' top bands and score banner are saturated team color here (109+),
- * while the live scoreboard is neutral gray and the replay browser only
- * saturated at the first spot (its own banner).
+ * Ink-color probes vs lookalikes: top bands and score banner are saturated here
+ * (109+), the live scoreboard is gray and the replay browser only saturates the first spot.
  */
 export const GATE_COLOR_PROBES: readonly Roi[] = [
 	{ x: 1300, y: 382, w: 100, h: 16 },
diff --git a/app/features/scanner/core/detectors/scoreboard-own/abilities.ts b/app/features/scanner/core/detectors/scoreboard-own/abilities.ts
index 8de287a3e..afa899d09 100644
--- a/app/features/scanner/core/detectors/scoreboard-own/abilities.ts
+++ b/app/features/scanner/core/detectors/scoreboard-own/abilities.ts
@@ -1,8 +1,4 @@
-/**
- * Ability badge templates for the personal-results gear cards. Same
- * composite-and-resize pipeline as the death panel (death/abilities.ts),
- * at this screen's smaller badge sizes and its gray-strip ink threshold.
- */
+/** Ability badge templates for the personal-results gear cards, via the death panel's pipeline. */
 import type { FrameData } from "../../image";
 import { type AbilityTemplates, buildAbilityRole } from "../death/abilities";
 import {
diff --git a/app/features/scanner/core/detectors/scoreboard-own/index.ts b/app/features/scanner/core/detectors/scoreboard-own/index.ts
index 3954e28ac..0891ba51d 100644
--- a/app/features/scanner/core/detectors/scoreboard-own/index.ts
+++ b/app/features/scanner/core/detectors/scoreboard-own/index.ts
@@ -1,14 +1,9 @@
 /**
- * ScoreboardOwnDetector: parses the personal results screen (the "your
- * results" view after a match) — lobby/mode/stage from the header tags
- * (identical to the live scoreboard header, parsing is shared), the
- * player's main weapon from the weapon card's title tag, and the own gear
- * abilities from the three gear cards' badge strips.
- *
- * The weapon arrives as text: the title is OCR'd with the death-weapon
- * atlas (the only atlas carrying the weapon-name charset) rescaled to this
- * screen's title size, then snapped against every language's main-weapon
- * names at once and reported under its canonical English name.
+ * ScoreboardOwnDetector: parses the personal results screen — header tags
+ * (shared with the live scoreboard), the main weapon from the weapon card's
+ * title (OCR'd with the death-weapon atlas, the only one with that charset,
+ * snapped against every language's names) and own gear abilities from the
+ * three gear cards' badge strips.
  */
 
 import type {
@@ -56,10 +51,7 @@ export interface ScoreboardOwnData {
 	stage: StageId | null;
 	/** the player's main weapon; null if unreadable */
 	weaponId: MainWeaponId | null;
-	/**
-	 * own gear abilities, [head, clothes, shoes] rows of
-	 * [main, sub, sub, sub] ability ids
-	 */
+	/** [head, clothes, shoes] rows of [main, sub, sub, sub] */
 	abilities: AbilityWithUnknown[][];
 }
 
@@ -73,11 +65,7 @@ interface WeaponCandidate {
 	entry: WeaponEntry;
 }
 
-/**
- * Every string the weapon card title can show: all languages' localized
- * main-weapon names plus the canonical English names (localized-messages
- * omits names identical to English).
- */
+/** Every string the title can show: all localized main-weapon names plus canonical English. */
 let weaponCandidates: WeaponCandidate[] | null = null;
 function mainWeaponCandidates(): WeaponCandidate[] {
 	if (weaponCandidates) return weaponCandidates;
@@ -162,12 +150,9 @@ export function createScoreboardOwnDetector(
 			confidences.push(header.confidence);
 		}
 
-		// Weapon card title, snapped to the main-weapon closed set. The band is
-		// recognized whole, NOT via readTagBand: the tag is fixed-width (the
-		// band lies entirely inside it, there is nothing to trim away), and the
-		// extent trim actively harms it — long names render horizontally
-		// condensed, whose dense antialiased columns fail the dark-or-bright
-		// tag-column test and truncate the read mid-name.
+		// weapon card title, recognized whole and NOT via readTagBand: the tag is
+		// fixed-width, and long names render condensed, whose dense antialiased
+		// columns fail the tag-column test and truncate the read mid-name
 		let weapon: string | null = null;
 		let weaponId: MainWeaponId | null = null;
 		let weaponScore = 0;
@@ -256,9 +241,8 @@ export function createScoreboardOwnDetector(
 		];
 	}
 
-	// just under the measured clean-read floor (fixtures 0.562-0.669,
-	// confirmed scan events 0.612-0.635 — this screen's ability-grid scores
-	// keep the mean low even on perfect reads)
+	// just under the clean-read floor (fixtures 0.562-0.669, scan events
+	// 0.612-0.635; the ability-grid scores keep the mean low even on perfect reads)
 	return {
 		id: "scoreboard-own",
 		sufficientConfidence: 0.55,
diff --git a/app/features/scanner/core/detectors/scoreboard-own/rois.ts b/app/features/scanner/core/detectors/scoreboard-own/rois.ts
index d66ad8d6d..661d105c9 100644
--- a/app/features/scanner/core/detectors/scoreboard-own/rois.ts
+++ b/app/features/scanner/core/detectors/scoreboard-own/rois.ts
@@ -1,21 +1,13 @@
 /**
- * ALL scoreboard-own ROI coordinates, in canonical 1920x1080 space.
- * Calibrated against scoreboard-own/private-battle-splat-zones-museum via
- * scripts/scanner/dump-crops.ts and column/row projection measurement.
- *
- * The personal results screen ("your results") shows the same header tags
- * as the live scoreboard (same positions, reuses its bands) over a dark
- * panel (~35) with the player's banner, medals list, and four bottom
- * cards: weapon card (yellow-bordered title tag, big render on white
- * square) then one gear card per slot, each with a gray ability strip of
- * one main badge (⌀~49) and three sub badges (⌀~38).
+ * Scoreboard-own ROIs in canonical 1920x1080 space, calibrated against the
+ * private-battle-splat-zones-museum fixture. Same header tags as the live
+ * scoreboard over a dark panel (~35); four bottom cards: weapon card (title
+ * tag, render on white) then one gear card per slot with a gray strip of one
+ * main badge (⌀~49) and three sub badges (⌀~38).
  */
 import type { Roi } from "../../canonical";
 
-/**
- * Weapon card title tag interior (black, white name left-aligned). Band
- * starts inside the tag so readTagBand's extent trim anchors immediately.
- */
+/** Weapon card title tag interior (black, white name left-aligned), recognized whole. */
 export const WEAPON_TITLE_BAND: Roi = { x: 876, y: 766, w: 200, h: 32 };
 /** Tight cap height of the title text at 1080p. */
 export const WEAPON_TITLE_TEXT_HEIGHT = 18;
@@ -30,10 +22,7 @@ const GEAR_SUB_DXS = [48, 88, 127] as const;
 export const GEAR_BADGE_CY = 927;
 export const GEAR_ROWS = 3;
 
-/**
- * Search boxes around each badge; heights double as the size filter
- * (matchTemplate skips templates taller than the ROI).
- */
+/** Search boxes around each badge; heights double as the size filter (matchTemplate skips taller templates). */
 export function gearMainRoi(row: number): Roi {
 	const cx = GEAR_MAIN_CXS[row]!;
 	return { x: cx - 32, y: GEAR_BADGE_CY - 32, w: 64, h: 64 };
@@ -47,23 +36,12 @@ export function gearSubRoi(row: number, slot: number): Roi {
 /** Template heights (px at 1080p) per badge role (main ⌀~49, sub ⌀~38). */
 export const OWN_ABILITY_MAIN_SIZES = [45, 49, 53] as const;
 export const OWN_ABILITY_SUB_SIZES = [34, 38, 42] as const;
-/**
- * Icon art diameter as fraction of badge box: ratio peaks at 1.0 for both
- * roles (art overflows the circle slightly), so the ring contributes nothing.
- */
+/** Art diameter as fraction of the badge box; peaks at 1.0 for both roles. */
 export const OWN_ABILITY_ART_RATIO = 1.0;
-/**
- * Ink threshold inside a badge box. Unlike the death panel these sit on a
- * light-gray strip (~140-155); 170 keeps the strip out while art still
- * clears it on its max channel.
- */
+/** Badges sit on a light-gray strip (~140-155); 170 keeps it out while art clears on max channel. */
 export const OWN_ABILITY_INK_THRESHOLD = 170;
 
-/**
- * Gate probes. Results panel is uniform dark (~35, edge ~54) at spots
- * dodging the banner/medals/cards; each title tag holds bright white
- * text at its left edge; the strip's gray shows after the third sub badge.
- */
+/** Gate probes on uniform dark panel (~35, edge ~54), dodging banner/medals/cards. */
 export const GATE_PANEL_PROBES: readonly Roi[] = [
 	{ x: 860, y: 245, w: 30, h: 20 },
 	{ x: 1690, y: 395, w: 30, h: 20 },
diff --git a/app/features/scanner/core/detectors/scoreboard/banner.ts b/app/features/scanner/core/detectors/scoreboard/banner.ts
index c2715095a..8c3de4b75 100644
--- a/app/features/scanner/core/detectors/scoreboard/banner.ts
+++ b/app/features/scanner/core/detectors/scoreboard/banner.ts
@@ -1,15 +1,11 @@
 /**
- * "Score:" banner parsing for the results screens. Each side of the colored
- * banner shows one team's game score (0-100) as white BlitzBold digits after
- * a localized label — some languages render no label at all, so the digits'
- * x position is not fixed. A knockout replaces the winning side's value with
- * the localized KNOCKOUT! burst, whose letters only weakly match digit
- * templates (real digits score 0.9+); the knockout itself is recognized from
- * the winner's team total instead (the box prints the count times five, and
- * only a knockout's full 100 count reaches 500). The score value bounces as
- * it lands, so a frame may catch the digits settled or mid-pop — this module
- * parses at every size and binarization threshold and keeps the best
- * read (valid over none, longer digit run over shorter, then confidence).
+ * "Score:" banner parsing: each side shows a team's score (0-100) as white
+ * BlitzBold digits after a localized label (some languages have none, so x is
+ * not fixed). A knockout replaces the winner's value with the KNOCKOUT! burst
+ * (weak digit matches; real digits score 0.9+) and is recognized from the
+ * winner's team total instead (count x5; only a full 100 reaches 500). Digits
+ * bounce as the value lands, so every size and threshold is parsed and the best
+ * read kept (valid over none, longer run over shorter, then confidence).
  */
 import { getCV, type Mat } from "../../cv";
 import {
@@ -24,24 +20,17 @@ import { copyRoi, type Roi } from "../../image";
 export const KO_MATCH_SCORE = 100;
 
 /**
- * The team box prints the count times five ("440 p" alongside a 88 banner),
- * so a knockout's full 100 count shows as 500 — a total only a knockout
- * reaches, which is what separates a burst-covered banner from an unread one.
+ * The team box prints count x5 ("440 p" for 88), so only a knockout reaches 500; separates a
+ * burst-covered banner from an unread one.
  */
 export const FULL_COUNT_TEAM_SCORE = KO_MATCH_SCORE * 5;
 
-/**
- * Replay-screen reads below this floor are discarded rather than trusted as
- * a score — burst/label letters overlapping a score ROI match digit
- * templates at ~0.4 there.
- */
+/** Replay-screen reads below this are discarded: burst/label letters match digit templates at ~0.4 there. */
 export const MATCH_SCORE_MIN_CONF = 0.6;
 
 /**
- * Char floor for the live banner's trailing-digit run. KNOCKOUT! letters
- * have matched digit templates at up to 0.62 (the ko-hagglefish fixture's
- * "07"), while genuine banner digits score 0.79+ across every fixture —
- * including 720p upscales.
+ * Char floor for the trailing-digit run: KNOCKOUT! letters reach 0.62 (ko-hagglefish "07"), real
+ * digits 0.79+ on every fixture.
  */
 const DIGIT_MIN_CONF = 0.75;
 
@@ -49,44 +38,28 @@ const DIGIT_MIN_CONF = 0.75;
 const BANNER_SCORE_BIN_THRESHOLD = 205;
 
 /**
- * Second binarization pass for pale team colors: a light banner (gray ~220,
- * with the wave-crest highlight brighter still) binarizes solid white at the
- * base threshold, gluing label and digits into one giant unmatchable blob
- * that can swallow all but the last digit. Only the ~250 digit ink survives
- * this threshold. Every pass always runs; a swallowed background can only
- * shorten the digit run, never lengthen it, so the longer run wins
- * regardless of confidence (the truncated read's surviving digit is genuine
- * ink and scores just as well).
+ * Second pass for pale banners (gray ~220): the base threshold glues label and
+ * digits into one blob, swallowing all but the last digit; only ~250 digit ink
+ * survives this. A swallowed background can only shorten the run, so the
+ * longer run wins regardless of confidence.
  */
 const BANNER_SCORE_BRIGHT_BIN_THRESHOLD = 240;
 
 /**
- * Third pass for the brightest banners: a yellow battle-log banner grays at
- * ~245 near the wave crest, so even the bright pass keeps label ink attached
- * and erodes the digits below the confidence floor. Only the ~250 digit
- * cores survive this threshold.
+ * Third pass: a yellow battle-log banner grays at ~245 near the wave crest; only the ~250 digit
+ * cores survive this.
  */
 const BANNER_SCORE_BRIGHTEST_BIN_THRESHOLD = 248;
 
-/**
- * Digits of one number nearly touch; anything further apart than this
- * fraction of a digit width is the label (or an unreadable glyph) ending
- * the run.
- */
+/** Digits of one number nearly touch; a gap past this fraction of a digit width ends the run. */
 const DIGIT_GAP_MAX_RATIO = 0.55;
 
-/**
- * A score digit spans the set's full height; the label's lowercase letters
- * top out ~0.75 of it, so they cannot pass as digits even when their shapes
- * correlate.
- */
+/** Digits span the set's full height; the label's lowercase letters top out ~0.75 of it. */
 const DIGIT_MIN_HEIGHT_RATIO = 0.82;
 
 /**
- * The banner's bright wave-crest highlight can dip into the score line as a
- * wide ~12px-tall streak whose columns merge into the digits' segments and
- * ruin their ink extents. Every real digit is at least ~26px tall, so ink
- * components shorter than this are wiped before recognition.
+ * The wave-crest highlight dips into the score line as a ~12px streak merging into digit segments;
+ * real digits are ~26px+ tall.
  */
 const MIN_COMPONENT_HEIGHT = 20;
 
@@ -109,13 +82,9 @@ const EMPTY_READ: BannerScoreRead = {
 };
 
 /**
- * Reads one banner side's score from `roi`: recognizes with each digit set
- * (one per on-screen text size) at each binarization threshold and keeps
- * the best read — a valid value beats none, a longer digit run beats a
- * shorter one, confidence breaks ties. The score is the trailing run of
- * full-height, confidently-matched digits — everything the localized label
- * or the KNOCKOUT! burst leaves in the ROI fails at least one of those
- * tests.
+ * One banner side's score: each digit set at each threshold, best read kept
+ * (isBetterRead). The score is the trailing run of full-height, confident
+ * digits; label and burst leftovers fail at least one of those tests.
  */
 export function parseBannerScore(
 	gray: Mat,
@@ -145,13 +114,9 @@ export function parseBannerScore(
 }
 
 /**
- * Winner-first score pair from the two banner sides. A confirmed knockout
- * (winner team total = 500) dominates: the winner reports the full count no
- * matter what was read off the burst-covered side, and the loser is the
- * more confident read (genuine digits score well clear of burst letters
- * that survive the floor). Without a knockout, ranked scores never tie, so
- * when both sides read the higher value is the winner's; one unreadable
- * side cannot be attributed to a team, so nothing is reported.
+ * Winner-first score pair. A confirmed knockout dominates: winner = full count,
+ * loser = the more confident read. Otherwise ranked scores never tie so the
+ * higher value is the winner's; one unreadable side reports nothing.
  */
 export function resolveMatchScores({
 	left,
@@ -212,11 +177,7 @@ function clearShortBlobs(band: Mat): void {
 	labels.delete();
 }
 
-/**
- * Read preference shared by every multi-attempt digit read: a valid value
- * beats none, a longer digit run beats a shorter one, confidence breaks
- * ties.
- */
+/** A valid value beats none, a longer digit run beats a shorter one, confidence breaks ties. */
 export function isBetterRead(
 	read: BannerScoreRead,
 	best: BannerScoreRead,
@@ -232,10 +193,8 @@ export interface TrailingDigitOptions {
 	/** char floor a glyph must clear to count as a digit of the number */
 	minCharScore?: number;
 	/**
-	 * lower floor for digits joining a run that another digit anchors at
-	 * `minCharScore` — motion blur / compression can erode one digit of a
-	 * genuine number below the main floor while its neighbor stays crisp.
-	 * Defaults to `minCharScore` (no two-tier extension).
+	 * lower floor for digits joining a run anchored by a `minCharScore` digit
+	 * (blur can erode one digit while its neighbor stays crisp); defaults to `minCharScore`
 	 */
 	extendMinScore?: number;
 	/** min ink height as a fraction of the set height (drops labels, '+') */
@@ -243,22 +202,14 @@ export interface TrailingDigitOptions {
 	/** values above this are rejected as misreads */
 	maxValue?: number;
 	/**
-	 * reject the read (null) when the char immediately left of the run sat
-	 * within digit-gap distance but failed the floors — on a band that holds
-	 * nothing but the number (objective counter plates), that char is a
-	 * blur-mangled leading digit and the run is a truncated misread ("50"
-	 * returning 0). Off for banner bands, where an adjacent label/burst
-	 * letter legitimately borders the digits.
+	 * reject the read when a char within digit-gap distance left of the run failed
+	 * the floors: on a number-only band that is a mangled leading digit ("50" as
+	 * 0). Off for banners, where a label/burst letter legitimately borders the digits.
 	 */
 	rejectTruncated?: boolean;
 }
 
-/**
- * The trailing run of full-height, confidently-matched digits of a
- * recognized line — the number-on-a-plate read shared by the score banner
- * and the objective counters, where a localized label / burst / '+' sign
- * precedes the digits and must fail at least one of the floors.
- */
+/** Trailing run of full-height, confident digits; shared by the score banner and objective counters. */
 export function trailingDigitRun(
 	raw: RecognizedText,
 	set: GlyphSet,
@@ -289,9 +240,8 @@ export function trailingDigitRun(
 	if (!run.some((c) => c.score >= minCharScore)) {
 		return { ...EMPTY_READ, reading: raw.text };
 	}
-	// A further digit left of the run means an unreadable glyph split the
-	// number (turf war percentages read "48", ".", "7") — the tail is not
-	// the score.
+	// a further digit left of the run means an unreadable glyph split the number
+	// (turf war "48", ".", "7"); the tail is not the score
 	for (let k = i; k >= 0; k--) {
 		const c = raw.chars[k]!;
 		if (c.score >= minCharScore && fullHeight(c)) {
diff --git a/app/features/scanner/core/detectors/scoreboard/digits.ts b/app/features/scanner/core/detectors/scoreboard/digits.ts
index 2abe4e296..d025ea049 100644
--- a/app/features/scanner/core/detectors/scoreboard/digits.ts
+++ b/app/features/scanner/core/detectors/scoreboard/digits.ts
@@ -1,6 +1,4 @@
-/**
- * Number field parsing on top of glyph recognition.
- */
+/** Number field parsing on top of glyph recognition. */
 import type { Mat } from "../../cv";
 import {
 	type GlyphSet,
@@ -17,11 +15,7 @@ export interface ParsedNumber {
 	raw: RecognizedText;
 }
 
-/**
- * Digits share a cap line; a lowercase suffix ("p") starts at x-height,
- * ~7px lower at the sizes we parse. A trailing char whose ink top sits at
- * least this far below the other chars' top line is the suffix, not a digit.
- */
+/** A lowercase "p" suffix starts ~7px below the digits' cap line; a trailing char this far down is the suffix. */
 const LOWERED_TRAILING_MIN_PX = 5;
 
 export function parseNumber(
@@ -34,9 +28,7 @@ export function parseNumber(
 		minCharScore: 0.3,
 		binThreshold: options.binThreshold,
 	});
-	// The replay paint column is left-aligned, so its "p" suffix moves with
-	// the digit count and can land inside the ROI, where the digit-only
-	// charset misreads it (a "6"). The geometry still tells it apart.
+	// the replay paint's "p" suffix can land inside the ROI and misread as a "6"
 	let chars = raw.chars;
 	if (options.dropLoweredTrailing && chars.length > 1) {
 		const capY0 = Math.min(...chars.slice(0, -1).map((c) => c.y0));
diff --git a/app/features/scanner/core/detectors/scoreboard/header.ts b/app/features/scanner/core/detectors/scoreboard/header.ts
index 03c7bd307..d5bb61711 100644
--- a/app/features/scanner/core/detectors/scoreboard/header.ts
+++ b/app/features/scanner/core/detectors/scoreboard/header.ts
@@ -1,12 +1,8 @@
 /**
- * Header parsing: lobby type ("X Battle"), mode ("Splat Zones") and stage
- * ("Scorch Gorge") from the black tags above the team boxes.
- *
- * Tags auto-size to their text, so the stage's x position depends on mode
- * length. Each band is trimmed to the tag extent (near-black bg + white
- * text; the map thumbnail around it is mid-brightness), then OCR'd as one
- * line and snapped against every language's mode × stage combos
- * (core/localized.ts) — reported values are always sendou.ink ids.
+ * Header parsing: lobby, mode and stage from the black tags above the team
+ * boxes. Tags auto-size, so each band is trimmed to the tag extent (near-black
+ * bg + white text vs the mid-brightness thumbnail), OCR'd as one line and
+ * snapped against every language's mode × stage combos (core/localized.ts).
  */
 import type { ModeShort, StageId } from "~/modules/in-game-lists/types";
 import type { ScannerLobby } from "../../../scanner-types";
@@ -46,10 +42,8 @@ const TAG_BRIGHT_MIN = 165;
 const TAG_GAP_TOLERANCE = 6;
 
 /**
- * Trim a band crop to the black-tag extent: the longest run of tag columns
- * starting within `maxLeadIn` of the left edge (a dark photo edge can fake
- * a short run before the real tag), each run extended right until the tag
- * ends. Returns a zero-width range when no tag is present at all.
+ * Longest run of tag columns starting within `maxLeadIn` of the left edge (a
+ * dark photo edge can fake a short run first); zero-width when no tag.
  */
 function tagExtent(
 	crop: Mat,
@@ -94,31 +88,17 @@ function tagExtent(
 
 export interface TagBandOptions extends RecognizeOptions {
 	/**
-	 * Dark ceiling for the tag-extent trim. Lifted-blacks captures (720p
-	 * streams upscaled and re-encoded) raise the tag background above the
-	 * default, truncating the trim to a sliver — callers whose closed-set
-	 * snap fails retry with a lifted ceiling.
+	 * dark ceiling for the extent trim; lifted-blacks captures truncate the trim to a sliver, so
+	 * callers retry with a lifted one
 	 */
 	tagDarkMax?: number;
-	/**
-	 * Non-tag columns tolerated before the tag begins. The battle log tags
-	 * are not left-anchored (a leading rank icon shifts line 1 per lobby
-	 * type), so its bands start on the stage photo and scan for the tag.
-	 */
+	/** non-tag columns tolerated before the tag; battle log tags are not left-anchored (a rank icon shifts line 1) */
 	tagLeadInMax?: number;
-	/**
-	 * Tag-like row fraction a column must reach. The battle log tags are
-	 * subtly tilted, so a horizontal band always catches a few photo rows
-	 * above or below the box — those bands pass a looser fraction.
-	 */
+	/** tag-like row fraction a column must reach; battle log tags are tilted so their bands catch photo rows */
 	tagColumnFraction?: number;
 }
 
-/**
- * OCR one header band: trim the crop to the black-tag extent, then
- * recognize it as a single line. Shared with the scoreboard-battle-log-replay
- * header, whose tags have the same style at different positions/sizes.
- */
+/** OCR one header band: trim to the black-tag extent, recognize as a single line. */
 export function readTagBand(
 	gray: Mat,
 	band: { x: number; y: number; w: number; h: number },
diff --git a/app/features/scanner/core/detectors/scoreboard/index.ts b/app/features/scanner/core/detectors/scoreboard/index.ts
index 0e9ae892c..4cae37774 100644
--- a/app/features/scanner/core/detectors/scoreboard/index.ts
+++ b/app/features/scanner/core/detectors/scoreboard/index.ts
@@ -60,17 +60,11 @@ export interface ScoreboardData {
 	lobby: ScannerLobby | null;
 	mode: ModeShort | null;
 	stage: StageId | null;
-	/**
-	 * the "Score:" banner game scores, [winner, loser]; a knockout's winner
-	 * reports 100 (the burst hides the real banner)
-	 */
+	/** "Score:" banner scores, [winner, loser]; a knockout's winner reports 100 (the burst hides the banner) */
 	matchScores: [number | null, number | null];
 	/** 8 players: rows 0-3 winning team, rows 4-7 losing team */
 	players: ScoreboardPlayer[];
-	/**
-	 * index into `players` of the recording player's row, marked by the
-	 * yellow arrow; null when no arrow is found (spectator/overhead footage)
-	 */
+	/** index into `players` of the yellow-arrow row; null when none (spectator footage) */
 	povIndex: number | null;
 }
 
@@ -88,95 +82,70 @@ export interface ScoreboardRowDebug {
 export interface ScoreboardResources {
 	weapons: WeaponTemplate[];
 	/**
-	 * Weapon renders prepared for the in-match icon strip (objective's
-	 * StripWeapons evidence). Optional: without them the strip slot →
-	 * scoreboard row assignment falls back to as-drawn order.
+	 * Renders for the in-match icon strip (StripWeapons); without them slot → row assignment falls
+	 * back to as-drawn order.
 	 */
 	stripWeapons?: WeaponTemplate[] | null;
 	/**
-	 * Special-weapon silhouettes (assets/cv/specials). Optional: without
-	 * them, near-tied weapon icons (Splash- vs Sploosh-o-matic) stay decided
-	 * by icon score alone.
+	 * Special silhouettes (assets/cv/specials); without them near-tied icons (Splash- vs
+	 * Sploosh-o-matic) stay decided by icon score.
 	 */
 	specials?: SpecialTemplate[] | null;
 	/** digit templates at paint size (h~28); team scores reuse these, scaled */
 	paintDigits: GlyphSet | null;
 	/** digit templates at stat-counter size (h~17) */
 	statDigits: GlyphSet | null;
-	/**
-	 * digit templates for team totals (h~33, outlined, on team-color box).
-	 * Optional: falls back to scaled paint digits, at reduced accuracy.
-	 */
+	/** digit templates for team totals (h~33, outlined, on team-color box); falls back to scaled paint digits */
 	teamDigits: GlyphSet | null;
 	nameGlyphs: GlyphSet | null;
 	/** header tag glyphs: lobby line, and the mode+stage line */
 	headerLobbyGlyphs: GlyphSet | null;
 	headerLineGlyphs: GlyphSet | null;
 	/**
-	 * Replay-browser extras (FOT-RowdyStd face, unlike everything above):
-	 * the replay code line, and the VICTORY/DEFEAT panel tags. Optional:
-	 * the replay detector falls back to rescaled name/header glyphs, at
-	 * reduced accuracy.
+	 * Replay-browser extras in FOT-RowdyStd (code line, VICTORY/DEFEAT tags); falls back to
+	 * rescaled name/header glyphs.
 	 */
 	replayCodeGlyphs?: GlyphSet | null;
 	replayResultGlyphs?: GlyphSet | null;
 	/**
-	 * Death-screen extras. Optional: the death detector skips the fields it
-	 * has no resources for. The weapon atlas carries both Blitz faces; the
-	 * tag-name atlas is BlitzBold + Rowdy (kana).
+	 * Death-screen extras; missing ones skip their fields. Weapon atlas = both Blitz faces;
+	 * tag-name = BlitzBold + Rowdy (kana).
 	 */
 	abilities?: import("../death/abilities").AbilityTemplates | null;
 	deathWeaponGlyphs?: GlyphSet | null;
 	/**
-	 * JA death-message glyphs (Kurokane/Rowdy condensed + fixture crops),
-	 * built at the on-screen text's native size. Optional: without them JA
-	 * death screens fail the constant-line confirmation and emit nothing.
+	 * JA death-message glyphs at native size (Kurokane/Rowdy condensed + fixture crops); without
+	 * them JA death screens emit nothing.
 	 */
 	deathWeaponJaGlyphs?: GlyphSet | null;
 	deathTagNameGlyphs?: GlyphSet | null;
 	/**
-	 * The main-weapon icons again, rebuilt at the death burst's icon size
-	 * (~124px vs the rows' 40-64px). Optional: without them the death
-	 * detector cannot recover the killer's weapon when the message text is
-	 * unreadable (e.g. the WIPEOUT banner covering the weapon name line).
+	 * Main-weapon icons at the death burst's size (~124px); without them an unreadable message
+	 * (WIPEOUT banner) loses the weapon.
 	 */
 	deathBurstWeapons?: WeaponTemplate[] | null;
-	/**
-	 * Personal-results extras: the same ability icons rebuilt at the gear
-	 * cards' badge sizes (scoreboard-own/abilities.ts). Optional: without
-	 * them the scoreboard-own detector skips the ability grid.
-	 */
+	/** Ability icons at the personal-results gear cards' badge sizes; without them the ability grid is skipped. */
 	ownAbilities?: import("../death/abilities").AbilityTemplates | null;
 	/**
-	 * Map-start intro extras: the big BlitzBold mode title, and the BlitzMain
-	 * stage name (whose atlas also reads the "MODE" label, rescaled).
-	 * Optional: without them the map-start detector emits nothing.
+	 * Map-start extras: BlitzBold mode title, BlitzMain stage name (also reads the "MODE" label
+	 * rescaled); without them map-start emits nothing.
 	 */
 	mapStartModeGlyphs?: GlyphSet | null;
 	mapStartStageGlyphs?: GlyphSet | null;
 	/**
-	 * Minimap extras (minimap/rois.ts documents the screen): the main-weapon
-	 * icons composited on the card-pill background for the teammate cards'
-	 * light silhouettes, a light-background variant for highlighted enemy
-	 * rows, and the ability icons at the cards' badge size. Optional: without
-	 * them the minimap detector skips the corresponding fields (enemy rows
-	 * fall back to the standard `weapons` set). Names reuse `nameGlyphs`.
+	 * Minimap extras: main-weapon icons on the card-pill background, a
+	 * light-background variant for special-ready camo, and ability icons at the
+	 * cards' badge size. Missing ones skip their fields; names reuse `nameGlyphs`.
 	 */
 	minimapCardWeapons?: WeaponTemplate[] | null;
 	minimapLightWeapons?: WeaponTemplate[] | null;
 	minimapAbilities?: WeaponTemplate[] | null;
 	/**
-	 * Sub-weapon silhouettes (assets/cv/sub-weapons) at the minimap sub
-	 * tile's sizes. Optional: without them, near-tied minimap weapon icons
-	 * whose kits differ only by sub (plain vs Custom Dualie Squelchers) stay
-	 * decided by icon score alone.
+	 * Sub silhouettes at the minimap sub tile's sizes; without them near-tied icons differing only
+	 * by sub stay decided by icon score.
 	 */
 	minimapSubWeapons?: SpecialTemplate[] | null;
-	/**
-	 * Planner-map structural signatures (assets/cv/planner) used by the
-	 * minimap detector to identify the stage. Optional: without them the
-	 * minimap event's `stage` stays null.
-	 */
+	/** Planner-map signatures (assets/cv/planner) for minimap stage identification; without them `stage` stays null. */
 	plannerStages?: import("../minimap/stage").PlannerStage[] | null;
 }
 
@@ -269,15 +238,12 @@ export function createScoreboardDetector(
 			confidences.push(header.confidence);
 		}
 
-		// The winner's team total is read only to recognize a knockout: the
-		// box prints the count times five, and only a knockout's full 100
-		// count reaches 500 (the banner value it would confirm is hidden
-		// under the KNOCKOUT! burst).
+		// the winner's total is read only to recognize a knockout: only a full 100
+		// count reaches 500, and the banner value is hidden under the KNOCKOUT! burst
 		let knockout = false;
 		let winnerTotalConf = 0;
 		if (teamDigits) {
-			// The total sits on the team-colored box (light swirl pattern),
-			// so binarize more aggressively than on the black pills.
+			// the total sits on the team-colored swirl box, so binarize higher than on black pills
 			const crop = cropRoi(gray, TEAM_SCORE_ROIS[0]);
 			const winnerTotal = parseNumber(crop, teamDigits, {
 				binThreshold: 175,
@@ -327,8 +293,7 @@ export function createScoreboardDetector(
 		];
 	}
 
-	// just under the measured clean-read floor (fixtures 0.865-0.899,
-	// confirmed scan events down to 0.799)
+	// just under the clean-read floor (fixtures 0.865-0.899, scan events down to 0.799)
 	return {
 		id: "scoreboard",
 		sufficientConfidence: 0.79,
diff --git a/app/features/scanner/core/detectors/scoreboard/kits.ts b/app/features/scanner/core/detectors/scoreboard/kits.ts
index 4705a6b48..cd6ccf702 100644
--- a/app/features/scanner/core/detectors/scoreboard/kits.ts
+++ b/app/features/scanner/core/detectors/scoreboard/kits.ts
@@ -1,10 +1,7 @@
 /**
- * Main-weapon kits (sub + special ids) keyed by in-game main weapon id,
- * derived directly from sendou.ink's weapon params (no generated copy).
- * Special ids match assets/cv/specials/<id>.png; the results scoreboard
- * shows each player's special icon above the specials counter, which lets
- * near-tied weapon icon matches be disambiguated by kit. The minimap's
- * sub-tile disambiguation (assets/cv/sub-weapons) reads `sub` the same way.
+ * Main-weapon kits (sub + special ids) keyed by main weapon id, derived from
+ * sendou.ink's weapon params. Ids match assets/cv/specials and
+ * assets/cv/sub-weapons; used to disambiguate near-tied weapon icons by kit.
  */
 import { weaponParams } from "~/features/build-analyzer/data/weapon-params";
 import type {
diff --git a/app/features/scanner/core/detectors/scoreboard/names.ts b/app/features/scanner/core/detectors/scoreboard/names.ts
index 3a9f31868..fc60c2634 100644
--- a/app/features/scanner/core/detectors/scoreboard/names.ts
+++ b/app/features/scanner/core/detectors/scoreboard/names.ts
@@ -1,6 +1,4 @@
-/**
- * Player name recognition: glyph matching over the name ROI.
- */
+/** Player name recognition: glyph matching over the name ROI. */
 import { getCV, type Mat } from "../../cv";
 import {
 	type GlyphSet,
@@ -17,25 +15,17 @@ export interface ParsedName {
 }
 
 /**
- * BlitzMain renders 'I', 'l', '|', and '1' as near-identical bars — no pixel
- * evidence separates them, so fall back to context, by decreasing weight of
- * evidence: a bar next to a lowercase letter is overwhelmingly an 'l' in
- * latin names ("Olise"), next to a digit it's a '1' ("Jrod_14"), next to an
- * uppercase letter it's an 'I' ("SHIP"), a bare bar hanging off an
- * underscore is a numbered-alt suffix ("gori_1"), and with no latin/digit
- * context at all (kana, symbols, edges) 'l' is the common case in the wild.
- * (This will genuinely miss e.g. "McIntosh", but so would a human reading
- * the pixels.)
+ * BlitzMain renders 'I', 'l', '|', '1' as near-identical bars, so context
+ * decides: next to lowercase 'l' ("Olise"), digit '1' ("Jrod_14"), uppercase
+ * 'I' ("SHIP"), off an underscore '1' ("gori_1"), else 'l'. Misses "McIntosh",
+ * but so would a human reading the pixels.
  */
 const BAR_CHARS = new Set(["I", "l", "|", "1"]);
 
 function normalizeBars(name: string): string {
 	const chars = [...name];
-	// Context is the nearest NON-BAR char within the word: consecutive bars
-	// ("ll" in "Chill") must all resolve from the same real-letter neighbor,
-	// not from each other's arbitrary raw reading. Underscores bound words
-	// like spaces do — "gori_1"'s lowercase must not leak across the
-	// separator onto the suffix.
+	// context is the nearest NON-BAR char within the word ("ll" in "Chill" must
+	// resolve from the same neighbor); underscores bound words like spaces
 	const neighbor = (i: number, step: -1 | 1): string | undefined => {
 		for (let j = i + step; j >= 0 && j < chars.length; j += step) {
 			const c = chars[j]!;
@@ -64,12 +54,8 @@ function normalizeBars(name: string): string {
 }
 
 /**
- * The kana long-vowel bar 'ー' and the ASCII hyphen '-' are horizontal-bar
- * homoglyphs the same way the vertical bars are: both are a single
- * horizontal stroke whose length difference drowns in capture blur, so
- * which template wins is noise ("ドラグ-ン"). Resolve by script context —
- * a kana neighbor reads 'ー', a Latin/digit neighbor reads '-', and with
- * no context the raw pick stands.
+ * Kana 'ー' and hyphen '-' are homoglyphs under capture blur ("ドラグ-ン"):
+ * a kana neighbor reads 'ー', a Latin/digit neighbor '-', else the raw pick stands.
  */
 const LONG_BAR_CHARS = new Set(["-", "ー"]);
 
@@ -100,12 +86,9 @@ function normalizeLongBars(name: string): string {
 }
 
 /**
- * BlitzMain's 'O' and '0' are the same rounded box at capture fidelity —
- * which template wins is noise — so, like the bars, resolve by context via
- * the nearest unambiguous neighbor in the word: a digit neighbor keeps '0',
- * an uppercase neighbor reads 'O' ("AHOO"), after a lowercase letter it's a
- * stylized digit ("y0s"), and word-initial before lowercase it's a
- * capitalized name ("Olise").
+ * BlitzMain's 'O' and '0' are the same box at capture fidelity: a digit neighbor
+ * keeps '0', uppercase reads 'O' ("AHOO"), after lowercase '0' ("y0s"),
+ * word-initial before lowercase 'O' ("Olise").
  */
 function normalizeOhs(name: string): string {
 	const chars = [...name];
@@ -138,13 +121,10 @@ function normalizeOhs(name: string): string {
 }
 
 /**
- * The round dots '.', '・', and '·' tight-crop to near-identical blobs, so
- * which template wins is noise. Vertical position decides in one direction
- * only: a period sits on the baseline, so a dot floating well above it
- * cannot be '.' — reread it as the best-scoring middle-dot candidate. The
- * reverse does not hold: BlitzMain draws '・' ON the baseline in some names
- * (scoreboard/robot row 5, "..・"), so baseline dots stay with the template
- * ranking, where the exact fixture crops separate the sizes.
+ * '.', '・', '·' tight-crop to near-identical blobs. A dot floating well above
+ * the baseline cannot be '.', so it rereads as the best middle-dot candidate;
+ * the reverse does not hold (BlitzMain draws '・' ON the baseline in some names,
+ * scoreboard/robot row 5), so baseline dots keep the template ranking.
  */
 const DOT_CHARS = new Set([".", "・", "·"]);
 const DOT_BASELINE_SLACK_PX = 3;
@@ -172,15 +152,11 @@ function fixRaisedDots(raw: RecognizedText): RecognizedText {
 }
 
 /**
- * On soft captures BlitzMain's 'b' and 'h' come down to whether the bowl
- * closes at the bottom, and template correlation weighs that stroke too
- * lightly to be trusted (a font 'h' beats a fixture 'b' by ~0.003 on a true
- * 'b'). The segment's own pixels decide: the bottom band between the stems
- * is solid ink in a 'b' (the bowl floor) and empty in an 'h' (open legs) —
- * measured 0.90 vs 0.15 across fixtures. Only near-tied twin reads are
- * re-decided; confident reads keep the template pick. Small text is exempt:
- * below ~20px of ink height the blur closes a true 'h' too (a 15px 'h'
- * measured 0.67), so the pixels only outrank the templates at row scale.
+ * On soft captures 'b' vs 'h' comes down to the bowl floor, which correlation
+ * weighs too lightly (font 'h' beats fixture 'b' by ~0.003 on a true 'b'). The
+ * bottom band between the stems is solid in a 'b', empty in an 'h' (0.90 vs
+ * 0.15). Only near-ties are re-decided, and only above ~20px ink height: blur
+ * closes a true 'h' below that (15px 'h' measured 0.67).
  */
 const BH_TWINS: Record<string, string> = { b: "h", h: "b" };
 const BH_SCORE_MARGIN = 0.08;
@@ -234,14 +210,9 @@ function resolveBhByBowlFloor(
 }
 
 /**
- * BlitzMain's 'P' and 'p' tight-crop to the same stem-and-bowl shape, so the
- * template scores between them are noise — but unlike the bars and ohs the
- * pixels do decide: 'p' hangs below the baseline while 'P' sits on it. The
- * templates lose that position, the segment keeps it. Take the baseline as
- * the median ink bottom of the non-twin glyphs (most chars rest exactly on
- * it, so the median shrugs off real descenders and symbols) and pick the
- * case by whether the segment descends past it. Skipped when no other glyph
- * anchors the baseline.
+ * 'P' and 'p' tight-crop to the same shape, but the segment keeps the position
+ * the templates lose: 'p' hangs below the baseline (median ink bottom of the
+ * non-twin glyphs, which shrugs off real descenders). Skipped with no anchor glyph.
  */
 const DESCENDER_TWINS: Record<string, [upper: string, lower: string]> = {
 	P: ["P", "p"],
diff --git a/app/features/scanner/core/detectors/scoreboard/pov.ts b/app/features/scanner/core/detectors/scoreboard/pov.ts
index dda76ebc6..68d6e21fd 100644
--- a/app/features/scanner/core/detectors/scoreboard/pov.ts
+++ b/app/features/scanner/core/detectors/scoreboard/pov.ts
@@ -1,10 +1,8 @@
 /**
- * POV arrow detection: both results screens mark the recording player's row
- * with a solid yellow arrow at the row's left edge (absent in spectator or
- * overhead footage). The arrow is the only saturated pure-yellow blob in
- * that strip — team-ink yellows there are patterned/duller and stay under
- * the mask thresholds — so a plain color-mask pixel count decides, no
- * template needed.
+ * POV arrow detection: the recording player's row carries a solid yellow arrow
+ * at its left edge (absent on spectator footage). It is the only saturated
+ * pure-yellow blob there (team-ink yellows are duller), so a color-mask pixel
+ * count decides.
  */
 import { getCV, type Mat } from "../../cv";
 import { cropRoi, type Roi } from "../../image";
@@ -17,10 +15,7 @@ const YELLOW_RG_MAX_DIFF = 60;
 
 /** Arrow pixels fill ~15-30% of the probe ROI; arrow-less rows measure ~0. */
 const POV_MIN_FRACTION = 0.05;
-/**
- * If the runner-up row reaches this share of the best row's fraction, the
- * yellow is ambient (team ink leaking into the strip), not the arrow.
- */
+/** A runner-up row at this share of the best means ambient team-ink yellow, not the arrow. */
 const POV_RUNNER_UP_MAX_RATIO = 0.5;
 
 /** Fraction of `roi` pixels that are arrow-yellow. `rgb` is a 3-channel RGB mat. */
@@ -50,10 +45,7 @@ export function povYellowFraction(rgb: Mat, roi: Roi): number {
 	return n > 0 ? yellow / n : 0;
 }
 
-/**
- * Pick the arrow row from per-row yellow fractions: the best row must clear
- * POV_MIN_FRACTION and stand clear of the runner-up; null means no arrow.
- */
+/** Arrow row from per-row yellow fractions; null when none clears POV_MIN_FRACTION or the runner-up is close. */
 export function findPovIndex(fractions: readonly number[]): number | null {
 	let best = -1;
 	for (let i = 0; i < fractions.length; i++) {
diff --git a/app/features/scanner/core/detectors/scoreboard/rois.ts b/app/features/scanner/core/detectors/scoreboard/rois.ts
index 9e76b8281..0c5774d04 100644
--- a/app/features/scanner/core/detectors/scoreboard/rois.ts
+++ b/app/features/scanner/core/detectors/scoreboard/rois.ts
@@ -1,33 +1,21 @@
 /**
- * ALL scoreboard ROI coordinates, in canonical 1920x1080 space.
- * Calibrated against scoreboard/xbattle-splat-zones-ko via
- * scripts/scanner/overlay-rois.ts and column-projection measurement.
- *
- * The results-screen scoreboard is a fixed-layout panel on the right side:
- * two team boxes (top = winner, bottom = loser), 4 dark "pill" rows each,
- * white text on the pills. Per row, left to right: avatar, weapon icon,
- * name (left-aligned from x=1125), paint ("842p", digits right-aligned
- * ending at x=1409, constant "p" glyph at 1411-1424), three stat counters
- * ("x12", zero-padded 2 digits) under the splat/death/special icons.
+ * Scoreboard ROIs in canonical 1920x1080 space, calibrated against the
+ * xbattle-splat-zones-ko fixture. Right-side panel: two team boxes (winner on
+ * top), 4 dark pill rows each; per row: avatar, weapon icon, name (from
+ * x=1125), paint ("842p", digits ending x=1409, "p" at 1411-1424), three
+ * zero-padded stat counters.
  */
 import type { Roi } from "../../canonical";
 
 /** Vertical centers of the 8 player rows: 4 winner rows, then 4 loser rows. */
 export const ROW_CENTERS = [416, 482, 547, 613, 770, 836, 901, 967] as const;
 
-/**
- * Weapon icon search region within a row. matchTemplate skips templates
- * taller than the region, so 56px fits the largest live icon while
- * excluding replay-browser template sizes.
- */
+/** 56px fits the largest live icon while excluding replay-browser template sizes. */
 export function weaponRoi(cy: number): Roi {
 	return { x: 1054, y: cy - 28, w: 67, h: 56 };
 }
 
-/**
- * Player name text region (white, left-aligned x=1126). Long names run
- * into the paint column; parse paint first and trim at its leftmost digit.
- */
+/** Name text from x=1126; long names run into paint, trim at its leftmost digit. */
 export function nameRoi(cy: number): Roi {
 	return { x: 1122, y: cy - 14, w: 208, h: 32 };
 }
@@ -48,35 +36,25 @@ export function statRoi(cy: number, index: 0 | 1 | 2): Roi {
 	return { x, y: cy + 1, w: 32, h: 23 };
 }
 
-/**
- * Special-weapon icon above the specials counter (~22px art, team ink
- * color). Bounded at cy+1 so counter digits stay out of the binarized shape.
- */
+/** Special icon above the specials counter (~22px, team ink); bounded at cy+1 to keep digits out. */
 export function specialIconRoi(cy: number): Roi {
 	return { x: 1595, y: cy - 29, w: 40, h: 30 };
 }
 
-/**
- * POV arrow: yellow arrow marking the recording player's row, left of the
- * avatar (x 933-985). Right edge stays short of the avatar circle (~x 995).
- */
+/** Yellow POV arrow left of the avatar (x 933-985), short of the avatar circle (~x 995). */
 export function povArrowRoi(cy: number): Roi {
 	return { x: 930, y: cy - 32, w: 58, h: 56 };
 }
 
-/**
- * Team point totals ("500 p"), right-aligned ending x=1658. Only read to
- * recognize a knockout (winner total 500) — not the match score.
- */
+/** Team totals ("500 p") ending x=1658, read only to recognize a knockout (500). */
 export const TEAM_SCORE_ROIS: readonly [Roi, Roi] = [
 	{ x: 1530, y: 330, w: 132, h: 44 },
 	{ x: 1530, y: 684, w: 132, h: 44 },
 ];
 
 /**
- * The two sides of the "Score:" banner. Left is left-aligned from x~946,
- * right right-aligned ending x~1691 (x~1712 mid-pop) — digits bounce
- * ~28-39px as the value lands (MATCH_SCORE_DIGIT_HEIGHTS).
+ * "Score:" banner sides: left from x~946, right ending x~1691 (x~1712 mid-pop); digits bounce
+ * 28-39px as they land.
  */
 export const MATCH_SCORE_ROIS: readonly [Roi, Roi] = [
 	{ x: 935, y: 231, w: 230, h: 50 },
@@ -86,10 +64,7 @@ export const MATCH_SCORE_ROIS: readonly [Roi, Roi] = [
 /** Banner score digit sizes: settled, and the landing bounce's peak. */
 export const MATCH_SCORE_DIGIT_HEIGHTS = [28, 39] as const;
 
-/**
- * Gate probe: the strip between the paint "p" suffix (ends 1424) and the
- * first stat "x" (starts 1477) is always empty pill background (near-black).
- */
+/** Strip between paint "p" (ends 1424) and first stat "x" (starts 1477): empty pill background. */
 export function gateDarkProbe(cy: number): Roi {
 	return { x: 1434, y: cy - 10, w: 38, h: 20 };
 }
@@ -106,11 +81,7 @@ export const GATE_PANEL_MAX_MEAN = 85;
 /** The paint "p" suffix region must contain bright (white) pixels. */
 export const GATE_TEXT_MIN_MAX = 180;
 
-/**
- * Header bands: lobby tag ("X Battle") on its own line, mode+stage share
- * the next. Tags size to their text, so bands are generous — header.ts
- * trims each to the actual tag extent.
- */
+/** Header bands: lobby tag on its own line, mode+stage on the next; header.ts trims each to the tag extent. */
 export const HEADER_LOBBY_BAND: Roi = { x: 828, y: 42, w: 330, h: 30 };
 export const HEADER_LINE_BAND: Roi = { x: 828, y: 88, w: 580, h: 40 };
 
diff --git a/app/features/scanner/core/detectors/scoreboard/row.ts b/app/features/scanner/core/detectors/scoreboard/row.ts
index 892823ba8..b0f720f96 100644
--- a/app/features/scanner/core/detectors/scoreboard/row.ts
+++ b/app/features/scanner/core/detectors/scoreboard/row.ts
@@ -1,10 +1,7 @@
 /**
- * The shared scoreboard row parse — weapon (with special-icon tie-break),
- * paint, name trimmed at the leftmost paint digit, stat counters — used by
- * both the results scoreboard and the replay-browser detail screen. The
- * callers differ only in ROI geometry (the replay panels are dx-shifted),
- * glyph sets (replay rows are smaller, so it passes rescaled sets), and two
- * match options.
+ * Shared scoreboard row parse (weapon with special-icon tie-break, paint, name
+ * trimmed at the leftmost paint digit, stats); callers differ only in ROI
+ * geometry, glyph sets and two match options.
  */
 import { toMainWeaponId } from "../../../scanner-types";
 import type { Mat } from "../../cv";
@@ -44,10 +41,7 @@ export interface RowResources {
 export interface RowOptions {
 	/** passed through to matchWeapon (replay rows sit on a lighter panel) */
 	weaponInkThreshold?: number;
-	/**
-	 * replay only: the left-aligned paint number puts the "p" suffix inside
-	 * the ROI when the paint has fewer than 4 digits
-	 */
+	/** replay only: the left-aligned paint puts the "p" suffix inside the ROI under 4 digits */
 	paintDropLoweredTrailing?: boolean;
 }
 
@@ -73,8 +67,7 @@ export function parseScoreboardRow(
 				: {},
 		);
 		crop.delete();
-		// near-tied icons with different kit specials: let the row's special
-		// icon break the tie
+		// near-tied icons with different kit specials: the row's special icon breaks the tie
 		if (resources.specials?.length && tiedWeaponsWithDistinctSpecials(weapon)) {
 			const spCrop = cropRoi(rgb, rois.specialIcon(cy));
 			special = matchSpecial(spCrop, resources.specials);
diff --git a/app/features/scanner/core/detectors/scoreboard/specials.ts b/app/features/scanner/core/detectors/scoreboard/specials.ts
index 9cb1a867e..1545af81e 100644
--- a/app/features/scanner/core/detectors/scoreboard/specials.ts
+++ b/app/features/scanner/core/detectors/scoreboard/specials.ts
@@ -1,14 +1,9 @@
 /**
- * Kit-icon identification: the team-tinted sub/special tiles next to a
- * player's main weapon (scoreboard: special icon above the specials
- * counter; minimap: sub-weapon tile). Tiles render the same art in each
- * team's ink hue, so unlike weapon icons the match is shape-only: alpha
- * silhouette vs the binarized search region, NCC + ink-coverage penalty.
- *
- * Low pixel budget (~22px specials, ~30px minimap subs) is enough because
- * it only splits main weapons whose *icons* are near-ties (Splash- vs
- * Sploosh-o-matic) — near-tie icon twins ship with far-apart kit
- * silhouettes (stamp vs crab, bomb vs beakon).
+ * Kit-icon identification: the team-tinted sub/special tiles (scoreboard
+ * special icon, minimap sub tile). Tinted per team, so the match is shape-only:
+ * alpha silhouette vs binarized region, NCC + ink-coverage penalty. ~22-30px is
+ * enough since it only splits near-tied main icons (Splash- vs Sploosh-o-matic)
+ * whose kit silhouettes are far apart (stamp vs crab, bomb vs beakon).
  */
 import { getCV, type Mat, minMaxLoc } from "../../cv";
 import type { FrameData } from "../../image";
@@ -33,12 +28,7 @@ export interface SpecialMatch {
 	top: { id: string; score: number }[];
 }
 
-/**
- * Build binary silhouette templates from raw RGBA icon images (128x128 with
- * alpha): tight-crop the alpha extent, binarize, downscale to each height.
- * `templateSizes` defaults to the scoreboard's special-icon sizes; the
- * minimap builds its sub-weapon set at the sub tile's larger sizes.
- */
+/** Binary silhouettes from RGBA icons: tight-crop alpha, binarize, downscale to each height. */
 export function prepareSpecialTemplates(
 	icons: { id: string; image: FrameData }[],
 	templateSizes: readonly number[] = SPECIAL_TEMPLATE_SIZES,
@@ -85,8 +75,7 @@ export function prepareSpecialTemplates(
 				0,
 				cv.INTER_AREA,
 			);
-			// re-binarize the interpolated edges so template and search region
-			// live on the same two-level scale
+			// re-binarize the interpolated edges to match the search region's two-level scale
 			const mat = new cv.Mat();
 			cv.threshold(resized, mat, 127, 255, cv.THRESH_BINARY);
 			resized.delete();
@@ -99,10 +88,7 @@ export function prepareSpecialTemplates(
 	});
 }
 
-/**
- * searchRgb: RGB crop of the row's special-icon ROI (view is fine).
- * The region is binarized on max(r,g,b) so any ink tint reads as shape.
- */
+/** searchRgb: RGB crop of the icon ROI (view is fine); binarized on max(r,g,b) so any tint reads as shape. */
 export function matchSpecial(
 	searchRgb: Mat,
 	templates: SpecialTemplate[],
@@ -155,13 +141,9 @@ export function matchSpecial(
 const WEAPON_TIE_MARGIN = 0.04;
 
 /**
- * Icon twins whose art differs only by the nozzle (Splash- vs
- * Sploosh-o-matic share the body, gauge and handle). On the replay
- * browser's dim, drop-shadowed rendering the wrong twin can beat the right
- * one by far more than WEAPON_TIE_MARGIN (0.15 observed on the
- * brinewater-1411 fixture), so whenever both appear among the top
- * candidates the kit evidence is consulted regardless of the icon-score
- * gap — the KIT_DECISION_MARGIN still guards the actual re-rank.
+ * Icon twins differing only by the nozzle: on the replay browser's dim rendering
+ * the wrong twin can win by 0.15 (brinewater-1411), far past WEAPON_TIE_MARGIN,
+ * so kit evidence is consulted whenever both are in the top candidates.
  * Symmetric pairs, extended per attested fixture need only.
  */
 const ICON_TWINS: ReadonlyMap<string, string> = new Map([
@@ -170,20 +152,16 @@ const ICON_TWINS: ReadonlyMap<string, string> = new Map([
 ]);
 
 /**
- * The kit-icon evidence must separate the tied kits' entries by at least
- * this much to override the icon ranking: the shape matcher's own confusions
- * (Wave Breaker vs Ink Vac/Reef Slider on ~22px of silhouette) all land
- * inside this band, while true silhouette splits (stamp vs crab) clear it.
+ * Kit evidence must separate tied kits by this much: shape-matcher confusions (Wave Breaker vs Ink
+ * Vac) sit inside, true splits (stamp vs crab) clear it.
  */
 const KIT_DECISION_MARGIN = 0.06;
 
 type KitPart = "sub" | "special";
 
 /**
- * Weapon-icon candidates tied within WEAPON_TIE_MARGIN (plus the leader's
- * ICON_TWIN at any gap) whose kits carry different subs/specials — the only
- * case the kit icon can help with. Returns null when the icon match already
- * decided (or the kit part can't).
+ * Candidates tied within WEAPON_TIE_MARGIN (plus the leader's ICON_TWIN) whose kits differ in
+ * `part`; null otherwise.
  */
 function tiedWeaponsWithDistinctKit(
 	match: WeaponMatch,
@@ -220,11 +198,7 @@ export function tiedWeaponsWithDistinctSubs(
 	return tiedWeaponsWithDistinctKit(match, "sub");
 }
 
-/**
- * Re-rank tied weapon candidates by how well their kits' sub/special
- * matches the tile evidence. Only reorders on decisive evidence; ties whose
- * kit entries all score alike keep the icon-match order.
- */
+/** Re-rank tied candidates by their kit part's tile evidence; only on decisive evidence. */
 function disambiguateWeaponByKit(
 	match: WeaponMatch,
 	evidence: SpecialMatch,
diff --git a/app/features/scanner/core/detectors/scoreboard/weapons.ts b/app/features/scanner/core/detectors/scoreboard/weapons.ts
index 59f8f1b4a..1227208fd 100644
--- a/app/features/scanner/core/detectors/scoreboard/weapons.ts
+++ b/app/features/scanner/core/detectors/scoreboard/weapons.ts
@@ -1,23 +1,13 @@
 /**
- * Weapon icon identification: NCC of every candidate icon (pre-scaled to a
- * few sizes) against the row's weapon ROI, with an ink-coverage penalty so a
- * small template can't win by matching a lucky sub-window of a bigger icon
- * (the template's opaque area should match the ink actually present).
- *
- * Large template sets run coarse-to-fine: every icon first ranked at quarter
- * resolution (same scoring), then only the shortlist re-matched at full res.
- * Small sets (ability badges) skip the coarse pass — not worth it below ~2x
- * the shortlist size.
+ * Weapon icon identification: NCC of every candidate icon (pre-scaled to a few
+ * sizes) against the weapon ROI, with an ink-coverage penalty so a small
+ * template can't win on a lucky sub-window of a bigger icon. Large sets run
+ * coarse-to-fine (quarter-res ranking, shortlist re-matched at full res).
  */
 import { getCV, type Mat, minMaxLoc } from "../../cv";
 import type { FrameData } from "../../image";
 
-/**
- * Icon heights (px at 1080p) to try. The live scoreboard renders in-row
- * icons at ~44-56px; the replay browser at ~60-64px. The oversized entries
- * are skipped inside the live detector's 56px-tall weapon ROI at match
- * time, so they only ever compete on the replay screen.
- */
+/** Icon heights to try: live rows ~44-56px, replay browser ~60-64px (skipped inside the live 56px ROI). */
 const WEAPON_TEMPLATE_SIZES = [40, 44, 48, 52, 56, 60, 64] as const;
 
 /** Row pill background the icons sit on (near-black). */
@@ -27,13 +17,9 @@ const PILL_BACKGROUND = 12;
 const INK_THRESHOLD = 40;
 
 /**
- * Scoped chargers' icons differ from their unscoped twins only by the scope
- * tube, which is near-black and sits on the near-black pill — measurably
- * invisible at ~50px (a synthetic scoped row probes *darker* in the scope
- * band than a real unscoped row does from barrel bleed). When the two
- * variants score within noise of each other, resolve to the unscoped one
- * (matches labeled fixtures and typical usage) and flag the ambiguity.
- * Map: scoped id -> unscoped id.
+ * Scoped chargers differ from unscoped twins only by the near-black scope tube,
+ * invisible on the near-black pill at ~50px. Within-noise ties resolve to the
+ * unscoped one (matches fixtures and typical usage) and flag the ambiguity.
  */
 const SCOPED_TWINS: ReadonlyMap<string, string> = new Map([
 	["2040", "2030"], // Splat Scope -> Splat Charger
@@ -87,15 +73,11 @@ function countInkRgb(mat: Mat, threshold: number): number {
 }
 
 /**
- * Downscale a composited RGB icon to each candidate size, with the coarse
- * variant and ink counts matchWeapon needs. Ink is counted on the resized
- * pixels, not scaled from source alpha (which undercounts antialiased edges
- * and can flip the coverage ratio toward a wrong icon).
- *
- * `referenceSize` scales by size/referenceSize instead of resizing to a
- * size×size square — "the art as it renders inside a size-sized padded
- * square" — letting a template whose icon square is taller than the ROI
- * still compete when its art fits (see prepareWeaponTemplates cropToArt).
+ * Downscale a composited RGB icon to each size with coarse variant and ink
+ * counts. Ink is counted on the resized pixels, not scaled from source alpha
+ * (undercounts antialiased edges). `referenceSize` scales by size/referenceSize
+ * instead of resizing to a square, so cropped art can compete when its padded
+ * square would exceed the ROI (see cropToArt).
  */
 export function buildTemplateSizes(
 	composited: Mat,
@@ -140,17 +122,11 @@ export function buildTemplateSizes(
 }
 
 /**
- * Build match-ready templates from raw RGBA icon images (256x256 with
- * alpha): composite over the pill background, then downscale to each size.
- * Screens whose pills aren't near-black (minimap cards, camo surfaces)
- * override `background` and `inkThreshold` (must clear the new background
- * or ink counts saturate).
- *
- * `cropToArt` trims each template to the icon's alpha bbox (source icons
- * carry generous transparent padding) while keeping the padded-square scale
- * semantics — without it, a screen rendering icons near the ROI height
- * (minimap cards, ~56-60px in a 54px box) can never match, since matchWeapon
- * skips templates taller/wider than the ROI.
+ * Match-ready templates from RGBA icons (256x256): composite over the pill
+ * background, downscale to each size. Lighter surfaces override `background`
+ * and `inkThreshold` (must clear the background or ink counts saturate).
+ * `cropToArt` trims to the alpha bbox while keeping padded-square scale; without
+ * it icons near the ROI height (minimap ~56-60px in a 54px box) can never match.
  */
 export function prepareWeaponTemplates(
 	icons: { id: string; image: FrameData }[],
@@ -217,7 +193,7 @@ function cropToAlphaBbox(rgba: Mat): Mat {
 	y1 = Math.min(rows - 1, y1 + ART_BBOX_MARGIN);
 	const view = rgba.roi(new cv.Rect(x0, y0, x1 - x0 + 1, y1 - y0 + 1));
 	const out = new cv.Mat();
-	view.copyTo(out); // ROI views: .data/.clone broken in this build, copy out
+	view.copyTo(out); // ROI views: .data/.clone broken, copy out
 	view.delete();
 	return out;
 }
@@ -238,12 +214,9 @@ function compositeOnBackground(rgba: Mat, background: number): Mat {
 }
 
 /**
- * Coarse pass: rank every template by its best quarter-resolution score
- * (same NCC + ink-coverage formula as the full pass) and return the
- * COARSE_SHORTLIST ids worth full-resolution matching. Scoped ids drag
- * their unscoped twin along so the twin tie-break always has both scores.
- * Returns null when no coarse template fits (caller falls back to the
- * full set, which then skips the same templates and reports unknown).
+ * Rank every template at quarter resolution (same formula) and return the
+ * COARSE_SHORTLIST ids; scoped ids drag their unscoped twin along for the
+ * tie-break. Null when no coarse template fits.
  */
 function coarseShortlist(
 	searchRgb: Mat,
@@ -271,8 +244,7 @@ function coarseShortlist(
 	for (const template of templates) {
 		let score = -1;
 		for (const { mat, coarse } of template.sizes) {
-			// gate on the *full-res* dims so a size competes here iff it competes
-			// in the full pass, then also require the coarse pair to fit
+			// gate on the *full-res* dims so a size competes here iff it competes in the full pass
 			if (mat.rows > searchRows || mat.cols > searchCols) continue;
 			if (coarse.mat.rows > regionRows || coarse.mat.cols > regionCols)
 				continue;
@@ -300,11 +272,9 @@ function coarseShortlist(
 }
 
 /**
- * searchRgb: RGB crop of the row's weapon ROI (view is fine).
- * inkThreshold separates icon ink from the pill background in the search
- * region — raise it on screens whose pills are lighter than the live
- * scoreboard's (~12), e.g. the replay browser (~61), or everything counts
- * as ink and the coverage penalty collapses.
+ * searchRgb: RGB crop of the weapon ROI (view is fine). Raise inkThreshold on
+ * screens with lighter pills (replay browser ~61 vs live ~12) or everything
+ * counts as ink and the coverage penalty collapses.
  */
 export function matchWeapon(
 	searchRgb: Mat,
@@ -321,8 +291,7 @@ export function matchWeapon(
 	const searchInk = countInkRgb(cont, inkThreshold);
 	cont.delete();
 
-	// shortlist large sets at coarse resolution first; below ~2x the shortlist
-	// size the coarse pass costs more calls than it saves
+	// below ~2x the shortlist size the coarse pass costs more calls than it saves
 	let pool = templates;
 	if (templates.length > COARSE_SHORTLIST * 2) {
 		const ids = coarseShortlist(searchRgb, templates, inkThreshold);
diff --git a/app/features/scanner/core/detectors/telemetry.ts b/app/features/scanner/core/detectors/telemetry.ts
index ae951ea4d..5b1b5dc81 100644
--- a/app/features/scanner/core/detectors/telemetry.ts
+++ b/app/features/scanner/core/detectors/telemetry.ts
@@ -1,9 +1,6 @@
 /**
- * Scan telemetry: counters the analyzer accumulates so scan performance is
- * measurable instead of guessed at — how many frames were decoded vs.
- * actually analyzed, where detector time goes (gate vs. parse), how much
- * work scheduling saved, and how much of a VoD was covered in skim mode.
- * Plain JSON so it travels over the worker boundary as-is.
+ * Scan telemetry: frames decoded vs. analyzed, gate vs. parse time, work saved
+ * by scheduling, VoD skim coverage. Plain JSON so it crosses the worker boundary.
  */
 
 export interface DetectorTelemetry {
diff --git a/app/features/scanner/core/detectors/types.ts b/app/features/scanner/core/detectors/types.ts
index d2df596d5..c8e36aafb 100644
--- a/app/features/scanner/core/detectors/types.ts
+++ b/app/features/scanner/core/detectors/types.ts
@@ -15,86 +15,58 @@ export interface GateResult {
 	pass: boolean;
 	/** raw score of the gate check, for tuning */
 	score: number;
-	/**
-	 * which screen variant the gate recognized, for detectors that gate more
-	 * than one (minimap: "overlay" | "spectator") — parse() branches on it
-	 * instead of re-running the gate probes
-	 */
+	/** screen variant the gate recognized (minimap: "overlay" | "spectator"); parse() branches on it */
 	variant?: string;
 	/**
-	 * coarse content fingerprint (grid-cell means over content ROIs, see
-	 * image.ts roiSignature) — the scheduler re-arms a suppressed streak
-	 * when it moves, for screens whose distinct real occurrences keep the
-	 * gate passing (browsing battle log / replay entries)
+	 * coarse content fingerprint (image.ts roiSignature); the scheduler re-arms a
+	 * suppressed streak when it moves (browsing battle log / replay entries)
 	 */
 	signature?: number[];
 }
 
 /**
- * A detector recognizes one event type on a canonical 1920x1080 RGBA frame.
- * gate() must be cheap (probes / tiny template match); parse() may be expensive
- * and only runs when gate() passes. Callers pass the gate result they already
- * computed into parse(); a detector must still cope without it (re-deriving
- * whatever it needs) so one-shot tools can call parse() directly.
+ * Recognizes one event type on a canonical 1920x1080 RGBA frame. gate() must be
+ * cheap; parse() runs only when it passes and must also cope without the gate
+ * result so one-shot tools can call it directly.
  */
 export interface Detector<TData = unknown> {
 	id: string;
 	/**
-	 * Minimum seconds between checks in *both* scheduling phases: frames
-	 * inside the interval skip gate and parse entirely
-	 * (core/detectors/scheduler.ts, applied by the analyzer worker). Also
-	 * exempts the detector from steady-frame suppression: it marks a screen
-	 * that stays up for minutes with *changing* content, which the
-	 * stagnating-confidence heuristic would wrongly silence.
+	 * Minimum seconds between checks in both scheduling phases. Also exempts the
+	 * detector from steady-frame suppression: it marks a long-lived screen with
+	 * changing content, which stagnation suppression would wrongly silence.
 	 */
 	checkIntervalS?: number;
 	/**
-	 * Check cadence while the gate keeps failing (the search phase); unset =
-	 * the scheduler's default (0.25s). Don't reason from raw-gameplay screen
-	 * lifetimes here: produced/casted VoDs cut screens (results, intros) to
-	 * as little as ~1s with transition flicker eating frames inside that
-	 * window, so the search cadence must sample it several times. Gates
-	 * cost ~1.6ms, so searching at the analysis floor is effectively free;
-	 * only override upward with strong evidence.
+	 * Check cadence while the gate fails; unset = scheduler default (0.25s).
+	 * Produced VoDs cut screens to ~1s with flicker inside, so the cadence must
+	 * sample that several times; gates cost ~1.6ms so only override upward with
+	 * strong evidence.
 	 */
 	searchIntervalS?: number;
 	/**
-	 * Check cadence while the gate is passing (the refine phase); unset =
-	 * the scheduler's dense default (0.15s). Only for detectors whose parse
-	 * is expensive enough that refining at the dense cadence multiplies
-	 * real cost — the sparser cadence still has to sample the screen's
-	 * lifetime several times.
+	 * Check cadence while the gate passes; unset = scheduler default (0.15s).
+	 * Only for expensive parses, and must still sample a screen's lifetime
+	 * several times.
 	 */
 	refineIntervalS?: number;
-	/**
-	 * Consecutive non-improving parses tolerated before stagnation
-	 * suppression; unset = the scheduler's default (6). Lower for expensive
-	 * parses to cap the worst-case cost of a stagnant streak.
-	 */
+	/** Non-improving parses tolerated before suppression; unset = default (6). Lower for expensive parses. */
 	maxStagnantParses?: number;
 	/**
-	 * A parse reaching this confidence ends the streak's refinement
-	 * immediately: the timeline keeps the best read per merge window, so a
-	 * read this good cannot be improved upon in any way that matters.
-	 * Set just under the detector's measured clean-read confidence floor
-	 * (fixture-suite reads + confirmed scan events), so a streak's first
-	 * full read suppresses the rest; degraded-footage reads below the
-	 * floor fall back to stagnation-based suppression.
+	 * A parse at this confidence ends refinement immediately. Set just under the
+	 * detector's measured clean-read floor (fixtures + confirmed scan events) so
+	 * the first full read suppresses the rest; degraded reads fall back to
+	 * stagnation suppression.
 	 */
 	sufficientConfidence?: number;
 	/**
-	 * After a sufficient read, skip parses for this long even across gate
-	 * drops — for overlays whose animated background flickers the gate
-	 * (death). Only safe when the event type's timeline merge is purely
-	 * time-based and the cooldown fits inside the merge window, so every
-	 * parse the cooldown skips would have merged into the same event anyway.
+	 * After a sufficient read, skip parses this long even across gate drops
+	 * (death: animated background flickers the gate). Only safe when the
+	 * timeline merge is purely time-based and the cooldown fits inside the merge
+	 * window.
 	 */
 	rearmCooldownS?: number;
-	/**
-	 * false = worker results for this detector's events ship without the
-	 * analyzed-frame PNG — for detectors whose events fire continuously,
-	 * where a stored frame per event would balloon IndexedDB.
-	 */
+	/** false = events ship without the frame PNG; for continuously firing events that would balloon IndexedDB */
 	attachFrame?: boolean;
 	gate(frame: Mat): GateResult;
 	parse(frame: Mat, t: number, gate?: GateResult): DetectedEvent<TData>[];
diff --git a/app/features/scanner/core/glyphs.ts b/app/features/scanner/core/glyphs.ts
index 9dabd4e1f..b53b52ec6 100644
--- a/app/features/scanner/core/glyphs.ts
+++ b/app/features/scanner/core/glyphs.ts
@@ -1,17 +1,15 @@
 /**
  * Glyph-template text recognition: font/size/position are known, so instead
- * of OCR we segment the crop by column projection and classify each segment
- * via sliding NCC against grayscale glyph templates (native scale;
- * scaleGlyphSet pre-scales for larger text like team scores). Accuracy
- * details: matching runs on the *masked* grayscale crop (background zeroed
- * via a dilated binary mask) so colored backgrounds behave like black pills
- * while antialiasing survives; scores carry an ink-coverage penalty (else a
- * narrow template inside a wider glyph wins, e.g. 'c' outscoring 'o');
- * segments wider than the median glyph split at deep projection dips ('T'
- * overhangs merge into the next letter); multi-stroke glyphs with a stroke
- * gap (katakana パ/ハ/リ) segment as fragments no template matches, so close
- * pairs are re-classified merged and kept only when the merge decisively
- * outscores both fragments.
+ * of OCR the crop is segmented by column projection and each segment
+ * classified via sliding NCC against grayscale glyph templates (native scale;
+ * scaleGlyphSet pre-scales for larger text). Matching runs on the *masked*
+ * grayscale crop (background zeroed via a dilated binary mask) so colored
+ * backgrounds behave like black while antialiasing survives; scores carry an
+ * ink-coverage penalty (else a narrow template inside a wider glyph wins, 'c'
+ * over 'o'); segments wider than the median glyph split at deep projection
+ * dips ('T' overhangs merge into the next letter); multi-stroke glyphs with a
+ * stroke gap (katakana パ/ハ/リ) segment as unmatched fragments, so close pairs
+ * are re-classified merged and kept only when the merge decisively wins.
  */
 import { getCV, type Mat } from "./cv";
 import type { FrameData } from "./image";
@@ -23,10 +21,9 @@ interface AtlasGlyphMeta {
 	w: number;
 	h: number;
 	/**
-	 * Template origin: "fixture" = exact pixel crop from a labeled frame
-	 * (high fidelity, sparse coverage); "font" = rendered from game fonts
-	 * (full coverage, imperfect). Recognition takes the max score, so
-	 * fixture glyphs win where they exist.
+	 * "fixture" = exact pixel crop from a labeled frame (high fidelity, sparse);
+	 * "font" = rendered from game fonts (full coverage, imperfect). Recognition
+	 * takes the max score, so fixture glyphs win where they exist.
 	 */
 	source?: "fixture" | "font";
 }
@@ -293,30 +290,25 @@ function measureSegment(binary: Mat, seg: Segment): SegmentInfo {
 
 /**
  * Fixture crops are ground truth; a font glyph must beat one by this margin
- * to win (stops 'I' noise-edging out an exact 'l' crop). Keep tight — at
- * 0.04 a fixture crop of a genuinely different char ('h' vs 'b') can
- * displace a correct font match.
+ * (stops 'I' noise-edging out an exact 'l' crop). Keep tight: at 0.04 a fixture
+ * crop of a different char ('h' vs 'b') can displace a correct font match.
  */
 const FIXTURE_TIEBREAK = 0.02;
 
 /**
  * A CJK-charset segment leaves thousands of templates eligible with barely
- * differing bounds (similar ink coverage and heights across the charset),
- * so the bound-sorted early break never fires and every template pays a
- * full matchTemplate — tens of seconds per segment. Above this eligibility
- * count a half-scale NCC pass ranks the templates first (matchTemplate
- * work scales with region area × template area, so ~16x cheaper) and only
- * glyphs whose estimated score lands within PRESCREEN_MARGIN of the
- * front-runner advance to full matching. The margin absorbs the low-res
- * estimate's error and sits far beyond FIXTURE_TIEBREAK, so the tie-break
- * pool survives; the estimate only prunes, never scores. Tuning is
- * accuracy-first, verified against the full scanner:report — at these
- * values the report is bit-identical to no-prescreen while a JP
- * splash-tag read drops from ~21s to ~1.3s. Quarter scale is too coarse
- * (20px glyphs land at ~5px where the NCC ranking turns to noise), a
- * tighter margin loses real reads ('R' at 0.12, and stragglers survive
- * past 0.22), and the keep cap is only a runaway backstop — capping at
- * 256 cut true glyphs that sat within the margin.
+ * differing bounds, so the bound-sorted early break never fires and every
+ * template pays a full matchTemplate (tens of seconds per segment). Above this
+ * eligibility count a half-scale NCC pass (~16x cheaper) ranks the templates
+ * first and only glyphs within PRESCREEN_MARGIN of the front-runner advance to
+ * full matching. The margin absorbs the low-res estimate's error and sits far
+ * beyond FIXTURE_TIEBREAK, so the tie-break pool survives; the estimate only
+ * prunes, never scores. Verified against scanner:report: at these values the
+ * report is bit-identical to no-prescreen while a JP splash-tag read drops
+ * from ~21s to ~1.3s. Quarter scale is too coarse (20px glyphs at ~5px turn
+ * the NCC ranking to noise), a tighter margin loses real reads ('R' at 0.12,
+ * stragglers past 0.22), and the keep cap is only a runaway backstop (256 cut
+ * true glyphs within the margin).
  */
 const PRESCREEN_MIN_ELIGIBLE = 200;
 const PRESCREEN_SCALE = 0.5;
@@ -328,11 +320,10 @@ function classifySegment(
 	seg: SegmentInfo,
 	set: GlyphSet,
 	/**
-	 * Exact early-reject floor: a score can never exceed its precomputed
-	 * bound, so a caller that only needs to know whether any glyph can beat
-	 * `scoreFloor` (mergeSplitGlyphs) lets the bound-sorted loop stop as soon
-	 * as none can. Scores that ARE computed come out identical — but the
-	 * returned list omits sub-floor candidates, so pass it only for probes.
+	 * Exact early-reject floor: a score never exceeds its precomputed bound, so a
+	 * caller only asking whether any glyph can beat `scoreFloor` (mergeSplitGlyphs)
+	 * lets the bound-sorted loop stop early. Computed scores are identical, but
+	 * sub-floor candidates are omitted, so pass it only for probes.
 	 */
 	scoreFloor = Number.NEGATIVE_INFINITY,
 ): { char: string; score: number; ncc: number; source: "fixture" | "font" }[] {
@@ -345,23 +336,20 @@ function classifySegment(
 	const x0 = Math.max(0, seg.x0 - pad);
 	const x1 = Math.min(masked.cols, seg.x1 + pad);
 	const regionCols = x1 - x0;
-	// Crop the search region vertically to the segment's ink rows: line crops
-	// can run far taller than the text (the death tag band is ~2x its glyphs),
-	// and every extra row multiplies matchTemplate work while only offering
-	// placements away from the ink no correct match can occupy. The slack
-	// keeps every hRatio-eligible template (tRows <= 1.3 * seg.height)
-	// placeable: seg.height + 2 * (0.15 * seg.height + 2) >= 1.3 * seg.height.
+	// Crop the search region vertically to the segment's ink rows: line crops can
+	// run far taller than the text (the death tag band is ~2x its glyphs) and every
+	// extra row multiplies matchTemplate work. The slack keeps every hRatio-eligible
+	// template (tRows <= 1.3 * seg.height) placeable.
 	const vSlack = Math.ceil(0.15 * seg.height) + 2;
 	const y0 = Math.max(0, seg.y0 - vSlack);
 	const y1 = Math.min(maskedRows, seg.y1 + vSlack);
 	const regionRows = y1 - y0;
 	const region = masked.roi(new cv.Rect(x0, y0, regionCols, regionRows));
 
-	// Both penalty factors below depend only on the glyph and the segment, and
-	// NCC <= 1, so their product bounds the score a glyph can reach before any
-	// matching runs. Matching in descending-bound order lets the loop stop as
-	// soon as no remaining glyph could come within FIXTURE_TIEBREAK of the
-	// best — those can neither win nor take part in the fixture tie-break.
+	// Both penalty factors depend only on glyph and segment, and NCC <= 1, so
+	// their product bounds a glyph's score before matching. Matching in
+	// descending-bound order lets the loop stop once no remaining glyph could
+	// come within FIXTURE_TIEBREAK of the best.
 	const eligible: EligibleGlyph[] = [];
 	for (const glyph of set.glyphs) {
 		const t = glyph.mat;
@@ -371,16 +359,14 @@ function classifySegment(
 		const wRatio = tCols / Math.max(segWidth, 1);
 		if (wRatio < 0.4 || wRatio > 2.5) continue;
 		const hRatio = tRows / Math.max(seg.height, 1);
-		// a template sliding freely inside a taller region can score high on a
-		// fragment of the segment (an 'l' bar inside a 'c'), so reject templates
-		// much taller or shorter than the segment's ink extent
+		// a template sliding freely in a taller region can score high on a fragment
+		// of the segment (an 'l' bar inside a 'c'), so reject height mismatches
 		if (hRatio < 0.5 || hRatio > 1.3) continue;
 		// ink-coverage penalty: templates should explain the segment's ink
 		const r =
 			Math.min(glyph.ink, seg.ink) / Math.max(Math.max(glyph.ink, seg.ink), 1);
-		// height-mismatch penalty: an x-height template sliding on an ascender/
-		// descender glyph ('o' on 'b' or 'g') can correlate well on the bowl
-		// alone; matching heights should outrank it
+		// height-mismatch penalty: an x-height template on an ascender/descender
+		// glyph ('o' on 'b') correlates well on the bowl alone
 		const hr =
 			Math.min(tRows, seg.height) / Math.max(tRows, Math.max(seg.height, 1));
 		eligible.push({
@@ -401,19 +387,16 @@ function classifySegment(
 		ncc: number;
 		source: "fixture" | "font";
 	}[] = [];
-	// Only consider placements that cover most of the segment: the region
-	// is padded, so a freely-sliding template can otherwise score a perfect
-	// match on the *neighboring* glyph inside the pad (an 'l' template next
-	// to a narrow 'i' segment matches the adjacent real 'l' at 0.97+), or
-	// on a fragment of the segment (a 't' stem on the left bar of a 'b').
+	// Only placements covering most of the segment: the region is padded, so a
+	// free-sliding template can otherwise match the *neighboring* glyph inside
+	// the pad ('l' next to a narrow 'i' at 0.97+) or a fragment ('t' stem on 'b').
 	const minOverlap = 0.7 * segWidth;
-	// In probe mode only the boolean "can any glyph beat the floor" matters,
-	// so the loop can stop as soon as either answer is certain: no remaining
-	// bound reaches the floor, or a computed score already cleared it.
+	// In probe mode only "can any glyph beat the floor" matters, so the loop stops
+	// once either answer is certain.
 	const probeMode = scoreFloor !== Number.NEGATIVE_INFINITY;
-	// a probe prunes against its own floor instead of the front-runner: its
-	// usual answer is "no glyph clears the floor", which otherwise costs a
-	// full match of every template whose loose bound exceeds it
+	// a probe prunes against its own floor instead of the front-runner: its usual
+	// answer is "nothing clears the floor", which otherwise costs a full match of
+	// every template whose loose bound exceeds it
 	const contenders =
 		eligible.length >= PRESCREEN_MIN_ELIGIBLE
 			? prescreen(
@@ -472,9 +455,9 @@ function classifySegment(
 			(c) =>
 				c.source === "fixture" &&
 				top.score - c.score < FIXTURE_TIEBREAK &&
-				// ...but only when the fixture's raw correlation is also competitive;
-				// a fixture crop of a *different* char that merely lands near the top
-				// score via the ink penalty must not displace a well-matching font glyph
+				// ...only when the fixture's raw correlation is also competitive: a fixture
+				// crop of a *different* char landing near the top via the ink penalty must
+				// not displace a well-matching font glyph
 				top.ncc - c.ncc < FIXTURE_TIEBREAK,
 		);
 		if (fixture && fixture !== top) {
@@ -494,13 +477,12 @@ interface EligibleGlyph {
 	bound: number;
 }
 
-/** Low-res ranking pass over an oversized eligibility list; see the
- * PRESCREEN_* constants for why and how survivors are chosen. `geometry`
- * carries the caller's placement window in full-res coordinates: without
- * the same min-overlap restriction the estimates suffer exactly the
- * failure the full loop guards against — a template scoring on the
- * neighboring glyph inside the pad — which inflates the front-runner and
- * prunes the true glyph. */
+/**
+ * Low-res ranking pass over an oversized eligibility list; see PRESCREEN_*.
+ * `geometry` carries the caller's placement window in full-res coordinates:
+ * without the same min-overlap restriction a template scoring on the neighbor
+ * inside the pad inflates the front-runner and prunes the true glyph.
+ */
 function prescreen(
 	region: Mat,
 	eligible: EligibleGlyph[],
@@ -525,10 +507,9 @@ function prescreen(
 	// boundary placement the full-res window allows
 	const minOverlap = geometry.minOverlap * PRESCREEN_SCALE - 1;
 	const result = new cv.Mat();
-	// entries the low-res pass cannot estimate (template degenerate or no
-	// valid placement after scaling) are force-kept — but must stay out of
-	// the front-runner max, or their untightened bound (≈1) inflates the
-	// floor and prunes every genuinely estimated glyph
+	// entries the low-res pass cannot estimate (degenerate template or no valid
+	// placement after scaling) are force-kept but stay out of the front-runner
+	// max, or their untightened bound (≈1) prunes every estimated glyph
 	const kept: EligibleGlyph[] = [];
 	const scored: { entry: EligibleGlyph; est: number }[] = [];
 	for (const entry of eligible) {
@@ -616,15 +597,13 @@ interface ClassifiedSegment {
 }
 
 /**
- * Multi-stroke glyphs whose strokes never connect (katakana ハ/パ/リ and kin)
- * segment as two fragments no full-glyph template can match (width-ratio
- * filter rejects a wide template on a narrow fragment). Close neighbor pairs
- * are re-classified merged and kept only when the merge beats both fragments
- * by a clear margin — genuine pairs ("rn", "VV") already read well alone, so
- * a lookalike merge ('m', 'W') can't clear it. Kana gaps run wide (い's
- * strokes sit ~0.4 medianWidth apart at tag-name scale), so
- * MERGE_MAX_GAP_RATIO reaches past that while staying below the space gap
- * (0.55), so merges never bridge a real word break.
+ * Multi-stroke glyphs whose strokes never connect (katakana ハ/パ/リ) segment as
+ * two fragments no full-glyph template matches (width-ratio filter). Close
+ * neighbor pairs are re-classified merged and kept only when the merge beats
+ * both fragments by a clear margin — genuine pairs ("rn", "VV") read well
+ * alone, so a lookalike merge ('m', 'W') can't clear it. Kana gaps run wide
+ * (い's strokes sit ~0.4 medianWidth apart at tag-name scale), so the gap ratio
+ * reaches past that while staying below the space gap (0.55).
  */
 const MERGE_MAX_GAP_RATIO = 0.45;
 const MERGE_MARGIN = 0.02;
@@ -652,10 +631,9 @@ function mergeSplitGlyphs(
 			b.ranked[0]?.score ?? 0,
 		);
 		const floor = fragmentBest + MERGE_MARGIN;
-		// Probe with the floor first: most neighbor pairs are genuine letter
-		// pairs whose merge can't win, and the floor lets the bound-sorted
-		// matching stop almost immediately. The probe's computed scores are
-		// exact, so "no candidate beats the floor" is a definitive reject.
+		// Probe with the floor first: most neighbor pairs are genuine letter pairs
+		// whose merge can't win, so the bound-sorted matching stops almost at once.
+		// Probe scores are exact, so "nothing beats the floor" is definitive.
 		const probe = classifySegment(masked, seg, set, floor);
 		let merged = false;
 		if (probe.some((c) => c.score > floor)) {
@@ -673,17 +651,14 @@ function mergeSplitGlyphs(
 }
 
 /**
- * A wide-segment split can land inside a glyph instead of at the true
- * boundary: capture blur can leave the gap between two glyphs shallower in
- * the column profile than the hollows of their bowls, so the deepest-dip cut
- * severs a bowl edge ("do" reading as "′k"). Both halves of such a miscut
- * classify poorly, so adjacent low-scoring segments are re-cut: each profile
- * dip across their joint span is tried as the boundary and the cut whose
- * weaker half classifies best wins. Template scores carry real noise at the
- * blur levels where miscuts happen (a wrong "l|U" outscored a true "d|u" by
- * 0.07), so a re-cut is adopted only when it is both a decent read in
- * absolute terms and decisively better than the original pair — otherwise
- * the read stays as segmented.
+ * A wide-segment split can land inside a glyph: capture blur can leave the gap
+ * between two glyphs shallower than the hollows of their bowls, so the
+ * deepest-dip cut severs a bowl edge ("do" reading as "′k"). Both halves then
+ * classify poorly, so adjacent low-scoring segments are re-cut at each profile
+ * dip across their joint span and the cut whose weaker half classifies best
+ * wins. Scores carry real noise at those blur levels (a wrong "l|U" outscored a
+ * true "d|u" by 0.07), so a re-cut is adopted only when it is a decent read in
+ * absolute terms and decisively better than the original pair.
  */
 const RECUT_MAX_SCORE = 0.75;
 const RECUT_MARGIN = 0.08;
@@ -749,10 +724,7 @@ function recutMiscutPairs(
 	}
 }
 
-/**
- * Recognize white-on-dark text in a grayscale crop.
- * The crop must be tight vertically (one text line).
- */
+/** Recognizes white-on-dark text in a grayscale crop tight to one text line. */
 export function recognizeText(
 	gray: Mat,
 	set: GlyphSet,
diff --git a/app/features/scanner/core/image.ts b/app/features/scanner/core/image.ts
index fcf9a0854..2efe54fdc 100644
--- a/app/features/scanner/core/image.ts
+++ b/app/features/scanner/core/image.ts
@@ -1,7 +1,6 @@
 /**
- * Environment-agnostic frame representation and helpers.
- * A FrameData is RGBA, same layout as browser ImageData — Node code builds it
- * from @napi-rs/canvas, browser code from a canvas or VideoFrame.
+ * Environment-agnostic frame representation: a FrameData is RGBA with the
+ * same layout as browser ImageData (Node builds it from @napi-rs/canvas).
  */
 
 import { CANONICAL_HEIGHT, CANONICAL_WIDTH, type Roi } from "./canonical";
@@ -22,10 +21,7 @@ export function toMat(frame: FrameData): Mat {
 	return cv.matFromImageData(frame as unknown as ImageData);
 }
 
-/**
- * Normalize any input frame to the canonical 1920x1080 RGBA mat that all ROI
- * constants are defined against. Returns a new mat; caller owns both.
- */
+/** Normalizes any frame to the canonical 1920x1080 RGBA mat all ROI constants assume. New mat; caller owns both. */
 export function normalizeFrame(src: Mat): Mat {
 	const cv = getCV();
 	const dst = new cv.Mat();
@@ -47,10 +43,9 @@ export function normalizeFrame(src: Mat): Mat {
 }
 
 /**
- * Crop a rect out of a mat. Returns a view: fine as *input* to OpenCV calls
- * (matchTemplate, mean, resize, ...) but NEVER read `.data` off it — in this
- * opencv.js build both `.data` and `.clone()` mishandle non-continuous views.
- * Use copyRoi when pixel access is needed.
+ * Crops a rect out of a mat as a view: fine as *input* to OpenCV calls but
+ * NEVER read `.data` off it — this opencv.js build mishandles `.data` and
+ * `.clone()` on non-continuous views. Use copyRoi for pixel access.
  */
 export function cropRoi(src: Mat, roi: Roi): Mat {
 	const cv = getCV();
@@ -67,9 +62,8 @@ export function copyRoi(src: Mat, roi: Roi): Mat {
 }
 
 /**
- * Mean brightness of a ROI: the average of the first three channels on a
- * color mat, the single channel's mean on a grayscale (or |Laplacian|) mat.
- * The shared probe primitive of every detector gate.
+ * Mean brightness of a ROI: average of the first three channels on a color
+ * mat, the single channel's mean on grayscale. The shared gate probe.
  */
 export function meanBrightness(mat: Mat, roi: Roi): number {
 	const view = cropRoi(mat, roi);
@@ -129,12 +123,11 @@ export function minChannel(mat: Mat, roi?: Roi): Mat {
 }
 
 /**
- * Coarse content fingerprint of a grayscale ROI: the mean brightness of each
- * cell in a cols x rows grid over the region. Cheap enough for gates.
- * Consecutive frames of one static screen move a cell by ≤~2 while different
- * text/content moves cells by tens (measured on battle log browsing footage)
- * — the scheduler compares fingerprints to re-arm suppression when a passing
- * gate's screen flips to a new real occurrence (GateResult.signature).
+ * Coarse content fingerprint of a grayscale ROI: mean brightness per cell of a
+ * cols x rows grid. Consecutive frames of one static screen move a cell by
+ * ≤~2 while different content moves cells by tens (measured on battle log
+ * browsing) — the scheduler compares fingerprints to re-arm suppression when
+ * a passing gate's screen flips to a new occurrence (GateResult.signature).
  */
 export function roiSignature(
 	gray: Mat,
diff --git a/app/features/scanner/core/ink-color.ts b/app/features/scanner/core/ink-color.ts
index ebe516717..45103be36 100644
--- a/app/features/scanner/core/ink-color.ts
+++ b/app/features/scanner/core/ink-color.ts
@@ -1,10 +1,8 @@
 /**
  * Team ink color sampling and comparison. Splatoon renders each team's UI
- * accents — counter plate fills and digits, minimap sub tiles — in the
- * team's ink color, fixed for the whole game and picked to contrast with
- * the opponent's. That makes ink hue a per-frame team identity signal
- * where screen position is not one: casted footage reorders HUD sides to
- * follow the currently specced player.
+ * accents (counter plate fills and digits, minimap sub tiles) in its ink
+ * color, fixed for the game and picked to contrast — a per-frame team identity
+ * signal where screen position is not one (casts reorder HUD sides).
  */
 import type { Mat } from "./cv";
 import { copyRoi, type Roi } from "./image";
@@ -22,10 +20,9 @@ const INK_MIN_SATURATION = 60;
 const MIN_INK_PIXELS = 30;
 
 /**
- * Mean RGB of the ink-saturated pixels across the ROIs (channel spread at
- * least `minSaturation`); null when fewer than MIN_INK_PIXELS qualify.
- * Averaging only saturated pixels keeps dark/white surroundings (plate
- * fills, digit cores, tile backgrounds) from washing the hue out.
+ * Mean RGB of the ink-saturated pixels across the ROIs (channel spread at least
+ * `minSaturation`); null when fewer than MIN_INK_PIXELS qualify. Averaging only
+ * saturated pixels keeps dark/white surroundings from washing the hue out.
  */
 export function meanInkColor(
 	frame: Mat,
diff --git a/app/features/scanner/core/localized.ts b/app/features/scanner/core/localized.ts
index df2f1ac80..9ec51d0f9 100644
--- a/app/features/scanner/core/localized.ts
+++ b/app/features/scanner/core/localized.ts
@@ -1,11 +1,8 @@
 /**
- * Flattened localized match sets derived from the generated
- * localized-entries.ts: detectors snap OCR output against every language's
- * strings at once and report the sendou.ink id, so ingestion works no
- * matter which language the player runs the game in. Combos (mode+stage,
- * lobby+mode) stay within one language — on-screen text never mixes
- * languages — which keeps the cross product from inventing pairings no UI
- * would show.
+ * Flattened localized match sets from the generated localized-entries.ts:
+ * detectors snap OCR output against every language's strings at once and
+ * report the sendou.ink id. Combos (mode+stage, lobby+mode) stay within one
+ * language — on-screen text never mixes languages.
  */
 import type { ModeShort, StageId } from "~/modules/in-game-lists/types";
 import type { ScannerLobby } from "../scanner-types";
diff --git a/app/features/scanner/core/match-builder.ts b/app/features/scanner/core/match-builder.ts
index 82a08615e..ef6a4a150 100644
--- a/app/features/scanner/core/match-builder.ts
+++ b/app/features/scanner/core/match-builder.ts
@@ -2,13 +2,11 @@
  * Groups a detected-event timeline into ScannerMatch objects
  * (scanner-match.ts). A MapStart opens a match, a scoreboard-type event
  * closes one, and deaths in between belong to it; a scoreboard with no
- * preceding MapStart claims the last 8 minutes of deaths. Between delimiters
- * (casted footage has none) minimaps group per map by stage change and time
- * gap, since a Splatoon game runs a few minutes. A match is emitted only
- * when a scoreboard or minimaps back it (a MapStart with a missed results
- * screen identifies nothing), regardless of lobby/outcome —
- * `ingestSkipReasons` filters those. Deaths are harvested onto player rows
- * as enemy builds (ability-harvest.ts).
+ * preceding MapStart claims the last 8 minutes of deaths. Without delimiters
+ * (casted footage) minimaps group per map by stage change and time gap. A
+ * match is emitted only when a scoreboard or minimaps back it, regardless of
+ * lobby/outcome — `ingestSkipReasons` filters those. Deaths are harvested
+ * onto player rows as enemy builds (ability-harvest.ts).
  */
 import type {
 	AbilityWithUnknown,
@@ -75,83 +73,64 @@ import {
 /** The lobby header value private battles (tournament games) carry. */
 const TOURNAMENT_LOBBY = "PRIVATE";
 
-/**
- * How far back a scoreboard with no preceding MapStart claims deaths as its
- * match — matches run well under 8 minutes, so anything older is another
- * (undelimited) match's.
- */
+/** How far back a scoreboard with no MapStart claims deaths: matches run well under 8 min. */
 const FALLBACK_WINDOW_SECONDS = 480;
 
-/**
- * Two minimaps more than this far apart cannot be the same game, so they
- * open separate matches even on the same stage.
- */
+/** Minimaps further apart than this cannot be the same game, even on the same stage. */
 const MATCH_GAP_SECONDS = 300;
 
 const PLAYERS_PER_TEAM = 4;
 
 /**
- * Slack the ended-early check gives a match before calling it a disconnect:
- * a counter read is a snapshot of numbers that keep moving, and the results
- * screen is only read some seconds after the last whistle.
+ * Slack before calling a match a disconnect: a counter read is a snapshot of
+ * moving numbers, and the results screen is read seconds after the last whistle.
  */
 const EARLY_END_MARGIN_SECONDS = 10;
 
 /**
- * The two team-ink hues must be at least this far apart before color is
- * trusted to orient counter reads: a game's color pair is picked to
- * contrast (attested pairs measure >130° apart), so a closer seed pair is
- * a misread, and orientation falls back to the as-read arrangement.
+ * Minimum hue distance between the two team inks before color orients counter
+ * reads: attested pairs measure >130° apart, so a closer seed pair is a misread
+ * and orientation falls back to the as-read arrangement.
  */
 const MIN_TEAM_HUE_SEPARATION = 30;
 
 /**
- * A counter read whose projected clock zero (`t + time`) sits further than
- * this from the match's dominant projection was taken off a broadcast
- * replay of another moment, not the live game. Live projections jitter by
- * a couple of seconds (wall clock and match timer both round to whole
- * seconds); attested replay wipes land a minute or more away.
+ * A read whose projected clock zero (`t + time`) sits further than this from
+ * the match's dominant projection came off a broadcast replay. Live projections
+ * jitter a couple of seconds (both clocks round to whole seconds); attested
+ * replay wipes land a minute or more away.
  */
 const REPLAY_ANCHOR_TOLERANCE_SECONDS = 10;
 
 /**
- * Dead-flag runs that fit between their flanking opposite-state reads in
- * less than these spans are physically impossible and get flipped to their
- * surroundings: the fastest respawn in Splatoon is 3.5s, so no true dead
- * stretch is shorter — while a respawned player CAN be re-splatted quickly
- * (spawncamps are real), so the alive floor stays a conservative 2s and
- * only clears blips like background ink bleeding through a crossed-out
- * icon. Judging by the flank-to-flank span (the longest the state could
- * truly have held) keeps sparse sampling honest: a lone dead read between
- * far-apart reads spans wide and is left alone.
+ * Dead-flag runs whose flank-to-flank span is shorter than these are flipped
+ * to their surroundings: the fastest respawn is 3.5s, so no true dead stretch
+ * is shorter, while a respawned player CAN be re-splatted fast (spawncamps),
+ * so the alive floor stays a conservative 2s. Judging by the flank-to-flank
+ * span keeps sparse sampling honest: a lone dead read between far-apart reads
+ * spans wide and is left alone.
  */
 const DEAD_RUN_MIN_SECONDS = 3.5;
 const ALIVE_RUN_MIN_SECONDS = 2;
 
 /**
- * A held special only goes away by being used (or by dying), and regaining
- * one takes at least this long — no special charges off ~10s of painting
- * even with max Special Charge Up. So an interior not-ready run flanked by
- * ready reads closer together than this, with no death inside the run, is
- * a misread gap (the ready wash pulses through a dim trough; overlays
- * clip the icons) and is bridged to ready.
+ * Regaining a used special takes at least this long (nothing charges off ~10s
+ * of painting even with max Special Charge Up), so a not-ready run flanked by
+ * ready reads closer than this, with no death inside, is a misread gap (the
+ * ready wash pulses through a dim trough; overlays clip icons) and is bridged.
  */
 const SPECIAL_REGAIN_MIN_SECONDS = 10;
 
 export interface BuiltMatch<E extends DetectedEvent> {
 	match: ScannerMatch;
-	/**
-	 * the input events the match was built from, chronological — the
-	 * send-status unit for callers with richer event records (StoredEvent)
-	 */
+	/** input events the match was built from, chronological — the send-status unit for callers */
 	sources: E[];
 }
 
 /**
- * Splits a timeline into ScannerMatch objects, chronological. Event types
- * that identify no match (ScoreboardOwn) are ignored. Every input event ends
- * up in at most one match's `sources` — orphan pools are cleared the moment
- * a boundary claims or invalidates them.
+ * Splits a timeline into ScannerMatch objects, chronological. Event types that
+ * identify no match (ScoreboardOwn) are ignored. Every input event ends up in
+ * at most one match's `sources`.
  */
 export function buildScannerMatches<E extends DetectedEvent>(
 	events: readonly E[],
@@ -211,9 +190,8 @@ export function buildScannerMatches<E extends DetectedEvent>(
 		} else if (event.type === MINIMAP_EVENT_TYPE) {
 			const stage = (event.data as MinimapData).stage;
 			if (open) {
-				// a stage change only splits when the next read doesn't refute
-				// it: a lone disagreeing frame is a misread to fold in as a
-				// minority vote, not a match boundary
+				// a stage change only splits when the next read doesn't refute it: a
+				// lone disagreeing frame is a misread folded in as a minority vote
 				const current = leadingStage(open.stageVotes);
 				const stageChanged =
 					current !== null &&
@@ -252,14 +230,12 @@ export type IngestSkipReason =
 	| "disconnect";
 
 /**
- * Which built matches are not worth sending to /ingest, and why. Kept out:
- * non-tournament lobbies (unread lobbies get the benefit of the doubt), and
- * games a disconnect cut short — proven either by counter reads showing the
- * game couldn't have ended on its own (see `endedEarly`), or by the same
- * map/mode being replayed right after with a score. Replay evidence only
- * ever arrives after the fact, so a live scan may already have sent the
- * abandoned game before its replay is detected; the counter-read check is
- * what catches it in the moment.
+ * Which built matches are not worth sending to /ingest, and why: non-tournament
+ * lobbies (unread lobbies get the benefit of the doubt), and games a disconnect
+ * cut short — counter reads show the game couldn't have ended on its own
+ * (`endedEarly`), or the same map/mode was replayed right after with a score.
+ * Replay evidence only arrives after the fact, so a live scan may already have
+ * sent the abandoned game; the counter-read check catches it in the moment.
  */
 export function ingestSkipReasons<E extends DetectedEvent>(
 	built: readonly BuiltMatch<E>[],
@@ -277,12 +253,10 @@ export function ingestSkipReasons<E extends DetectedEvent>(
 }
 
 /**
- * Objective-counter and player-status reads that landed on a match whose
+ * Objective-counter, player-status and strip-weapon reads on a match whose
  * detected mode is not Splat Zones — the SZ parser (the only one so far)
- * misreading another mode's counter overlay, and the statuses that rode
- * along with those misreads. The builder already leaves such a match's
- * `objective`/`playerStatus` null; callers should delete these events from
- * their stores.
+ * misreading another mode's overlay. The builder already leaves such a match's
+ * `objective`/`playerStatus` null; callers should delete these from their stores.
  */
 export function invalidObjectiveEvents<E extends DetectedEvent>(
 	built: readonly BuiltMatch<E>[],
@@ -300,12 +274,10 @@ export function invalidObjectiveEvents<E extends DetectedEvent>(
 }
 
 /**
- * Whether a disconnect ended the match before it could be decided: it has a
- * results screen but no score on it, and its last counter read still needed
- * more game left than the footage gave it. From that read a game can end no
- * sooner than the clock running out, or the lower counter falling to zero at
- * its 1/s cap (a knockout) with any penalty worked off first — so when even
- * that came due after the match was already over, it was cut short.
+ * A disconnect ended the match before it was decided: a results screen with no
+ * score, and the last counter read still needed more game than the footage
+ * gave it — a game ends no sooner than the clock running out or the lower
+ * counter falling to zero at its 1/s cap (penalty worked off first).
  */
 function endedEarly(match: ScannerMatch): boolean {
 	// no results screen at all: an unfinished scan, not an unfinished game
@@ -335,10 +307,9 @@ function secondsUntilSoonestEnd(
 
 /**
  * Whether the scoreless match at `index` was played again right after: the
- * run of matches following it on the same mode and stage is the same game
- * restarted, so one of them reaching a score means the earlier attempts
- * ended in a disconnect. The run stops at the first other map, which keeps
- * the same map coming up again later in the scan out of it.
+ * following matches on the same mode and stage are the same game restarted, so
+ * one of them reaching a score means the earlier attempts were disconnects.
+ * The run stops at the first other map.
  */
 function wasReplayed<E extends DetectedEvent>(
 	built: readonly BuiltMatch<E>[],
@@ -370,12 +341,10 @@ interface OpenMatch<E extends DetectedEvent> {
 	stripWeapons: E[];
 	scoreboard: E | null;
 	/**
-	 * per-stage read counts (a MapStart's stage seeds it); the plurality
-	 * winner delimits same-vs-next map so one misread frame can't poison
-	 * the whole match
+	 * per-stage read counts (a MapStart's stage seeds it); the plurality winner
+	 * delimits same-vs-next map so one misread frame can't poison the match
 	 */
 	stageVotes: Map<StageId, number>;
-	/** t of the last minimap added, for the gap check */
 	lastMinimapT: number | null;
 }
 
@@ -394,8 +363,8 @@ function startMatch<E extends DetectedEvent>(): OpenMatch<E> {
 }
 
 /**
- * For each minimap event, the next minimap's non-null stage read (walked
- * backwards) — the refutation signal for the stage-change split.
+ * For each minimap event, the next minimap's non-null stage read — the
+ * refutation signal for the stage-change split.
  */
 function buildNextStageMap<E extends DetectedEvent>(
 	sorted: readonly E[],
@@ -471,10 +440,9 @@ function toBuiltMatch<E extends DetectedEvent>(
 	const minimaps = minimapReads.map((read) => read.data);
 
 	const mode = board?.mode ?? start?.mode ?? null;
-	// only the SZ counter is parsed — reads on a known other-mode match are
-	// misreads of a lookalike overlay, not progress data (statuses included:
-	// they only ever ride along with counter reads). Minimap card states are
-	// mode-agnostic, so they feed the status samples regardless
+	// only the SZ counter is parsed: reads on a known other-mode match are
+	// lookalike-overlay misreads (statuses ride along with counter reads).
+	// Minimap card states are mode-agnostic and feed status samples regardless
 	const counterModeValid = mode === null || mode === "SZ";
 	const progress = buildProgress(
 		counterModeValid ? objectives : [],
@@ -505,11 +473,10 @@ function toBuiltMatch<E extends DetectedEvent>(
 			? board.matchScores
 			: null,
 		replayCode: timestamped?.replayCode ?? null,
-		// layout alone cannot flag a broadcast: S3 first-person POV footage
-		// draws both narrow strip geometries, so only actual cast evidence
-		// counts — the spectator map screen or badge-proven strips. A results
-		// screen that identified the POV seat disproves them all: casts never
-		// see a results screen, so such evidence was misread
+		// layout alone cannot flag a broadcast (S3 POV footage draws both narrow
+		// strip geometries), so only the spectator map screen or badge-proven
+		// strips count; a results screen that identified the POV seat disproves
+		// them all — casts never see one
 		cast:
 			pov === null &&
 			(open.minimaps.some((event) => (event.data as MinimapData).spectator) ||
@@ -532,48 +499,36 @@ function floorOrNull(t: number | undefined): number | null {
 
 /**
  * The counter reads as `objective` samples and the icon-strip reads as
- * `playerStatus` samples, both in `teams` order. On POV footage the left
- * plate is the POV/alpha side for the whole game, but casted footage
- * reorders the plates to follow the specced player — so each counter read
- * is first oriented by its sides' team ink hues (clustered against the
- * first read that saw both), making the series side-stable; a status read
- * carries no ink of its own and inherits the orientation of the counter
- * read nearest in time (they are emitted off the same frames). Broadcast
- * replay wipes re-run an earlier moment with the whole HUD intact, so both
- * series are anchored by their projected clock zero (`t + time`) against
- * one shared dominant projection — the live game — and reads off it are
- * dropped; timerless reads follow their preceding anchored neighbor. A
- * displayed count never increases (it shows the team's best remaining), so
- * each side's counter series then keeps only its longest non-increasing
- * run of scores — surviving OCR blips are voided rather than charted. Both
- * series then go into `teams` order: a scoreboard-closed match is
- * winner-first (POV seat when read; else in SZ the winner is the side
- * whose remaining count went furthest down), a minimap-grouped match
- * anchors on the minimap's own/alpha-vs-enemy/bravo ink colors, and with
- * no signal the first read's arrangement stands. A side's four slots keep
- * their on-screen left-to-right order through a side swap — whether the
- * game mirrors slot order across sides is unattested so far.
+ * `playerStatus` samples, both in `teams` order. POV footage keeps the POV
+ * side on the left plate, but casted footage reorders the plates to follow
+ * the specced player — so each counter read is first oriented by its sides'
+ * ink hues (clustered against the first read that saw both); a status read
+ * carries no ink and inherits the orientation of the nearest counter read in
+ * time (same frames). Broadcast replay wipes re-run an earlier moment with the
+ * HUD intact, so both series are anchored by projected clock zero (`t + time`)
+ * against one shared dominant projection and reads off it are dropped;
+ * timerless reads follow their preceding anchored neighbor. A displayed count
+ * never increases, so each side keeps only its longest non-increasing score
+ * run (blips voided, not charted). Then into `teams` order: scoreboard-closed
+ * is winner-first (POV seat when read; else in SZ the side whose count went
+ * furthest down), minimap-grouped anchors on the minimap's own-vs-enemy ink
+ * colors, no signal keeps the first read's arrangement. Slots keep their
+ * on-screen left-to-right order through a side swap (whether the game mirrors
+ * slot order across sides is unattested).
  *
- * Minimap reads contribute status samples too (their card cross-out and
- * special-camo states), interleaved with the icon-strip reads on the same
- * replay-wipe anchor (timerless, so each follows its anchored neighbor).
- * Their sides are own/alpha-vs-enemy/bravo — camera-stable, unlike the
- * plates — so they skip the per-read cluster orientation and map to
- * `teams` through the same minimap ink anchor the whole match uses
- * (identity on a minimap-grouped match by construction).
+ * Minimap reads contribute status samples too (card cross-out and camo
+ * states), interleaved on the same replay-wipe anchor. Their sides are
+ * own/enemy — camera-stable — so they skip cluster orientation and map to
+ * `teams` through the match's minimap ink anchor.
  *
- * Within a side, the strip's slot order is the lobby seating while a
- * results scoreboard re-sorts its rows per game (attested in the
- * sendou-triton VoD) — so on a scoreboard-closed match each side's slots
- * are reordered into row order via the slot→row assignment
- * (slot-row-assignment.ts): weapon votes from the sampled StripWeapons
- * evidence plus the minimap's card columns, which mirror the strip's
- * seating (attested for the enemy column; the spectator screen's own
- * column is assumed symmetric). The POV overlay's teammate diamond
- * follows neither order, so diamond-sourced flags map by card name
- * instead, and keep their as-drawn order when too few names resolve. A
- * minimap-grouped match's `teams` come from the cards themselves, so its
- * samples stay as drawn by construction.
+ * Within a side the strip's slot order is the lobby seating while a results
+ * scoreboard re-sorts rows per game (attested in the sendou-triton VoD), so on
+ * a scoreboard-closed match each side's slots are reordered into row order via
+ * slot-row-assignment.ts: weapon votes from StripWeapons evidence plus the
+ * minimap's card columns (mirror the strip seating; attested for the enemy
+ * column, own column assumed symmetric). The POV diamond follows neither
+ * order, so its flags map by card name and stay as drawn when too few names
+ * resolve. A minimap-grouped match's samples stay as drawn by construction.
  */
 function buildProgress(
 	objectives: readonly { t: number; data: ObjectiveData }[],
@@ -689,19 +644,16 @@ interface SlotRowPerms {
 }
 
 /**
- * How much one minimap card's parsed weapon counts next to the strip
- * evidence's raw NCC scores (~0.3-0.6 per candidate per read): the card
- * parser is gated on a clean read, so one card outweighs a single strip
- * sample without being able to drown a match's worth of them.
+ * One minimap card's parsed weapon next to raw strip NCC scores (~0.3-0.6 per
+ * candidate per read): the card parser is gated on a clean read, so one card
+ * outweighs a single strip sample without drowning a match's worth of them.
  */
 const MINIMAP_CARD_VOTE = 1;
 
 /**
- * Accumulate the match's weapon votes (sampled strip evidence oriented
- * read-by-read like the status samples; minimap cards through the match's
- * minimap anchor) and solve each side's slot→row assignment against the
- * scoreboard's weapons, plus the diamond's name-based assignment for POV
- * teammate cards.
+ * Accumulates the match's weapon votes (strip evidence oriented read-by-read,
+ * minimap cards through the minimap anchor) and solves each side's slot→row
+ * assignment against the scoreboard's weapons, plus the diamond's name-based one.
  */
 function slotRowPermutations(
 	board: ScoreboardData,
@@ -792,9 +744,8 @@ function slotRowPermutations(
 }
 
 /**
- * Which permutation a status read's `sourceSide` flags go through on their
- * way to teams side `side`: strip-seated sources (the strip itself, card
- * columns) take the weapon-vote assignment, the POV diamond its name
+ * The permutation a status read's `sourceSide` flags take to teams side `side`:
+ * strip-seated sources use the weapon-vote assignment, the POV diamond its name
  * assignment; a minimap-grouped match (no perms) keeps everything as drawn.
  */
 function readPermutation(
@@ -811,12 +762,11 @@ function readPermutation(
 }
 
 /**
- * Debounce per-slot dead flags across a match's samples: an interior run
- * whose flanking opposite-state reads sit closer together than the state
- * could truly have held (DEAD/ALIVE_RUN_MIN_SECONDS) is a misread blip
- * (background ink bleeding through a translucent splatted icon, or a box
- * over a mid-animation icon) and takes the flanking state instead. Edge
- * runs stay — nothing attests what came before or after the match window.
+ * Debounces per-slot dead flags: an interior run whose flanking opposite-state
+ * reads sit closer than the state could have held (DEAD/ALIVE_RUN_MIN_SECONDS)
+ * is a misread blip (background ink through a translucent splatted icon, a box
+ * over a mid-animation icon) and takes the flanking state. Edge runs stay —
+ * nothing attests what came before or after the match window.
  */
 function withImpossibleDeadRunsFlipped(
 	samples: ScannerMatchPlayerStatusSample[],
@@ -863,13 +813,11 @@ function withImpossibleDeadRunsFlipped(
 }
 
 /**
- * Bridge per-slot special-ready gaps: an interior not-ready run whose
- * flanking ready reads sit closer together than a special could truly be
- * regained (SPECIAL_REGAIN_MIN_SECONDS), with no death inside the run to
- * explain the loss, is a misread gap (the ready wash pulses through a dim
- * trough) and reads ready throughout. Short READY runs are left alone — a
- * just-charged special really can be spent within a read or two. Edge
- * runs stay too: nothing attests the state beyond the match window.
+ * Bridges per-slot special-ready gaps: an interior not-ready run whose flanking
+ * ready reads sit closer than SPECIAL_REGAIN_MIN_SECONDS, with no death inside
+ * to explain the loss, is a misread gap (the ready wash's dim pulse trough) and
+ * reads ready throughout. Short READY runs stay (a fresh special really can be
+ * spent within a read or two), as do edge runs.
  */
 function withShortSpecialGapsBridged(
 	samples: ScannerMatchPlayerStatusSample[],
@@ -915,11 +863,7 @@ interface StatusRead {
 	t: number;
 	/** minimap sides are own/enemy — camera-stable, unlike the HUD plates */
 	fromMinimap: boolean;
-	/**
-	 * minimap reads only: the 8-card spectator screen, whose own-side
-	 * column is card-seated like the enemy one — the POV overlay's
-	 * teammate diamond is not (see readPermutation)
-	 */
+	/** minimap reads only: the 8-card spectator screen, whose own column is card-seated like the enemy one — the POV diamond is not (see readPermutation) */
 	spectator?: boolean;
 	data: {
 		time: number | null;
@@ -929,11 +873,9 @@ interface StatusRead {
 }
 
 /**
- * The minimap reads' card/row states as status reads: own/alpha side
- * first, slots in card order — the same order `teamsFromMinimaps` seats
- * players — with absent cards padded false (nothing to chart, never a
- * fabricated state). A read that saw no cards at all identifies nobody
- * and contributes nothing.
+ * The minimap reads' card states as status reads: own side first, slots in card
+ * order (the order `teamsFromMinimaps` seats players), absent cards padded
+ * false. A read that saw no cards identifies nobody and contributes nothing.
  */
 function minimapStatusReads(
 	minimapReads: readonly { t: number; data: MinimapData }[],
@@ -969,10 +911,9 @@ function sideFlags(
 }
 
 /**
- * The cluster-orientation flag of the counter read nearest in time —
- * status reads are emitted off the same frames as counter reads, so the
- * nearest one saw the same camera arrangement. False when no counter read
- * carried a usable flag (POV footage never swaps anyway).
+ * The cluster-orientation flag of the counter read nearest in time — status
+ * reads come off the same frames, so the nearest one saw the same camera
+ * arrangement. False when no counter read carried a flag (POV never swaps).
  */
 function nearestSwapFlag(
 	objectives: readonly { t: number }[],
@@ -1001,9 +942,8 @@ interface OrientedObjectiveRead {
 }
 
 /**
- * The two team-ink cluster hues, seeded from the first read that saw both
- * sides' colors far enough apart; null when no read qualifies (color
- * orientation then stays at the as-read arrangement).
+ * The two team-ink cluster hues, seeded from the first read that saw both sides
+ * far enough apart; null when none qualifies (orientation stays as read).
  */
 function seedClusterHues(
 	objectives: readonly { data: ObjectiveData }[],
@@ -1018,11 +958,10 @@ function seedClusterHues(
 }
 
 /**
- * Per-read cluster assignment of the sides: a read whose ink hues sit
- * closer to the clusters crosswise is swapped (the cast switched the
- * specced side). Reads with no readable color inherit the previous read's
- * orientation — plate arrangement only changes with a camera change, which
- * leaves the colors readable once the plates are back.
+ * Per-read side orientation: a read whose ink hues sit closer to the clusters
+ * crosswise is swapped (the cast switched the specced side). Reads with no
+ * readable color inherit the previous orientation — plates only rearrange with
+ * a camera change, which leaves the colors readable once they are back.
  */
 function readSwapFlags(
 	objectives: readonly { t: number; data: ObjectiveData }[],
@@ -1073,9 +1012,8 @@ function readSwapped(
 }
 
 /**
- * Whether the cluster order is bravo-first, judged against the minimap's
- * ink colors (own/alpha column, enemy/bravo column) — the `teams` anchor
- * for cast matches, which never see a results screen.
+ * Whether the cluster order is bravo-first, judged against the minimap's ink
+ * colors (own then enemy) — the `teams` anchor for cast matches.
  */
 function minimapAnchorSwap(
 	clusterHues: [number, number] | null,
@@ -1093,10 +1031,7 @@ function minimapAnchorSwap(
 	return swappedCost < identityCost;
 }
 
-/**
- * Componentwise mean of the minimap reads' per-side ink colors; null when
- * no read got a side's color (or there were no minimaps at all).
- */
+/** Componentwise mean of the minimap reads' per-side ink colors; null when unread. */
 function minimapTeamColors(
 	minimaps: readonly MinimapData[],
 ): [InkRgb | null, InkRgb | null] | null {
@@ -1116,9 +1051,8 @@ function minimapTeamColors(
 }
 
 /**
- * The dominant clock-zero projection across every read that carried a
- * timer; null when none did. Counter and status reads project the same
- * live clock, so one shared anchor voids replay wipes from both series.
+ * The dominant clock-zero projection across every timed read; null when none.
+ * Counter and status reads project the same clock, so one anchor voids both.
  */
 function dominantAnchorOf(
 	reads: readonly { t: number; data: { time: number | null } }[],
@@ -1130,14 +1064,12 @@ function dominantAnchorOf(
 }
 
 /**
- * Drops reads taken off broadcast replay wipes: `t + time` projects the
- * wall-clock moment the match timer reaches zero, which stays constant
- * across a live game but lands far away when the broadcast re-runs an
- * earlier moment, clock and all. Only reads near the dominant projection
- * (the live series always outnumbers ~30s replay clips) are kept; a
- * timerless read shares the fate of its preceding anchored neighbor (the
- * following one for a timerless head), so an unreadable — or as yet
- * unattested overtime — timer display never voids live reads.
+ * Drops reads taken off broadcast replay wipes: `t + time` projects the moment
+ * the match timer hits zero, constant across a live game but far off when the
+ * broadcast re-runs an earlier moment. Only reads near the dominant projection
+ * (the live series outnumbers ~30s replay clips) are kept; a timerless read
+ * shares the fate of its preceding anchored neighbor (the following one for a
+ * timerless head), so an unreadable timer never voids live reads.
  */
 function withoutReplayReads<
 	T extends { t: number; data: { time: number | null } },
@@ -1179,12 +1111,10 @@ function dominantAnchor(anchors: readonly number[]): number {
 }
 
 /**
- * Voids score reads that contradict SZ's countdown: per side, only the
- * longest non-increasing subsequence of the readable scores is kept and
- * every read off it gets that side's score nulled (its penalty/control
- * stand). A misread that slipped past the detector — a truncated "50"
- * charted as a 0-dip, a stray 100 — is always the minority against the
- * surrounding correct series, so it is what gets dropped.
+ * Voids score reads that contradict SZ's countdown: per side, only the longest
+ * non-increasing subsequence of readable scores is kept and every read off it
+ * gets that side's score nulled (penalty/control stand). A misread (a truncated
+ * "50" charted as 0, a stray 100) is always the minority, so it is what drops.
  */
 function withMonotonicScores(
 	oriented: readonly OrientedObjectiveRead[],
@@ -1237,11 +1167,10 @@ function bestCount(
 }
 
 /**
- * The wall-clock time the match was played: a replay/battle log screen's
- * on-screen recording timestamp (anchored to when the screen was seen, not
- * a possibly much later send), else the closing scoreboard's detection
- * time. Detection times ride richer event records (StoredEvent) and are
- * read structurally so the builder stays generic.
+ * When the match was played: a replay/battle log screen's on-screen recording
+ * timestamp (anchored to when the screen was seen, not a later send), else the
+ * closing scoreboard's detection time — read structurally off richer event
+ * records (StoredEvent) so the builder stays generic.
  */
 function playedAt(
 	scoreboard: DetectedEvent | null,
@@ -1288,9 +1217,9 @@ function teamsFromScoreboard(
 }
 
 /**
- * Players merged across a match's minimap frames, alpha side then bravo:
- * weapons and names are fixed for a match, so a slot missed in one frame is
- * filled from another (first frame that read it wins).
+ * Players merged across a match's minimap frames, alpha then bravo: weapons and
+ * names are fixed for a match, so a slot missed in one frame is filled from
+ * another (first read wins).
  */
 function teamsFromMinimaps(
 	frames: readonly MinimapData[],
@@ -1350,11 +1279,10 @@ interface MinimapCardRead {
 }
 
 /**
- * Gear mains per scoreboard row, harvested from the match's minimap cards.
- * A card's drawn position is no seat — a frame leaves absent and
- * evidence-less cards out of its columns — so cards identify their row by
- * name and weapon instead, within their own column's side (own/enemy is
- * camera-stable, unlike the HUD plates).
+ * Gear mains per scoreboard row, harvested from the minimap cards. A card's
+ * drawn position is no seat (frames leave absent cards out of their columns),
+ * so cards identify their row by name and weapon within their own column's
+ * side (own/enemy is camera-stable, unlike the HUD plates).
  */
 function minimapMainsByRow(
 	board: ScoreboardData,
@@ -1381,8 +1309,8 @@ function minimapMainsByRow(
 
 /**
  * The gear mains a set of card reads agree on: badges come and go with
- * cross-outs and camo surfaces, so each slot takes its first identified
- * read. Null when no read identified any of the three.
+ * cross-outs and camo, so each slot takes its first identified read. Null when
+ * no read identified any of the three.
  */
 function mergeMains(reads: readonly GearMains[]): GearMains | null {
 	const mains = GEAR_SLOTS.map((slot) => {
diff --git a/app/features/scanner/core/match-sets.ts b/app/features/scanner/core/match-sets.ts
index ef112ebad..483ea1b41 100644
--- a/app/features/scanner/core/match-sets.ts
+++ b/app/features/scanner/core/match-sets.ts
@@ -1,28 +1,22 @@
 /**
- * Divide a chronological run of ScannerMatches into sets — consecutive games
- * played by the same eight players (a Bo3/Bo5 between two teams). Rosters
- * are compared by in-game names pooled across both teams (scoreboards list
- * winners first, so team sides swap between games): names match fuzzily
- * because two OCR reads of the same name can differ by a glyph or two, and
- * one differing player is tolerated as a sub between games. A match with no
- * readable names is inconclusive and never opens a new set.
+ * Divides a chronological run of ScannerMatches into sets — consecutive games
+ * by the same eight players. Rosters are compared by names pooled across both
+ * teams (sides swap between games), fuzzily since two OCR reads of a name can
+ * differ by a glyph or two; one differing player is tolerated as a sub. A
+ * match with no readable names is inconclusive and never opens a new set.
  */
 import type { ScannerMatch } from "./scanner-match";
 import { matchKey, rankBy } from "./text";
 
-/**
- * closestBy score two reads of the same name must reach — 0.7 forgives one
- * bad glyph on a four-letter name, two on longer ones.
- */
+/** closestBy score two reads of a name must reach: 0.7 forgives one bad glyph on four letters. */
 const SAME_NAME_SCORE = 0.7;
 
 /** Players allowed to differ between consecutive games of one set. */
 const MAX_SUBS_PER_GAME = 1;
 
 /**
- * For each match its 1-based set number, aligned by index with the input;
- * matches must be in chronological order. Numbers only ever step up by one:
- * a match whose roster disagrees with the current set's opens the next set.
+ * Each match's 1-based set number, aligned by index with the (chronological)
+ * input. A roster disagreeing with the current set's opens the next set.
  */
 export function assignMatchSets(matches: readonly ScannerMatch[]): number[] {
 	const setNumbers: number[] = [];
@@ -48,9 +42,8 @@ function rosterNames(match: ScannerMatch): string[] {
 
 /**
  * Whether two rosters read as the same eight players: every name of the
- * smaller roster must find a partner in the other, short of
- * MAX_SUBS_PER_GAME misses. Partial reads compare only what both saw, so a
- * minimap-sourced half-roster still chains a set together.
+ * smaller roster must find a partner in the other, short of MAX_SUBS_PER_GAME
+ * misses. Partial reads compare only what both saw.
  */
 function sameRoster(a: readonly string[], b: readonly string[]): boolean {
 	const remaining = [...b];
@@ -69,11 +62,10 @@ function sameRoster(a: readonly string[], b: readonly string[]): boolean {
 }
 
 /**
- * Whether two reads of a name agree on a leading prefix long enough that the
- * difference reads as tail damage, not another player. CJK names run 2-4
- * glyphs, so a single truncated (れた → れ) or garbled (ほった → ほっ′`)
- * tail glyph sinks the edit-distance score below any usable threshold while
- * the OCR damage sits, as it nearly always does, at the end of the row.
+ * Whether two reads of a name share a prefix long enough that the difference
+ * reads as tail damage. CJK names run 2-4 glyphs, so one truncated (れた → れ)
+ * or garbled (ほった → ほっ′`) tail glyph sinks the edit-distance score below
+ * any usable threshold, while OCR damage nearly always sits at the row's end.
  */
 function sharedPrefixRead(a: string, b: string): boolean {
 	const keyA = matchKey(a);
diff --git a/app/features/scanner/core/replay-time.ts b/app/features/scanner/core/replay-time.ts
index d9fab2aff..2c0a87ab0 100644
--- a/app/features/scanner/core/replay-time.ts
+++ b/app/features/scanner/core/replay-time.ts
@@ -1,14 +1,12 @@
 /**
- * Turns the replay browser's on-screen recording timestamp (locale-formatted
- * by the console, e.g. "3/7/2026 22:28", "7.3.2026 22:28", "2026/3/7 22:28")
- * into a UTC epoch, read in the local timezone. The string carries no
- * timezone or day/month-order marker, so ambiguous day-vs-month (both ≤ 12)
- * resolves in three steps: hour 0 or ≥13 proves a 24h clock (12h consoles
- * render AM/PM) and 24h locales are near-universally day-first, except
- * en-US which is 12h; failing that, the browser locale's date-part order
- * decides; finally, since the console's locale and the browser's can still
- * disagree, a recency check swaps day/month when that reading lands near now
- * while the un-swapped one doesn't (replays are near-always ingested soon
+ * Turns the replay browser's on-screen recording timestamp (console-locale
+ * formatted: "3/7/2026 22:28", "7.3.2026 22:28", "2026/3/7 22:28") into a UTC
+ * epoch in the local timezone. The string carries no timezone or day/month
+ * marker, so an ambiguous day-vs-month (both ≤ 12) resolves in three steps:
+ * hour 0 or ≥13 proves a 24h clock, and 24h locales are near-universally
+ * day-first (en-US is 12h); failing that, the browser locale's date-part
+ * order decides; finally a recency check swaps day/month when that reading
+ * lands near now while the un-swapped one doesn't (replays are ingested soon
  * after recording).
  */
 
@@ -23,10 +21,9 @@ const FUTURE_SLACK_MS = 24 * 60 * 60 * 1000;
 type Ymd = { year: number; month: number; day: number };
 
 /**
- * Parses a replay timestamp into UTC epoch milliseconds, or null when the
- * string doesn't form a valid date. `locale` defaults to the environment's;
- * `now` (default `Date.now()`) anchors the recency disambiguation — pass the
- * moment the replay screen was on-screen, not the send time.
+ * Parses a replay timestamp into UTC epoch ms, or null when invalid. `now`
+ * (default `Date.now()`) anchors the recency disambiguation — pass the moment
+ * the replay screen was on-screen, not the send time.
  */
 export function parseReplayTimestamp(
 	raw: string,
@@ -39,9 +36,8 @@ export function parseReplayTimestamp(
 	const minutes = Number(m[5]!);
 	if (hours > 23 || minutes > 59) return null;
 
-	// hour 0 or ≥13 only occurs on a 24h clock, and 24h locales are
-	// near-universally day-first; only an ambiguous hour falls back to the
-	// browser locale, which may not match the console's
+	// hour 0 or ≥13 only occurs on a 24h clock, and 24h locales are near-universally
+	// day-first; only an ambiguous hour falls back to the browser locale
 	const is24hClock = hours === 0 || hours >= 13;
 	const resolved = resolveDateParts(
 		dateParts,
@@ -88,12 +84,11 @@ function toEpoch(
 }
 
 /**
- * Splits the three date segments into year/month/day. The year is the
- * segment with ≥3 digits (leading for ja-style "2026/3/7", trailing
- * otherwise); with no such segment the last one is a 2-digit year. Day vs
- * month resolves by magnitude when one exceeds 12, else by the caller's
- * order guess (year-first formats are month-first — no locale writes Y/D/M);
- * a guessed split also reports the swapped reading for the recency check.
+ * Splits the three date segments into year/month/day. The year is the segment
+ * with ≥3 digits (leading for ja-style, trailing otherwise), else the last one
+ * as a 2-digit year. Day vs month resolves by magnitude when one exceeds 12,
+ * else by the caller's order guess (year-first formats are month-first); a
+ * guessed split also reports the swapped reading for the recency check.
  */
 function resolveDateParts(
 	parts: number[],
diff --git a/app/features/scanner/core/resources.ts b/app/features/scanner/core/resources.ts
index 3e7a9b752..0e0f3ecc1 100644
--- a/app/features/scanner/core/resources.ts
+++ b/app/features/scanner/core/resources.ts
@@ -1,12 +1,10 @@
 /**
- * Environment-agnostic assembly of ScoreboardResources. Node (filesystem)
- * and the worker (HTTP) inject only the four IO primitives; every resource
- * key, icon directory, template option set, and atlas name lives here once,
- * so adding a resource cannot desync the two loaders. Icon/atlas decoding is
- * eager (cheap), but template prep and atlas slicing are deferred behind
- * memoized getters — a test process loads the full bundle while its one
- * detector touches only a slice, and unused sets (four weapon-template
- * builds alone are ~7k resizes) dominated startup.
+ * Environment-agnostic assembly of ScoreboardResources: Node (filesystem) and
+ * the worker (HTTP) inject only the IO primitives; every resource key, icon
+ * directory, template option set and atlas name lives here once. Icon/atlas
+ * decoding is eager (cheap); template prep and atlas slicing are memoized
+ * getters, since unused sets (four weapon-template builds alone are ~7k
+ * resizes) dominated startup.
  */
 
 import { abilities as abilityList } from "~/modules/in-game-lists/abilities";
diff --git a/app/features/scanner/core/scanner-match.ts b/app/features/scanner/core/scanner-match.ts
index 5905106d7..664ae28b8 100644
--- a/app/features/scanner/core/scanner-match.ts
+++ b/app/features/scanner/core/scanner-match.ts
@@ -1,9 +1,8 @@
 /**
- * ScannerMatch — the unit the scanner hands to the rest of sendou.ink: one
- * detected game with everything the scan could read. Built from the event
- * timeline by core/match-builder.ts; validated at the boundaries by
- * scannerMatchSchema (../scanner-schemas.ts). Every field is nullable —
- * a match may be partial (features/scanner-ingest merges partials).
+ * ScannerMatch — one detected game with everything the scan could read, built
+ * by core/match-builder.ts and validated at the boundaries by
+ * scannerMatchSchema (../scanner-schemas.ts). Every field is nullable: a match
+ * may be partial (features/scanner-ingest merges partials).
  */
 import type {
 	AbilityWithUnknown,
@@ -22,10 +21,7 @@ export interface ScannerMatchPlayer {
 	ka: number | null;
 	d: number | null;
 	s: number | null;
-	/**
-	 * [head, clothes, shoes] ability rows: death screens read whole rows
-	 * (main and subs), minimap cards their mains alone
-	 */
+	/** [head, clothes, shoes] ability rows: death screens read whole rows, minimap cards mains only */
 	abilities?: AbilityWithUnknown[][];
 }
 
@@ -38,9 +34,8 @@ export interface ScannerMatchObjectiveSample {
 	/** whole seconds into the video/stream the counter was read at */
 	t: number;
 	/**
-	 * seconds shown on the match timer at the read ("3:35" = 215); null =
-	 * unreadable. The game clock is the axis to graph progress on — score
-	 * moves at most 1/s against it.
+	 * seconds shown on the match timer ("3:35" = 215); null = unreadable. The
+	 * game clock is the axis to graph progress on — score moves at most 1/s
 	 */
 	time: number | null;
 	/** displayed count per team, in `teams` order; null = unreadable */
@@ -54,9 +49,8 @@ export interface ScannerMatchObjectiveSample {
 /**
  * Objective-counter progress over the match. Samples are chronological and
  * deduped to state changes, with an unchanged state re-confirmed every ~10s
- * while the counter stays on screen — so consecutive samples further apart
- * than that were not observed in between (capture gap, covered HUD): render
- * such stretches as unknown instead of interpolating.
+ * while the counter stays on screen — so a larger gap between samples was not
+ * observed (capture gap, covered HUD): render it as unknown, don't interpolate.
  */
 export interface ScannerMatchObjective {
 	mode: "SZ";
@@ -68,10 +62,7 @@ export type ScannerMatchPlayerFlags = [boolean, boolean, boolean, boolean];
 export interface ScannerMatchPlayerStatusSample {
 	/** whole seconds into the video/stream the icon strip was read at */
 	t: number;
-	/**
-	 * seconds shown on the match timer at the read — the same key the
-	 * objective samples carry, for charting both on one clock axis
-	 */
+	/** seconds shown on the match timer — the same key the objective samples carry */
 	time: number | null;
 	/** special held per player, teams in `teams` order, slots in row order */
 	special: [ScannerMatchPlayerFlags, ScannerMatchPlayerFlags];
@@ -80,11 +71,9 @@ export interface ScannerMatchPlayerStatusSample {
 }
 
 /**
- * Per-player special/death states over the match, read off the icon strip
- * next to the objective counter. Chronological and deduped to state
- * changes like the objective samples, with an unchanged state re-confirmed
- * every ~6s — render longer sample gaps as unknown, not as a continued
- * state.
+ * Per-player special/death states over the match, read off the icon strip next
+ * to the objective counter. Chronological and deduped like the objective
+ * samples, re-confirmed every ~6s — render longer gaps as unknown.
  */
 export interface ScannerMatchPlayerStatus {
 	samples: ScannerMatchPlayerStatusSample[];
@@ -95,40 +84,31 @@ export interface ScannerMatch {
 	startsAt: number | null;
 	/** whole seconds into the video/stream the match was last seen at */
 	endsAt: number | null;
-	/**
-	 * wall-clock ms the game was played: a replay scoreboard's recording
-	 * time, else the closing scoreboard's detection time; null on VoD scans
-	 */
+	/** wall-clock ms: a replay scoreboard's recording time, else the closing scoreboard's detection time; null on VoD scans */
 	playedAt: number | null;
 	lobby: ScannerLobby | null;
 	mode: ModeShort | null;
 	stage: StageId | null;
 	/**
-	 * the "Score:" banner game scores (0-100) in `teams` order, from a
-	 * results/replay screen; a knockout's winner reports 100. Null when no
-	 * such screen was seen.
+	 * the "Score:" banner game scores (0-100) in `teams` order from a
+	 * results/replay screen; a knockout's winner reports 100. Null when unseen.
 	 */
 	matchScores: [number | null, number | null] | null;
 	replayCode: string | null;
-	/** spectator/casted footage (the 8-player spectator map screen was seen) */
+	/** spectator/casted footage (spectator map screen or badge-proven icon strip seen) */
 	cast: boolean;
 	/**
-	 * counter progress samples in `teams` order — the builder tracks each
-	 * side's team ink color, so casted footage's plate swaps (the plates
-	 * follow the specced player) can't scramble the series; null when no
-	 * counter was read
+	 * counter progress samples in `teams` order — the builder tracks each side's
+	 * ink color so casted footage's plate swaps can't scramble the series; null
+	 * when no counter was read
 	 */
 	objective: ScannerMatchObjective | null;
 	/**
-	 * per-player special/death samples in `teams` order, oriented alongside
-	 * the objective samples (a status read pairs with the counter read of
-	 * its frame); null when the icon strip was never read
+	 * per-player special/death samples in `teams` order, oriented alongside the
+	 * objective samples; null when the icon strip was never read
 	 */
 	playerStatus: ScannerMatchPlayerStatus | null;
-	/**
-	 * on-screen order: scoreboard rows 0-3 are teams[0] (the winners),
-	 * minimap alpha/own side is teams[0]
-	 */
+	/** on-screen order: scoreboard rows 0-3 are teams[0] (the winners), minimap own side is teams[0] */
 	teams: [ScannerMatchTeam, ScannerMatchTeam];
 	/** scoreboard-sourced matches know it (0); minimap-only matches don't */
 	winner: 0 | 1 | null;
diff --git a/app/features/scanner/core/slot-row-assignment.ts b/app/features/scanner/core/slot-row-assignment.ts
index a80a1211f..5798d4f85 100644
--- a/app/features/scanner/core/slot-row-assignment.ts
+++ b/app/features/scanner/core/slot-row-assignment.ts
@@ -1,23 +1,18 @@
 /**
  * Strip-slot → scoreboard-row assignment. The in-match icon strip (and the
  * minimap's card columns, which mirror it) keeps the lobby seating for the
- * whole set, while the results scoreboard re-sorts each team per game — so
- * per-slot status series can only be paired with scoreboard rows through
- * identity evidence. Two kinds are combined:
+ * whole set, while the results scoreboard re-sorts each team per game, so
+ * per-slot status series pair with rows only through identity evidence:
  *
  * - weapon votes: per-slot candidate scores accumulated across a match's
- *   sampled StripWeapons reads (strip-weapons.ts) plus the minimap cards'
- *   parsed weapons. The best-scoring of the 24 possible slot→row
- *   assignments against the scoreboard's four weapons wins — the global
- *   constraint corrects slots whose own evidence is wrong or missing
- *   (attested: a slot with zero readable votes still lands right by
- *   elimination).
- * - card names (the POV minimap's teammate diamond): matched directly
- *   against scoreboard row names.
+ *   StripWeapons reads plus the minimap cards' parsed weapons. The best of the
+ *   24 slot→row assignments against the scoreboard's four weapons wins — the
+ *   global constraint corrects slots whose own evidence is wrong or missing
+ *   (attested: a slot with zero readable votes still lands by elimination).
+ * - card names (the POV minimap's teammate diamond): matched against row names.
  *
  * Ties resolve toward the fewest moved slots, so two rows sharing a weapon
- * keep their as-drawn relative order, and thin evidence degrades to the
- * as-drawn arrangement rather than a coin flip.
+ * keep their as-drawn order and thin evidence degrades to as-drawn, not a coin flip.
  */
 import type { MainWeaponId } from "~/modules/in-game-lists/types";
 
@@ -27,12 +22,10 @@ export type SlotRowPermutation = readonly [number, number, number, number];
 export const IDENTITY_PERMUTATION: SlotRowPermutation = [0, 1, 2, 3];
 
 /**
- * Total accumulated vote score the winning assignment needs before it may
- * reorder anything, and the lead it needs over the best differing
- * assignment. Calibrated on the sendou-triton VoD, where correct
- * assignments scored 10-33 with margins 2.2-5.3 over ~20 sampled reads;
- * junk evidence (a strip geometry mispick, non-Splatoon lookalikes)
- * spreads flat and fails the margin.
+ * Total vote score the winning assignment needs before it may reorder, and
+ * its lead over the best differing assignment. Calibrated on the sendou-triton
+ * VoD: correct assignments scored 10-33 with margins 2.2-5.3 over ~20 reads;
+ * junk evidence (a strip geometry mispick, lookalikes) spreads flat and fails.
  */
 const MIN_ASSIGNMENT_SCORE = 1.5;
 const MIN_ASSIGNMENT_MARGIN = 0.75;
@@ -52,10 +45,9 @@ const PERMUTATIONS: SlotRowPermutation[] = (() => {
 })();
 
 /**
- * The slot→row assignment best supported by one side's accumulated weapon
- * votes, against that side's scoreboard row weapons. Falls back to the
- * as-drawn order when the evidence is too thin or too close to call (see
- * MIN_ASSIGNMENT_SCORE/MARGIN).
+ * The slot→row assignment best supported by one side's weapon votes against
+ * its scoreboard row weapons; as-drawn when the evidence is too thin or too
+ * close to call (MIN_ASSIGNMENT_SCORE/MARGIN).
  */
 export function weaponSlotRowPermutation(
 	votes: readonly ReadonlyMap<MainWeaponId, number>[],
@@ -86,12 +78,10 @@ export function weaponSlotRowPermutation(
 }
 
 /**
- * A card→row assignment from card names (the POV minimap's teammate
- * diamond, whose order matches neither the strip nor the scoreboard):
- * unique case-insensitive name matches place their cards, the leftovers
- * keep their relative as-drawn order. Null — keep the as-drawn order —
- * when fewer than two cards resolve, since a single hit cannot attest the
- * arrangement is worth disturbing.
+ * A card→row assignment from card names (the POV minimap's teammate diamond,
+ * ordered like neither the strip nor the scoreboard): unique case-insensitive
+ * name matches place their cards, leftovers keep their as-drawn order. Null
+ * (keep as drawn) when fewer than two cards resolve.
  */
 export function nameSlotRowPermutation(
 	cardNames: readonly (string | null)[],
diff --git a/app/features/scanner/core/text.ts b/app/features/scanner/core/text.ts
index dfc05c5ab..e92ae16d3 100644
--- a/app/features/scanner/core/text.ts
+++ b/app/features/scanner/core/text.ts
@@ -1,6 +1,4 @@
-/**
- * Small text utilities: edit distance and closed-set snapping for OCR output.
- */
+/** Small text utilities: edit distance and closed-set snapping for OCR output. */
 
 function editDistance(a: string, b: string): number {
 	const dp = Array.from({ length: a.length + 1 }, (_, i) => {
@@ -21,11 +19,7 @@ function editDistance(a: string, b: string): number {
 	return dp[a.length]![b.length]!;
 }
 
-/**
- * Case-, space- and diacritic-insensitive comparison key (é≈e), so OCR
- * confusing an accented glyph with its base form stays a near-match across
- * the localized closed sets.
- */
+/** Case-, space- and diacritic-insensitive comparison key (é≈e), so an accent misread stays a near-match. */
 export function matchKey(s: string): string {
 	return s
 		.toLowerCase()
@@ -81,25 +75,19 @@ export function rankBy<T>(
 		.sort((a, b) => b.score - a.score);
 }
 
-/**
- * One recognized text segment with its ranked alternatives — structurally
- * compatible with glyphs.ts RecognizedChar, kept minimal here so string
- * utilities stay decoupled from the recognition module.
- */
+/** One recognized segment with its ranked alternatives — structurally compatible with glyphs.ts RecognizedChar. */
 export interface ReadSegment {
 	candidates?: readonly { char: string; score: number }[];
 }
 
 /**
- * Rank a closed set against the segment *candidate lists* of a recognized
- * line instead of its greedy top-1-per-segment string. On low-fidelity
- * captures (720p upscaled) the right glyph often sits at rank 2-3 of a
- * segment while the top-1 string is garbage; plain edit distance can't see
- * it, this can. Alignment is a weighted edit distance: matching a segment
- * to a target char costs 1 minus that char's score in the segment's
- * candidate list (1 when absent), insert/delete cost 1. Scores land well
- * below rankBy's for the same quality of match (a correct char still costs
- * 1 - templateScore), so the two scales must not share thresholds.
+ * Ranks a closed set against a recognized line's per-segment *candidate lists*
+ * instead of its greedy top-1 string: on low-fidelity captures the right
+ * glyph often sits at rank 2-3 while the top-1 string is garbage. Alignment
+ * is a weighted edit distance: matching a segment to a target char costs 1
+ * minus that char's candidate score (1 when absent), insert/delete cost 1.
+ * Scores land well below rankBy's for the same match quality, so the two
+ * scales must not share thresholds.
  */
 export function rankByRead<T>(
 	segments: readonly ReadSegment[],
diff --git a/app/features/scanner/core/timeline/index.ts b/app/features/scanner/core/timeline/index.ts
index 3de112f71..bfd993e5e 100644
--- a/app/features/scanner/core/timeline/index.ts
+++ b/app/features/scanner/core/timeline/index.ts
@@ -1,7 +1,6 @@
 /**
- * TimelineBuilder: minimal event stream cleanup for the POC.
- * Same-type events within a merge window collapse into one, keeping the
- * highest-confidence version; events below a confidence floor are dropped.
+ * TimelineBuilder: same-type events within a merge window collapse into one
+ * (highest confidence kept); events below a confidence floor are dropped.
  */
 
 import {
@@ -26,43 +25,30 @@ import { sameScoreboardMatch } from "./same-scoreboard";
 export interface TimelineOptions {
 	/** same-type events closer than this (seconds) merge */
 	mergeWindow: number;
-	/**
-	 * per-type mergeWindow overrides: repeatable events need a window shorter
-	 * than the minimum spacing between two real occurrences
-	 */
+	/** per-type overrides: repeatable events need a window shorter than the spacing between two real occurrences */
 	mergeWindowByType: Record<string, number>;
 	/**
-	 * per-type content guard: same-type events inside the window merge only
-	 * when this returns true for their data — screens whose distinct real
-	 * occurrences can appear seconds apart (replay browsing) need content,
-	 * not time, to tell them apart. Absent = merge on time alone.
+	 * per-type content guard: same-type events inside the window merge only when
+	 * this returns true for their data — screens whose distinct occurrences can
+	 * appear seconds apart (replay browsing) need content, not time, to split.
 	 */
 	sameEventDataByType: Record<string, (a: unknown, b: unknown) => boolean>;
 	/** events below this confidence are dropped */
 	minConfidence: number;
-	/**
-	 * per-type confidence floor overrides: evidence-carrying events whose
-	 * scores live on a different scale than parse confidences (raw NCC
-	 * peaks) opt out of the shared floor
-	 */
+	/** per-type floor overrides: evidence events scored on a different scale (raw NCC peaks) opt out of the shared floor */
 	minConfidenceByType: Record<string, number>;
 }
 
 const DEFAULT_TIMELINE_OPTIONS: TimelineOptions = {
 	mergeWindow: 30,
-	// the death screen shows for ~5s and respawn takes ~8.5s, so repeat frames
-	// of one death land within the window while consecutive deaths are outside;
-	// players flick the map open for 1-3s and each open is a fresh sample
-	// (slots read differently across opens), so minimap frames merge only
-	// within one open — and a dead/special flip caught mid-open stays its
-	// own event via the content guard
-	// objective counter reads repeat every check second; the content guard
-	// below keeps every actual change while the window collapses static
-	// stretches into one event per state. Player statuses can revisit an
-	// exact prior state no sooner than a respawn takes (~9s), so their
-	// window must stay under that
-	// strip weapon evidence is sampled every ~5s and consecutive samples are
-	// distinct evidence — only same-frame re-reads should collapse
+	// Death: the overlay shows ~5s and respawn takes ~8.5s, so repeat frames of
+	// one death land inside while consecutive deaths fall outside. Minimap:
+	// players flick the map open for 1-3s and each open is a fresh sample, so
+	// frames merge only within one open (a mid-open dead/special flip stays its
+	// own event via the content guard). Objective: reads repeat every second; the
+	// content guard keeps every change while static stretches collapse.
+	// PlayerStatus: a state can recur no sooner than a respawn (~9s), so the
+	// window stays under that. StripWeapons: sampled every ~5s, each distinct evidence
 	mergeWindowByType: {
 		Death: 8,
 		[MINIMAP_EVENT_TYPE]: 5,
diff --git a/app/features/scanner/core/timeline/same-scoreboard.ts b/app/features/scanner/core/timeline/same-scoreboard.ts
index 572fb99ec..7c13a38ca 100644
--- a/app/features/scanner/core/timeline/same-scoreboard.ts
+++ b/app/features/scanner/core/timeline/same-scoreboard.ts
@@ -1,27 +1,21 @@
 /**
- * Content guard for merging scoreboard-shaped events (results screen,
- * replay-browser detail). The replay browser lets users flip between
- * different matches' detail screens within seconds, so a time window alone
- * can't tell "same board, re-sampled" from "next replay opened." Two events
- * are treated as the same match unless something decisive says otherwise;
- * every check tolerates read jitter (glyph misreads, a flipped winner side,
- * fields that only read on some frames), so a split only happens on
- * evidence that survives that noise.
+ * Content guard for merging scoreboard-shaped events. The replay browser lets
+ * users flip between matches' detail screens within seconds, so time alone
+ * can't tell "same board, re-sampled" from "next replay opened". Two events
+ * are the same match unless something decisive says otherwise; every check
+ * tolerates read jitter (glyph misreads, a flipped winner side, fields read
+ * on some frames only).
  */
 import type { ScoreboardData } from "../detectors/scoreboard/index";
 import type { ScoreboardBattleLogReplayData } from "../detectors/scoreboard-battle-log-replay/index";
 
 /**
- * Replay codes of the same replay re-read on a low-fidelity capture differ
- * in a few glyphs (U/V, G/C confusions); different replays share almost no
- * positions. Split only past this many mismatched characters.
+ * Re-reads of one replay code on a low-fidelity capture differ in a few glyphs
+ * (U/V, G/C); different replays share almost no positions.
  */
 const CODE_DIFF_MIN = 7;
 
-/**
- * Paint totals are per-match fingerprints that read reliably (big digits).
- * Compared only when both events read at least this many of the 8 rows.
- */
+/** Paint totals are reliable per-match fingerprints; compared only when both read this many of 8 rows. */
 const PAINT_MIN_READ = 6;
 
 /** Positions where two equal-length strings disagree (∞ on length mismatch). */
diff --git a/app/features/scanner/node/assets-dir.ts b/app/features/scanner/node/assets-dir.ts
index 8406de54a..a0b4dd6a7 100644
--- a/app/features/scanner/node/assets-dir.ts
+++ b/app/features/scanner/node/assets-dir.ts
@@ -1,10 +1,9 @@
 /**
- * Where Node-side code (tests, atlas builders) reads and writes the scanner
- * asset sets, both in the sibling sendou-ink/assets checkout the CDN mirrors.
- * SCANNER_ASSETS_DIR holds the scanner-specific atlases (glyphs, planner
- * signatures; overridable with the env var of the same name) — its version
- * segment must match the worker-side ATLAS_PATH (worker/resources.ts).
- * GAME_IMG_DIR is the shared `img/**` tree the game icons are read from.
+ * Where Node-side code reads and writes the scanner asset sets, both in the
+ * sibling sendou-ink/assets checkout the CDN mirrors. SCANNER_ASSETS_DIR holds
+ * the atlases (overridable by env var of the same name); its version segment
+ * must match the worker-side ATLAS_PATH (worker/resources.ts). GAME_IMG_DIR
+ * is the shared `img/**` tree the game icons come from.
  */
 const ASSETS_REPO_DIR = new URL("../../../../../assets/assets", import.meta.url)
 	.pathname;
diff --git a/app/features/scanner/node/fixtures.ts b/app/features/scanner/node/fixtures.ts
index ced917e95..d850db193 100644
--- a/app/features/scanner/node/fixtures.ts
+++ b/app/features/scanner/node/fixtures.ts
@@ -1,9 +1,7 @@
 /**
- * Fixture discovery and detector execution for tests and tools.
- *
- * A fixture is a directory under app/features/scanner/tests/fixtures/<detector>/<case-name>/ containing
- * frame.png or frame.jpg (raw capture, any resolution — normalization happens
- * inside the pipeline under test) and expected.json.
+ * Fixture discovery and detector execution for tests and tools. A fixture is a
+ * directory under tests/fixtures/<detector>/<case-name>/ holding frame.png or
+ * frame.jpg (raw capture, any resolution) and expected.json.
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -90,9 +88,8 @@ interface ExpectedScoreboard {
 		/** index of the yellow POV-arrow row in `players`; null = no arrow */
 		povIndex?: number | null;
 		/**
-		 * Death: killer's weapon id and kind (ids are unique per kind).
-		 * ScoreboardOwn: the player's own main weapon (weaponType unused).
-		 * weaponLabel is informational for the human corrector.
+		 * Death: killer's weapon id and kind (ids are unique per kind). ScoreboardOwn:
+		 * the player's own main (weaponType unused). weaponLabel is informational.
 		 */
 		weaponLabel?: string;
 		weaponId?: number | null;
@@ -117,11 +114,7 @@ interface ExpectedScoreboard {
 		layout?: "even" | "narrow-right" | "narrow-left";
 		/** PlayerStatus only: white camera badges proved a casted spectator HUD */
 		cast?: true | null;
-		/**
-		 * StripWeapons only: the true weapon per slot, [left team, right
-		 * team], null = slot skipped (splatted icon). weaponLabels is
-		 * informational for the human corrector.
-		 */
+		/** StripWeapons only: true weapon per slot, [left team, right team], null = splatted slot skipped */
 		weapons?: [(MainWeaponId | null)[], (MainWeaponId | null)[]];
 		weaponLabels?: [(string | null)[], (string | null)[]];
 		/** Minimap only: casted 8-player spectator map screen (not parsed yet) */
diff --git a/app/features/scanner/node/image-io.ts b/app/features/scanner/node/image-io.ts
index 53a2871c0..63f5ca759 100644
--- a/app/features/scanner/node/image-io.ts
+++ b/app/features/scanner/node/image-io.ts
@@ -1,10 +1,8 @@
 /**
  * Node-only image decode/encode (@napi-rs/canvas). Never imported from core/.
- *
- * Decoding goes through a canvas, whose backing store is alpha-premultiplied;
- * RGB at partial-alpha pixels can shift by ±1. Everything we read is either
- * fully opaque (frames, atlases) or consumed premultiplied anyway (weapon
- * icons are composited over a background), so this is lossless in practice.
+ * Decoding goes through a canvas whose backing store is alpha-premultiplied, so
+ * RGB at partial-alpha pixels can shift by ±1; everything read is either fully
+ * opaque or consumed premultiplied anyway, so this is lossless in practice.
  */
 import { readFileSync, writeFileSync } from "node:fs";
 import { createCanvas, Image, ImageData } from "@napi-rs/canvas";
diff --git a/app/features/scanner/node/resources.ts b/app/features/scanner/node/resources.ts
index 338887c72..13df55681 100644
--- a/app/features/scanner/node/resources.ts
+++ b/app/features/scanner/node/resources.ts
@@ -1,10 +1,8 @@
 /**
- * Node IO for ScoreboardResources: reads the scanner asset sets from the local
- * sendou-ink/assets checkout (tests and atlas builders never touch the
- * CDN). Game icons come from the checkout's shared `img/**` tree, the
- * scanner-specific atlases from its `scanner/v1/**`. What the bundle contains — every
- * key, template option set, and atlas name — lives in core/resources.ts,
- * shared with the worker's HTTP loader.
+ * Node IO for ScoreboardResources: reads the asset sets from the local
+ * sendou-ink/assets checkout (tests and atlas builders never touch the CDN) —
+ * game icons from its `img/**` tree, atlases from `scanner/v1/**`. What the
+ * bundle contains lives in core/resources.ts.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
diff --git a/app/features/scanner/routes/scanner.fixtures.ts b/app/features/scanner/routes/scanner.fixtures.ts
index d7cc8ca83..7281aad98 100644
--- a/app/features/scanner/routes/scanner.fixtures.ts
+++ b/app/features/scanner/routes/scanner.fixtures.ts
@@ -1,8 +1,7 @@
 /**
- * Dev-only resource route backing the scanner Fixtures tab: without params it
- * lists every fixture with its expected.json, with params it serves the raw
- * frame bytes. Registered under devOnlyRoutes — the fixture corpus only
- * exists in a source checkout.
+ * Dev-only resource route backing the Fixtures tab: without params it lists
+ * every fixture with its expected.json, with params it serves the raw frame
+ * bytes. Registered under devOnlyRoutes — the corpus only exists in a checkout.
  */
 import { readdirSync, readFileSync } from "node:fs";
 import type { LoaderFunctionArgs } from "react-router";
diff --git a/app/features/scanner/routes/scanner.tsx b/app/features/scanner/routes/scanner.tsx
index 091ee89a9..e4c899400 100644
--- a/app/features/scanner/routes/scanner.tsx
+++ b/app/features/scanner/routes/scanner.tsx
@@ -24,10 +24,9 @@ export const meta: MetaFunction = (args) => {
 	});
 };
 
-// Everything below the shell assumes a browser: the OpenCV.js worker,
-// IndexedDB, WebCodecs, getUserMedia. Nothing from core/worker/capture/store
-// may be imported at route-module top level — only from inside this lazily
-// imported client component tree, after hydration.
+// Everything below the shell assumes a browser (OpenCV.js worker, IndexedDB,
+// WebCodecs, getUserMedia): nothing from core/worker/capture/store may be
+// imported at route-module top level — only inside this lazy client tree.
 const ScannerApp = lazy(() =>
 	import("~/features/scanner/components/ScannerApp").then((m) => ({
 		default: m.ScannerApp,
diff --git a/app/features/scanner/scanner-schemas.ts b/app/features/scanner/scanner-schemas.ts
index 07235a5b5..bb300852d 100644
--- a/app/features/scanner/scanner-schemas.ts
+++ b/app/features/scanner/scanner-schemas.ts
@@ -1,13 +1,9 @@
 /**
- * Valibot schemas for the scanner domain — the single source of truth shared by
- * the producer (the scanner match builder/UI in this feature) and the
- * validator (features/scanner-ingest). Every domain field is a sendou.ink id
- * type; the compile-time asserts at the bottom pin each schema to the
- * corresponding core interface so producer and validator cannot drift.
- *
- * The core/worker modules consume only the *types* (type-only imports point
- * the other way), so valibot never enters the worker bundle; runtime validation
- * happens at the boundaries (ingest action, prefill loader).
+ * Valibot schemas for the scanner domain, shared by the producer (match
+ * builder/UI) and the validator (features/scanner-ingest). Every field is a
+ * sendou.ink id type; the compile-time asserts at the bottom pin each schema
+ * to its core interface. core/worker consume only the *types*, so valibot
+ * never enters the worker bundle; validation happens at the boundaries.
  */
 import * as v from "valibot";
 import { abilities } from "~/modules/in-game-lists/abilities";
@@ -125,8 +121,6 @@ export const scannerMatchSchema = v.object({
 	),
 });
 
-// ---- compile-time drift protection: schema output <-> core interface ----
-
 type MutuallyAssignable<A, B> = [A] extends [B]
 	? [B] extends [A]
 		? true
diff --git a/app/features/scanner/scanner-search-params.ts b/app/features/scanner/scanner-search-params.ts
index c973b4514..f36c6310e 100644
--- a/app/features/scanner/scanner-search-params.ts
+++ b/app/features/scanner/scanner-search-params.ts
@@ -17,9 +17,6 @@ export const scannerSearchParams = SearchParams.define({
 	inspect: SP.param(v.nullable(v.pipe(v.string(), v.maxLength(100))), {
 		loader: false,
 	}),
-	/**
-	 * Opt-in scan telemetry: counters are accumulated and the panel is shown
-	 * only when this is set by hand in the URL (no link points at it)
-	 */
+	/** Opt-in scan telemetry: accumulated and shown only when set by hand in the URL (no link points at it) */
 	telemetry: SP.param(v.boolean(), { default: false, loader: false }),
 });
diff --git a/app/features/scanner/scanner-types.ts b/app/features/scanner/scanner-types.ts
index c127dc6b7..c4cbdf9ca 100644
--- a/app/features/scanner/scanner-types.ts
+++ b/app/features/scanner/scanner-types.ts
@@ -1,8 +1,6 @@
 /**
- * Shared domain vocabulary for the scanner feature: events, snap tables, and
- * constants speak sendou.ink's id types (ModeShort, StageId, weapon ids,
- * Ability) — canonical English strings live only inside the OCR snap
- * layer and never leave a detector.
+ * Shared domain vocabulary for the scanner: events, snap tables and constants
+ * speak sendou.ink's id types — canonical English strings never leave a detector.
  */
 import { abilities } from "~/modules/in-game-lists/abilities";
 import type {
@@ -26,9 +24,8 @@ export function toMainWeaponId(id: number | string): MainWeaponId | null {
 }
 
 /**
- * Narrow an ability-template id to an AbilityWithUnknown; null when the id is
- * not a known template. Note "UNKNOWN" is a template of its own (the badge was
- * read but not recognized) and is distinct from null.
+ * Narrows an ability-template id to an AbilityWithUnknown; null when unknown.
+ * "UNKNOWN" is a template of its own (badge read but not recognized), distinct from null.
  */
 export function toAbilityWithUnknown(id: string): AbilityWithUnknown | null {
 	if (id === "UNKNOWN") return id;
diff --git a/app/features/scanner/store/db.ts b/app/features/scanner/store/db.ts
index f3a00f360..930122d69 100644
--- a/app/features/scanner/store/db.ts
+++ b/app/features/scanner/store/db.ts
@@ -1,13 +1,11 @@
 /**
- * Shared IndexedDB handle for the app's stores:
- *  - `events`: live-tab detections, keyed by auto id (see events.ts)
- *  - `frames`: the live events' full-res analyzed PNGs, keyed by event id —
- *    kept out of `events` so listing the feed never deserializes them
- *  - `vods`: one summary record per fully scanned VoD, keyed by file name
- *  - `vod-events`: the detections of each saved VoD, indexed by VoD name
- *  - `vod-frames`: the vod-events' PNGs, keyed by vod-event id
- *  - `inspect-frames`: one-shot Inspect handoffs into a new screenshot tab,
- *    keyed by handoff key (see inspect.ts)
+ * Shared IndexedDB handle. Stores:
+ *  - `events`: live-tab detections, keyed by auto id (events.ts)
+ *  - `frames`: their full-res analyzed PNGs by event id, kept apart so listing the feed never deserializes them
+ *  - `vods`: one summary per fully scanned VoD, keyed by file name
+ *  - `vod-events`: each saved VoD's detections, indexed by VoD name
+ *  - `vod-frames`: their PNGs, keyed by vod-event id
+ *  - `inspect-frames`: one-shot Inspect handoffs into a new screenshot tab (inspect.ts)
  */
 const DB_NAME = "scanner";
 const DB_VERSION = 1;
@@ -19,10 +17,7 @@ export const VOD_EVENTS_STORE = "vod-events";
 export const VOD_FRAMES_STORE = "vod-frames";
 export const INSPECT_FRAMES_STORE = "inspect-frames";
 
-/**
- * Recreates the schema from scratch, dropping any stores already there, so a
- * DB_VERSION bump is always a clean slate at the cost of wiping scanner data.
- */
+/** Recreates the schema from scratch, so a DB_VERSION bump is a clean slate that wipes scanner data. */
 function createStores(database: IDBDatabase): void {
 	for (const name of Array.from(database.objectStoreNames)) {
 		database.deleteObjectStore(name);
diff --git a/app/features/scanner/store/events.ts b/app/features/scanner/store/events.ts
index 1ba800b32..3d7ede9ca 100644
--- a/app/features/scanner/store/events.ts
+++ b/app/features/scanner/store/events.ts
@@ -1,39 +1,28 @@
 /**
- * IndexedDB event store: one `events` object store, keyed by auto id,
- * indexed by timestamp. A small thumbnail of the detection frame is kept
- * per event for the feed; the full-res analyzed PNG lives in the separate
- * `frames` store under the same id (loaded on demand via loadEventFrame),
- * so listing the feed never deserializes megabytes of blobs. The store is
- * capped: saving past MAX_EVENTS evicts the oldest events and their frames,
- * and past MAX_FRAMES the oldest frames alone (the events stay, marked
- * frameless).
+ * IndexedDB event store: one `events` store keyed by auto id, indexed by
+ * timestamp, with a small thumbnail per event; the full-res analyzed PNG lives
+ * in the separate `frames` store under the same id (loadEventFrame) so listing
+ * the feed never deserializes megabytes of blobs. Saving past MAX_EVENTS
+ * evicts the oldest events and their frames; past MAX_FRAMES the oldest
+ * frames alone (the events stay, marked frameless).
  */
 import type { IngestedMatchLink } from "~/features/scanner-ingest/scanner-ingest-schemas";
 import type { DetectedEvent } from "../core/detectors/types";
 import { db, EVENTS_STORE, FRAMES_STORE, tx } from "./db";
 
 /**
- * Oldest events are evicted past this count. Counter/status reads land ~2.2
- * events a second of match time, so a cap must hold a whole session — at
- * 1000 the store rolled over in ~8 minutes and evicted matches before they
- * were ever sent (2026-08-23: Mahi-Mahi reached sendou.ink with no data).
- * Events are small; the full-res frames are capped separately below.
+ * Counter/status reads land ~2.2 events a second of match time, so the cap must
+ * hold a whole session: at 1000 the store rolled over in ~8 minutes and evicted
+ * matches before they were sent (2026-08-23: Mahi-Mahi reached sendou.ink with no data).
  */
 const MAX_EVENTS = 10_000;
 
-/**
- * Oldest full-res frame PNGs (~1-2MB each) are evicted past this count,
- * independently of their events — the event keeps its thumbnail and data,
- * only "Save fixture" loses the byte-exact frame.
- */
+/** Full-res frame PNGs (~1-2MB each) evicted past this count; only "Save fixture" loses them. */
 const MAX_FRAMES = 200;
 
 /** Where an event stands with sendou.ink /ingest; absent = never attempted. */
 export interface SendStatus {
-	/**
-	 * "unlinked": sendou.ink stored the match but its game is not reported
-	 * yet, so it has no scoreboard to attach to — resent on a backoff.
-	 */
+	/** "unlinked": sendou.ink stored the match but its game is not reported yet — resent on a backoff */
 	state: "queued" | "sending" | "sent" | "unlinked" | "failed";
 	/** wall-clock time of the last state change */
 	at: number;
@@ -61,9 +50,8 @@ export interface StoredEvent {
 }
 
 /**
- * Persist a detection; resolves to its store id. `reuseId` overwrites that
- * existing row (and its frame) instead of adding a new one, so an event a
- * better read replaces keeps a stable id.
+ * Persists a detection; resolves to its store id. `reuseId` overwrites that row
+ * (and its frame) so an event a better read replaces keeps a stable id.
  */
 export async function saveEvent(
 	event: DetectedEvent,
diff --git a/app/features/scanner/store/inspect.ts b/app/features/scanner/store/inspect.ts
index cda8d7c9b..ba5bfaa2f 100644
--- a/app/features/scanner/store/inspect.ts
+++ b/app/features/scanner/store/inspect.ts
@@ -1,10 +1,8 @@
 /**
- * Cross-tab frame handoff for the Inspect action: the source tab stashes the
- * frame under a fresh key and opens the screenshot page in a new browser tab
- * with ?inspect=<key>. The write races the new tab's load, so claiming polls
- * briefly before giving up. Claimed records are deleted; unclaimed leftovers
- * (blocked popup, tab closed mid-load) are swept by key age on the next
- * handoff.
+ * Cross-tab frame handoff for Inspect: the source tab stashes the frame under
+ * a fresh key and opens the screenshot page with ?inspect=<key>. The write
+ * races the new tab's load, so claiming polls briefly. Claimed records are
+ * deleted; unclaimed leftovers (blocked popup) are swept by key age next time.
  */
 
 import { INSPECT_FRAMES_STORE, tx } from "./db";
diff --git a/app/features/scanner/store/vods.ts b/app/features/scanner/store/vods.ts
index b995624f5..40bc11fbd 100644
--- a/app/features/scanner/store/vods.ts
+++ b/app/features/scanner/store/vods.ts
@@ -1,11 +1,9 @@
 /**
- * Persistence for completed VoD scans, keyed by the VoD's file name so a
- * scanned video can be reinspected later without re-decoding it. The
- * summary lives in `vods`; the detections live in `vod-events` under a
- * `vod` index, and their full-res analyzed PNGs in `vod-frames` under the
- * event id (loaded on demand via loadVodEventFrame), so listing VoDs and
- * their events stays cheap. Re-scanning the same file name overwrites the
- * previous save.
+ * Persistence for completed VoD scans, keyed by file name so a video can be
+ * reinspected without re-decoding. The summary lives in `vods`, detections in
+ * `vod-events` under a `vod` index, full-res PNGs in `vod-frames` under the
+ * event id (loadVodEventFrame), so listing stays cheap. Re-scanning the same
+ * file name overwrites the previous save.
  */
 import type { IngestedMatchLink } from "~/features/scanner-ingest/scanner-ingest-schemas";
 import { db, tx, VOD_EVENTS_STORE, VOD_FRAMES_STORE, VODS_STORE } from "./db";
@@ -104,9 +102,8 @@ export async function saveVod(
 }
 
 /**
- * Records how a VoD's "Send results" went, so reopening the scan reports
- * what was sent instead of showing every match as never sent. Re-scanning
- * the file starts over: `saveVod` writes a summary without one.
+ * Records how a VoD's "Send results" went, so reopening the scan reports what
+ * was sent. Re-scanning starts over: `saveVod` writes a summary without one.
  */
 export async function saveVodResultsSend(
 	name: string,
diff --git a/app/features/scanner/tests/ability-harvest.test.ts b/app/features/scanner/tests/ability-harvest.test.ts
index c8909bf62..48d6b9b7b 100644
--- a/app/features/scanner/tests/ability-harvest.test.ts
+++ b/app/features/scanner/tests/ability-harvest.test.ts
@@ -1,9 +1,7 @@
 /**
- * Unit tests for connectAbilities: deaths are attributed to the next
- * scoreboard event and matched to a player row by name/weapon, with
- * ambiguous matches (two players on the same weapon, misread name)
- * left unattributed. harvestCardMains puts minimap cards through the same
- * matching, merging their gear mains across the match's frames.
+ * connectAbilities: deaths are attributed to the next scoreboard event and
+ * matched to a row by name/weapon, ambiguous matches left unattributed.
+ * harvestCardMains puts minimap cards through the same matching.
  */
 
 import assert from "node:assert/strict";
diff --git a/app/features/scanner/tests/banner.test.ts b/app/features/scanner/tests/banner.test.ts
index ebb922f69..83d78a97a 100644
--- a/app/features/scanner/tests/banner.test.ts
+++ b/app/features/scanner/tests/banner.test.ts
@@ -1,7 +1,4 @@
-/**
- * resolveMatchScores is pure — the parse side of banner.ts is covered by
- * the scoreboard fixture suite, this pins the winner/loser resolution.
- */
+/** resolveMatchScores is pure — the parse side of banner.ts is covered by the scoreboard fixture suite. */
 
 import assert from "node:assert/strict";
 import {
diff --git a/app/features/scanner/tests/logic/frame-queue.test.ts b/app/features/scanner/tests/logic/frame-queue.test.ts
index ddae9f830..57e4e9702 100644
--- a/app/features/scanner/tests/logic/frame-queue.test.ts
+++ b/app/features/scanner/tests/logic/frame-queue.test.ts
@@ -1,8 +1,7 @@
 /**
- * Unit tests for the live frame backlog's decimating eviction: which index
- * gets dropped, and the property the policy exists for — a long parse
- * stall keeps thinned coverage of its whole span instead of truncating to
- * the newest limit/fps seconds.
+ * Tests for the live frame backlog's decimating eviction: which index drops,
+ * and the property it exists for — a long stall keeps thinned coverage of
+ * its whole span instead of truncating to the newest limit/fps seconds.
  */
 
 import assert from "node:assert/strict";
diff --git a/app/features/scanner/tests/logic/match-builder.test.ts b/app/features/scanner/tests/logic/match-builder.test.ts
index 9ae09b82d..2182fb6c0 100644
--- a/app/features/scanner/tests/logic/match-builder.test.ts
+++ b/app/features/scanner/tests/logic/match-builder.test.ts
@@ -784,11 +784,9 @@ test("a confirmed stage change splits even when the misread-looking frame is mid
 	);
 });
 
-// KNOWN LIMITATION (documented, not desired): two consecutive games on the
-// SAME stage with a between-games break shorter than MATCH_GAP_SECONDS merge
-// into one match — no native UI delimits them on casted footage and the
-// simplified minimap carries no signal to split on. Real mode/game detection
-// should replace this.
+// KNOWN LIMITATION: two consecutive games on the SAME stage with a break
+// shorter than MATCH_GAP_SECONDS merge into one match — casted footage has no
+// native delimiter and the minimap carries no signal to split on.
 test("same-stage rematch within the gap window merges into one match (known limitation)", () => {
 	const game1 = [minimap(70), minimap(150)];
 	const game2 = [minimap(380), minimap(460)];
@@ -869,8 +867,6 @@ test("no minimaps and no scoreboard means no match", () => {
 	assert.deepEqual(buildScannerMatches([mapStart(30), mapStart(400)]), []);
 });
 
-// ---- player-status samples ----
-
 const ALL_FALSE = [
 	[false, false, false, false],
 	[false, false, false, false],
@@ -1208,8 +1204,6 @@ test("a losing-side pov swaps minimap-sourced samples into teams order", () => {
 	]);
 });
 
-// ---- strip-slot → scoreboard-row assignment ----
-
 test("strip weapon evidence reorders status slots into scoreboard rows", () => {
 	// strip seating [2010, 40, 3030, 1001] vs scoreboard rows ALPHA
 	// [40, 1001, 2010, 3030]: slot0 belongs to row2
diff --git a/app/features/scanner/tests/logic/scheduler.test.ts b/app/features/scanner/tests/logic/scheduler.test.ts
index 9c0cb2674..6312cef3b 100644
--- a/app/features/scanner/tests/logic/scheduler.test.ts
+++ b/app/features/scanner/tests/logic/scheduler.test.ts
@@ -1,8 +1,6 @@
 /**
- * Unit tests for DetectorScheduler: search/refine check cadence,
- * steady-frame suppression (stagnation and sufficient-confidence early
- * stop), the rearm cooldown, checkIntervalS compatibility, and the calm
- * signal that drives VoD skim mode.
+ * DetectorScheduler tests: search/refine cadence, steady-frame suppression,
+ * the rearm cooldown, checkIntervalS compatibility, and the calm signal.
  */
 
 import assert from "node:assert/strict";
diff --git a/app/features/scanner/tests/map-start.test.ts b/app/features/scanner/tests/map-start.test.ts
index 3361f5053..8978d0799 100644
--- a/app/features/scanner/tests/map-start.test.ts
+++ b/app/features/scanner/tests/map-start.test.ts
@@ -1,9 +1,6 @@
 /**
- * Golden-file tests for the MapStartDetector over every fixture in
- * map-start/, mirroring tests/suites/death.ts, plus cross-negative sweeps in
- * both directions: the map-start gate must stay quiet on every scoreboard,
- * replay, and death positive, and their gates must stay quiet on the
- * map-start fixtures.
+ * Golden-file tests for the MapStartDetector over every fixture in map-start/,
+ * plus cross-negative sweeps both ways against scoreboard, replay and death positives.
  */
 
 import assert from "node:assert/strict";
@@ -85,9 +82,8 @@ for (const fixture of fixtures) {
 	});
 }
 
-// The intro splash overlays live gameplay while the other screens replace
-// or overlay it differently; none of the four gates may fire on another
-// detector's positives.
+// The intro splash overlays live gameplay while the other screens replace or
+// overlay it differently; none of the four gates may fire on another's positives.
 const otherPositives = [
 	...loadFixtures("scoreboard").filter(
 		(f) => f.expected.event === "Scoreboard",
diff --git a/app/features/scanner/tests/minimap.test.ts b/app/features/scanner/tests/minimap.test.ts
index 369428d1f..89d1d4c14 100644
--- a/app/features/scanner/tests/minimap.test.ts
+++ b/app/features/scanner/tests/minimap.test.ts
@@ -1,8 +1,6 @@
 /**
  * Golden-file tests for the MinimapDetector over every fixture in minimap/,
- * plus cross-negative sweeps in both directions: the minimap gate must stay
- * quiet on every other detector's positives (and the shared negatives), and
- * every other gate must stay quiet on the minimap fixtures.
+ * plus cross-negative sweeps both ways against every other detector's positives.
  */
 
 import assert from "node:assert/strict";
@@ -203,10 +201,9 @@ for (const fixture of fixtures) {
 	});
 }
 
-// The columns' sub-tile ink means anchor the objective counter's color
-// clusters to `teams` order (match-builder); the SWS26 spectator fixture
-// pairs with objective/splat-zones-cast-* from the same game, where the
-// plates read green ~78° and purple ~302°.
+// The columns' sub-tile ink means anchor the objective counter's color clusters
+// to `teams` order (match-builder); the SWS26 spectator fixture pairs with
+// objective/splat-zones-cast-* from the same game (green ~78°, purple ~302°).
 test("spectator sub tiles read the two team ink colors", async () => {
 	const fixture = fixtures.find((f) => f.name === "spectator-sws26-swiss");
 	assert.ok(fixture, "spectator-sws26-swiss fixture missing");
diff --git a/app/features/scanner/tests/node-test-compat.ts b/app/features/scanner/tests/node-test-compat.ts
index 01ca591bd..13079375d 100644
--- a/app/features/scanner/tests/node-test-compat.ts
+++ b/app/features/scanner/tests/node-test-compat.ts
@@ -1,10 +1,8 @@
 /**
  * node:test-shaped `test` on top of Vitest, so the golden-file suites keep
- * their original shape (dynamic per-fixture tests with nested `t.test`
- * subtests and `{ skip }` options — a pattern Vitest has no native
- * equivalent for). Subtests run inline; every failure is collected and the
- * parent test reports them all at once, preserving node:test's
- * "one field mismatch doesn't hide the next" behavior.
+ * their dynamic per-fixture tests with nested `t.test` subtests and `{ skip }`
+ * options (no native Vitest equivalent). Subtests run inline; every failure is
+ * collected and reported at once, so one field mismatch doesn't hide the next.
  */
 import { test as vitestTest } from "vitest";
 
diff --git a/app/features/scanner/tests/objective.test.ts b/app/features/scanner/tests/objective.test.ts
index c05a4726e..91b993581 100644
--- a/app/features/scanner/tests/objective.test.ts
+++ b/app/features/scanner/tests/objective.test.ts
@@ -1,9 +1,7 @@
 /**
- * Golden-file tests for the ObjectiveDetector over every fixture in
- * objective/, mirroring map-start.test.ts, plus cross-negative sweeps in
- * both directions: the objective gate must stay quiet on every other
- * detector's positives (and the shared negatives), and their gates must
- * stay quiet on the objective fixtures.
+ * Golden-file tests for the ObjectiveDetector over every fixture in objective/,
+ * plus cross-negative sweeps both ways: the objective gate must stay quiet on
+ * every other detector's positives (and the shared negatives), and vice versa.
  */
 
 import assert from "node:assert/strict";
@@ -134,12 +132,10 @@ for (const fixture of fixtures) {
 	});
 }
 
-// The cast fixture pair captures the same game under both camera
-// arrangements (the specced team's plate sits left, so purple is left in
-// one frame and right in the other): each frame's two ink hues must
-// separate cleanly, and cross-frame the same team's hue must land on the
-// same cluster with the sides swapped — the invariant cast score tracking
-// (match-builder's color orientation) rests on.
+// The cast fixture pair captures the same game under both camera arrangements
+// (the specced team's plate sits left): each frame's two ink hues must separate
+// cleanly, and cross-frame the same team's hue must land on the same cluster
+// with sides swapped — the invariant match-builder's color orientation rests on.
 test("cast fixture pair: team ink hues identify sides across camera swaps", async () => {
 	const pair = [
 		"splat-zones-cast-specced-purple-left",
@@ -194,10 +190,9 @@ for (const [dir, eventType] of otherPositiveSets) {
 	}
 }
 
-// No sweep over death positives: the death overlay rides live gameplay
-// whose counter HUD stays visible (several death fixtures show full,
-// correctly-readable plates), so neither gate- nor parse-level quiet can be
-// promised there. Death frames with counters make fine objective fixtures.
+// No sweep over death positives: the death overlay rides live gameplay whose
+// counter HUD stays visible (several death fixtures show readable plates), so
+// no quiet can be promised there. Death frames with counters make fine fixtures.
 
 // Shared negatives (tests/fixtures/negative/): frames no detector may fire on.
 for (const fixture of loadFixtures("negative")) {
diff --git a/app/features/scanner/tests/player-status.test.ts b/app/features/scanner/tests/player-status.test.ts
index 540153d36..e27649a25 100644
--- a/app/features/scanner/tests/player-status.test.ts
+++ b/app/features/scanner/tests/player-status.test.ts
@@ -1,11 +1,9 @@
 /**
  * Golden-file tests for the PlayerStatus event over every fixture in
- * player-status/, mirroring objective.test.ts. The event is emitted by the
- * ObjectiveDetector alongside each counter read — a positive fixture must
- * produce both events off one parse, with the icon-strip statuses and the
- * shared timer matching the hand-corrected labels. Other detectors' gates
- * must stay quiet on these frames (they show live gameplay HUD, which only
- * the objective family may claim — death excepted, see objective.test.ts).
+ * player-status/. The event is emitted by the ObjectiveDetector alongside each
+ * counter read — a positive fixture must produce both off one parse, with the
+ * statuses and shared timer matching the labels. Other detectors' gates must
+ * stay quiet on these frames (death excepted, see objective.test.ts).
  */
 
 import assert from "node:assert/strict";
diff --git a/app/features/scanner/tests/scoreboard-battle-log-replay.1.test.ts b/app/features/scanner/tests/scoreboard-battle-log-replay.1.test.ts
index d9a57d91c..e308d8c87 100644
--- a/app/features/scanner/tests/scoreboard-battle-log-replay.1.test.ts
+++ b/app/features/scanner/tests/scoreboard-battle-log-replay.1.test.ts
@@ -1,7 +1,4 @@
-/**
- * Shard 1/2 of the replay suite — see
- * tests/suites/scoreboard-battle-log-replay.ts.
- */
+/** Shard 1/2 of the replay suite — see tests/suites/scoreboard-battle-log-replay.ts. */
 import { runScoreboardBattleLogReplaySuite } from "./suites/scoreboard-battle-log-replay";
 
 await runScoreboardBattleLogReplaySuite(0, 2);
diff --git a/app/features/scanner/tests/scoreboard-battle-log-replay.2.test.ts b/app/features/scanner/tests/scoreboard-battle-log-replay.2.test.ts
index 15e174970..d293cf1df 100644
--- a/app/features/scanner/tests/scoreboard-battle-log-replay.2.test.ts
+++ b/app/features/scanner/tests/scoreboard-battle-log-replay.2.test.ts
@@ -1,7 +1,4 @@
-/**
- * Shard 2/2 of the replay suite — see
- * tests/suites/scoreboard-battle-log-replay.ts.
- */
+/** Shard 2/2 of the replay suite — see tests/suites/scoreboard-battle-log-replay.ts. */
 import { runScoreboardBattleLogReplaySuite } from "./suites/scoreboard-battle-log-replay";
 
 await runScoreboardBattleLogReplaySuite(1, 2);
diff --git a/app/features/scanner/tests/scoreboard-battle-log.test.ts b/app/features/scanner/tests/scoreboard-battle-log.test.ts
index 49bc3867b..96c621fda 100644
--- a/app/features/scanner/tests/scoreboard-battle-log.test.ts
+++ b/app/features/scanner/tests/scoreboard-battle-log.test.ts
@@ -1,9 +1,7 @@
 /**
  * Golden-file suite for the ScoreboardBattleLogDetector over every fixture in
- * scoreboard-battle-log/, mirroring
- * tests/suites/scoreboard-battle-log-replay.ts (the battle log shows the same
- * data sans the replay code), plus cross-negative sweeps: the battle log gate
- * must stay quiet on both lookalike results screens.
+ * scoreboard-battle-log/ (same data as the replay screen sans replay code),
+ * plus cross-negative sweeps against both lookalike results screens.
  */
 
 import assert from "node:assert/strict";
@@ -200,9 +198,8 @@ for (const fixture of fixtures) {
 	});
 }
 
-// The three scoreboard-shaped screens must not trigger each other's
-// detectors; the mirror sweeps live in scoreboard.test.ts and
-// suites/scoreboard-battle-log-replay.ts.
+// The three scoreboard-shaped screens must not trigger each other's detectors;
+// the mirror sweeps live in scoreboard.test.ts and suites/scoreboard-battle-log-replay.ts.
 for (const fixture of [
 	...loadFixtures("scoreboard").filter(
 		(f) => f.expected.event === "Scoreboard",
diff --git a/app/features/scanner/tests/scoreboard-own.test.ts b/app/features/scanner/tests/scoreboard-own.test.ts
index abc59edd7..a55f000e5 100644
--- a/app/features/scanner/tests/scoreboard-own.test.ts
+++ b/app/features/scanner/tests/scoreboard-own.test.ts
@@ -1,8 +1,6 @@
 /**
  * Golden-file tests for the ScoreboardOwnDetector over every fixture in
- * scoreboard-own/, plus cross-negative sweeps in both directions: the own
- * gate must stay quiet on every other detector's positives (and the shared
- * negatives), and every other gate must stay quiet on the own fixtures.
+ * scoreboard-own/, plus cross-negative sweeps both ways.
  */
 
 import assert from "node:assert/strict";
diff --git a/app/features/scanner/tests/scoreboard.test.ts b/app/features/scanner/tests/scoreboard.test.ts
index b864458a2..4eceb8884 100644
--- a/app/features/scanner/tests/scoreboard.test.ts
+++ b/app/features/scanner/tests/scoreboard.test.ts
@@ -1,9 +1,7 @@
 /**
- * Golden-file tests: run the ScoreboardDetector over every fixture and
- * compare per field, so a failure names the exact field and row with the
- * raw match score (threshold problems must look different from ROI problems).
- *
- * Target one case: pnpm test:scanner -t "xbattle"
+ * Golden-file tests: run the ScoreboardDetector over every fixture and compare
+ * per field, so a failure names the exact field and row with the raw match
+ * score. Target one case: pnpm test:scanner -t "xbattle"
  */
 
 import assert from "node:assert/strict";
@@ -163,10 +161,8 @@ for (const fixture of fixtures) {
 	});
 }
 
-// Mirror of the cross-negative sweeps in
-// suites/scoreboard-battle-log-replay.ts and scoreboard-battle-log.test.ts:
-// the live gate must stay quiet on every replay-browser and battle log
-// positive.
+// Mirror of the cross-negative sweeps in suites/scoreboard-battle-log-replay.ts
+// and scoreboard-battle-log.test.ts: the live gate must stay quiet on their positives.
 for (const fixture of [
 	...loadFixtures("scoreboard-battle-log-replay").filter(
 		(f) => f.expected.event === "ScoreboardBattleLogReplay",
diff --git a/app/features/scanner/tests/strip-weapons.test.ts b/app/features/scanner/tests/strip-weapons.test.ts
index f41db5957..6360cb624 100644
--- a/app/features/scanner/tests/strip-weapons.test.ts
+++ b/app/features/scanner/tests/strip-weapons.test.ts
@@ -1,12 +1,10 @@
 /**
- * Golden-file tests for the StripWeapons evidence event over every fixture
- * in strip-weapons/. Single reads are deliberately weak (the true weapon
- * ranks top-1 only about half the time), so per-slot assertions stay
- * structural — splatted slots skipped, alive slots ranked — and the
- * accuracy assertion is the one production relies on: votes aggregated
- * across the fixtures assign every slot to its scoreboard row. The
- * fixtures are frames of one match of the sendou-triton VoD, whose results
- * screen (and D-column ground truth) attests both sides' row orders.
+ * Golden-file tests for the StripWeapons evidence event. Single reads are
+ * deliberately weak (the true weapon ranks top-1 about half the time), so
+ * per-slot assertions stay structural and the accuracy assertion is the one
+ * production relies on: votes aggregated across the fixtures (frames of one
+ * sendou-triton VoD match, whose results screen attests both row orders)
+ * assign every slot to its scoreboard row.
  */
 
 import assert from "node:assert/strict";
@@ -84,14 +82,12 @@ for (const fixture of fixtures) {
 	});
 }
 
-// The assertion production leans on: aggregated across the match's sampled
-// reads, each side's best-of-24 assignment against the results screen's
-// row weapons places every slot. Row orders attested on the VoD's results
-// screen: left/losing side rows [Snipewriter 5H, Custom Blaster,
-// Splattershot Jr., Splat Roller] vs strip seating [Snipewriter, Jr,
-// Custom Blaster, Roller]; right/winning side rows [.52 Gal, Neo
-// Splash-o-matic, Snipewriter 5H, Planetz Big Swig Roller] vs seating
-// [Planetz, .52, Neo Splash, Snipewriter].
+// The assertion production leans on: aggregated across the match's reads, each
+// side's best-of-24 assignment places every slot. Row orders attested on the
+// results screen: left/losing side rows [Snipewriter 5H, Custom Blaster,
+// Splattershot Jr., Splat Roller] vs strip seating [Snipewriter, Jr, Custom
+// Blaster, Roller]; right/winning side rows [.52 Gal, Neo Splash-o-matic,
+// Snipewriter 5H, Planetz Big Swig Roller] vs seating [Planetz, .52, Neo Splash, Snipewriter].
 test("aggregated votes assign every slot to its scoreboard row", () => {
 	assert.ok(parsed.size >= 2, "needs at least two parsed fixtures");
 	const votes = [0, 1].map(() =>
diff --git a/app/features/scanner/tests/suites/death.ts b/app/features/scanner/tests/suites/death.ts
index f591bf293..34a525f2a 100644
--- a/app/features/scanner/tests/suites/death.ts
+++ b/app/features/scanner/tests/suites/death.ts
@@ -1,14 +1,9 @@
 /**
- * Golden-file suite for the DeathDetector over every fixture in death/,
- * mirroring tests/scoreboard.test.ts, plus cross-negative sweeps in both
- * directions: the death gate must stay quiet on every scoreboard and
- * replay positive, and their gates must stay quiet on the death fixtures.
- *
- * Death parses are the most expensive in the repo (four burst-line reads
- * plus up to six splash-tag name passes each), so the suite is sharded
- * across processes: tests/death.<n>.test.ts each run one shard. Every
- * fixture group is dealt round-robin, so the shards together still cover
- * exactly what the old single file did.
+ * Golden-file suite for the DeathDetector over every fixture in death/, plus
+ * cross-negative sweeps both ways against scoreboard and replay positives.
+ * Death parses are the most expensive in the repo (four burst-line reads plus
+ * up to six splash-tag name passes each), so the suite is sharded across
+ * processes: death.<n>.test.ts each run one round-robin shard.
  */
 
 import assert from "node:assert/strict";
diff --git a/app/features/scanner/tests/suites/scoreboard-battle-log-replay.ts b/app/features/scanner/tests/suites/scoreboard-battle-log-replay.ts
index f51d87670..66aecbf47 100644
--- a/app/features/scanner/tests/suites/scoreboard-battle-log-replay.ts
+++ b/app/features/scanner/tests/suites/scoreboard-battle-log-replay.ts
@@ -1,15 +1,10 @@
 /**
  * Golden-file suite for the ScoreboardBattleLogReplayDetector over every
- * fixture in scoreboard-battle-log-replay/, mirroring tests/scoreboard.test.ts,
- * plus the replay extras (timestamp, replay code, match scores) and a
- * cross-negative sweep: the replay gate must stay quiet on every
- * live-scoreboard positive.
- *
- * Replay parses are expensive (eight 68px weapon rows plus the Rowdy-face
- * code line), so the suite is sharded across processes:
- * tests/scoreboard-battle-log-replay.<n>.test.ts each run one shard. Every
- * fixture group is dealt round-robin, so the shards together still cover
- * exactly what the old single file did.
+ * fixture in scoreboard-battle-log-replay/, plus the replay extras (timestamp,
+ * replay code, match scores) and a cross-negative sweep over live-scoreboard
+ * positives. Replay parses are expensive (eight 68px weapon rows plus the
+ * Rowdy-face code line), so the suite is sharded across processes:
+ * scoreboard-battle-log-replay.<n>.test.ts each run one round-robin shard.
  */
 
 import assert from "node:assert/strict";
diff --git a/app/features/scanner/worker/analyzer.worker.ts b/app/features/scanner/worker/analyzer.worker.ts
index 02ffb56d7..9e7642000 100644
--- a/app/features/scanner/worker/analyzer.worker.ts
+++ b/app/features/scanner/worker/analyzer.worker.ts
@@ -1,14 +1,11 @@
 /**
  * AnalyzerWorker: owns OpenCV.js (WASM), the detector registry and a
- * DetectorScheduler. Two entry points: "frame" — the main thread posts one
- * ImageBitmap/VideoFrame at a time (live capture, screenshot harness, VoD
- * seek fallback); results come back per detector, then a "done" carrying the
- * scheduler's calm signal and telemetry. "scanChunk" — a VoD time slice is
- * demuxed/decoded entirely in the worker with mediabunny: the worker owns a
- * contiguous slice so scheduling is exact, undue frames skip canvas
- * readback, and calm stretches skim by keyframe hops instead of decoding
- * every frame — the big VoD speedup, since sequential decode bounds scan
- * wall-clock time.
+ * DetectorScheduler. "frame": the main thread posts one ImageBitmap/VideoFrame
+ * at a time; results come back per detector, then a "done" with the calm
+ * signal and telemetry. "scanChunk": a VoD slice is demuxed/decoded in the
+ * worker with mediabunny — the worker owns a contiguous slice so scheduling is
+ * exact, undue frames skip canvas readback, and calm stretches skim by
+ * keyframe hops — the big VoD speedup, since sequential decode bounds scan time.
  */
 import {
 	ALL_FORMATS,
@@ -41,11 +38,7 @@ import type {
 } from "./protocol";
 import { fetchScoreboardResources } from "./resources";
 
-/**
- * Widest skim hop: calm footage is sampled at the keyframe cadence, capped
- * here so long-GOP recordings still cannot slip a results screen (~10s) or
- * a match intro (~7s) between two samples.
- */
+/** Widest skim hop, so long-GOP recordings can't slip a results screen (~10s) or intro (~7s) between samples. */
 const MAX_SKIM_STRIDE_S = 2.5;
 const PROGRESS_POST_INTERVAL_MS = 400;
 const PREVIEW_POST_INTERVAL_MS = 600;
@@ -87,10 +80,7 @@ async function init({
 	}
 }
 
-/**
- * Run the due detectors over one frame; closes `bitmap`. When the scheduler
- * has no detector due, the canvas readback and normalize are skipped too.
- */
+/** Runs the due detectors over one frame; closes `bitmap`. Readback and normalize are skipped when nothing is due. */
 async function analyzeFrame(
 	bitmap: ImageBitmap | VideoFrame,
 	t: number,
@@ -122,9 +112,8 @@ async function analyzeFrame(
 	}
 	if (telemetry) telemetry.analyzedFrames++;
 
-	// On detection, ship back the exact analyzed pixels (lossless, at capture
-	// resolution) so the UI never has to re-grab a later frame — encoded at
-	// most once per frame, however many detectors fire on it.
+	// ship back the exact analyzed pixels (lossless, capture resolution) so the
+	// UI never re-grabs a later frame — encoded at most once per frame
 	let encoded: Promise<Blob> | null = null;
 	const frameBlob = () =>
 		(encoded ??= canvas.convertToBlob({ type: "image/png" }));
diff --git a/app/features/scanner/worker/client.ts b/app/features/scanner/worker/client.ts
index d05af4732..48eed2ddd 100644
--- a/app/features/scanner/worker/client.ts
+++ b/app/features/scanner/worker/client.ts
@@ -1,14 +1,12 @@
 /**
  * Main-thread wrapper around the AnalyzerWorker: init handshake, then either
- * one in-flight frame at a time (live capture / screenshot / seek fallback —
- * each frame yields one result per due detector, then a "done" carrying the
- * scheduler's calm signal and telemetry) or one in-flight chunk scan (the
- * worker decodes and analyzes a VoD time slice by itself, streaming results
- * and progress until "chunkDone"). `frameQueueLimit` opts a client into
- * buffering frames that arrive while a frame is in flight instead of
- * dropping them — live capture uses it so a slow parse streak (a browsed
- * battle log entry) can't swallow the footage sampled meanwhile; timestamps
- * ride with the frames, so late analysis still lands events at capture time.
+ * one in-flight frame at a time (live / screenshot / seek fallback — each
+ * frame yields one result per due detector, then a "done" carrying the calm
+ * signal and telemetry) or one in-flight chunk scan (the worker decodes and
+ * analyzes a VoD slice itself, streaming until "chunkDone"). `frameQueueLimit`
+ * buffers frames arriving while one is in flight instead of dropping them —
+ * live capture uses it so a slow parse streak can't swallow the footage
+ * sampled meanwhile; timestamps ride with the frames.
  */
 import { Config } from "../../../config";
 import type { ScanTelemetry } from "../core/detectors/telemetry";
@@ -28,8 +26,7 @@ export type DoneHandler = (t: number, info: DoneInfo) => void;
 export type ChunkProgress = Extract<WorkerResponse, { kind: "chunkProgress" }>;
 export type ChunkProgressHandler = (progress: ChunkProgress) => void;
 
-/** each chunk-scanning worker decodes and analyzes on its own; leave a core
- * for the main thread and one for the browser's media stack */
+/** Each chunk worker decodes and analyzes on its own; leave a core for the main thread and one for the media stack. */
 export function defaultScanWorkerCount(): number {
 	return Math.min(4, Math.max(1, (navigator.hardwareConcurrency || 4) - 2));
 }
@@ -110,9 +107,8 @@ export class AnalyzerClient {
 				this.#fail(msg.message);
 			}
 		};
-		// A throw outside the worker's own try/catch posts neither "error" nor
-		// "done"; without these handlers `busy` would stay true forever and the
-		// sampler / VoD scan would silently freeze.
+		// A throw outside the worker's own try/catch posts neither "error" nor "done";
+		// without these handlers `busy` would stay true and the scan silently freeze.
 		this.#worker.onerror = (e: ErrorEvent) => {
 			this.#fail(`worker error: ${e.message || String(e)}`);
 		};
@@ -143,10 +139,9 @@ export class AnalyzerClient {
 	}
 
 	/**
-	 * Analyze a frame now, or — with `frameQueueLimit` set — buffer it until
-	 * the in-flight frame settles (past the limit the backlog is decimated:
-	 * see frame-queue.ts). Returns false (and closes the bitmap) only when
-	 * the frame was dropped outright.
+	 * Analyzes a frame now, or with `frameQueueLimit` buffers it until the
+	 * in-flight frame settles (past the limit the backlog is decimated, see
+	 * frame-queue.ts). False (and the bitmap closed) only when dropped outright.
 	 */
 	analyze(bitmap: ImageBitmap | VideoFrame, t: number): boolean {
 		if (this.busy) {
@@ -169,9 +164,8 @@ export class AnalyzerClient {
 	}
 
 	/**
-	 * Scan [tStart, tEnd) of `file` inside the worker. Results stream to the
-	 * shared result handler; resolves with the chunk's telemetry once done
-	 * (an aborted chunk resolves too — abort is not an error).
+	 * Scans [tStart, tEnd) of `file` inside the worker; results stream to the
+	 * shared handler, resolves with the chunk's telemetry (an abort resolves too).
 	 */
 	scanChunk(
 		request: { file: File; chunkIndex: number; tStart: number; tEnd: number },
diff --git a/app/features/scanner/worker/frame-queue.ts b/app/features/scanner/worker/frame-queue.ts
index c1625d891..09155064d 100644
--- a/app/features/scanner/worker/frame-queue.ts
+++ b/app/features/scanner/worker/frame-queue.ts
@@ -1,21 +1,15 @@
 /**
  * Eviction policy for the live capture's frame backlog. Dropping the oldest
- * frame truncates the buffered window to limit/fps seconds, so a parse
- * stall longer than that (a CJK splash-tag name read runs tens of seconds)
- * silently discards whole screens — including the scoreboard that closes a
- * match. Instead the backlog is decimated: evict the frame whose two
- * neighbors sit closest together in time. Repeated evictions thin the
- * buffer toward evenly spaced coverage of the whole stall, so a screen that
- * appeared mid-stall keeps a few frames rather than losing all of them
- * (measured: a 50s stall at 2fps/24 slots keeps a mid-stall 10s screen at
- * 4 frames with a 3s worst gap). The oldest and newest frames are never
- * evicted, so the covered span itself always survives.
+ * frame truncates the window to limit/fps seconds, so a longer parse stall (a
+ * CJK splash-tag read runs tens of seconds) silently discards whole screens,
+ * the match-closing scoreboard included. Instead the backlog is decimated:
+ * evict the frame whose two neighbors sit closest in time, thinning toward
+ * even coverage of the whole stall (measured: a 50s stall at 2fps/24 slots
+ * keeps a mid-stall 10s screen at 4 frames, 3s worst gap). The oldest and
+ * newest frames are never evicted, so the covered span survives.
  */
 
-/**
- * Index of the frame to evict from a backlog of capture timestamps
- * (ascending). Timestamps only — the caller owns the frames themselves.
- */
+/** Index of the frame to evict from an ascending backlog of capture timestamps. */
 export function frameEvictionIndex(times: readonly number[]): number {
 	if (times.length < 3) return 0;
 	let best = 1;
diff --git a/app/features/scanner/worker/protocol.ts b/app/features/scanner/worker/protocol.ts
index ca4d4d466..cae0deca6 100644
--- a/app/features/scanner/worker/protocol.ts
+++ b/app/features/scanner/worker/protocol.ts
@@ -3,42 +3,30 @@ import type { DetectedEvent, GateResult } from "../core/detectors/types";
 
 export interface InitRequest {
 	kind: "init";
-	/**
-	 * static assets CDN root the worker fetches icons and atlases from
-	 * (`Config.staticAssetsUrl`); passed in the init message so the worker
-	 * bundle stays free of the app config graph
-	 */
+	/** static assets CDN root (`Config.staticAssetsUrl`), passed in so the worker bundle stays free of the app config graph */
 	assetsBaseUrl: string;
 	/**
 	 * skip parse() for a detector whose gate keeps firing without confidence
-	 * improving (static screen), and let the scheduler thin out checks;
-	 * default true — one-shot consumers like the screenshot harness turn it
-	 * off to get every detector on every frame
+	 * improving and let the scheduler thin out checks; default true — one-shot
+	 * consumers like the screenshot harness turn it off
 	 */
 	suppressSteadyFrames?: boolean;
-	/**
-	 * accumulate scan telemetry counters (and time the detectors) so they can
-	 * be reported back with progress and done messages; default false — the
-	 * VoD tab only asks for them when the telemetry panel is opted into
-	 */
+	/** accumulate scan telemetry counters and time the detectors; default false (VoD telemetry panel opts in) */
 	collectTelemetry?: boolean;
 }
 
 export interface AnalyzeRequest {
 	kind: "frame";
-	/** VideoFrame is what VoD decode produces; transferring it directly skips
-	 * a main-thread ImageBitmap conversion */
+	/** VideoFrame is what VoD decode produces; transferring it skips a main-thread ImageBitmap conversion */
 	bitmap: ImageBitmap | VideoFrame;
 	/** seconds into the stream */
 	t: number;
 }
 
 /**
- * Scan a time slice of a VoD entirely inside the worker: demux + decode with
- * mediabunny, schedule detectors, post results as they fire. Decoding in the
- * worker removes the per-frame main-thread hop and lets each worker own a
- * contiguous slice, so scheduler state (cadence, suppression, calm) is exact
- * instead of split across a pool.
+ * Scans a VoD time slice entirely inside the worker: demux + decode with
+ * mediabunny, schedule detectors, post results as they fire. Each worker owns
+ * a contiguous slice, so scheduler state (cadence, suppression, calm) is exact.
  */
 export interface ScanChunkRequest {
 	kind: "scanChunk";
diff --git a/app/features/scanner/worker/resources.ts b/app/features/scanner/worker/resources.ts
index 2e0b5fc34..586a94e46 100644
--- a/app/features/scanner/worker/resources.ts
+++ b/app/features/scanner/worker/resources.ts
@@ -1,12 +1,9 @@
 /**
- * Worker/browser IO for ScoreboardResources: fetches over HTTP. Game icons
- * come from the CDN's shared `img/<dir>/<id>.avif` sets the rest of the app
- * already uses; the scanner-specific atlases (glyphs, planner signatures) come
- * from the same CDN under `scanner/v1/**`. What the bundle contains — every
- * key, template option set, and atlas name — lives in core/resources.ts,
- * shared with the Node loader. The base URL arrives via the worker init
- * message (see worker/protocol.ts) so this module never imports the app
- * config.
+ * Worker/browser IO for ScoreboardResources over HTTP: game icons come from
+ * the CDN's shared `img/<dir>/<id>.avif` sets, the scanner atlases from the
+ * same CDN under `scanner/v1/**`. What the bundle contains lives in
+ * core/resources.ts. The base URL arrives via the worker init message
+ * (worker/protocol.ts) so this module never imports the app config.
  */
 
 import {
@@ -19,10 +16,11 @@ import { type AtlasMeta, type GlyphSet, loadGlyphSet } from "../core/glyphs";
 import type { FrameData } from "../core/image";
 import { assembleScoreboardResources } from "../core/resources";
 
-/** Scanner parser atlases, relative to the CDN base; the version segment
- * guards against cache skew — bump it together with breaking atlas format
- * changes (must match the Node-side SCANNER_ASSETS_DIR default in
- * node/assets-dir.ts). */
+/**
+ * Atlas path relative to the CDN base; the version segment guards against
+ * cache skew — bump it with breaking atlas format changes (must match the
+ * Node-side SCANNER_ASSETS_DIR default in node/assets-dir.ts).
+ */
 const ATLAS_PATH = "scanner/v1";
 
 async function fetchImage(url: string): Promise<FrameData> {
diff --git a/app/features/scrims/ScrimMapListRepository.server.ts b/app/features/scrims/ScrimMapListRepository.server.ts
index 4a0617e78..4b924317e 100644
--- a/app/features/scrims/ScrimMapListRepository.server.ts
+++ b/app/features/scrims/ScrimMapListRepository.server.ts
@@ -10,11 +10,7 @@ import type { ScrimSide } from "./scrims-types";
 
 type SubmitMapListArgs = Omit<TablesInsertable["ScrimMapList"], "updatedAt">;
 
-/**
- * Inserts a map list row for the given side, replacing any existing row for
- * the same `(scrimPostId, side)` pair, and (atomically) generates and inserts
- * the next map for the scrim if no unreported map is currently waiting.
- */
+/** Upserts the side's map list row and, atomically, inserts the scrim's next map if no unreported one is waiting. */
 export async function submitMapListAndGenerateIfNeeded(
 	args: SubmitMapListArgs,
 ): Promise<void> {
@@ -64,12 +60,7 @@ export type ResolvedScrimMapList = {
 	updatedAt: number;
 };
 
-/**
- * Returns all submitted map lists for the scrim with the pool resolved into
- * concrete `(mode, stageId)` pairs. Tournament-sourced rows additionally carry
- * the tournament's id and name for display. Pass a transaction as `trx`
- * to read within an existing transaction.
- */
+/** The scrim's submitted map lists with pools resolved to `(mode, stageId)` pairs; tournament-sourced rows carry the tournament's id and name. */
 export async function findMapListsByScrimPostId(
 	scrimPostId: number,
 	trx?: Transaction<DB>,
diff --git a/app/features/scrims/ScrimMapRepository.server.ts b/app/features/scrims/ScrimMapRepository.server.ts
index 1310395c6..c8cb4c344 100644
--- a/app/features/scrims/ScrimMapRepository.server.ts
+++ b/app/features/scrims/ScrimMapRepository.server.ts
@@ -14,11 +14,7 @@ interface ReportMapArgs {
 	winnerSide: NonNullable<TablesInsertable["ScrimMap"]["winnerSide"]>;
 }
 
-/**
- * Marks an existing map as reported with the given winner side, and
- * (atomically) generates and inserts the next map for the scrim if no
- * unreported map is currently waiting.
- */
+/** Marks a map as reported with the winner side and, atomically, inserts the next map if no unreported one is waiting. */
 export async function reportMapAndGenerateNext(
 	args: ReportMapArgs,
 ): Promise<void> {
@@ -38,11 +34,7 @@ export async function reportMapAndGenerateNext(
 	});
 }
 
-/**
- * Reverses the most recent report: deletes the currently unreported map (the
- * auto-generated next slot, if any) and clears the winner/reportedAt fields on
- * the most recently reported map so it can be played again.
- */
+/** Reverses the most recent report: deletes the unreported next slot (if any) and clears winner/reportedAt on the last reported map. */
 export async function undoMostRecentMap(scrimPostId: number): Promise<void> {
 	await db.transaction().execute(async (trx) => {
 		await trx
@@ -80,11 +72,7 @@ interface ReplaceCurrentMapArgs {
 	stageId: StageId;
 }
 
-/**
- * Replaces the currently unreported map for the scrim with the given
- * mode/stage. Used by both the "replay previous map" and "pick a map" actions.
- * The current map's index is preserved.
- */
+/** Replaces the scrim's unreported map with the given mode/stage, keeping its index ("replay previous map" and "pick a map"). */
 export async function replaceCurrentMap(
 	args: ReplaceCurrentMapArgs,
 ): Promise<void> {
@@ -109,13 +97,7 @@ export function findMapsByScrimPostId(scrimPostId: number) {
 		.execute();
 }
 
-/**
- * If a pool can be derived from the submitted map lists and no unreported map
- * is currently waiting, generates and inserts the next map. Runs entirely
- * within the caller's transaction so the read of the existing maps and the
- * insert see a consistent snapshot and no two concurrent report/submit actions
- * can insert a "next" map at the same index.
- */
+/** Inserts the next map when a pool derives from the submitted lists and no unreported map waits. Runs in the caller's transaction so two concurrent actions can't insert the same index. */
 export async function tryGenerateAndInsertNextMap(
 	scrimPostId: number,
 	trx: Transaction<DB>,
diff --git a/app/features/scrims/ScrimPickupRosterRepository.server.ts b/app/features/scrims/ScrimPickupRosterRepository.server.ts
index 31bff1260..3d9dc8eb4 100644
--- a/app/features/scrims/ScrimPickupRosterRepository.server.ts
+++ b/app/features/scrims/ScrimPickupRosterRepository.server.ts
@@ -6,9 +6,7 @@ import { databaseTimestampNow, dateToDatabaseTimestamp } from "~/utils/dates";
 import { commonUserSelect, jsonArrayFrom } from "~/utils/kysely.server";
 import { SCRIM } from "./scrims-constants";
 
-/**
- * Pick-up rosters recently used by the logged in user, newest first.
- */
+/** Pick-up rosters recently used by the logged in user, newest first. */
 export function findAllOwnRecent() {
 	return db
 		.selectFrom("ScrimPickupRoster")
@@ -33,13 +31,7 @@ export function findAllOwnRecent() {
 		.execute();
 }
 
-/**
- * Marks the given roster as the most recently used pick-up of the logged in user.
- * Reuses the existing roster if the same members were already saved and prunes
- * the rosters that fall out of the most recently used ones.
- *
- * @returns id of the roster that was inserted or reused
- */
+/** Marks the roster as the user's most recently used pick-up, reusing a saved one with the same members and pruning the ones that fall out. @returns id of the inserted or reused roster */
 export function upsertOwn(memberUserIds: number[]) {
 	const ownerId = actorId();
 
diff --git a/app/features/scrims/ScrimPostRepository.server.ts b/app/features/scrims/ScrimPostRepository.server.ts
index 5ac77c36a..736390e92 100644
--- a/app/features/scrims/ScrimPostRepository.server.ts
+++ b/app/features/scrims/ScrimPostRepository.server.ts
@@ -90,12 +90,7 @@ type InsertRequestArgs = Pick<
 	>;
 };
 
-/**
- * Inserts a new request to a scrim post.
- *
- * @returns id of the new request
- * @throws {DuplicateEntryError} If the team already has a request for the post
- */
+/** Inserts a request to a scrim post, returning its id. @throws {DuplicateEntryError} if the team already has one for the post. */
 export function insertRequest(args: InsertRequestArgs) {
 	invariant(args.users.length > 0, "At least one user must be provided");
 
@@ -535,17 +530,10 @@ export function cancelScrim(id: number, reason: string) {
 	});
 }
 
-/**
- * Finds all accepted scrims scheduled within a specific time range.
- *
- * @returns Array of accepted (matched) scrim posts within the time range
- */
+/** Accepted scrims starting within [startTime, endTime), excluding ones created after `excludeRecentlyCreated`. */
 export async function findAcceptedScrimsBetweenTwoTimestamps({
-	/** The earliest scrim start time to include (inclusive) */
 	startTime,
-	/** The latest scrim start time to include (exclusive) */
 	endTime,
-	/** Exclude scrims created after this timestamp */
 	excludeRecentlyCreated,
 }: {
 	startTime: Date;
@@ -566,14 +554,7 @@ export async function findAcceptedScrimsBetweenTwoTimestamps({
 	return rows.map(mapDBRowToScrimPost).filter((post) => Scrim.isAccepted(post));
 }
 
-/**
- * Finds the accepted (booked), uncanceled scrims of the given users whose
- * resolved start time — the accepted request's chosen time for a range post,
- * the post's own otherwise — falls within the given window. Used to resolve
- * availability commitments.
- *
- * @returns one row per participating user per scrim
- */
+/** Accepted, uncanceled scrims of the users whose resolved start (accepted request's time for a range post, else the post's) falls in the window; one row per participating user per scrim. */
 export async function findAllAcceptedByUserIds({
 	userIds,
 	startsAt,
@@ -619,12 +600,9 @@ export async function findAllAcceptedByUserIds({
 }
 
 /**
- * Finds pending (unaccepted, uncanceled, future) scrim posts and requests
- * involving any of the given users whose time overlaps [startTime, endTime].
- * Used to auto-clean conflicting availability when a scrim is scheduled.
- *
- * @returns posts (with their member ids, for notifying) and request ids
- * (deleted silently) that should be removed
+ * Pending (unaccepted, uncanceled, future) posts and requests involving the users that overlap
+ * [startTime, endTime], for auto-cleaning when a scrim is scheduled: posts come with member ids
+ * for notifying, requests are deleted silently.
  */
 export async function findPendingOverlapsForUsers({
 	userIds,
diff --git a/app/features/scrims/actions/scrims.new.server.ts b/app/features/scrims/actions/scrims.new.server.ts
index c49faf939..3fcf454e0 100644
--- a/app/features/scrims/actions/scrims.new.server.ts
+++ b/app/features/scrims/actions/scrims.new.server.ts
@@ -123,7 +123,7 @@ export const usersListForPost = async ({
 		(member) => getMemberRoleType(member) !== "OTHER",
 	);
 
-	// handle case when all users are from excluded roles
+	// falls back to everyone when too few members have a playing role
 	const result = (
 		filteredMembers.length >= SCRIM.MIN_MEMBERS_PER_TEAM
 			? filteredMembers
@@ -134,7 +134,7 @@ export const usersListForPost = async ({
 		errorToast("Your team does not have enough members (4) to scrim");
 	}
 
-	// ensure author is included in the list even if they match the ignore condition
+	// the author is included even with an excluded role
 	return result.includes(authorId) ? result : [authorId, ...result];
 };
 
diff --git a/app/features/scrims/actions/scrims.request.server.test.ts b/app/features/scrims/actions/scrims.request.server.test.ts
index 64857887c..265a42c0a 100644
--- a/app/features/scrims/actions/scrims.request.server.test.ts
+++ b/app/features/scrims/actions/scrims.request.server.test.ts
@@ -6,7 +6,7 @@ import * as ScrimPostRepository from "../ScrimPostRepository.server";
 import type { scrimRequestFormSchema } from "../scrims-schemas";
 import { action as scrimsAction } from "./scrims.server";
 
-// The request action fires a fire-and-forget push/DB notification; not under test here.
+// the action's fire-and-forget notification is not under test
 vi.mock("~/features/notifications/core/notify.server", () => ({
 	notify: () => Promise.resolve(),
 }));
@@ -50,8 +50,7 @@ describe("Scrim requests: pickup roster validation", () => {
 			{ user: "regular" },
 		);
 
-		// The post-creation path rejects this via validatePickupFriends; the request
-		// path must too, rather than going through without the victim.
+		// post creation rejects this via validatePickupFriends; the request path must too
 		expect(res?.fieldErrors?.from).toBeTruthy();
 		expect(await requestsForPost(post.id)).toHaveLength(0);
 	});
diff --git a/app/features/scrims/components/ScrimAvailability.tsx b/app/features/scrims/components/ScrimAvailability.tsx
index eb084e326..8ed3f0e61 100644
--- a/app/features/scrims/components/ScrimAvailability.tsx
+++ b/app/features/scrims/components/ScrimAvailability.tsx
@@ -23,13 +23,9 @@ export interface ScrimRosterFit {
 }
 
 /**
- * How one of the viewer's teams fits a post they could request, resolved from
- * the schedules the browsing page loaded. `teamId` picks the team (their main
- * one by default) and `at` narrows the fit to one start inside the post's
- * flexibility instead of the best one on offer.
- *
- * Null whenever there is nothing to show: no team, a post past the reportable
- * horizon, or a week nobody filled in.
+ * How one of the viewer's teams (`teamId`, main by default) fits a post, from the schedules the
+ * page loaded; `at` narrows the fit to one start instead of the best on offer. Null when there
+ * is nothing to show: no team, a post past the reportable horizon, or a week nobody filled in.
  */
 export function useRosterFit({
 	post,
@@ -67,13 +63,7 @@ export function useRosterFit({
 	return { team, roster, fit };
 }
 
-/**
- * The post card's fit indicator: a stripe above the card's actions saying how
- * much of the viewer's roster could play it, the who and when a click away.
- *
- * Left out when none of them could — a row of zeroes down the page is noise,
- * and the request button says all there is to say then.
- */
+/** The post card's fit stripe: how much of the viewer's roster could play it, details a click away. Left out when none could — a row of zeroes down the page is noise. */
 export function ScrimFitStripe({ post }: { post: ScrimPost }) {
 	const { t } = useTranslation(["schedule"]);
 	const fit = useRosterFit({ post });
diff --git a/app/features/scrims/components/ScrimSchedulePicker.tsx b/app/features/scrims/components/ScrimSchedulePicker.tsx
index 4aa116b37..254b99e43 100644
--- a/app/features/scrims/components/ScrimSchedulePicker.tsx
+++ b/app/features/scrims/components/ScrimSchedulePicker.tsx
@@ -44,13 +44,9 @@ interface DaySlot extends Scrim.PickableSlot {
 }
 
 /**
- * The roster's merged free time as a week of day tracks, one click on which
- * fills in the post's start and start-time flexibility. Which roster is merged
- * follows the "With" field, so this only appears once a team or a full pick-up
- * has been picked.
- *
- * Only ever a prefill: the start inputs stay authoritative, and a start the
- * schedules do not cover is warned about, never blocked.
+ * The roster's merged free time as a week of day tracks; a click fills in the post's start and
+ * flexibility. Follows the "With" field, so it only appears once a team or full pick-up is picked.
+ * Only a prefill: the start inputs stay authoritative, an uncovered start is warned about, never blocked.
  */
 export function ScrimSchedulePicker({
 	schedule,
diff --git a/app/features/scrims/core/Scrim.ts b/app/features/scrims/core/Scrim.ts
index 6a61ec4b6..f6b7281af 100644
--- a/app/features/scrims/core/Scrim.ts
+++ b/app/features/scrims/core/Scrim.ts
@@ -44,9 +44,7 @@ export function resolvePoolCode(postId: number) {
 	return `SC${(postId % 9) + 1}`;
 }
 
-/**
- * Returns an array of participant IDs from the given post object that is accepted (scrim page exists).
- */
+/** Participant ids of an accepted post (one whose scrim page exists). */
 export function participantIdsListFromAccepted(post: ScrimPost) {
 	const acceptedRequest = post.requests.find((r) => r.isAccepted);
 
@@ -61,20 +59,13 @@ export function participantIdsListFromAccepted(post: ScrimPost) {
 		.concat(acceptedRequest?.users.map((u) => u.id) ?? []);
 }
 
-/**
- * Returns the actual start time of the scrim.
- * When the post has a time range (rangeEndsAt is set), returns the accepted request's specific time if available.
- * Otherwise returns the post's start time.
- */
+/** The scrim's actual start: the accepted request's time when the post has a range (rangeEndsAt set), else the post's start. */
 export function getStartTime(post: ScrimPost): number {
 	const acceptedRequest = post.requests.find((r) => r.isAccepted);
 	return acceptedRequest?.startsAt ?? post.startsAt;
 }
 
-/**
- * Returns a display name for a scrim side: the team name when set,
- * otherwise "{ownerUsername}'s pickup".
- */
+/** Display name of a scrim side: the team name, else "{ownerUsername}'s pickup". */
 export function sideDisplayName(side: {
 	team: { name: string } | null;
 	users: Array<{ username: string; isOwner: boolean }>;
@@ -158,13 +149,7 @@ export function filtersAreDefault(filters: ScrimFilters): boolean {
 	return R.isShallowEqual(filters, defaultFilters());
 }
 
-/**
- * Returns the side ("ALPHA" or "BRAVO") the user belongs to in the scrim, or
- * null when the user is not part of the accepted pairing.
- *
- * The post's own users list is treated as the ALPHA side; the accepted
- * request's users list is treated as the BRAVO side.
- */
+/** The user's side in the scrim (post's users are ALPHA, accepted request's are BRAVO), or null when not in the accepted pairing. */
 export function sideOfUser(post: ScrimPost, userId: number): ScrimSide | null {
 	if (post.users.some((u) => u.id === userId)) return "ALPHA";
 
@@ -175,12 +160,9 @@ export function sideOfUser(post: ScrimPost, userId: number): ScrimSide | null {
 }
 
 /**
- * Returns true when map-by-map tracking is locked: the auto-lock window has
- * elapsed since the last activity (most recent reported map, falling back to
- * the most recently updated submitted map list). Activity happening before the
- * scrim starts does not begin the window, it only starts running once the
- * scrim is under way. Returns false when no map list has been submitted yet
- * (tracking is not active).
+ * Whether map-by-map tracking is locked: the auto-lock window has elapsed since the last activity
+ * (latest reported map, else latest submitted map list). The window only starts running once the
+ * scrim is under way. False when no map list has been submitted yet.
  */
 export function isTrackingLocked({
 	startTime,
@@ -210,10 +192,7 @@ export function isTrackingLocked({
 	return elapsedHours > SCRIM_TRACKING_AUTO_LOCK_HOURS;
 }
 
-/**
- * Returns the next 0-based map index to be inserted given a list of existing
- * maps. Existing maps need not be in any particular order.
- */
+/** The next 0-based map index to insert; existing maps need not be ordered. */
 export function nextMapIndex(
 	maps: Pick<Tables["ScrimMap"], "index">[],
 ): number {
@@ -221,10 +200,7 @@ export function nextMapIndex(
 	return latest ? latest.index + 1 : 0;
 }
 
-/**
- * Returns the most recently reported map (by `index`), or undefined if no map
- * has been reported yet.
- */
+/** The most recently reported map (by `index`), or undefined if none. */
 export function lastReportedMap<
 	T extends Pick<Tables["ScrimMap"], "index" | "reportedAt">,
 >(maps: T[]): T | undefined {
@@ -244,11 +220,7 @@ export interface PickableSlot extends TimeRange {
 	pick: { startsAt: number; rangeEnd: RangeEndOption | null };
 }
 
-/**
- * The roster's shared free time as the slots a scrim post can be picked from:
- * maximal spans where the team is at most one player short, the `ONE_SHORT`
- * ones being the "grab a sub" case.
- */
+/** The roster's shared free time as pickable slots: maximal spans where the team is at most one player short (`ONE_SHORT` = "grab a sub"). */
 export function pickableSlots({
 	members,
 	minPlayers,
@@ -286,10 +258,7 @@ export function pickableSlots({
 	});
 }
 
-/**
- * The members a scrim is played with: the team's players, or its whole roster
- * when there are not enough players on it to field a team.
- */
+/** The members a scrim is played with: the team's players, or the whole roster when too few players to field a team. */
 export function teamPlayers<
 	T extends { role: MemberRole | null; roleType: MemberRoleType | null },
 >(members: Array<T>): Array<T> {
@@ -311,12 +280,8 @@ export interface RosterFit {
 }
 
 /**
- * How well a roster fits a scrim post: the start among `starts` the most of
- * them are free for, and how each member relates to a scrim played from it.
- * Ties go to the earliest start.
- *
- * Null when nobody on the roster filled in the week the post falls in — a fit
- * nothing is known about is not worth showing.
+ * How well a roster fits a post: the start among `starts` most of them are free for (ties to the
+ * earliest) and how each member relates to it. Null when nobody filled in the post's week.
  */
 export function rosterFit({
 	starts,
diff --git a/app/features/scrims/core/ScrimMapByMap.ts b/app/features/scrims/core/ScrimMapByMap.ts
index d0b7d6224..226d147d0 100644
--- a/app/features/scrims/core/ScrimMapByMap.ts
+++ b/app/features/scrims/core/ScrimMapByMap.ts
@@ -14,9 +14,7 @@ type ScrimMapRow = Pick<
 	"index" | "mode" | "stageId" | "winnerSide" | "reportedAt"
 >;
 
-/**
- * Merges the submitted map lists into a single deduplicated MapPool.
- */
+/** Merges the submitted map lists into one deduplicated MapPool. */
 export function unionPool(lists: ResolvedMapListRow[]): MapPool {
 	const buckets: Record<ModeShort, Set<StageId>> = {
 		TW: new Set(),
@@ -43,10 +41,7 @@ export function unionPool(lists: ResolvedMapListRow[]): MapPool {
 	return new MapPool(merged);
 }
 
-/**
- * Generates the next single map for the scrim, keeping the pool's mode order
- * stable across calls and avoiding already-played `(mode, stage)` pairs.
- */
+/** The scrim's next map, keeping the pool's mode order stable across calls and avoiding played `(mode, stage)` pairs. */
 export function generateNextMap(args: {
 	pool: MapPool;
 	history: Pick<Tables["ScrimMap"], "mode" | "stageId">[];
@@ -70,10 +65,7 @@ export function generateNextMap(args: {
 	return { mode: result[0].mode, stageId: result[0].stageId };
 }
 
-/**
- * Returns true when the given map is the most recently reported one and is
- * therefore eligible to be undone.
- */
+/** Whether the map is the most recently reported one, and so can be undone. */
 export function canUndo(
 	map: ScrimMapRow | undefined,
 	history: ScrimMapRow[],
@@ -100,11 +92,7 @@ export type Stats = {
 	byStageMode: StatsRow[];
 };
 
-/**
- * Aggregates per-mode, per-stage, and per-(stage, mode) win/loss counts from
- * the viewer's perspective. Maps outside `restrictToPool` (when provided) are
- * skipped, as are unreported maps. Empty rows are filtered out.
- */
+/** Per-mode, per-stage and per-(stage, mode) win/loss counts from the viewer's perspective; unreported maps and ones outside `restrictToPool` are skipped, empty rows dropped. */
 export function stats(
 	maps: ScrimMapRow[],
 	viewerSide: "ALPHA" | "BRAVO",
diff --git a/app/features/scrims/loaders/scrims.server.ts b/app/features/scrims/loaders/scrims.server.ts
index 5bd14300b..19e295798 100644
--- a/app/features/scrims/loaders/scrims.server.ts
+++ b/app/features/scrims/loaders/scrims.server.ts
@@ -81,11 +81,7 @@ export const loader = async ({ request }: LoaderFunctionArgs) => {
 	};
 };
 
-/**
- * How the viewer's teams relate to the posts they could request: the material
- * the fit indicators on the post cards and in the request dialog are resolved
- * from, one entry per post.
- */
+/** How the viewer's teams relate to the requestable posts, one entry per post: what the fit indicators on cards and in the request dialog resolve from. */
 async function rosterAvailability({
 	posts,
 	teams,
diff --git a/app/features/scrims/scrims-types.ts b/app/features/scrims/scrims-types.ts
index e09cbcee9..9cc14c833 100644
--- a/app/features/scrims/scrims-types.ts
+++ b/app/features/scrims/scrims-types.ts
@@ -14,9 +14,8 @@ export interface ScrimPost {
 	visibility: AssociationVisibility | null;
 	text: string | null;
 	divs: {
-		/** Max div in the whole system is "X" */
+		/** the highest div is "X", the lowest "11" */
 		max: LutiDiv;
-		/** Min div in the whole system is "11" */
 		min: LutiDiv;
 	} | null;
 	maps: "SZ" | "ALL" | "RANKED" | null;
diff --git a/app/features/scrims/scrims-utils.ts b/app/features/scrims/scrims-utils.ts
index 962bc0481..7880f838a 100644
--- a/app/features/scrims/scrims-utils.ts
+++ b/app/features/scrims/scrims-utils.ts
@@ -59,10 +59,7 @@ export const parseLutiDiv = (div: number): LutiDiv => {
 	return String(div) as LutiDiv;
 };
 
-/**
- * Extracts the LUTI division (e.g. `"X"`, `"2"`) from a tournament name such as
- * "LUTI: Season 15 - Division 2". Returns `null` if no valid division token is found.
- */
+/** The LUTI division (e.g. `"X"`, `"2"`) of a name like "LUTI: Season 15 - Division 2", or `null`. */
 export const parseLutiDivFromName = (name: string): LutiDiv | null => {
 	const match = name.match(/\bdiv(?:ision)?\.?\s*(X|11|10|[1-9])\b/i);
 	if (!match) return null;
@@ -79,12 +76,7 @@ export const serializeLutiDiv = (div: LutiDiv): number => {
 	return Number(div);
 };
 
-/**
- * The starts a request for the post can still be made for: its start, the half
- * hours inside its start-time flexibility and the end of that flexibility,
- * with the ones already past dropped. A post with no flexibility left offers
- * `now` — "looking now" is what it means.
- */
+/** Starts a request can still be made for: the post's start, the half hours inside its flexibility and its end, past ones dropped. No flexibility left offers `now` ("looking now"). */
 export function requestStarts({
 	post,
 	now,
@@ -104,10 +96,7 @@ export function requestStarts({
 	return upcoming.length > 0 ? upcoming : [now];
 }
 
-/**
- * The whole span the post's scrim could take up: from the earliest start still
- * on offer to the end of a scrim played from the latest one.
- */
+/** The whole span the scrim could take up: earliest start still on offer to the end of a scrim from the latest one. */
 export function postSpan({
 	post,
 	now,
diff --git a/app/features/sendouq-match/GroupMatchContinueVoteRepository.server.ts b/app/features/sendouq-match/GroupMatchContinueVoteRepository.server.ts
index 21ec6fd63..e5cad7b09 100644
--- a/app/features/sendouq-match/GroupMatchContinueVoteRepository.server.ts
+++ b/app/features/sendouq-match/GroupMatchContinueVoteRepository.server.ts
@@ -30,10 +30,7 @@ export async function findAllByGroupIds(
 	}));
 }
 
-/**
- * Records the logged in user's vote on continuing with their group. Voting against continuing also
- * clears the group's votes in favor, since those were cast for a group size that no longer applies.
- */
+/** Records the user's continue vote. A no vote also clears the group's yes votes, cast for a size that no longer applies. */
 export async function castOwnVote(
 	{
 		groupId,
@@ -50,9 +47,8 @@ export async function castOwnVote(
 
 	const runner = async (t: Transaction<DB>) => {
 		if (!isContinuing) {
-			// every vote is only valid for a specific continuing size
-			// e.g. if i want to keep going with a full group, i might not
-			// want to continue with just 3 people -> revote required from all
+			// a yes vote is for a specific size: wanting to keep a full group is not
+			// wanting to continue with 3, so everyone revotes
 			await t
 				.deleteFrom("GroupMatchContinueVote")
 				.where("GroupMatchContinueVote.groupId", "=", groupId)
diff --git a/app/features/sendouq-match/MatchSkillRepository.server.ts b/app/features/sendouq-match/MatchSkillRepository.server.ts
index 37e596509..e0adea983 100644
--- a/app/features/sendouq-match/MatchSkillRepository.server.ts
+++ b/app/features/sendouq-match/MatchSkillRepository.server.ts
@@ -13,9 +13,7 @@ type InsertMatchSkills = Pick<
 	"groupMatchId" | "identifier" | "mu" | "season" | "sigma" | "userId"
 >[];
 
-/**
- * Inserts the new skill rows resulting from a match and their team memberships.
- */
+/** Inserts the new skill rows resulting from a match and their team memberships. */
 export async function insertMatchSkills(
 	skills: InsertMatchSkills,
 	trx?: Transaction<DB>,
diff --git a/app/features/sendouq-match/PlayerStatRepository.server.ts b/app/features/sendouq-match/PlayerStatRepository.server.ts
index 69889c825..88dde4339 100644
--- a/app/features/sendouq-match/PlayerStatRepository.server.ts
+++ b/app/features/sendouq-match/PlayerStatRepository.server.ts
@@ -149,10 +149,7 @@ export async function findSeasonMatesEnemiesByUserId({
 		.execute();
 }
 
-/**
- * Chronological (oldest first) scores of every set the user played in a given
- * season, both SendouQ matches and ranked tournaments.
- */
+/** Oldest-first scores of every set the user played in a season, SendouQ and ranked tournaments. */
 export async function findSeasonSetScoresByUserId(args: {
 	userId: number;
 	season: number;
@@ -181,11 +178,9 @@ export async function findSeasonSetScoresByUserId(args: {
 }
 
 /**
- * The user's won sets of a season ranked by the average opponent skill
- * (ordinal) at the time the set was played, best first. Covers both SendouQ
- * matches and ranked tournaments; tournament sets are skipped unless at least
- * two opponents have a calculated skill for that tournament. Only the best set
- * against any given opponent roster is included.
+ * The user's won sets of a season, best first by average opponent ordinal at play time. SendouQ
+ * and ranked tournaments; tournament sets need at least two opponents with a calculated skill.
+ * Only the best set against each opponent roster is included.
  */
 export async function findSeasonBestSetsByUserId({
 	userId,
@@ -353,11 +348,7 @@ export async function findSeasonBestSetsByUserId({
 	).slice(0, limit);
 }
 
-/**
- * The user's ranked tournament results of a season with the tournament's tier,
- * field size and the average end of season skill (ordinal) of its top 8 placing
- * players, for picking their best tournament run.
- */
+/** The user's ranked tournament results of a season with tier, field size and the average end-of-season ordinal of the top 8, for picking their best run. */
 export async function findSeasonTournamentRunsByUserId({
 	userId,
 	season,
@@ -466,10 +457,7 @@ export function upsertPlayerResults(
 		.execute();
 }
 
-/**
- * SendouQ sets of the user's season with the map score summed per match.
- * Callers add their extra selects and finish with a `groupBy("GroupMatch.id")`.
- */
+/** SendouQ sets of the user's season with the map score summed per match; callers add selects and finish with `groupBy("GroupMatch.id")`. */
 function sqSetScoresQuery({
 	userId,
 	season,
@@ -511,10 +499,7 @@ interface SeasonTournamentSet {
 	playedAt: number;
 }
 
-/**
- * One row per set the user played in the season's ranked tournaments (the
- * tournaments they have a `Skill` row for).
- */
+/** One row per set the user played in the season's ranked tournaments (those they have a `Skill` row for). */
 function tournamentSetsQuery({
 	userId,
 	season,
@@ -558,11 +543,7 @@ function tournamentSetsQuery({
 		.groupBy("TournamentMatch.id");
 }
 
-/**
- * Games of a tournament set won by either side, counted over every game of the
- * set since the user may have sat out some of them. Correlates on a
- * `tournamentSetsQuery` aliased as `"TournamentSet"`.
- */
+/** Games of a tournament set won by either side, over every game since the user may have sat some out. Correlates on `tournamentSetsQuery` aliased `"TournamentSet"`. */
 function tournamentSetGamesWonCount(
 	eb: ExpressionBuilder<
 		DB & { TournamentSet: SeasonTournamentSet },
diff --git a/app/features/sendouq-match/ReportedWeaponRepository.server.ts b/app/features/sendouq-match/ReportedWeaponRepository.server.ts
index d445f9440..ef9c3cb60 100644
--- a/app/features/sendouq-match/ReportedWeaponRepository.server.ts
+++ b/app/features/sendouq-match/ReportedWeaponRepository.server.ts
@@ -139,12 +139,7 @@ export async function deleteOwnByMapIndexTournament({
 		.execute();
 }
 
-/**
- * Deletes reported weapons that no longer correspond to a played game, i.e.
- * those reported "in advance" for map indexes beyond the games that ended up
- * being played. Called when a set ends to trim leftover weapons that earlier
- * score undos intentionally left dangling.
- */
+/** Deletes weapons reported "in advance" for map indexes beyond the games played; called when a set ends to trim what score undos intentionally left dangling. */
 export async function deleteExtraByTournamentMatchId(
 	{
 		tournamentMatchId,
@@ -182,10 +177,7 @@ export async function findByTournamentMatchId(matchId: number) {
 	return rows;
 }
 
-/**
- * Aggregates a user's reported weapons across both SendouQ matches and
- * finalized tournaments that fall within the given season's date range.
- */
+/** A user's reported weapons across SendouQ matches and finalized tournaments within the season's date range. */
 export async function findSeasonReportedWeaponsByUserId({
 	userId,
 	season,
@@ -253,10 +245,7 @@ export interface WeaponUsageStat {
 	losses: number;
 }
 
-/**
- * Reports how often a user and the mates/enemies they played against used each
- * weapon on a given stage and mode during a season, along with win/loss counts.
- */
+/** How often a user and their mates/enemies used each weapon on a stage and mode during a season, with win/loss counts. */
 export async function findAllWeaponUsageStats({
 	userId,
 	mode,
diff --git a/app/features/sendouq-match/SQMatchRepository.server.test.ts b/app/features/sendouq-match/SQMatchRepository.server.test.ts
index d536dee62..8404d3882 100644
--- a/app/features/sendouq-match/SQMatchRepository.server.test.ts
+++ b/app/features/sendouq-match/SQMatchRepository.server.test.ts
@@ -528,9 +528,8 @@ describe("finalizeMatch", () => {
 		expect((await fetchChatRoom(setup.match.chatRoomId!)).inactive).toBe(1);
 	});
 
-	// Demonstrates a bug: reportMapWinner checks the match lock on a snapshot read
-	// outside the finalizing transaction, so two teammates confirming the score at
-	// the same time both finalize. Rating/stat changes get applied twice.
+	// regression: the lock state must be read inside the finalizing transaction, or two
+	// teammates confirming at once both finalize and apply rating/stat changes twice
 	test("concurrent score confirmations finalize the match only once", async () => {
 		const setup = await setupMatch();
 
diff --git a/app/features/sendouq-match/SQMatchRepository.server.ts b/app/features/sendouq-match/SQMatchRepository.server.ts
index 7d21dd241..65660a584 100644
--- a/app/features/sendouq-match/SQMatchRepository.server.ts
+++ b/app/features/sendouq-match/SQMatchRepository.server.ts
@@ -313,9 +313,7 @@ function groupWithTeamAndMembers(
 	);
 }
 
-/**
- * Retrieves the pages count of results for a specific user and season. Counting both SendouQ matches and ranked tournaments.
- */
+/** Page count of a user's season results, counting both SendouQ matches and ranked tournaments. */
 export async function countSeasonResultPagesByUserId({
 	userId,
 	season,
@@ -441,9 +439,8 @@ const rosterSp = sql<
 	end`;
 
 /**
- * The SP a rating change was worth, or `null` while the rating is still being calculated
- * and so has never been shown. Reads the columns
- * {@link previousRatingColumns} adds, plus `ordinal`, off the named selection.
+ * The SP a rating change was worth, or `null` while the rating is still being calculated and so
+ * has never been shown. Reads the columns {@link previousRatingColumns} adds, plus `ordinal`.
  */
 const spDiffOf = (of: "userSkill" | "rosterSkill") =>
 	sql<
@@ -453,9 +450,8 @@ const spDiffOf = (of: "userSkill" | "rosterSkill") =>
 		end`;
 
 /**
- * Season's Skill rows partitioned by `partitionBy`, each carrying the rating it replaced.
- * Rows from SendouQ sets are included and not just the tournament ones the seasons page
- * shows, because a tournament rating's predecessor is just as often a SendouQ set.
+ * Season's Skill rows partitioned by `partitionBy`, each carrying the rating it replaced. SendouQ
+ * rows are included too, since a tournament rating's predecessor is just as often a SendouQ set.
  */
 const previousRatingColumns = (
 	eb: ExpressionBuilder<DB, "Skill">,
@@ -472,9 +468,7 @@ const previousRatingColumns = (
 			.as("previousMatchesCount"),
 	] as const;
 
-/**
- * Retrieves results of given user, competitive season & page. Both SendouQ matches and ranked tournaments.
- */
+/** A page of a user's season results, both SendouQ matches and ranked tournaments. */
 export async function findSeasonResultsByUserId({
 	userId,
 	season,
@@ -796,11 +790,7 @@ export async function findCancelNominationCountsByUserIds({
 	});
 }
 
-/**
- * Creates a match between two groups. Every match made in the app comes from a
- * ready check, which is resolved as part of the same transaction; only seeds and
- * tests, which have no check to resolve, leave `readyCheckId` out.
- */
+/** Creates a match between two groups, resolving its ready check in the same transaction; only seeds and tests leave `readyCheckId` out. */
 export function insert({
 	alphaGroupId,
 	bravoGroupId,
@@ -912,11 +902,7 @@ export interface MatchTiers {
 	}>;
 }
 
-/**
- * Records the tiers on the groups and members themselves, so that the match page keeps showing
- * what was held when it was played. Recomputing could not: tier thresholds are percentiles of
- * the season's live distribution and so shift as the season goes on.
- */
+/** Snapshots tiers on the groups and members: thresholds are percentiles of the live distribution, so recomputing later would show different tiers. */
 async function snapshotTiers(tiers: MatchTiers, trx: Transaction<DB>) {
 	for (const group of tiers.groups) {
 		await trx
@@ -1639,11 +1625,7 @@ export type ResolveUnfinishedMatchResult =
 	| { status: "CONFIRMED" }
 	| { status: "ALREADY_LOCKED" };
 
-/**
- * Resolves a match the teams never finished: cancels it if the score is not
- * decisive, otherwise confirms the one team's report on the other's behalf.
- * Leaves `confirmedByUserId` empty as no user acted.
- */
+/** Resolves a never-finished match: cancels when the score is not decisive, else confirms the one report on the other team's behalf. `confirmedByUserId` stays empty. */
 export async function resolveUnfinishedMatch(
 	matchId: number,
 ): Promise<ResolveUnfinishedMatchResult> {
diff --git a/app/features/sendouq-match/actions/q.match.$id.server.ts b/app/features/sendouq-match/actions/q.match.$id.server.ts
index f865288d7..bd7ca5f49 100644
--- a/app/features/sendouq-match/actions/q.match.$id.server.ts
+++ b/app/features/sendouq-match/actions/q.match.$id.server.ts
@@ -155,7 +155,7 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
 					});
 				}
 
-				// The group re-enters the looking pool, so refresh every looking client.
+				// the group re-enters the looking pool
 				ChatSystemMessage.send({ channel: SENDOUQ_LOOKING_CHANNEL });
 
 				break;
@@ -230,8 +230,7 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
 						viewerGroup.members.map((member) => member.id),
 					);
 
-					// The continuing group re-enters the looking pool, so refresh
-					// every looking client.
+					// the continuing group re-enters the looking pool
 					ChatSystemMessage.send({ channel: SENDOUQ_LOOKING_CHANNEL });
 				}
 
@@ -426,9 +425,8 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
 			}
 		}
 	} catch (error) {
-		// some errors are expected to happen, for example two requests racing to
-		// create/join a group. return null so loaders re-run and the user sees
-		// the fresh state instead of an error page
+		// expected errors (two requests racing to create/join a group): return null so
+		// loaders re-run and the user sees the fresh state instead of an error page
 		if (error instanceof SendouQError) {
 			return null;
 		}
diff --git a/app/features/sendouq-match/core/RejoinVote.ts b/app/features/sendouq-match/core/RejoinVote.ts
index 201304d71..768d1ce61 100644
--- a/app/features/sendouq-match/core/RejoinVote.ts
+++ b/app/features/sendouq-match/core/RejoinVote.ts
@@ -9,11 +9,7 @@ export interface RejoinVote {
 
 const MIN_CONTINUING_GROUP_SIZE = 2;
 
-/**
- * Resolves the overall vote state. ONGOING until every member of a full group
- * has cast a vote, then RESOLVED with the ids of those who chose to continue,
- * or FAILED if too few want to continue to form a viable group.
- */
+/** ONGOING until every member of a full group has voted, then RESOLVED with the ids continuing, or FAILED if too few to form a viable group. */
 export function result(votes: RejoinVote[]) {
 	if (votes.length !== FULL_GROUP_SIZE) {
 		return { type: "ONGOING" as const };
@@ -33,18 +29,12 @@ export function result(votes: RejoinVote[]) {
 	};
 }
 
-/**
- * Returns the given user's vote (true/false), or null if they have not voted.
- */
+/** The user's vote, or null if they have not voted. */
 export function userContinueStatus(votes: RejoinVote[], userId: number) {
 	return votes.find((vote) => vote.userId === userId)?.isContinuing ?? null;
 }
 
-/**
- * Whether the given user is still eligible to cast `isContinuing` as their vote.
- * A first vote is always allowed while the vote is ongoing, and a yes vote can
- * still be changed to a no; a no vote is final.
- */
+/** Whether the user may still cast `isContinuing`: a first vote while ongoing, or changing a yes to a no; a no is final. */
 export function canCastVote(
 	votes: RejoinVote[],
 	userId: number,
@@ -58,10 +48,7 @@ export function canCastVote(
 	return currentVote && !isContinuing;
 }
 
-/**
- * Collects the votes cast within the viewing user's own group. Returns null if
- * the user is not a member of either side of the match.
- */
+/** Votes cast within the viewer's own group, or null if they are in neither side of the match. */
 export function extractOwnGroupVotesFromSendouqMatch(
 	match: Pick<SQMatch, "groupAlpha" | "groupBravo">,
 	userId: number,
@@ -90,10 +77,7 @@ export function extractOwnGroupVotesFromSendouqMatch(
 	);
 }
 
-/**
- * Returns the group member ids that remain after removing anyone who voted
- * against continuing.
- */
+/** Group member ids minus anyone who voted against continuing. */
 export function currentUserIds(
 	votes: RejoinVote[],
 	groupMemberIds: number[],
diff --git a/app/features/sendouq-match/core/SendouQMatch.ts b/app/features/sendouq-match/core/SendouQMatch.ts
index 648518843..9bd0a61d1 100644
--- a/app/features/sendouq-match/core/SendouQMatch.ts
+++ b/app/features/sendouq-match/core/SendouQMatch.ts
@@ -2,11 +2,7 @@ import type { DBBoolean } from "~/db/tables";
 import type { TierName } from "~/features/mmr/mmr-constants";
 import { SENDOUQ_BEST_OF } from "~/features/sendouq/q-constants";
 
-/**
- * Calculates the current map win counts for each group in a SendouQ match and
- * indicates whether the match has been decided (i.e. one group has reached the
- * required number of map wins for the configured best-of).
- */
+/** Each group's map win count and whether one has reached the best-of's required wins. */
 export function score(match: {
 	mapList: Array<{ winnerGroupId: number | null }>;
 	groupAlpha: { id: number };
@@ -36,10 +32,7 @@ export function allMembers<T>(match: {
 	return [...match.groupAlpha.members, ...match.groupBravo.members];
 }
 
-/**
- * Returns which side ("ALPHA" or "BRAVO") of the match the given user belongs
- * to, or null if they are not a member of either group.
- */
+/** The user's side of the match, or null if in neither group. */
 export function resolveGroupMemberOf(args: {
 	groupAlpha: { members: { id: number }[] };
 	groupBravo: { members: { id: number }[] };
@@ -58,11 +51,7 @@ export function resolveGroupMemberOf(args: {
 	return null;
 }
 
-/**
- * Tier a group held when its match started, read off the snapshot taken then rather than
- * recomputed, because tier thresholds shift as a season's rating distribution does.
- * `undefined` for matches from before the snapshot was recorded.
- */
+/** Tier a group held when its match started, from the snapshot taken then (thresholds shift with the season's distribution). `undefined` for matches predating the snapshot. */
 export function groupTier(group: {
 	tierName: TierName | null;
 	tierIsPlus: DBBoolean;
diff --git a/app/features/sendouq-match/core/SkillDifference.ts b/app/features/sendouq-match/core/SkillDifference.ts
index 62e5c657c..a33f8daee 100644
--- a/app/features/sendouq-match/core/SkillDifference.ts
+++ b/app/features/sendouq-match/core/SkillDifference.ts
@@ -6,7 +6,6 @@ type CalculatingSkill = {
 	calculated: false;
 	matchesCount: number;
 	matchesCountNeeded: number;
-	/** Freshly calculated skill */
 	newSp?: number;
 };
 
@@ -27,20 +26,14 @@ export type GroupSkillDifference =
 	  }
 	| CalculatingSkill;
 
-/**
- * A rating a match produced together with the one it replaced, as found on two consecutive
- * `Skill` rows of the same season. `previous*` are `null` when the match produced the season's
- * first rating, which is also when the rating is furthest from being calculated.
- */
+/** A rating a match produced with the one it replaced (two consecutive season `Skill` rows). `previous*` are `null` for the season's first rating. */
 export interface RatingChange {
 	ordinal: number;
 	previousOrdinal: number | null;
 	previousMatchesCount: number | null;
 }
 
-/**
- * What a match did to one player's SP, as their match page shows it.
- */
+/** What a match did to one player's SP, as their match page shows it. */
 export function forUser(change: RatingChange): UserSkillDifference {
 	const { oldSp, newSp, calculated, matchesCount } = resolve(change);
 
@@ -56,9 +49,7 @@ export function forUser(change: RatingChange): UserSkillDifference {
 	};
 }
 
-/**
- * What a match did to one group's team SP, as their match page shows it.
- */
+/** What a match did to one group's team SP, as their match page shows it. */
 export function forGroup(change: RatingChange): GroupSkillDifference {
 	const { oldSp, newSp, calculated, matchesCount } = resolve(change);
 
diff --git a/app/features/sendouq-match/core/discord-webhook.server.ts b/app/features/sendouq-match/core/discord-webhook.server.ts
index 943287c44..df58fe41d 100644
--- a/app/features/sendouq-match/core/discord-webhook.server.ts
+++ b/app/features/sendouq-match/core/discord-webhook.server.ts
@@ -16,10 +16,7 @@ interface CancelReport {
 	nominatedPlayers: Array<{ userId: number }>;
 }
 
-/**
- * Posts a rich embed about a finalized SendouQ match cancellation to the SendouQ
- * cancels channel Discord webhook. Fire-and-forget (see `sendSQCancelDiscordWebhook`).
- */
+/** Posts a rich embed about a finalized SendouQ cancellation to the cancels channel webhook. Fire-and-forget (see `sendSQCancelDiscordWebhook`). */
 export function sendMatchCanceledWebhook(args: {
 	matchId: number;
 	members: MatchMember[];
diff --git a/app/features/sendouq-match/core/match-timeline.ts b/app/features/sendouq-match/core/match-timeline.ts
index c0cec27b5..75b2d0b05 100644
--- a/app/features/sendouq-match/core/match-timeline.ts
+++ b/app/features/sendouq-match/core/match-timeline.ts
@@ -12,11 +12,7 @@ import type { SendouQMatchLoaderData } from "../loaders/q.match.$id.server";
 
 type MatchData = SendouQMatchLoaderData["match"];
 
-/**
- * Resolves display names for the two groups in a match, falling back to the
- * translated "Group Alpha"/"Group Bravo" labels when a group is not associated
- * with a registered team.
- */
+/** Display names of a match's two groups, translated "Group Alpha"/"Group Bravo" for ones without a registered team. */
 export function resolveGroupNames(match: MatchData, t: TFunction<["q"]>) {
 	return {
 		alpha: match.groupAlpha.team?.name ?? t("q:match.groupAlpha"),
diff --git a/app/features/sendouq-match/core/match.server.test.ts b/app/features/sendouq-match/core/match.server.test.ts
index 50945ae82..d5e107318 100644
--- a/app/features/sendouq-match/core/match.server.test.ts
+++ b/app/features/sendouq-match/core/match.server.test.ts
@@ -245,8 +245,7 @@ describe("matchMapList()", () => {
 
 		vi.mocked(getDefaultMapWeights).mockResolvedValue(mockDefaults);
 
-		// Both teams have empty preferences (no map pools set)
-		// This forces the system to rely entirely on defaults
+		// empty preferences force the system to rely entirely on defaults
 		const emptyPreferences = {
 			modes: [{ mode: "SZ" as const, preference: "PREFER" as const }],
 			pool: [],
@@ -272,11 +271,9 @@ describe("matchMapList()", () => {
 	});
 
 	test("user selected maps should be preferred over default maps even with small pool", async () => {
-		// User selected stages - just 7 stages per mode (less than half of 25)
-		// Note: stages 1 (EELTAIL_ALLEY) and 9 (STURGEON_SHIPYARD) are banned for SZ
+		// 7 stages per mode (less than half of 25); stages 1 (EELTAIL_ALLEY) and 9 (STURGEON_SHIPYARD) are banned for SZ
 		const userSelectedStageIds: StageId[] = [0, 2, 3, 4, 5, 6, 7];
 
-		// Default stages include many more maps that users did NOT select
 		const defaultStageIds: StageId[] = [
 			8, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
 		];
@@ -288,7 +285,6 @@ describe("matchMapList()", () => {
 
 		vi.mocked(getDefaultMapWeights).mockResolvedValue(mockDefaults);
 
-		// Both teams have selected the same 5 stages
 		const teamPreferences = {
 			modes: [{ mode: "SZ" as const, preference: "PREFER" as const }],
 			pool: [
@@ -323,7 +319,6 @@ describe("matchMapList()", () => {
 
 		const szMaps = result.filter((m) => m.mode === "SZ");
 
-		// All selected maps should come from user preferences, not defaults
 		for (const map of szMaps) {
 			expect(userSelectedStageIds).toContain(map.stageId);
 		}
diff --git a/app/features/sendouq-match/core/match.server.ts b/app/features/sendouq-match/core/match.server.ts
index fb07d5704..b8ca5def9 100644
--- a/app/features/sendouq-match/core/match.server.ts
+++ b/app/features/sendouq-match/core/match.server.ts
@@ -59,15 +59,7 @@ async function calculateMapWeights(
 	return applyDefaultWeights(combinedWeights);
 }
 
-/**
- * Normalizes and combines map weights from two teams.
- *
- * When both teams have weights, team one's weights are normalized to match
- * team two's total before combining. This ensures fair weighting when teams
- * have different numbers of preferences.
- *
- * @returns Combined weights map with all keys from both teams
- */
+/** Combines two teams' map weights, first normalizing team one's to team two's total so differing preference counts weigh fairly. */
 export function normalizeAndCombineWeights(
 	teamOneWeights: Map<string, number>,
 	teamTwoWeights: Map<string, number>,
@@ -99,15 +91,7 @@ export function normalizeAndCombineWeights(
 	return combinedWeights;
 }
 
-/**
- * Applies default map weights to combined weights for any maps not already weighted.
- *
- * Fetches global default weights and adds them to the combined weights map for any
- * map-mode combinations that don't already have weights. This ensures the pool always
- * has a baseline selection of maps.
- *
- * @returns Combined weights with defaults applied
- */
+/** Adds the global default weights for map-mode combinations not already weighted, so the pool always has a baseline. */
 async function applyDefaultWeights(
 	combinedWeights: WeightsMap,
 ): Promise<WeightsMap> {
@@ -312,7 +296,6 @@ export function compareMatchToReportedScores({
 	newReporterGroupId: number;
 	previousReporterGroupId?: number;
 }) {
-	// match has not been reported before
 	if (!match.mapList.some((m) => m.reportedByUserId !== null)) {
 		return "FIRST_REPORT";
 	}
diff --git a/app/features/sendouq-match/core/reported-weapons.server.ts b/app/features/sendouq-match/core/reported-weapons.server.ts
index 6aa2cac5e..38a87af4b 100644
--- a/app/features/sendouq-match/core/reported-weapons.server.ts
+++ b/app/features/sendouq-match/core/reported-weapons.server.ts
@@ -18,7 +18,6 @@ export function mergeReportedWeapons({
 }): ReportedWeapon[] {
 	let result: ReportedWeaponForMerging[] = [];
 
-	// make corrections to the old weapons
 	for (const oldWeapon of oldWeapons) {
 		const replacement = newWeapons.find(
 			(newWeapon) =>
@@ -34,7 +33,6 @@ export function mergeReportedWeapons({
 		}
 	}
 
-	// add new weapons that were not reported in the old list
 	for (const newWeapon of newWeapons) {
 		if (
 			!result.some(
@@ -48,7 +46,7 @@ export function mergeReportedWeapons({
 		}
 	}
 
-	// if the score got adjusted we need to get rid of the extra reported weapons
+	// an adjusted score leaves extra reported weapons behind
 	if (newReportedMapsCount) {
 		result = result.filter((wpn) => wpn.mapIndex < newReportedMapsCount);
 	}
diff --git a/app/features/sendouq-match/core/skills.server.ts b/app/features/sendouq-match/core/skills.server.ts
index 9149fff00..579da8abb 100644
--- a/app/features/sendouq-match/core/skills.server.ts
+++ b/app/features/sendouq-match/core/skills.server.ts
@@ -34,7 +34,6 @@ export async function calculateMatchSkills({
 		const oldWinnerRatings = winner.map((userId) => ratings.user(userId));
 		const oldLoserRatings = loser.map((userId) => ratings.user(userId));
 
-		// individual skills
 		const [winnerTeamNew, loserTeamNew] = rate([
 			oldWinnerRatings.map(({ rating }) => rating),
 			oldLoserRatings.map(({ rating }) => rating),
@@ -64,7 +63,6 @@ export async function calculateMatchSkills({
 	}
 
 	{
-		// team skills
 		const oldWinnerGroupRating = ratings.team(winnerTeamIdentifier);
 		const oldLoserGroupRating = ratings.team(loserTeamIdentifier);
 
diff --git a/app/features/sendouq-streams/core/streams.server.ts b/app/features/sendouq-streams/core/streams.server.ts
index b51d9110e..5ab3082fb 100644
--- a/app/features/sendouq-streams/core/streams.server.ts
+++ b/app/features/sendouq-streams/core/streams.server.ts
@@ -44,17 +44,14 @@ export function cachedStreams() {
 					return -1;
 				}
 
-				// sort by base tier
 				if (aTierIndex !== bTierIndex) {
 					return aTierIndex - bTierIndex;
 				}
 
-				// if base tier is the same, sort by plus
 				if (a.tier?.isPlus !== b.tier?.isPlus) {
 					return a.tier?.isPlus ? -1 : 1;
 				}
 
-				// if tier is the same, sort by viewer count
 				return b.stream.viewerCount - a.stream.viewerCount;
 			});
 		},
diff --git a/app/features/sendouq/SQGroupRepository.server.ts b/app/features/sendouq/SQGroupRepository.server.ts
index 576e07744..052bead6d 100644
--- a/app/features/sendouq/SQGroupRepository.server.ts
+++ b/app/features/sendouq/SQGroupRepository.server.ts
@@ -253,11 +253,7 @@ export async function insertFromPrevious(
 	});
 }
 
-/**
- * Stamps the group as a team's, when a full group's worth of its members share one,
- * and clears the stamp otherwise. A team's group queues on the team's own map & mode
- * preferences rather than on those of its members.
- */
+/** Stamps the group as a team's when a full group's worth of members share one, else clears it. A team's group queues on the team's own map & mode preferences. */
 export async function syncTeamId(groupId: number, trx: Transaction<DB>) {
 	// the tables are joined directly instead of through `TeamMemberWithSecondary`,
 	// which SQLite materializes in full before the group filter narrows it down
@@ -320,11 +316,7 @@ function deleteSuggestionsByGroupId(groupId: number, trx: Transaction<DB>) {
 		.execute();
 }
 
-/**
- * Deletes every like and suggestion where the given group is on either side.
- * Called when the group's pending challenges and suggestions stop being
- * actionable e.g. its roster changed or it started a match.
- */
+/** Deletes every like and suggestion with the group on either side, for when they stop being actionable (roster changed, match started). */
 export async function deleteLikesAndSuggestionsByGroupId(
 	groupId: number,
 	trx: Transaction<DB>,
@@ -844,11 +836,7 @@ export function deleteAllLikesByGroupId(groupId: number) {
 	return db.transaction().execute((trx) => deleteLikesByGroupId(groupId, trx));
 }
 
-/**
- * Removes the user from their group, deleting the group if they were its last
- * member. A ready check the group was in is called off, its groups returning to
- * the looking pool. Returns the ids of the groups that were in that check.
- */
+/** Removes the user from their group (deleting it if they were last). A ready check the group was in is called off; returns the ids of the groups that were in it. */
 export function leaveGroup(userId: number) {
 	return db.transaction().execute(async (trx) => {
 		const userGroup = await trx
@@ -1038,11 +1026,7 @@ export function findAllReadyChecksStartedBefore(date: Date) {
 		.execute();
 }
 
-/**
- * Starts a ready check between two groups, taking both out of the looking pool
- * along with everything they had pending. The user starting it counts as ready
- * right away.
- */
+/** Starts a ready check between two groups, taking both and everything they had pending out of the looking pool. The starter counts as ready right away. */
 export function insertReadyCheck({
 	alphaGroupId,
 	bravoGroupId,
@@ -1134,11 +1118,7 @@ export function insertReadyCheckConfirmation({
 	});
 }
 
-/**
- * Ends a ready check, returning both of its groups to the looking pool. With
- * `markMissedMembers` the members who never confirmed are marked as having
- * missed it, which is what lets the rest of their group kick them.
- */
+/** Ends a ready check, returning both groups to the looking pool. `markMissedMembers` marks the unconfirmed as having missed it, which lets the rest of their group kick them. */
 export function deleteReadyCheck(
 	{ id, markMissedMembers }: { id: number; markMissedMembers: boolean },
 	trx?: Transaction<DB>,
@@ -1202,11 +1182,9 @@ async function deleteReadyCheckInTrx(
 }
 
 /**
- * Records the user as not continuing with the group they last played a matchmade
- * match with, taking that group's votes in favour down with it. Getting a group
- * elsewhere overrides a vote already cast in favour: the group can no longer
- * continue at the size that vote was for, so the rest have to vote again. Once
- * their no vote is in, that group is settled and later queue actions leave it be.
+ * Records the user as not continuing with the group they last played a matchmade match with,
+ * clearing that group's yes votes: it can no longer continue at the size they were for, so the
+ * rest have to vote again. Once the no vote is in, later queue actions leave that group be.
  */
 async function recordImplicitRejoinNoVote(
 	userId: number,
diff --git a/app/features/sendouq/actions/q.looking.server.ts b/app/features/sendouq/actions/q.looking.server.ts
index 365c2a8b7..8dd62f5d1 100644
--- a/app/features/sendouq/actions/q.looking.server.ts
+++ b/app/features/sendouq/actions/q.looking.server.ts
@@ -19,9 +19,8 @@ import {
 } from "../q-constants";
 import { SendouQError } from "../q-utils.server";
 
-// this function doesn't throw normally because we are assuming
-// if there is a validation error the user saw stale data
-// and when we return null we just force a refresh
+// a validation error means the user saw stale data, so instead of throwing
+// this returns null to force a refresh
 export const action: ActionFunction = async ({ request }) => {
 	const user = requireUser();
 	const result = await parseFormData({
@@ -273,9 +272,8 @@ export const action: ActionFunction = async ({ request }) => {
 
 		return null;
 	} catch (error) {
-		// some errors are expected to happen, for example they might request two groups at the same time
-		// then after morphing one group the other request fails because the group no longer exists
-		// return null causes loaders to run and they see the fresh state again instead of error page
+		// expected errors (e.g. two groups requested at once, the second failing once the first
+		// morphed): return null so loaders re-run and the user sees the fresh state
 		if (error instanceof SendouQError) {
 			return null;
 		}
diff --git a/app/features/sendouq/actions/q.preparing.server.ts b/app/features/sendouq/actions/q.preparing.server.ts
index abd8caaae..ecbcc0a91 100644
--- a/app/features/sendouq/actions/q.preparing.server.ts
+++ b/app/features/sendouq/actions/q.preparing.server.ts
@@ -98,9 +98,8 @@ export const action = async ({ request }: ActionFunctionArgs) => {
 			}
 		}
 	} catch (error) {
-		// some errors are expected to happen, for example two requests racing to
-		// create/join a group. return null so loaders re-run and the user sees
-		// the fresh state instead of an error page
+		// expected errors (two requests racing to create/join a group): return null so
+		// loaders re-run and the user sees the fresh state instead of an error page
 		if (error instanceof SendouQError) {
 			return null;
 		}
diff --git a/app/features/sendouq/actions/q.server.ts b/app/features/sendouq/actions/q.server.ts
index fcaaf25d9..efd3fc87a 100644
--- a/app/features/sendouq/actions/q.server.ts
+++ b/app/features/sendouq/actions/q.server.ts
@@ -64,8 +64,7 @@ export const action: ActionFunction = async ({ request, url }) => {
 
 				await refreshSendouQInstance();
 
-				// Joining directly creates an ACTIVE group that enters the pool, so
-				// refresh every looking client. (A PREPARING group isn't in the pool.)
+				// joining directly creates an ACTIVE group that enters the pool (a PREPARING one isn't in it)
 				if (data.direct === "true") {
 					ChatSystemMessage.send({ channel: SENDOUQ_LOOKING_CHANNEL });
 				}
@@ -102,15 +101,12 @@ export const action: ActionFunction = async ({ request, url }) => {
 				await refreshSendouQInstance();
 
 				if (groupInvitedTo.status === "PREPARING") {
-					// A preparing group isn't in the pool, so notify just its existing
-					// members (on the preparing page) via the group topic.
+					// a preparing group isn't in the pool, so only its members (on the preparing page)
 					ChatSystemMessage.send({
 						channel: sqGroupChannel(groupInvitedTo.id),
 					});
 				} else {
-					// Joining an active group changes its size/suitability for the whole
-					// pool, so refresh every looking client — which already includes the
-					// group's own existing members.
+					// the group's size/suitability changed for the whole pool, its own members included
 					ChatSystemMessage.send({ channel: SENDOUQ_LOOKING_CHANNEL });
 				}
 
@@ -159,9 +155,8 @@ export const action: ActionFunction = async ({ request, url }) => {
 			}
 		}
 	} catch (error) {
-		// some errors are expected to happen, for example two requests racing to
-		// create/join a group. return null so loaders re-run and the user sees
-		// the fresh state instead of an error page
+		// expected errors (two requests racing to create/join a group): return null so
+		// loaders re-run and the user sees the fresh state instead of an error page
 		if (error instanceof SendouQError) {
 			return null;
 		}
diff --git a/app/features/sendouq/components/GroupCard.browser.test.tsx b/app/features/sendouq/components/GroupCard.browser.test.tsx
index 3fd27078c..987026591 100644
--- a/app/features/sendouq/components/GroupCard.browser.test.tsx
+++ b/app/features/sendouq/components/GroupCard.browser.test.tsx
@@ -200,7 +200,6 @@ describe("GroupCard", () => {
 				}),
 			});
 
-			// Tier info is shown in a popover button, check it renders
 			await expect
 				.element(screen.getByTestId("sendouq-group-card-member"))
 				.toBeVisible();
@@ -220,7 +219,6 @@ describe("GroupCard", () => {
 				}),
 			});
 
-			// Weapons are rendered as img elements
 			const images = screen.container.querySelectorAll("img");
 			expect(images.length).toBeGreaterThan(0);
 		});
@@ -314,7 +312,6 @@ describe("GroupCard", () => {
 				}),
 			});
 
-			// REPLAY text is rendered, translations are loaded
 			await expect.element(screen.getByText(/REPLAY/i)).toBeVisible();
 		});
 	});
@@ -330,7 +327,6 @@ describe("GroupCard", () => {
 				displayOnly: false,
 			});
 
-			// Actual translated text is "Invite"
 			await expect.element(screen.getByText("Invite")).toBeVisible();
 		});
 
@@ -344,7 +340,6 @@ describe("GroupCard", () => {
 				displayOnly: false,
 			});
 
-			// Actual translated text is "Challenge"
 			await expect.element(screen.getByText("Challenge")).toBeVisible();
 		});
 
@@ -358,7 +353,6 @@ describe("GroupCard", () => {
 				displayOnly: false,
 			});
 
-			// Actual translated text is "Start match"
 			await expect.element(screen.getByText("Start match")).toBeVisible();
 		});
 	});
@@ -427,7 +421,6 @@ describe("GroupCard", () => {
 			await expect
 				.element(screen.getByTestId("sendouq-group-card-member"))
 				.toBeVisible();
-			// VC button should not be visible, only member info
 		});
 
 		test("hides weapons when hideWeapons=1", async () => {
diff --git a/app/features/sendouq/components/GroupCard.tsx b/app/features/sendouq/components/GroupCard.tsx
index 5e59b821c..2b978214c 100644
--- a/app/features/sendouq/components/GroupCard.tsx
+++ b/app/features/sendouq/components/GroupCard.tsx
@@ -316,7 +316,6 @@ function GroupCardContainer({
 	layout: "mobile" | "desktop";
 	children: React.ReactNode;
 }) {
-	// we don't want it to animate
 	if (isOwnGroup) return <>{children}</>;
 
 	return <Flipped flipId={`${layout}-${groupId}`}>{children}</Flipped>;
@@ -655,9 +654,8 @@ function VoiceChatInfo({
 
 	const color = () => {
 		const languagesMatch =
-			// small hack to show green for yourself always to avoid confusion
-			// might show red because root loaders don't reload
-			// till there is a full page refresh
+			// always green for yourself: root loaders don't reload until a full
+			// page refresh, so it could otherwise show red
 			member.id === user?.id ||
 			member.languages?.some((l) => user?.languages.includes(l));
 
diff --git a/app/features/sendouq/core/SendouQ.server.test.ts b/app/features/sendouq/core/SendouQ.server.test.ts
index ff36c916c..3cb152d0f 100644
--- a/app/features/sendouq/core/SendouQ.server.test.ts
+++ b/app/features/sendouq/core/SendouQ.server.test.ts
@@ -50,11 +50,7 @@ const createGroup = async (
 	return group.id;
 };
 
-/**
- * Gives every group the same `latestActionAt`, so the sort comparator's recency
- * tie-breaker stays neutral and the assertion does not depend on whether the group
- * inserts straddle a second boundary (which they can on slow CI).
- */
+/** Gives every group the same `latestActionAt` so the recency tie-breaker stays neutral even when inserts straddle a second boundary (slow CI). */
 const alignLatestActionAt = async (groupIds: number[]) => {
 	const at = new Date();
 
diff --git a/app/features/sendouq/core/SendouQ.server.ts b/app/features/sendouq/core/SendouQ.server.ts
index 160685650..c7f662962 100644
--- a/app/features/sendouq/core/SendouQ.server.ts
+++ b/app/features/sendouq/core/SendouQ.server.ts
@@ -61,7 +61,6 @@ class SendouQClass {
 	#isAccurateTiers;
 	#userSkills;
 	#intervals;
-	/** Array of user IDs currently in the queue */
 	usersInQueue;
 
 	constructor(
@@ -110,13 +109,8 @@ class SendouQClass {
 		}));
 	}
 
-	/**
-	 * Determines the current view state for a user based on their group status.
-	 */
-	currentViewByUserId(
-		/** The ID of the logged in user */
-		userId: number,
-	) {
+	/** The current view state for a user based on their group status. */
+	currentViewByUserId(userId: number) {
 		const ownGroup = this.findOwnGroup(userId);
 
 		if (!ownGroup) return "default";
@@ -127,43 +121,25 @@ class SendouQClass {
 		return "looking";
 	}
 
-	/**
-	 * Finds the group that a user belongs to.
-	 * @returns The user's group, or undefined if not in a group
-	 */
+	/** The user's group, or undefined if not in one. */
 	findOwnGroup(userId: number) {
 		return this.groups.find((group) =>
 			group.members.some((member) => member.id === userId),
 		);
 	}
 
-	/**
-	 * Finds a group by its ID without censoring sensitive data.
-	 * @returns The uncensored group, or undefined if not found
-	 */
+	/** A group by id without censoring sensitive data. */
 	findUncensoredGroupById(groupId: number) {
 		return this.groups.find((group) => group.id === groupId);
 	}
 
-	/**
-	 * Finds a group by its invite code.
-	 * @returns The group with matching invite code, or undefined if not found
-	 */
+	/** A group by its invite code. */
 	findGroupByInviteCode(inviteCode: string) {
 		return this.groups.find((group) => group.inviteCode === inviteCode);
 	}
 
-	/**
-	 * Maps a database match to a format with appropriate censoring based on user permissions.
-	 * Includes private notes for team members and censors sensitive data for non-participants.
-	 * @returns The mapped match with censored data based on user permissions
-	 */
-	mapMatch(
-		/** The database match object to map */
-		match: DBMatch,
-		/** The authenticated user viewing the match (if any) */
-		user?: AuthenticatedUser,
-	) {
+	/** Maps a database match for the viewer: private notes for team members, sensitive data censored for non-participants. */
+	mapMatch(match: DBMatch, user?: AuthenticatedUser) {
 		const viewerSide = SendouQMatch.resolveGroupMemberOf({
 			groupAlpha: match.groupAlpha,
 			groupBravo: match.groupBravo,
@@ -244,14 +220,8 @@ class SendouQClass {
 		};
 	}
 
-	/**
-	 * Returns all groups with wide tier ranges for preview purposes. Full groups being preview always show the full range (IRON-LEVIATHAN)
-	 * @returns Array of censored groups with preview tier ranges
-	 */
-	previewGroups(
-		/** The ID of the user viewing the preview */
-		userId: number,
-	) {
+	/** All groups with wide tier ranges for preview; full groups always show the full range (IRON-LEVIATHAN). */
+	previewGroups(userId: number) {
 		const usersTier = this.#getUserTier(userId);
 		return this.groups
 			.filter((group) => this.#isSuitableLookingGroup({ group }))
@@ -260,16 +230,8 @@ class SendouQClass {
 			.map((group) => this.#censorGroup(group));
 	}
 
-	/**
-	 * Returns groups that are available for matchmaking for a specific user based on their current group size.
-	 * Filters groups based on member count compatibility, activity status, and excludes stale groups.
-	 * Results are sorted by tier difference and activity.
-	 * @returns Array of compatible groups sorted by relevance, or empty array if user has no group
-	 */
-	lookingGroups(
-		/** The ID of the user looking for groups */
-		userId: number,
-	) {
+	/** Groups compatible with the user's own group's size, stale ones excluded, sorted by tier difference and activity. Empty if the user has no group. */
+	lookingGroups(userId: number) {
 		const ownGroup = this.findOwnGroup(userId);
 		if (!ownGroup) return [];
 
@@ -476,7 +438,6 @@ class SendouQClass {
 			}
 		}
 
-		// reasonable default
 		if (modePreferences.length === 0) {
 			return ["SZ"];
 		}
@@ -608,13 +569,10 @@ function matchMapPools(match: DBMatch) {
 	);
 }
 
-/** Global instance of the SendouQ manager. Manages all active groups and matchmaking state. */
+/** Global SendouQ manager: all active groups and matchmaking state. */
 export let SendouQ = await freshSendouQInstance();
 
-/**
- * Refreshes the global SendouQ instance with the latest data from the database.
- * Should be called after any database changes that affect groups or matches.
- */
+/** Reloads the global SendouQ instance from the database; call after any change to groups or matches. */
 export async function refreshSendouQInstance() {
 	SendouQ = await freshSendouQInstance();
 }
@@ -631,7 +589,7 @@ async function freshSendouQInstance() {
 	return new SendouQClass(groups, recentMatches, skills);
 }
 
-/** User needs to be on certain page depending on their SendouQ group status. This functions throws a `Redirect` if they are trying to load the wrong page. */
+/** Throws a redirect when the user loads a page other than the one their SendouQ group status puts them on. */
 export async function sqRedirectIfNeeded({
 	ownGroup,
 	currentLocation,
@@ -643,7 +601,6 @@ export async function sqRedirectIfNeeded({
 		await groupUnlessSeasonIsOver(ownGroup),
 	);
 
-	// we are already in the correct location, don't redirect
 	if (currentLocation === "default" && newLocation === SENDOUQ_PAGE) return;
 	if (currentLocation === "preparing" && newLocation === SENDOUQ_PREPARING_PAGE)
 		return;
@@ -655,17 +612,12 @@ export async function sqRedirectIfNeeded({
 	throw redirect(newLocation);
 }
 
-/**
- * Takes the group out of the queue if the season it was queueing for has ended,
- * leaving nowhere for it to be redirected but the front page. A group that got
- * its match stays as it is, so the match can be reported during its grace period.
- */
+/** Takes the group out of the queue if its season has ended (nowhere to redirect but the front page); a group in a match stays so it can be reported during the grace period. */
 async function groupUnlessSeasonIsOver(ownGroup?: SQOwnGroup) {
 	if (!ownGroup || ownGroup.matchId || Seasons.current()) return ownGroup;
 
-	// the ready check the group is in can't produce a rated match anymore, and
-	// leaving it behind would have the expiry routine mark its members as having
-	// missed a check they never had the chance to make
+	// the ready check can't produce a rated match anymore; left behind, the expiry
+	// routine would mark its members as having missed a check they never could make
 	if (ownGroup.status === "READY_CHECK") {
 		const readyCheck = await SQGroupRepository.findReadyCheckByGroupId(
 			ownGroup.id,
diff --git a/app/features/sendouq/core/groups.ts b/app/features/sendouq/core/groups.ts
index acdfa1d3c..1e73cdcf1 100644
--- a/app/features/sendouq/core/groups.ts
+++ b/app/features/sendouq/core/groups.ts
@@ -3,11 +3,7 @@ import { databaseTimestampToDate } from "~/utils/dates";
 import type { GroupExpiryStatus } from "../q-types";
 import type { SQGroup } from "./SendouQ.server";
 
-/**
- * Which group's settings the two groups keep when they morph into one. The bigger
- * group decides, and if they are the same size the group who liked consents to the
- * other group's settings.
- */
+/** Whose settings two morphing groups keep: the bigger group's, or at equal size the liked group's. */
 export function groupAfterMorph({
 	ourGroup,
 	theirGroup,
@@ -42,10 +38,7 @@ export function isInLookingPool(group: {
 	return group.status === "ACTIVE" && !group.matchId;
 }
 
-/**
- * Whether the group's members can suggest other groups to each other. A suggestion
- * is a pointer for teammates, so a solo group has no one to point at anything.
- */
+/** Whether members can suggest groups to each other; a solo group has no one to point at anything. */
 export function canSuggest(group: { members: unknown[] }) {
 	return group.members.length > 1;
 }
diff --git a/app/features/sendouq/core/likes.server.ts b/app/features/sendouq/core/likes.server.ts
index 105735a8a..ac03a6bf6 100644
--- a/app/features/sendouq/core/likes.server.ts
+++ b/app/features/sendouq/core/likes.server.ts
@@ -8,12 +8,7 @@ import {
 } from "../q-constants";
 import { refreshSendouQInstance, SendouQ } from "./SendouQ.server";
 
-/**
- * Cancels every pending challenge (both given and received) involving the user's
- * active and full SendouQ group. Only full groups are affected: partial groups
- * merge (rather than start a match) when a request is accepted, so their members'
- * preferences are not yet locked in.
- */
+/** Cancels every pending challenge involving the user's active full group. Partial groups merge rather than start a match on accept, so their preferences are not locked in yet. */
 export async function cancelActiveGroupLikes(userId: number) {
 	const ownGroup = SendouQ.findOwnGroup(userId);
 	if (!ownGroup) return;
diff --git a/app/features/sendouq/core/ready-check.server.ts b/app/features/sendouq/core/ready-check.server.ts
index 2caae9581..d12b9c7a8 100644
--- a/app/features/sendouq/core/ready-check.server.ts
+++ b/app/features/sendouq/core/ready-check.server.ts
@@ -42,11 +42,7 @@ export function hasExpired(readyCheck: { createdAt: number }) {
 	return expiresAt(readyCheck) <= new Date();
 }
 
-/**
- * Starts a ready check between two groups that matched up. Both leave the
- * looking pool while their members confirm they are ready to play. The user
- * starting it counts as ready right away.
- */
+/** Starts a ready check between two matched groups; both leave the looking pool while members confirm. The starter counts as ready right away. */
 export async function start({
 	ownGroup,
 	theirGroup,
@@ -64,9 +60,8 @@ export async function start({
 
 	await refreshSendouQInstance();
 
-	// Both groups revalidate (→ sent to the ready check by their looking loader)
-	// and play the ready check sound. Sent to the groups' topics so it reaches
-	// every member reliably, not just live chat participants.
+	// both groups revalidate (→ sent to the ready check by their looking loader) and play
+	// the sound; sent to the groups' topics so it reaches every member, not just chat participants
 	ChatSystemMessage.send([
 		{
 			channel: sqGroupChannel(ownGroup.id),
@@ -91,11 +86,7 @@ export async function start({
 	});
 }
 
-/**
- * Records the user as ready to play. Once everyone from both groups has, the
- * match is created.
- * @returns Id of the created match, or `null` if others are still to confirm or the ready check already ended
- */
+/** Records the user as ready; once everyone from both groups is, the match is created. @returns its id, or `null` if others are still to confirm or the check already ended */
 export async function confirm({
 	readyCheck,
 	userId,
@@ -131,11 +122,7 @@ export async function confirm({
 	return createMatch({ readyCheck, actorUserId: userId });
 }
 
-/**
- * Ends a ready check that ran out of time. Both groups go back to looking with
- * their challenges gone, and the members who never confirmed are marked as
- * having missed it so the rest of their group can kick them.
- */
+/** Ends a timed-out ready check: both groups go back to looking with challenges gone, and unconfirmed members are marked as having missed it so the rest can kick them. */
 export async function expire(readyCheck: {
 	id: number;
 	alphaGroupId: number;
@@ -145,10 +132,7 @@ export async function expire(readyCheck: {
 	await endReadyCheck(readyCheck, { markMissedMembers: true });
 }
 
-/**
- * Ends a ready check that can no longer result in a match. Both groups go back to
- * looking with nobody marked as having missed the check, as nobody is at fault.
- */
+/** Ends a ready check that can no longer result in a match; both groups go back to looking with nobody marked as having missed it. */
 export async function abort(readyCheck: {
 	id: number;
 	alphaGroupId: number;
diff --git a/app/features/sendouq/q-constants.ts b/app/features/sendouq/q-constants.ts
index 98cc3a76f..92429b18a 100644
--- a/app/features/sendouq/q-constants.ts
+++ b/app/features/sendouq/q-constants.ts
@@ -26,14 +26,11 @@ export const ACTION_TAB_AFTER_LOCKED_SECONDS = 24 * 60 * 60; // 24 hours
 /** Event bus channel that every user on the looking page subscribes to. */
 export const SENDOUQ_LOOKING_CHANNEL = "sq-looking";
 
-/**
- * Event bus channel for revalidation messages targeted at a single group (e.g. a
- * received like)
- * */
+/** Event bus channel for revalidation messages targeted at a single group (e.g. a received like) */
 export const sqGroupChannel = (groupId: number) =>
 	`${CHANNEL_PREFIX.sqGroup}${groupId}`;
 
 export const USER_SKILLS_CACHE_KEY = "user-skills";
 
-/** Breakpoint (in px) for the main container after which we switch from 3-column layout to tabs */
+/** Main container width (px) below which the 3-column layout switches to tabs */
 export const IS_Q_LOOKING_MOBILE_BREAKPOINT = 700;
diff --git a/app/features/sendouq/q-utils.server.ts b/app/features/sendouq/q-utils.server.ts
index 0b94f5126..dfb26bc11 100644
--- a/app/features/sendouq/q-utils.server.ts
+++ b/app/features/sendouq/q-utils.server.ts
@@ -2,7 +2,6 @@ import { TIERS } from "~/features/mmr/mmr-constants";
 import * as SkillRepository from "~/features/mmr/SkillRepository.server";
 import type { TieredSkill } from "~/features/mmr/tiered.server";
 
-/** Error class for SendouQ (expected) errors */
 export class SendouQError extends Error {
 	constructor(message: string) {
 		super(message);
diff --git a/app/features/sendouq/routes/q.looking.tsx b/app/features/sendouq/routes/q.looking.tsx
index bac7af12c..e41b97f3e 100644
--- a/app/features/sendouq/routes/q.looking.tsx
+++ b/app/features/sendouq/routes/q.looking.tsx
@@ -87,11 +87,9 @@ function QLookingPage() {
 	const data = useLoaderData<typeof loader>();
 	const [joining] = useSearchParam(qLookingSearchParams, "joining");
 
-	// Pool-shape changes (a group joining/leaving, a morph, a match starting) are
-	// broadcast to this shared room so every looking client revalidates.
+	// pool-shape changes (a group joining/leaving, a morph, a match starting)
 	useTopicRevalidation(SENDOUQ_LOOKING_CHANNEL);
-	// Group-specific updates (e.g. a received like) are pushed to the group's own
-	// dedicated topic.
+	// group-specific updates (e.g. a received like)
 	useTopicRevalidation(
 		data.ownGroup ? sqGroupChannel(data.ownGroup.id) : "",
 		Boolean(data.ownGroup),
@@ -487,11 +485,9 @@ function Groups() {
 }
 
 /**
- * Floats groups a teammate suggested to the very top, then groups the viewer has
- * a positive private note on up and groups with a negative note down, while
- * preserving the server's tier/activity ordering within each bucket and keeping
- * full (censored) groups last. The note sentiment is read from the already-loaded
- * `userCards` data so the server does not need to attach notes to group members.
+ * Floats teammate-suggested groups to the top, then positive private note groups up and negative
+ * ones down, keeping the server's order within each bucket and full (censored) groups last. Note
+ * sentiment comes from the already-loaded `userCards`.
  */
 function sortGroups<T extends { id: number; members?: { id: number }[] }>(
 	groups: T[],
diff --git a/app/features/sendouq/tests/season-clock.ts b/app/features/sendouq/tests/season-clock.ts
index c545a50aa..ae4976242 100644
--- a/app/features/sendouq/tests/season-clock.ts
+++ b/app/features/sendouq/tests/season-clock.ts
@@ -19,11 +19,7 @@ const insideASeason = new Date(
 	),
 );
 
-/**
- * Pins the suite's clock inside a season, for the tests whose subject only happens
- * while one is running. Seasons are a fixed list, so between the last one ending and
- * the next one being added every such test would otherwise fail.
- */
+/** Pins the suite's clock inside a season; seasons are a fixed list, so between the last ending and the next being added such tests would otherwise fail. */
 export function pinClockInsideSeason() {
 	beforeAll(() => {
 		vi.useFakeTimers({ toFake: ["Date"] });
diff --git a/app/features/settings/actions/settings.server.ts b/app/features/settings/actions/settings.server.ts
index 2fcf0fb95..55e7834c1 100644
--- a/app/features/settings/actions/settings.server.ts
+++ b/app/features/settings/actions/settings.server.ts
@@ -77,8 +77,7 @@ export const action = async ({ request }: ActionFunctionArgs) => {
 					noScreen: toDBBoolean(data.noScreen),
 				});
 
-			// Challenges are made based on the modes/preferences shown at that
-			// moment, so changing them must undo pending requests to/from the group.
+			// challenges are based on the preferences shown at the time, so changing them undoes pending ones
 			if (mapModePreferencesChanged || noScreenChanged) {
 				await cancelActiveGroupLikes(user.id);
 			}
diff --git a/app/features/settings/components/ModeMapPoolPicker.tsx b/app/features/settings/components/ModeMapPoolPicker.tsx
index 1b24dd886..afe50c2dc 100644
--- a/app/features/settings/components/ModeMapPoolPicker.tsx
+++ b/app/features/settings/components/ModeMapPoolPicker.tsx
@@ -29,7 +29,6 @@ export function ModeMapPoolPicker({
 	/** When provided, the divider becomes a tab switcher between these modes. */
 	modeTabs?: ModeShort[];
 	onModeChange?: (mode: ModeShort) => void;
-	/** When true, stages can't be picked or removed (view-only). */
 	disabled?: boolean;
 }) {
 	const [wigglingStageId, setWigglingStageId] = React.useState<StageId | null>(
@@ -46,13 +45,11 @@ export function ModeMapPoolPicker({
 	};
 
 	const handleUnpickedStageClick = (stageId: StageId) => {
-		// is there space left?
 		if (stages[amountToPick - 1] !== null) {
 			setWigglingStageId(stageId);
 			return;
 		}
 
-		// was it already picked?
 		if (pool.includes(stageId)) {
 			return;
 		}
diff --git a/app/features/settings/match-profile-schemas.ts b/app/features/settings/match-profile-schemas.ts
index 46e314012..f46f22232 100644
--- a/app/features/settings/match-profile-schemas.ts
+++ b/app/features/settings/match-profile-schemas.ts
@@ -35,9 +35,7 @@ export const mapModePreferencesValueSchema = v.pipe(
 			}),
 		),
 	}),
-	// Pools for avoided modes are kept in the client form state so they can be
-	// restored if the user later un-avoids the mode, but they must not be
-	// persisted as active pools. Strip them out before the value reaches the action.
+	// avoided modes' pools stay in client state (restorable on un-avoid) but must not persist
 	v.transform((val) => ({
 		...val,
 		pool: val.pool.filter((pool) => {
diff --git a/app/features/sidebar/core/StreamRanking.ts b/app/features/sidebar/core/StreamRanking.ts
index e866e74a2..1d872b91c 100644
--- a/app/features/sidebar/core/StreamRanking.ts
+++ b/app/features/sidebar/core/StreamRanking.ts
@@ -4,10 +4,7 @@ import type { TournamentTierNumber } from "~/features/tournament/core/tiering";
 
 type RankedStream = { stream: SidebarStream; score: number };
 
-/**
- * Score for admin-curated external streams. Below every other source's minimum (0) so they sort
- * to the top of the ranking, reserving the first sidebar slots.
- */
+/** Below every other source's minimum (0) so external streams take the first sidebar slots. */
 export const EXTERNAL_STREAM_SCORE = -1;
 
 export function rank(
diff --git a/app/features/sidebar/core/sidebar.server.ts b/app/features/sidebar/core/sidebar.server.ts
index 61ccee313..32d579e1e 100644
--- a/app/features/sidebar/core/sidebar.server.ts
+++ b/app/features/sidebar/core/sidebar.server.ts
@@ -155,10 +155,7 @@ export async function resolveSidebarData(user: AuthenticatedUser | undefined) {
 	};
 }
 
-/**
- * Whether to prompt the user to report next week: they are on its last day, it
- * is still empty, and they have not waved the prompt away for this week.
- */
+/** Prompt to report next week: on its last day, still empty, and not dismissed this week. */
 async function showScheduleNudge(user: AuthenticatedUser | undefined) {
 	if (!user) return false;
 
@@ -461,7 +458,7 @@ export function tournamentToSidebarEvent(
 
 const TEAM_EVENT_WINDOW_DAYS = 14;
 
-/** Team events shown on the sidebar and the personal calendar page: ongoing ones and those starting within the next two weeks. */
+/** Ongoing team events and those starting within two weeks. */
 export function findUpcomingTeamEvents(userId: number) {
 	const now = new Date();
 
diff --git a/app/features/team/TeamRepository.server.ts b/app/features/team/TeamRepository.server.ts
index 410d9ce36..9849e35fb 100644
--- a/app/features/team/TeamRepository.server.ts
+++ b/app/features/team/TeamRepository.server.ts
@@ -112,9 +112,8 @@ export async function findByCustomUrl(
 		includeMapModePreferences = false,
 	} = {},
 ) {
-	// join the unvalidated table (instead of the validated-only `UserSubmittedImage` view) so the
-	// edit page can preview images still pending moderation; for everyone else the url is gated on
-	// `validatedAt` so pending images stay hidden
+	// joins the unvalidated table so the edit page can preview images pending moderation;
+	// for everyone else the url is gated on `validatedAt`
 	const row = await db
 		.selectFrom("Team")
 		.leftJoin(
@@ -218,9 +217,7 @@ export function findResultPlacementsById(teamId: number) {
 		.execute();
 }
 
-/**
- * Retrieves tournament results for a given team by its ID.
- */
+/** Tournament results of the team. */
 export async function findResultsById(teamId: number) {
 	const rows = await db
 		.with("results", (db) =>
@@ -314,9 +311,7 @@ export async function findResultsById(teamId: number) {
 	});
 }
 
-// reads AllTeamMember instead of the TeamMemberWithSecondary view because the
-// view filters out members who have left, and past members are exactly what
-// subsOfResult needs to tell substitutes apart from since-departed roster members
+// AllTeamMember rather than the TeamMemberWithSecondary view: subsOfResult needs past members too
 function allMembersById(teamId: number) {
 	return db
 		.selectFrom("AllTeamMember")
@@ -409,8 +404,7 @@ export async function update({
 			.where("id", "=", id)
 			.executeTakeFirst();
 
-		// images that got removed or replaced are no longer referenced by anything,
-		// so their submitted image rows are cleaned up
+		// removed or replaced images' submitted image rows are cleaned up
 		const orphanedImageIds: number[] = [];
 		if (current?.avatarImgId && current.avatarImgId !== avatarImgId) {
 			orphanedImageIds.push(current.avatarImgId);
@@ -459,7 +453,7 @@ export async function updateCustomTheme({
 		.execute();
 }
 
-/** Updates the team's SendouQ map/mode preferences, or clears them when passed `null`. Keeps existing map pools of modes missing from the new value. */
+/** Sets (or clears with `null`) SendouQ map/mode preferences; map pools of modes missing from the new value are kept. */
 export async function updateMapModePreferences({
 	id,
 	mapModePreferences,
@@ -532,7 +526,7 @@ export function deleteById(teamId: number) {
 			.where("teamId", "=", teamId)
 			.execute();
 
-		// switch main team to another if they at least one secondary team
+		// switch main team to a secondary team if they have one
 		for (const member of members) {
 			const currentTeams = await findAllByMemberUserId(member.userId, trx);
 
@@ -635,10 +629,7 @@ export function handleMemberLeaving({
 		.execute((trx) => memberLeave(trx, { userId, teamId, newOwnerUserId }));
 }
 
-/**
- * Applies a roster edit in a single transaction: updates each kept member's role
- * & editor status and removes (kicks) the members in `kickedUserIds`.
- */
+/** In one transaction: updates kept members' role & editor status and kicks `kickedUserIds`. */
 export function updateRoster({
 	teamId,
 	members,
diff --git a/app/features/team/routes/t.$customUrl.tsx b/app/features/team/routes/t.$customUrl.tsx
index b2683ef22..fc7e34a8d 100644
--- a/app/features/team/routes/t.$customUrl.tsx
+++ b/app/features/team/routes/t.$customUrl.tsx
@@ -56,8 +56,7 @@ export const handle: SendouRouteHandle = {
 };
 
 export default function TeamPage() {
-	// breakout container so the schedule tab's table can size against the full
-	// content area; the wrapper keeps every page at the normal width
+	// breakout container so the schedule tab's table can use the full content area
 	return (
 		<Main breakoutContainer>
 			<div className={clsx(containerClassName("normal"), "stack sm")}>
diff --git a/app/features/team/team-constants.ts b/app/features/team/team-constants.ts
index f5cd2eca8..d24e80138 100644
--- a/app/features/team/team-constants.ts
+++ b/app/features/team/team-constants.ts
@@ -29,7 +29,7 @@ export type MemberRole = (typeof TEAM_MEMBER_ROLES)[number];
 /** Classifies how a team member's `customRole` should be treated. */
 export type MemberRoleType = "PLAYER" | "OTHER";
 
-/** Roles that are not part of a team's active competitive lineup. Excluded when sourcing a roster (e.g. prefilling tournament registration or a scrim post). */
+/** Not part of the competitive lineup; excluded when sourcing a roster (e.g. tournament registration). */
 export const NON_PLAYER_TEAM_ROLES: readonly (typeof TEAM_MEMBER_ROLES)[number][] =
 	["CHEERLEADER", "COACH", "SUB"];
 
diff --git a/app/features/team/team-utils.ts b/app/features/team/team-utils.ts
index b99f1be32..541a0778a 100644
--- a/app/features/team/team-utils.ts
+++ b/app/features/team/team-utils.ts
@@ -42,7 +42,7 @@ export function canAddCustomizedColors(team: {
 	);
 }
 
-/** Returns the user who will become the new owner after old one leaves */
+/** Who becomes owner after the current one leaves. */
 export function resolveNewOwner(
 	members: Array<{
 		id: number;
@@ -65,9 +65,8 @@ export function resolveNewOwner(
 }
 
 /**
- * Resolves how a team member's role should be classified. For custom roles the explicit
- * `roleType` is authoritative; for predefined roles it is derived from {@link NON_PLAYER_TEAM_ROLES}.
- * Returns `null` when the member has no role at all (treated as a player by callers).
+ * Custom roles use their explicit `roleType`, predefined ones derive from {@link NON_PLAYER_TEAM_ROLES}.
+ * `null` without a role (callers treat as a player).
  */
 export function getMemberRoleType(member: {
 	role: MemberRole | null;
@@ -78,14 +77,7 @@ export function getMemberRoleType(member: {
 	return NON_PLAYER_TEAM_ROLES.includes(member.role) ? "OTHER" : "PLAYER";
 }
 
-/**
- * Returns a list of participant IDs who are considered "substitutes" for a given tournament result,
- * based on the team's member history and the result's participants.
- *
- * A participant is considered a substitute if both:
- * - They are not a current member (i.e., their `leftAt` is set).
- * - They are not a past member who was part of the team during the result's start time.
- */
+/** Participants of the result who were neither a current member nor a member at the time of the result. */
 export function subsOfResult<T extends { id: number }>(
 	result: { participants: Array<T>; startsAt: number },
 	members: Array<Pick<Tables["TeamMember"], "userId" | "createdAt" | "leftAt">>,
diff --git a/app/features/theme/theme-constants.ts b/app/features/theme/theme-constants.ts
index 097cb3efa..31548c359 100644
--- a/app/features/theme/theme-constants.ts
+++ b/app/features/theme/theme-constants.ts
@@ -35,7 +35,7 @@ export const CUSTOM_THEME_VARS = [
 
 export type CustomThemeVar = (typeof CUSTOM_THEME_VARS)[number];
 
-/** Subset of {@link CUSTOM_THEME_VARS} the patron chip in the footer resolves its background and text color from. */
+/** Subset of {@link CUSTOM_THEME_VARS} the footer's patron chip resolves its colors from. */
 export const PATRON_CHIP_THEME_VARS = [
 	"--_base-h",
 	"--_base-c-2",
diff --git a/app/features/tier-list-maker/components/TierListGraphic.module.css b/app/features/tier-list-maker/components/TierListGraphic.module.css
index 6888890a7..b71af974f 100644
--- a/app/features/tier-list-maker/components/TierListGraphic.module.css
+++ b/app/features/tier-list-maker/components/TierListGraphic.module.css
@@ -14,7 +14,7 @@
 	gap: var(--s-1-5);
 }
 
-/* the author credit belongs visually to the title above it, counteract the container gap */
+/* the author credit belongs to the title above it */
 .title + .author {
 	margin-top: calc(-1 * var(--s-3));
 }
diff --git a/app/features/tier-list-maker/hooks/useTierList.ts b/app/features/tier-list-maker/hooks/useTierList.ts
index 48b20780a..b62c4e09c 100644
--- a/app/features/tier-list-maker/hooks/useTierList.ts
+++ b/app/features/tier-list-maker/hooks/useTierList.ts
@@ -134,8 +134,7 @@ export function useTierList() {
 				? findContainer(overItem)
 				: null;
 
-		// Same-container reordering is handled in handleDragEnd. Doing it here
-		// would create a render → dragOver ping-pong loop with arrayMove.
+		// same-container reordering is in handleDragEnd; here it would ping-pong render → dragOver
 		if (!overContainer || activeContainer === overContainer) {
 			return;
 		}
@@ -482,11 +481,7 @@ export function useTierList() {
 	};
 }
 
-/**
- * The tier list state itself. `setTiers` only updates React state (drag-over
- * fires on every pointer move); `persistTiersStateToParams` writes the state
- * to the URL and is called when a drag or tier edit settles.
- */
+/** `setTiers` only touches React state (drag-over fires per pointer move); `persistTiersStateToParams` writes the URL. */
 function useSearchParamTiersState() {
 	const [stateParam, setStateParam] = useSearchParam(
 		tierListMakerSearchParams,
diff --git a/app/features/tier-list-maker/tier-list-maker-constants.ts b/app/features/tier-list-maker/tier-list-maker-constants.ts
index dc15c4a79..d1b703690 100644
--- a/app/features/tier-list-maker/tier-list-maker-constants.ts
+++ b/app/features/tier-list-maker/tier-list-maker-constants.ts
@@ -2,7 +2,7 @@ import type { TierListMakerTier } from "./tier-list-maker-schemas";
 
 export const TIER_NAME_MAX_LENGTH = 50;
 
-/** Search params that hold the tier list itself, shared by the maker page and the links pointing back to it */
+/** Params holding the tier list itself, shared by the maker page and links back to it */
 export const TIER_LIST_SEARCH_PARAM_NAMES = {
 	STATE: "state",
 	TITLE: "title",
diff --git a/app/features/tier-list-maker/tier-list-maker-utils.ts b/app/features/tier-list-maker/tier-list-maker-utils.ts
index 1d12f5218..e832c1d86 100644
--- a/app/features/tier-list-maker/tier-list-maker-utils.ts
+++ b/app/features/tier-list-maker/tier-list-maker-utils.ts
@@ -10,10 +10,7 @@ export function tierListItemId(item: TierListItem) {
 	return `${item.type}:${item.id}${item.nth ? `:${item.nth}` : ""}`;
 }
 
-/**
- * Path to the tier list maker page that opens the given tier list as it was made,
- * used by the exported image's QR code.
- */
+/** Path that reopens the given tier list, used by the exported image's QR code. */
 export function tierListMakerPathWithState({
 	state,
 	title,
@@ -30,11 +27,7 @@ export function tierListMakerPathWithState({
 	});
 }
 
-/**
- * Returns a new tier list state with the given item appended to the end of the
- * specified tier. Used by the "click" placement mode. If the tier does not
- * exist the state is returned unchanged.
- */
+/** State with the item appended to the tier; unchanged if the tier does not exist. */
 export function addItemToTier(
 	state: TierListState,
 	tierId: string,
@@ -54,11 +47,7 @@ export function addItemToTier(
 	};
 }
 
-/**
- * Finds the next nth value for a duplicate item in the tier list.
- * Searches through all tiers to find the maximum nth value for items
- * with the same id and type, then returns max + 1.
- */
+/** Next `nth` for a duplicate item: max across all tiers of the same id and type, plus one. */
 export function getNextNthForItem(
 	item: TierListItem,
 	tiers: TierListState,
@@ -77,10 +66,7 @@ export function getNextNthForItem(
 	);
 }
 
-/**
- * Resolves the font size for a tier label so that longer tier names
- * shrink to fit inside the fixed-width label.
- */
+/** Longer tier names shrink to fit the fixed-width label. */
 export function tierNameFontSize(name: string) {
 	const length = name.length;
 	for (const breakpoint of TIER_NAME_FONT_SIZE_BREAKPOINTS) {
diff --git a/app/features/timezone/timezone-context.server.ts b/app/features/timezone/timezone-context.server.ts
index c4bc8bd17..0a1313fe0 100644
--- a/app/features/timezone/timezone-context.server.ts
+++ b/app/features/timezone/timezone-context.server.ts
@@ -7,10 +7,7 @@ interface ViewerTimezoneContext {
 export const viewerTimezoneAsyncLocalStorage =
 	new AsyncLocalStorage<ViewerTimezoneContext>();
 
-/**
- * The viewer's IANA timezone for the current request. `null` when the browser has
- * not reported it yet, which is the case for a device's very first document request.
- */
+/** `null` until the browser has reported it, i.e. on a device's very first document request. */
 export function getViewerTimezone(): string | null {
 	return viewerTimezoneAsyncLocalStorage.getStore()?.timezone ?? null;
 }
diff --git a/app/features/timezone/timezone-cookie.ts b/app/features/timezone/timezone-cookie.ts
index 6ed4d789b..c09a57580 100644
--- a/app/features/timezone/timezone-cookie.ts
+++ b/app/features/timezone/timezone-cookie.ts
@@ -17,11 +17,7 @@ const ianaTimezone = v.pipe(
 	}),
 );
 
-/**
- * Stores the browser's IANA timezone in a cookie so that the server can read it
- * while rendering. Neither a request header nor a client hint carries the
- * timezone, so it has to be written client-side before the server can know it.
- */
+/** No request header or client hint carries the timezone, so the browser writes it to a cookie for the server. */
 export function writeViewerTimezoneCookie() {
 	try {
 		const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -51,10 +47,7 @@ export function writeViewerTimezoneCookie() {
 	}
 }
 
-/**
- * The viewer's IANA timezone as written by {@link writeViewerTimezoneCookie}.
- * `null` when the cookie is missing or holds something that is not a timezone.
- */
+/** Timezone written by {@link writeViewerTimezoneCookie}; `null` when missing or not a timezone. */
 export function viewerTimezoneFromCookieHeader(
 	header: string | null,
 ): string | null {
diff --git a/app/features/timezone/timezone-middleware.server.ts b/app/features/timezone/timezone-middleware.server.ts
index 254fa3827..903168959 100644
--- a/app/features/timezone/timezone-middleware.server.ts
+++ b/app/features/timezone/timezone-middleware.server.ts
@@ -2,10 +2,7 @@ import type { MiddlewareFunction } from "react-router";
 import { viewerTimezoneAsyncLocalStorage } from "./timezone-context.server";
 import { viewerTimezoneFromCookieHeader } from "./timezone-cookie";
 
-/**
- * Resolves the viewer's timezone from their cookie and makes it available to
- * loaders via `getViewerTimezone` for the duration of the request.
- */
+/** Reads the timezone cookie into request context for `getViewerTimezone`. */
 export const timezoneMiddleware: MiddlewareFunction<Response> = (
 	{ request },
 	next,
diff --git a/app/features/top-search/XRankPlacementRepository.server.ts b/app/features/top-search/XRankPlacementRepository.server.ts
index c1a1b29be..9c75bfaab 100644
--- a/app/features/top-search/XRankPlacementRepository.server.ts
+++ b/app/features/top-search/XRankPlacementRepository.server.ts
@@ -12,18 +12,11 @@ export type XRankPlacementInsertArgs = Omit<
 > & {
 	/** In-game id of the player the placement belongs to. */
 	playerSplId: string;
-	/**
-	 * Site user whose results these are, for a source that already knows the pairing.
-	 * A player claiming their own results afterwards goes through
-	 * `AdminRepository.linkUserAndPlayer`, which also refreshes what the link derives.
-	 */
+	/** For sources that already know the pairing; claiming later goes through `AdminRepository.linkUserAndPlayer`. */
 	playerUserId?: number;
 };
 
-/**
- * Adds the given placements, creating a `SplatoonPlayer` row for every in-game id
- * not seen before. Returns the placement ids in insertion order.
- */
+/** Inserts placements, creating `SplatoonPlayer` rows for new in-game ids. Returns ids in insertion order. */
 export function insertMany(placements: XRankPlacementInsertArgs[]) {
 	return db.transaction().execute(async (trx) => {
 		const ids: number[] = [];
@@ -59,7 +52,7 @@ export function insertMany(placements: XRankPlacementInsertArgs[]) {
 	});
 }
 
-/** Removes every placement of the given month, before its results are read in anew. */
+/** Removes every placement of the given month. */
 export function deleteAllByMonthYear(
 	args: Pick<Tables["XRankPlacement"], "month" | "year">,
 ) {
@@ -89,10 +82,7 @@ export async function isPlayerLinkedByUserId(userId: number): Promise<boolean> {
 	return Boolean(player);
 }
 
-/**
- * The user's verified peak XP, read from their linked player's denormalized `SplatoonPlayer.peakXp`
- * column (see {@link refreshAllPeakXp}). `null` when they have no linked player or no placements.
- */
+/** From the linked player's denormalized `SplatoonPlayer.peakXp` (see {@link refreshAllPeakXp}); `null` without one. */
 export async function findPeakVerifiedXpByUserId(
 	userId: Tables["User"]["id"],
 ): Promise<number | null> {
@@ -225,8 +215,7 @@ export async function refreshAllPeakXp() {
 	await db
 		.updateTable("SplatoonPlayer")
 		.set({
-			// denormalized PeakXP json: overall + per-division peaks
-			// (region WEST = Tentatek, otherwise Takoroka). null when no placements.
+			// denormalized PeakXP json: overall + per-division peaks (WEST = Tentatek, else Takoroka)
 			peakXp: sql<string | null>`(
 				select iif(
 					max("XRankPlacement"."power") is null,
diff --git a/app/features/top-search/routes/xsearch.tsx b/app/features/top-search/routes/xsearch.tsx
index ff8ca3d2f..602b36865 100644
--- a/app/features/top-search/routes/xsearch.tsx
+++ b/app/features/top-search/routes/xsearch.tsx
@@ -101,9 +101,8 @@ function SeasonMonthsSelect() {
 }
 
 /**
- * Rendered as its own component (rather than formatted where the select's items are built)
- * because React Aria snapshots item content when it builds the collection, which happens
- * before hydration and thus before the locale aware formatting is available.
+ * Its own component because React Aria snapshots item content when building the collection,
+ * before hydration and thus before locale aware formatting is available.
  */
 function MonthYearSpan({ monthYear }: { monthYear: MonthYear }) {
 	const span = monthYearToSpan(monthYear);
diff --git a/app/features/tournament-admin/actions/to.$id.admin.index.server.ts b/app/features/tournament-admin/actions/to.$id.admin.index.server.ts
index 2a701830b..e0c7b4f10 100644
--- a/app/features/tournament-admin/actions/to.$id.admin.index.server.ts
+++ b/app/features/tournament-admin/actions/to.$id.admin.index.server.ts
@@ -147,10 +147,8 @@ export const action: ActionFunction = async ({ request, params }) => {
 };
 
 /**
- * Drops a single team out: assigns a random active roster for teams with subs,
- * ends their in-progress matches and marks the team dropped out. Returns the ids
- * of matches that were ended so the caller can broadcast a single batch of chat
- * messages.
+ * Drops a team out: random active roster for teams with subs, ends their in-progress matches,
+ * marks them dropped. Returns the ended match ids for one batch of chat messages.
  */
 async function dropTeamOut({
 	tournament,
@@ -162,8 +160,7 @@ async function dropTeamOut({
 	const droppingTeam = tournament.teamById(teamId);
 	invariant(droppingTeam, "Invalid team id");
 
-	// Set active roster only for teams with subs (can't infer which players played)
-	// Teams without subs have their roster trivially inferred in summarizer
+	// only teams with subs need an active roster set, the summarizer infers the rest trivially
 	const hasSubs =
 		droppingTeam.memberUserIds.length > tournament.minMembersPerTeam;
 	if (hasSubs && !droppingTeam.activeRosterUserIds) {
diff --git a/app/features/tournament-admin/actions/to.$id.admin.registration.server.ts b/app/features/tournament-admin/actions/to.$id.admin.registration.server.ts
index c0b6ce616..4e54f0ca8 100644
--- a/app/features/tournament-admin/actions/to.$id.admin.registration.server.ts
+++ b/app/features/tournament-admin/actions/to.$id.admin.registration.server.ts
@@ -25,11 +25,7 @@ import { adminRegistrationFormSchemaServer } from "../tournament-admin-registrat
 export const action: ActionFunction = (args) =>
 	upsertRegistrationAction(args, { allowTournamentNameUpdates: true });
 
-/**
- * The registration upsert itself, shared with the public API's version of this
- * endpoint. That one passes `allowTournamentNameUpdates: false`: tournament names
- * are the admin form's business and the API can only read them.
- */
+/** Shared with the public API, which passes `allowTournamentNameUpdates: false` as it may only read tournament names. */
 export const upsertRegistrationAction = async (
 	{ request, params }: ActionFunctionArgs,
 	{ allowTournamentNameUpdates }: { allowTournamentNameUpdates: boolean },
@@ -93,8 +89,7 @@ export const upsertRegistrationAction = async (
 		return [{ userId: member.userId, inGameName: member.inGameName }];
 	});
 
-	// only a submission from someone allowed to edit tournament names says anything
-	// about them, everyone else leaves the names the players have untouched
+	// only a submission from someone allowed to edit tournament names says anything about them
 	const tournamentNameUpdates =
 		allowTournamentNameUpdates && tournament.canEditTournamentNames(user)
 			? submittedMembers.map((member) => ({
@@ -103,8 +98,7 @@ export const upsertRegistrationAction = async (
 				}))
 			: [];
 
-	// the map pool field is only shown while it can still be changed, so a submission
-	// from any other state says nothing about the pool the team has
+	// the map pool field is only shown while it can still be changed, other states say nothing about it
 	const mapPool =
 		tournament.teamsPrePickMaps && !tournament.hasStarted
 			? new MapPool(data.mapPool)
diff --git a/app/features/tournament-admin/components/ExportDialog.test.ts b/app/features/tournament-admin/components/ExportDialog.test.ts
index 3f3223872..aaf9b56ec 100644
--- a/app/features/tournament-admin/components/ExportDialog.test.ts
+++ b/app/features/tournament-admin/components/ExportDialog.test.ts
@@ -25,17 +25,14 @@ function checkIns(
 	})) as unknown as TournamentTeamFull["checkIns"];
 }
 
-// Event-level check-in is stored with bracketIdx === null (see CHECK_IN action:
-// `bracketIdx: bracket.sources ? data.bracketIdx : undefined`). A team checked in
-// to the tournament therefore has a single null-bracket, non-checkout row.
+// event-level check-in is stored with bracketIdx === null, so a team checked in to the
+// tournament has a single null-bracket, non-checkout row
 const checkedInAtEventLevel = team(1, checkIns([{ bracketIdx: null }]));
 
 describe("scopedAndSortedTeams() check-in filtering", () => {
-	// A bracket without its own check-in (the starting bracket / any bracket where
-	// requiresCheckIn is false) is exported against the event-level check-in. This is
-	// the user-reported case: selecting such a bracket previously matched bracketIdx
-	// against the (null) event rows, so "Checked in" was empty and "Not checked in"
-	// listed the teams that were actually checked in.
+	// a bracket without its own check-in (starting bracket / requiresCheckIn false) is exported
+	// against the event-level check-in; regression: matching bracketIdx against the null event
+	// rows emptied "Checked in" and listed the checked in teams under "Not checked in"
 	describe("bracket without its own check-in", () => {
 		const bracketParticipantIds = new Set([checkedInAtEventLevel.id]);
 
@@ -66,8 +63,7 @@ describe("scopedAndSortedTeams() check-in filtering", () => {
 		});
 	});
 
-	// A bracket with its own check-in (requiresCheckIn) is exported against its own
-	// per-bracket rows, so an event-level check-in alone is not enough.
+	// a bracket with its own check-in is exported against its per-bracket rows, event-level alone is not enough
 	describe("bracket with its own check-in", () => {
 		const checkedIntoBracket = team(
 			1,
diff --git a/app/features/tournament-admin/components/ExportDialog.tsx b/app/features/tournament-admin/components/ExportDialog.tsx
index f7073e65e..b98baecab 100644
--- a/app/features/tournament-admin/components/ExportDialog.tsx
+++ b/app/features/tournament-admin/components/ExportDialog.tsx
@@ -118,9 +118,8 @@ export function ExportDialog({
 			sort,
 			bracketIdx,
 			bracketRequiresOwnCheckIn,
-			// A team belongs to a bracket whether or not it has checked in: the
-			// checked-in teams populate the matches, the rest are pending check-in.
-			// Both are scoped out of the export when they don't belong to the bracket.
+			// a team belongs to a bracket whether or not it has checked in (the rest are pending check-in);
+			// both are scoped out of the export when they don't belong to it
 			bracketParticipantIds: selectedBracket
 				? new Set([
 						...selectedBracket.participantTournamentTeamIds,
@@ -438,10 +437,8 @@ function buildContent({
 		return CSV.serialize([header, ...rows]);
 	}
 
-	// list: members grouped under each team (omitted when no member fields chosen,
-	// so a team-name-only export is just a plain list of names). Members are only
-	// indented under a team header when team fields are present — without them the
-	// export is a tight flat list (e.g. captains-only + Discord mention).
+	// list: members grouped under each team; without member fields a plain list of team names, without
+	// team fields a tight flat list of members (e.g. captains-only + Discord mention)
 	const hasMemberFields = memberFields.length > 0;
 	const groupByTeam = teamFields.length > 0;
 
diff --git a/app/features/tournament-admin/routes/to.$id.admin.brackets.tsx b/app/features/tournament-admin/routes/to.$id.admin.brackets.tsx
index a21bc02dd..45b4c7f5c 100644
--- a/app/features/tournament-admin/routes/to.$id.admin.brackets.tsx
+++ b/app/features/tournament-admin/routes/to.$id.admin.brackets.tsx
@@ -151,9 +151,8 @@ function BracketProgressionEdit() {
 					values.progression,
 				);
 
-				// started brackets can't be edited in the form, so pass their stored
-				// version through untouched — re-deriving their settings from form
-				// values could register them as changed and fail the server's guard
+				// started brackets pass through untouched: re-deriving their settings from form values
+				// could register them as changed and fail the server's guard
 				const originalInputBrackets =
 					Progression.validatedBracketsToInputFormat(
 						tournament.ctx.settings.bracketProgression,
diff --git a/app/features/tournament-admin/routes/to.$id.admin.import-teams.ts b/app/features/tournament-admin/routes/to.$id.admin.import-teams.ts
index daf86f0b3..c5ebd91af 100644
--- a/app/features/tournament-admin/routes/to.$id.admin.import-teams.ts
+++ b/app/features/tournament-admin/routes/to.$id.admin.import-teams.ts
@@ -11,10 +11,7 @@ import { tournamentImportTeamsSearchParams } from "../tournament-admin-search-pa
 
 export type ImportTeamsLoaderData = SerializeFrom<typeof loader>;
 
-/**
- * Returns the teams (with rosters) of another tournament so an organizer can
- * import one into the registration form they are filling out.
- */
+/** Teams (with rosters) of another tournament for importing into the registration form. */
 export const loader = async ({ request }: LoaderFunctionArgs) => {
 	const user = requireUser();
 
diff --git a/app/features/tournament-admin/routes/to.$id.admin.index.tsx b/app/features/tournament-admin/routes/to.$id.admin.index.tsx
index d2c00cb67..4b104bf7e 100644
--- a/app/features/tournament-admin/routes/to.$id.admin.index.tsx
+++ b/app/features/tournament-admin/routes/to.$id.admin.index.tsx
@@ -1,10 +1,6 @@
 import { Outlet, useOutletContext } from "react-router";
 
-/**
- * Layout shared by the admin teams table (index) and the registration editor.
- * Rendering them as sibling routes lets the editor take over the content area
- * in place of the table instead of opening as a modal on top of it.
- */
+/** Shared by the teams table (index) and the registration editor as sibling routes, so the editor replaces the table instead of a modal. */
 export default function TournamentAdminTeamsLayout() {
 	const outletContext = useOutletContext();
 
diff --git a/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.browser.test.tsx b/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.browser.test.tsx
index 908d061a6..18ff351f3 100644
--- a/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.browser.test.tsx
+++ b/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.browser.test.tsx
@@ -33,8 +33,7 @@ vi.mock("~/features/tournament/tournament-context", () => ({
 	useTournament: () => mockTournament,
 }));
 
-// Stub the server action re-exported by the route module so importing the route
-// in a browser test doesn't pull in the database-backed action code.
+// stubbed so importing the route in a browser test doesn't pull in the database-backed action
 vi.mock(
 	"~/features/tournament-admin/actions/to.$id.admin.registration.server",
 	() => ({ action: vi.fn() }),
@@ -65,7 +64,7 @@ describe("tournament admin registration - captain field", () => {
 	});
 
 	test("removing the captain's roster row does not leave a stale captain that fails validation", async () => {
-		// A linked/edited team whose captain (OWNER) is the first roster member.
+		// captain (OWNER) is the first roster member
 		mockLoaderData.team = {
 			id: 10,
 			name: "low ink buddies",
@@ -80,9 +79,8 @@ describe("tournament admin registration - captain field", () => {
 
 		const screen = await renderPage();
 
-		// Remove the captain's row (member #1). The Captain <select> is non-clearable
-		// so it now visually shows the remaining member ("Jolt") as selected, but the
-		// form's ownerId still points at the removed user (1) and nothing resyncs it.
+		// the non-clearable Captain <select> now shows the remaining member ("Jolt") as selected, but
+		// nothing resyncs the form's ownerId still pointing at the removed user (1)
 		const removeButtons = () =>
 			screen.container.querySelectorAll<HTMLButtonElement>(
 				'button[aria-label="Remove item"]',
@@ -92,9 +90,7 @@ describe("tournament admin registration - captain field", () => {
 
 		await screen.getByRole("button", { name: "Submit" }).click();
 
-		// The captain shown in the dropdown IS a current player, so submitting should
-		// not be blocked by "the captain must be one of the players": the form makes
-		// it to the server instead of stopping at client-side validation.
+		// the shown captain IS a current player, so "the captain must be one of the players" must not block the submit
 		await expect.poll(() => submitMock.mock.calls.length).toBe(1);
 		await expect
 			.element(screen.getByText(CAPTAIN_NOT_A_MEMBER_ERROR))
diff --git a/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.captain-label.browser.test.tsx b/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.captain-label.browser.test.tsx
index dde80ffdc..5f0b08929 100644
--- a/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.captain-label.browser.test.tsx
+++ b/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.captain-label.browser.test.tsx
@@ -79,16 +79,15 @@ describe("tournament admin registration - captain label", () => {
 	test("captain dropdown shows the searched player's name, not a generic placeholder", async () => {
 		const screen = await renderPage();
 
-		// Pick a player in member #1 via the user search.
 		await userEvent.click(screen.getByRole("button", { name: "Player" }));
 		await userEvent.type(
 			screen.getByTestId("user-search-input").element(),
 			GREY.name,
 		);
-		// Auto-retries until the debounced search resolves and the result appears.
+		// auto-retries until the debounced search resolves
 		await screen.getByTestId("user-search-item").click();
 
-		// The Captain <select> should label that player by name, not "Player 1".
+		// labelled by name, not "Player 1"
 		await expect
 			.poll(
 				() =>
diff --git a/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.tsx b/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.tsx
index 533e369bc..600147c8e 100644
--- a/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.tsx
+++ b/app/features/tournament-admin/routes/to.$id.admin.registration.$tid.tsx
@@ -168,8 +168,7 @@ function RegistrationFields({ team }: { team: TournamentTeamFull | null }) {
 			userId: member.userId,
 			inGameName: member.inGameName,
 			tournamentName: member.tournamentName,
-			// fresh key so the member rows remount and their user-search inputs
-			// re-resolve when importing a different team over a previous import
+			// fresh key so member rows remount and re-resolve their user search when importing over a previous import
 			_key: crypto.randomUUID(),
 		}));
 		importedValues.ownerId = owner ? String(owner.userId) : "";
@@ -188,9 +187,7 @@ function RegistrationFields({ team }: { team: TournamentTeamFull | null }) {
 			setValue(name, value);
 		}
 
-		// if the form was already submitted, recompute against the imported values
-		// so stale "required" errors don't linger on now-filled fields; before any
-		// submit there are no errors to surface yet
+		// after a submit, recompute against the imported values so stale "required" errors don't linger
 		if (hasSubmitted) {
 			revalidateAll({ ...values, ...importedValues });
 		}
@@ -206,9 +203,8 @@ function RegistrationFields({ team }: { team: TournamentTeamFull | null }) {
 			label: usernames[member.userId] ?? `${t("forms:labels.player")} ${i + 1}`,
 		}));
 
-	// the non-clearable Captain <select> always displays a member as selected, so
-	// keep ownerId in sync with it: default to the first member and reset when the
-	// current captain is no longer on the roster (e.g. their row was removed)
+	// the non-clearable Captain <select> always shows a member as selected, so keep ownerId in sync:
+	// default to the first member, reset when the current captain left the roster
 	const ownerOptionsKey = ownerOptions.map((option) => option.value).join(",");
 	React.useEffect(() => {
 		if (ownerOptions.length === 0) return;
@@ -227,8 +223,7 @@ function RegistrationFields({ team }: { team: TournamentTeamFull | null }) {
 			<FormField name="linkedTeam" />
 			{linkedTeam ? (
 				<FormField
-					// remount the search when a different team is imported so it picks up
-					// the new initialTeam instead of clearing its stale selection
+					// remount on import so the search picks up the new initialTeam instead of clearing
 					key={team?.team?.id ?? importedLinkedTeam?.id ?? "new"}
 					name="teamId"
 					options={
@@ -275,17 +270,14 @@ function RegistrationFields({ team }: { team: TournamentTeamFull | null }) {
 							name={`${itemName}.userId`}
 							options={
 								{
-									// capture the picked user's name so the Captain dropdown can
-									// label them instead of falling back to "Player N"
+									// the Captain dropdown labels by name instead of "Player N"
 									onUserSelected: (user) => {
 										if (!user) return;
 										setUsernames((prev) => ({ ...prev, [user.id]: user.name }));
-										// prefill the in-game name from the user's existing one
 										if (requireInGameNames && user.inGameName) {
 											setValue(`${itemName}.inGameName`, user.inGameName);
 										}
-										// the field is saved as is, so it has to show the name the
-										// user already has or saving would clear it
+										// saved as is, so it must show the user's current name or saving would clear it
 										if (canEditTournamentNames) {
 											setValue(
 												`${itemName}.tournamentName`,
@@ -330,8 +322,7 @@ function MapPoolField({
 	const { t } = useTranslation(["common"]);
 	const validationStatus = useCounterPickMapPoolValidationStatus(value);
 
-	// the pickers are a group of buttons rather than one control, so there is no
-	// input for the label to point at
+	// the pickers are a group of buttons, so there is no input for the label to point at
 	return (
 		<div className="stack sm">
 			<Label spaced={false}>{t("common:maps.mapPool")}</Label>
@@ -418,9 +409,8 @@ function ImportTeamFields({
 	const teams = fetcher.data?.teams ?? [];
 	teamsRef.current = teams;
 
-	// the non-clearable native select visually shows the first option, so keep the
-	// form value in sync with it: default to the first team and reset when the
-	// loaded set of teams changes (e.g. after picking a different tournament)
+	// the non-clearable native select shows the first option, so keep the form value in sync:
+	// default to the first team, reset when the loaded teams change
 	const teamIdsKey = teams.map((team) => team.id).join(",");
 	React.useEffect(() => {
 		if (teams.length === 0) return;
diff --git a/app/features/tournament-admin/routes/to.$id.admin.staff.tsx b/app/features/tournament-admin/routes/to.$id.admin.staff.tsx
index 669bf9e17..996d79a6e 100644
--- a/app/features/tournament-admin/routes/to.$id.admin.staff.tsx
+++ b/app/features/tournament-admin/routes/to.$id.admin.staff.tsx
@@ -133,10 +133,7 @@ const ORGANIZATION_STAFF_ROLES: ReadonlyArray<
 	Tables["TournamentOrganizationMember"]["role"]
 > = TOURNAMENT_ORGANIZATION_ROLES.filter((role) => role !== "MEMBER");
 
-/**
- * Users who already have staff permissions implicitly (the tournament author
- * and organization staff) shown for info only - they can't be edited or removed.
- */
+/** The author and organization staff, info only as their permissions are implicit. */
 function ImplicitStaffRows() {
 	const { t } = useTranslation(["tournament"]);
 	const tournament = useTournament();
diff --git a/app/features/tournament-admin/tournament-admin-registration-schemas.server.ts b/app/features/tournament-admin/tournament-admin-registration-schemas.server.ts
index 47f20d804..48a9df326 100644
--- a/app/features/tournament-admin/tournament-admin-registration-schemas.server.ts
+++ b/app/features/tournament-admin/tournament-admin-registration-schemas.server.ts
@@ -17,10 +17,8 @@ import {
 } from "./tournament-admin-registration-schemas";
 
 /**
- * Extends the client {@link adminRegistrationFormSchema} with server-only,
- * context-dependent validations that surface as field errors (rather than toasts):
- * unique team name, roster size limit, and per-member friend code / in-game name /
- * ban / already-on-another-team checks.
+ * {@link adminRegistrationFormSchema} plus server-only validations surfacing as field errors:
+ * unique name, roster size, per-member friend code / in-game name / ban / other-team checks.
  */
 export function adminRegistrationFormSchemaServer({
 	tournament,
@@ -56,8 +54,7 @@ export function adminRegistrationFormSchemaServer({
 				});
 			}
 
-			// the map pool is only written while it can still be changed, matching the
-			// form field's own visibility, so any other state says nothing about it
+			// the map pool is only written while it can still be changed, matching the field's visibility
 			if (tournament.teamsPrePickMaps && !tournament.hasStarted) {
 				const currentMapPool =
 					typeof data.tournamentTeamId === "number"
@@ -67,9 +64,8 @@ export function adminRegistrationFormSchemaServer({
 								])
 							).get(data.tournamentTeamId) ?? [])
 						: [];
-				// a pool valid when picked can stop being valid later (a map gets banned, the
-				// tie-breaker pool changes), so only a changed pool is held to being valid and
-				// an untouched one can't block unrelated edits to the team
+				// a pool can stop being valid after picking (map banned, tie-breaker pool changed), so only
+				// a changed pool is validated and an untouched one can't block unrelated edits
 				const mapPoolChanged =
 					MapPool.serialize(data.mapPool) !== MapPool.serialize(currentMapPool);
 
diff --git a/app/features/tournament-admin/tournament-admin-registration-schemas.ts b/app/features/tournament-admin/tournament-admin-registration-schemas.ts
index 059cb4355..50cb2d9cf 100644
--- a/app/features/tournament-admin/tournament-admin-registration-schemas.ts
+++ b/app/features/tournament-admin/tournament-admin-registration-schemas.ts
@@ -17,11 +17,7 @@ import {
 import { modeShort, stageId, superRefine } from "~/utils/schema";
 import { IN_GAME_NAME_MAX_LENGTH } from "../user-page/in-game-name";
 import { USER } from "../user-page/user-page-constants";
-/**
- * Roster size cap for organizer-managed registrations. The per-tournament
- * `maxMembersPerTeam` limit intentionally doesn't apply to organizers, so this
- * is a safety ceiling rather than a competitive constraint.
- */
+/** Safety ceiling for organizer-managed rosters; the tournament's `maxMembersPerTeam` intentionally doesn't apply to them. */
 export const ADMIN_REGISTRATION_MAX_MEMBERS = 12;
 
 const memberFieldset = fieldset({
@@ -31,11 +27,7 @@ const memberFieldset = fieldset({
 			label: "labels.inGameName",
 			maxLength: IN_GAME_NAME_MAX_LENGTH,
 		}),
-		/**
-		 * Only editable by members of an established organization
-		 * (`Tournament.canEditTournamentNames`), whose submission is authoritative:
-		 * `null` clears the name the player has. Ignored from everyone else.
-		 */
+		/** Authoritative (`null` clears) from members of an established organization (`Tournament.canEditTournamentNames`), ignored from others. */
 		tournamentName: textFieldOptional({
 			label: "labels.tournamentName",
 			bottomText: "bottomTexts.tournamentName",
@@ -107,12 +99,7 @@ export type AdminRegistrationFormValues = v.InferInput<
 	typeof adminRegistrationFormSchema
 >;
 
-/**
- * Modal form used to import an existing team's roster from another tournament
- * into the {@link adminRegistrationFormSchema} when adding a new team. Validated
- * client-side only — submitting prefills the registration form rather than
- * hitting the server.
- */
+/** Modal importing a roster from another tournament into {@link adminRegistrationFormSchema}. Client-side only, prefills the form. */
 export const importTeamFormSchema = v.pipe(
 	v.object({
 		sourceTournamentId: tournamentSearchOptional({
diff --git a/app/features/tournament-admin/tournament-admin-schemas.ts b/app/features/tournament-admin/tournament-admin-schemas.ts
index 16c0ae407..1d01da2f0 100644
--- a/app/features/tournament-admin/tournament-admin-schemas.ts
+++ b/app/features/tournament-admin/tournament-admin-schemas.ts
@@ -16,11 +16,7 @@ import {
 import { bracketIdx } from "../tournament-bracket/tournament-bracket-schemas";
 import { adminStaffFormSchema } from "./tournament-admin-staff-schemas";
 
-/**
- * Extends the client {@link adminStaffFormSchema} with a server-only,
- * context-dependent validation: the tournament author can't be added as staff
- * (they are always shown as an organizer for info only).
- */
+/** {@link adminStaffFormSchema} plus the server-only rule that the author (always shown as organizer) can't be added as staff. */
 export function adminStaffFormSchemaServer({
 	tournament,
 }: {
diff --git a/app/features/tournament-bracket/BracketRepository.server.ts b/app/features/tournament-bracket/BracketRepository.server.ts
index 5b3deae1c..13a575bab 100644
--- a/app/features/tournament-bracket/BracketRepository.server.ts
+++ b/app/features/tournament-bracket/BracketRepository.server.ts
@@ -19,16 +19,12 @@ import type {
 } from "./core/engine/types";
 
 const CHAT_ROOM_LIFESPAN_DAYS = 7;
-// a league round can be scheduled weeks out, and its rooms are all created when
-// the bracket is inserted (see insertBracket)
+// league rounds can be scheduled weeks out and all rooms are created on insertBracket
 const LEAGUE_CHAT_ROOM_LIFESPAN_DAYS = 30;
 
 /**
- * Loads the full BracketData for a tournament (all stages). Includes the
- * score/totalKos aggregation over TournamentMatchGameResult. Direct replacement
- * for the old manager.get.tournamentData(); also called from write actions
- * inside their transaction (propagation must be computed from fresh rows, not
- * the cached Tournament instance).
+ * Full BracketData of all stages, with score/totalKos aggregated over TournamentMatchGameResult.
+ * Also called inside write transactions: propagation needs fresh rows, not the cached Tournament.
  */
 export async function findByTournamentId(
 	tournamentId: number,
@@ -125,11 +121,7 @@ export async function findByTournamentId(
 	return { stage, group, round, match };
 }
 
-/**
- * Builds the opponent JSON with the freshly aggregated KO count: sets
- * `totalKos` to the SQL sum over the match's game results. Resolves to `null`
- * for BYEs (the column is `null`).
- */
+/** Opponent JSON with `totalKos` summed over the match's game results, `null` for BYEs. */
 function serializedOpponentWithKos(
 	column: "opponentOne" | "opponentTwo",
 ): RawBuilder<ParticipantResult | null> {
@@ -147,11 +139,7 @@ function serializedOpponentWithKos(
 	)`;
 }
 
-/**
- * Persists Engine.create output in one transaction. Inserts stage → groups →
- * rounds → matches, translating the engine's local ids to real row ids. The
- * stage number is assigned from the existing stages of the tournament.
- */
+/** Persists Engine.create output, translating local ids to row ids. Stage number follows the existing stages. */
 export function insertBracket(args: {
 	tournamentId: number;
 	name: string;
@@ -217,9 +205,8 @@ export function insertBracket(args: {
 
 		const statuses = matchStatuses(args.bracket);
 
-		// only matches that can already be played get a chat room; the rest get
-		// theirs as they start (see syncStartedAt). A league's rounds are
-		// independent, so every one of its matches is playable right away
+		// only playable matches get a chat room now, the rest as they start (see syncStartedAt).
+		// A league's rounds are independent so every match is playable right away
 		const startedMatches = args.bracket.match.filter(
 			(match) => statuses.get(match.id) === "STARTED",
 		);
@@ -256,12 +243,10 @@ export function insertBracket(args: {
 }
 
 /**
- * UPDATEs the opponents of the changed matches and keeps startedAt in sync with
- * the statuses that the new state implies. Called inside the caller's
- * transaction with the bracket data the operation was computed from.
+ * UPDATEs the changed matches' opponents and syncs startedAt with the implied statuses. Called inside
+ * the caller's transaction with the bracket data the operation was computed from.
  *
- * @returns ids of the chat rooms whose inactive flag was rewritten, for the
- * caller to notify their participants of once the transaction has committed
+ * @returns ids of the chat rooms whose inactive flag changed, to notify participants of after commit
  */
 export async function applyMatchChanges(
 	args: {
@@ -297,10 +282,8 @@ export async function applyMatchChanges(
 }
 
 /**
- * A match starts when it stops being pending, which can also happen as a side
- * effect of another match's result (the teams of a round robin round becoming
- * free, an opponent advancing). Matches that were already started keep the
- * timestamp they got, and one that goes back to pending loses it.
+ * A match starts when it stops being pending, possibly as a side effect of another match's result.
+ * Already started matches keep their timestamp, one going back to pending loses it.
  */
 async function syncStartedAt(
 	args: { previousData: BracketData; data: BracketData; isLeague: boolean },
@@ -365,8 +348,7 @@ async function syncStartedAt(
 }
 
 /**
- * A match completing marks its chat room inactive; a completed match losing its
- * winner again (reopen, undone final game) marks the room back active.
+ * Completing marks the chat room inactive, losing the winner again (reopen, undone final game) reactivates it.
  *
  * @returns ids of the rewritten chat rooms
  */
@@ -556,10 +538,7 @@ function hasBothOpponents(match: GeneratedRound["matches"][number]) {
 	return Boolean(match.opponent1?.id && match.opponent2?.id);
 }
 
-/**
- * Lines the ids of a multi-row insert back up with the rows they were inserted for. SQLite assigns
- * ids in insertion order, but RETURNING makes no ordering promise, so the ids are sorted first.
- */
+/** SQLite assigns ids in insertion order but RETURNING makes no ordering promise, so the ids are sorted first. */
 function zipInsertedIds(
 	sources: Array<{ id: number }>,
 	inserted: Array<{ id: number }>,
diff --git a/app/features/tournament-bracket/actions/to.$id.brackets.server.ts b/app/features/tournament-bracket/actions/to.$id.brackets.server.ts
index fa012dc0c..5f2e7fa02 100644
--- a/app/features/tournament-bracket/actions/to.$id.brackets.server.ts
+++ b/app/features/tournament-bracket/actions/to.$id.brackets.server.ts
@@ -80,9 +80,7 @@ export const action: ActionFunction = async ({ params, request }) => {
 					? abDivisionsForSeeding(seeding, tournament, groupCount)
 					: undefined;
 
-			// in rr/swiss every group shares one map list per round number, and
-			// groups can have different round counts when teams divide unevenly,
-			// so compare against the number of distinct round numbers
+			// rr/swiss groups share one map list per round number and can have different round counts
 			const distinctRoundNumberCount = new Set(
 				bracket.data.round.map((round) => round.number),
 			).size;
@@ -110,7 +108,7 @@ export const action: ActionFunction = async ({ params, request }) => {
 				isLeague: tournament.isLeague,
 			});
 
-			// persist maps as prepared even if they weren't initially so sibling brackets can reuse them
+			// persisted as prepared so sibling brackets can reuse them
 			const existingPreparedMaps =
 				await TournamentRepository.findPreparedMapsById(tournamentId);
 			if (!existingPreparedMaps?.[data.bracketIdx]) {
diff --git a/app/features/tournament-bracket/components/Bracket/Elimination.tsx b/app/features/tournament-bracket/components/Bracket/Elimination.tsx
index 31428de27..844513ddb 100644
--- a/app/features/tournament-bracket/components/Bracket/Elimination.tsx
+++ b/app/features/tournament-bracket/components/Bracket/Elimination.tsx
@@ -17,8 +17,7 @@ interface EliminationBracketSideProps {
 	isExpanded?: boolean;
 }
 
-// these values must match --match-height in index.module.css and the match
-// gap in BracketColumns.module.css
+// must match --match-height in index.module.css and the match gap in BracketColumns.module.css
 const MATCH_HEIGHT = 55;
 const GAP = 32;
 const MATCH_SPACING = MATCH_HEIGHT + GAP;
@@ -191,12 +190,9 @@ export function EliminationBracketSide(props: EliminationBracketSideProps) {
 }
 
 /**
- * Resolves whether the first round should be rendered compacted, meaning one
- * slot per second round match instead of two. This is possible when fewer
- * than half of the potential first round matches are played, as then each
- * second round match has at most one first round feeder and the played
- * matches can be laid out right next to their destination with a straight
- * connector, halving the bracket's height.
+ * Compacted = one first round slot per second round match instead of two, halving the height. Possible
+ * when fewer than half of the potential first round matches are played, as then each second round match
+ * has at most one feeder that can sit right next to it with a straight connector.
  */
 function resolveCompactedFirstRoundId(args: {
 	rounds: ReturnType<typeof getRounds>;
diff --git a/app/features/tournament-bracket/components/Bracket/Swiss.tsx b/app/features/tournament-bracket/components/Bracket/Swiss.tsx
index 6781381b0..363563fc1 100644
--- a/app/features/tournament-bracket/components/Bracket/Swiss.tsx
+++ b/app/features/tournament-bracket/components/Bracket/Swiss.tsx
@@ -37,8 +37,7 @@ export function SwissBracket({
 		tournamentBracketsSearchParams,
 		"group",
 	);
-	// the group of the shipped matches rather than that of the search param, so that
-	// the group being switched to only shows up once its matches have loaded
+	// group of the shipped matches rather than the search param's, so a switch shows once its matches loaded
 	const selectedGroupId = groupId ?? groups[0].groupId;
 
 	const selectedGroup = groups.find((g) => g.groupId === selectedGroupId)!;
@@ -67,8 +66,7 @@ export function SwissBracket({
 		return true;
 	};
 
-	// with the early advance variation the group can run out of teams before every
-	// round has been played, those rounds can never be started
+	// early advance: the group can run out of teams before every round is played
 	const groupHasActiveTeams = Engine.groupHasActiveTeams(bracket.data, {
 		groupId: selectedGroupId,
 		standings: bracket.liveStandings,
diff --git a/app/features/tournament-bracket/components/Bracket/index.module.css b/app/features/tournament-bracket/components/Bracket/index.module.css
index 413d69607..ade12e6b9 100644
--- a/app/features/tournament-bracket/components/Bracket/index.module.css
+++ b/app/features/tournament-bracket/components/Bracket/index.module.css
@@ -19,11 +19,9 @@
 	overflow: scroll;
 	user-select: none;
 
-	/* Inside a breakout wrapper (see `mainBreakout`) grow only as wide as the
-	   bracket actually needs: never narrower than the normal page width, never
-	   wider than the content area (then it scrolls), centered either way.
-	   Height fills down to the bottom of the viewport using the top offset
-	   published by JS (`--bracket-fill-top`), floored so it never collapses. */
+	/* In a breakout wrapper (see `mainBreakout`): as wide as needed between the normal page width and
+	   the content area (then it scrolls), centered. Height fills down to the viewport bottom using the
+	   JS-published `--bracket-fill-top`, floored so it never collapses. */
 	:global([data-main-breakout]) & {
 		width: fit-content;
 		min-width: min(72rem, 100%);
@@ -49,9 +47,7 @@
 	}
 }
 
-/* Lets the bracket size against the full content area instead of the page
-   width. cqw resolves to <main>, which spans the content area in breakout
-   mode (its own padding keeps the bracket off the edges). */
+/* Sizes against the full content area: cqw resolves to <main>, which spans it in breakout mode. */
 .breakoutWrapper {
 	:global([data-main-breakout]) & {
 		width: 100cqw;
diff --git a/app/features/tournament-bracket/components/Bracket/index.tsx b/app/features/tournament-bracket/components/Bracket/index.tsx
index 23de4c1f1..608469f19 100644
--- a/app/features/tournament-bracket/components/Bracket/index.tsx
+++ b/app/features/tournament-bracket/components/Bracket/index.tsx
@@ -109,11 +109,9 @@ function ScrollableBracketContainer({
 }
 
 /**
- * Inside a breakout container (see `mainBreakout`), publishes the bracket's
- * distance from the top of the viewport as the `--bracket-fill-top` CSS
- * variable. The bracket's `max-height` is then derived from it in CSS, which
- * can account for the viewport, the mobile bottom nav and safe area insets in
- * ways JS can't read. A no-op elsewhere, so the static `max-height` applies.
+ * Inside a breakout container (see `mainBreakout`) publishes the bracket's distance from the viewport top
+ * as `--bracket-fill-top`, from which CSS derives `max-height` accounting for the mobile bottom nav and
+ * safe area insets JS can't read. No-op elsewhere, so the static `max-height` applies.
  */
 function usePublishBracketTopOffset(ref: React.RefObject<HTMLElement | null>) {
 	useIsomorphicLayoutEffect(() => {
diff --git a/app/features/tournament-bracket/components/BracketMapListDialog.tsx b/app/features/tournament-bracket/components/BracketMapListDialog.tsx
index 1b97221af..2e0e567f3 100644
--- a/app/features/tournament-bracket/components/BracketMapListDialog.tsx
+++ b/app/features/tournament-bracket/components/BracketMapListDialog.tsx
@@ -125,8 +125,7 @@ export function BracketMapListDialog({
 				return true;
 			}
 
-			// if maps were set before infer default from whether finals and third place match have different maps or not
-
+			// infer default from whether finals and third place match have different maps
 			const finalsMaps = preparedMaps.maps
 				.filter((map) => map.groupId === 0)
 				.sort((a, b) => b.roundId - a.roundId)[0];
@@ -276,7 +275,6 @@ export function BracketMapListDialog({
 		for (const groupCounts of mapCounts.values()) {
 			let roundPreviousValue = 0;
 			for (const [, roundValue] of Array.from(groupCounts.entries()).sort(
-				// sort by round number
 				(a, b) => a[0] - b[0],
 			)) {
 				if (roundPreviousValue > roundValue.count) {
@@ -287,7 +285,7 @@ export function BracketMapListDialog({
 			}
 		}
 
-		// check grands have at least as many maps as winners final (different groups)
+		// grands need at least as many maps as winners final (different groups)
 		if (bracket.type === "double_elimination") {
 			const grandsCounts = Array.from(mapCounts.get(2)?.values() ?? []);
 			const winnersCounts = Array.from(mapCounts.get(0)?.values() ?? []);
@@ -768,8 +766,7 @@ function inferMapCounts({
 				groupId,
 				new Map(result.get(groupId)).set(roundNumber, {
 					count,
-					// currently "best of" / "play all" is defined per bracket but in future it might be per round
-					// that's why there is this hardcoded default value for now
+					// "best of" / "play all" is per bracket for now, might be per round in the future
 					type: "BEST_OF",
 				}),
 			);
@@ -818,7 +815,7 @@ function teamCountAdjustedBracketData({
 			// always has the same amount of rounds even if 0 participants
 			return bracket.data;
 		case "round_robin":
-			// ensure a full bracket (no bye round) gets generated even if registration is underway
+			// full bracket (no bye round) even if registration is underway
 			return bracket.generateMatchesData(
 				nullFilledArray(
 					bracket.settings?.teamsPerGroup ??
@@ -857,7 +854,7 @@ function EliminationTeamCountSelect({
 				<option value="">Select count</option>
 				{PreparedMaps.eliminationTeamCountOptions({
 					type,
-					// the prepared for count can be below the current team count e.g. when some of the registered teams are not expected to play
+					// prepared for count can be below the current team count e.g. when some registered teams are not expected to play
 					currentCount: Math.min(realCount, count ?? realCount),
 				}).map((teamCountRange) => {
 					const label =
@@ -1188,13 +1185,8 @@ function MapListRow({
 }
 
 /**
- * Filter for the map search input that supports an optional game mode prefix.
- *
- * - `"sz"` matches every Splat Zones map
- * - `"sz crab"` matches Splat Zones maps whose stage name contains "crab"
- * - input without a recognized mode prefix matches against the stage name as before
- *
- * Expects `textValue` to be formatted as `"${modeShort} ${stageName}"`.
+ * Map search filter with an optional mode prefix: "sz" matches every Splat Zones map, "sz crab" those
+ * whose stage name contains "crab", no prefix matches the stage name. `textValue` is `"${modeShort} ${stageName}"`.
  */
 export function mapSearchFilter(
 	textValue: string,
diff --git a/app/features/tournament-bracket/core/AbDivisions.ts b/app/features/tournament-bracket/core/AbDivisions.ts
index 4319abb87..4415af1d4 100644
--- a/app/features/tournament-bracket/core/AbDivisions.ts
+++ b/app/features/tournament-bracket/core/AbDivisions.ts
@@ -6,17 +6,9 @@ interface ValidateArgs {
 }
 
 /**
- * Validates that the checked-in teams are ready to start a bipartite (A/B) round robin bracket.
- *
- * Returns the division assignments parallel to the seeding order on success, or an error message
- * suitable for surfacing to the organizer if any of the following are violated:
- *
- * - Every team has an A (0) or B (1) assignment
- * - The counts of A and B teams differ by at most 1
- * - When the counts differ by 1, there must be only one group (uneven divisions can't be split
- *   evenly across multiple groups)
- * - When the counts are equal, the total team count splits evenly across the groups and each
- *   group's team count is even (so A and B can be balanced within the group)
+ * Division assignments parallel to the seeding for an A/B round robin, or an error message for the
+ * organizer: every team needs an A (0) or B (1) assignment, counts may differ by at most 1 (and then
+ * only one group is allowed), equal counts must split evenly into groups of even size.
  */
 export function validate({
 	abDivisionsBySeedOrder,
diff --git a/app/features/tournament-bracket/core/Bracket/Bracket.ts b/app/features/tournament-bracket/core/Bracket/Bracket.ts
index f6cc233d0..bf2bfaa5f 100644
--- a/app/features/tournament-bracket/core/Bracket/Bracket.ts
+++ b/app/features/tournament-bracket/core/Bracket/Bracket.ts
@@ -114,11 +114,7 @@ export abstract class Bracket {
 		this.startTime = startTime;
 	}
 
-	/**
-	 * Can the organizer start this bracket at this moment? Evaluated on access rather than
-	 * stored because it depends on the current time, and a bracket can be built (and cached)
-	 * long before the clock reaches its start time.
-	 */
+	/** Evaluated on access as it depends on the current time and a bracket can be built (and cached) long before its start time. */
 	get canBeStarted() {
 		if (!this.participantsReady) return false;
 		if (this.startTime && this.startTime > new Date()) return false;
@@ -127,10 +123,7 @@ export abstract class Bracket {
 		return this.tournament.regularCheckInHasEnded;
 	}
 
-	/**
-	 * Bracket data with the results of the unplayed matches filled in, showing how teams are
-	 * expected to advance. Simulating is expensive so it happens on first access only.
-	 */
+	/** Unplayed matches filled in with the expected results. Simulating is expensive so it happens on first access only. */
 	get simulatedData(): BracketData | undefined {
 		if (!this._simulatedData) {
 			this._simulatedData = { value: this.createdSimulation() };
@@ -258,10 +251,7 @@ export abstract class Bracket {
 
 	abstract get type(): Tables["TournamentStage"]["type"];
 
-	/**
-	 * Standings that are settled i.e. teams still playing are left out. Safe to
-	 * use for deciding who advances to another bracket.
-	 */
+	/** Settled standings, teams still playing left out. Safe for deciding who advances. */
 	get standings(): Standing[] {
 		if (!this._standings) {
 			this._standings = this.calculateStandings();
@@ -272,11 +262,7 @@ export abstract class Bracket {
 
 	protected abstract calculateStandings(): Standing[];
 
-	/**
-	 * How many rounds a swiss bracket has. Comes from the bracket's own stage
-	 * settings rather than `settings` (the progression's, editable at any time),
-	 * so it can't drift from the bracket that actually exists.
-	 */
+	/** From the bracket's own stage settings rather than the progression's (editable at any time), so it can't drift. */
 	get swissRoundCount() {
 		return Engine.swissRoundCount(this.data);
 	}
@@ -289,10 +275,7 @@ export abstract class Bracket {
 		) as number[];
 	}
 
-	/**
-	 * Standings including teams that are still playing. Meant for displaying the
-	 * bracket's current state, not for deciding who advances.
-	 */
+	/** Includes teams still playing: for display, not for deciding who advances. */
 	get liveStandings(): Standing[] {
 		if (!this._liveStandings) {
 			this._liveStandings = this.calculateLiveStandings();
@@ -309,15 +292,15 @@ export abstract class Bracket {
 		return;
 	}
 
-	/** Returns true if this bracket is a starting bracket (i.e., teams in it start their tournament from this bracket). Note: there can be more than one starting bracket. */
+	/** Teams start their tournament from this bracket. There can be more than one. */
 	get isStartingBracket() {
 		return !this.sources || this.sources.length === 0;
 	}
 
-	/** Resolves teams' effective seeds: the better of a team's own seed and the best
-	 * seed of a team it defeated in this bracket. A team that beats a higher seed
-	 * inherits that seed, so cross-group placement ties break in the overtaker's
-	 * favor while defaulting to the original seeding when no upsets happened. */
+	/**
+	 * Effective seed = the better of a team's own seed and the best seed it defeated in this bracket,
+	 * so cross-group placement ties break in the overtaker's favor.
+	 */
 	protected effectiveSeedResolver(): (tournamentTeamId: number) => number {
 		const teamSeed = (tournamentTeamId: number) => {
 			const seed = this.tournament.teamById(tournamentTeamId)?.seed;
@@ -447,10 +430,7 @@ export abstract class Bracket {
 		);
 	}
 
-	/**
-	 * Whether the standings of this bracket are final i.e. no further match can
-	 * change them. While false the standings are provisional.
-	 */
+	/** No further match can change the standings. */
 	get standingsAreFinal() {
 		return this.everyMatchOver;
 	}
@@ -491,9 +471,10 @@ export abstract class Bracket {
 		teams: number[];
 	};
 
-	/** Advances top finishers by their standings placement. Only settled teams appear in
-	 * the standings, so placements are matched raw until the full standings resolve and
-	 * only then normalized (1,3,5 -> 1,2,3) the way group brackets source. */
+	/**
+	 * Only settled teams appear in the standings, so placements are matched raw until the full
+	 * standings resolve and only then normalized (1,3,5 -> 1,2,3) the way group brackets source.
+	 */
 	protected sourceByStandings(placements: number[], rest: boolean) {
 		const standings = this.standings;
 		const relevantMatchesFinished =
@@ -549,13 +530,7 @@ export abstract class Bracket {
 		return status;
 	}
 
-	/**
-	 * Returns match IDs that are currently ongoing (ready to start).
-	 * A match is ongoing when:
-	 * - Both teams are defined
-	 * - No team has an earlier match (lower number) currently in progress
-	 * - Match is not completed
-	 */
+	/** Matches with both teams defined, not completed and neither team busy in an earlier (lower number) match. */
 	ongoingMatches(): number[] {
 		const ongoingMatchIds: number[] = [];
 
diff --git a/app/features/tournament-bracket/core/Bracket/RoundRobinBracket.ts b/app/features/tournament-bracket/core/Bracket/RoundRobinBracket.ts
index 4881e1b3a..7443c8110 100644
--- a/app/features/tournament-bracket/core/Bracket/RoundRobinBracket.ts
+++ b/app/features/tournament-bracket/core/Bracket/RoundRobinBracket.ts
@@ -180,7 +180,7 @@ export class RoundRobinBracket extends Bracket {
 				}
 			};
 
-			// every team of the group belongs in the standings even if all of its matches were forfeited by dropped out opponents, dropped out ones are seeded further below
+			// every team belongs in the standings even if all its matches were forfeited by dropped out opponents
 			const groupTeamIds = R.unique(
 				matches
 					.flatMap((match) => [match.opponent1?.id, match.opponent2?.id])
@@ -217,7 +217,7 @@ export class RoundRobinBracket extends Bracket {
 						"RoundRobinBracket.standings: winner or loser id not found",
 				);
 
-				// note: score might be missing in the case the set was ended early. In the future we might want to handle this differently than defaulting both to 0.
+				// score might be missing when the set was ended early, defaulting both to 0 for now
 
 				updateTeam({
 					teamId: winner.id,
@@ -260,7 +260,7 @@ export class RoundRobinBracket extends Bracket {
 				}
 			}
 
-			// Seed dropped teams here (after wins-against-tied) so forfeit matches don't credit opponents while still keeping them in standings.
+			// dropped teams seeded after wins-against-tied so forfeits don't credit opponents while keeping them in standings
 			for (const teamId of droppedOutWithIncompleteMatches) {
 				teams.push({
 					id: teamId,
diff --git a/app/features/tournament-bracket/core/Bracket/SingleEliminationBracket.ts b/app/features/tournament-bracket/core/Bracket/SingleEliminationBracket.ts
index 841abacfc..e71db5c2c 100644
--- a/app/features/tournament-bracket/core/Bracket/SingleEliminationBracket.ts
+++ b/app/features/tournament-bracket/core/Bracket/SingleEliminationBracket.ts
@@ -172,8 +172,7 @@ export class SingleEliminationBracket extends Bracket {
 			return this.sourceByStandings(placements, rest === true);
 		}
 
-		// third place match lives in a separate (higher) group; the winners
-		// group teams get eliminated from is the lowest group id
+		// third place match lives in a separate (higher) group, the lowest group id is the winners group
 		const mainGroupId = Math.min(...this.data.group.map((group) => group.id));
 
 		const orderedRoundsIds = this.data.round
@@ -220,11 +219,7 @@ export class SingleEliminationBracket extends Bracket {
 	}
 }
 
-/**
- * A third place match with only one opponent is decided by a BYE: the semifinal
- * on the other side was itself won against a BYE, so it produced no loser and
- * the lone semifinal loser takes third place without playing.
- */
+/** The other semifinal was won against a BYE and produced no loser, so the lone semifinal loser takes third without playing. */
 function winnerOfThirdPlaceMatch(match: MatchData | undefined) {
 	if (!match) return undefined;
 
diff --git a/app/features/tournament-bracket/core/Bracket/SwissBracket.ts b/app/features/tournament-bracket/core/Bracket/SwissBracket.ts
index dc7bd2180..a9516270a 100644
--- a/app/features/tournament-bracket/core/Bracket/SwissBracket.ts
+++ b/app/features/tournament-bracket/core/Bracket/SwissBracket.ts
@@ -34,8 +34,7 @@ export class SwissBracket extends Bracket {
 
 		const relevantMatchesFinished = this.standingsAreFinal;
 
-		// explicit placements override the threshold, e.g. a consolation
-		// bracket for the teams that did not advance
+		// explicit placements override the threshold, e.g. a consolation bracket for the teams that did not advance
 		if (advanceThreshold && placements.length === 0) {
 			return {
 				relevantMatchesFinished,
@@ -54,7 +53,6 @@ export class SwissBracket extends Bracket {
 			};
 		}
 
-		// Standard Swiss logic without early advance/elimination
 		const uniquePlacements = R.unique(standings.map((s) => s.placement));
 
 		// 1,3,5 -> 1,2,3 e.g.
@@ -75,9 +73,8 @@ export class SwissBracket extends Bracket {
 	}
 
 	/**
-	 * Swiss rounds are paired one at a time, so a round that has no matches yet can still change the standings.
-	 * Exception being rounds that can never be paired because every team of the group has already
-	 * advanced or been eliminated (early advance variation).
+	 * Rounds are paired one at a time, so a round without matches yet can still change the standings,
+	 * unless it can never be paired because every team already advanced or got eliminated.
 	 */
 	get everyMatchOver() {
 		if (!super.everyMatchOver) return false;
@@ -385,16 +382,13 @@ export class SwissBracket extends Bracket {
 						if (a.setLosses < b.setLosses) return -1;
 						if (a.setLosses > b.setLosses) return 1;
 
-						// TIEBREAKER 2) losses against tied - a team that lost to fewer of the
-						// teams it is tied with is placed higher. Unlike round robin (which uses
-						// wins against tied), Swiss counts losses because not every tied team has
-						// played each other: rewarding wins would unfairly favor teams who simply
-						// faced more of their tied peers, whereas penalizing head-to-head losses is
-						// schedule-independent. (winsAgainstTied is still tracked for display only.)
+						// TIEBREAKER 2) losses against tied. Unlike round robin (wins against tied), Swiss counts
+						// losses because not every tied team has played each other: wins would favor teams who
+						// faced more tied peers, losses are schedule-independent. winsAgainstTied is display only.
 						if (a.lossesAgainstTied > b.lossesAgainstTied) return 1;
 						if (a.lossesAgainstTied < b.lossesAgainstTied) return -1;
 
-						// TIEBREAKER 3) opponent set win % - how good the opponents they played against were?
+						// TIEBREAKER 3) opponent set win %
 						const aOpponentSetWinPercentage = this.trackRecordToWinPercentage(
 							a.opponentSets,
 						);
@@ -415,7 +409,7 @@ export class SwissBracket extends Bracket {
 						if (a.mapLosses < b.mapLosses) return -1;
 						if (a.mapLosses > b.mapLosses) return 1;
 
-						// TIEBREAKER 5) map wins against tied OW% (M) - note that this needs to be lower than map wins tiebreaker to make sure that throwing maps is not optimal
+						// TIEBREAKER 5) map wins against tied OW% (M), must rank below map wins so throwing maps is not optimal
 						const aOpponentMapWinPercentage = this.trackRecordToWinPercentage(
 							a.opponentMaps,
 						);
diff --git a/app/features/tournament-bracket/core/Bracket/utils.ts b/app/features/tournament-bracket/core/Bracket/utils.ts
index 07f59f1d8..b01913297 100644
--- a/app/features/tournament-bracket/core/Bracket/utils.ts
+++ b/app/features/tournament-bracket/core/Bracket/utils.ts
@@ -2,11 +2,8 @@ import * as R from "remeda";
 import type { BracketData } from "~/features/tournament-bracket/core/engine/types";
 
 /**
- * Maps each roundId to the cumulative number of teams eliminated by the end of
- * that round, counting one elimination per non-bye match. This is a structural
- * property of the bracket that does not depend on which matches have already
- * been reported, so teams tied at the same placement resolve to the same
- * placement even while some of their round's matches are still in progress.
+ * roundId -> teams eliminated by the end of that round (one per non-bye match). Structural, independent
+ * of reported matches, so tied teams resolve to the same placement while their round is in progress.
  */
 export function cumulativeEliminationsByRound(
 	matches: BracketData["match"],
diff --git a/app/features/tournament-bracket/core/Deadline.ts b/app/features/tournament-bracket/core/Deadline.ts
index 2673bdd18..197cb7b7a 100644
--- a/app/features/tournament-bracket/core/Deadline.ts
+++ b/app/features/tournament-bracket/core/Deadline.ts
@@ -1,21 +1,12 @@
 const PREP_TIME_MINUTES = 6.5;
 const MINUTES_PER_GAME = 6.5;
 
-/**
- * Calculates the max duration for a match considered acceptable.
- * @param maxGamesCount - The maximum number of games in the match
- * @returns Time in minutes (preparation time + game time)
- */
+/** Acceptable max duration of a match in minutes (preparation time + game time). */
 export function totalMatchTime(maxGamesCount: number): number {
 	return PREP_TIME_MINUTES + MINUTES_PER_GAME * maxGamesCount;
 }
 
-/**
- * Calculates the progress percentage based on elapsed time.
- * @param elapsedMinutes - Time elapsed since match start
- * @param totalMinutes - Total expected match duration
- * @returns Percentage value (0-100+)
- */
+/** Elapsed share of the expected duration as a percentage (0-100+). */
 export function progressPercentage(
 	elapsedMinutes: number,
 	totalMinutes: number,
@@ -23,11 +14,7 @@ export function progressPercentage(
 	return (elapsedMinutes / totalMinutes) * 100;
 }
 
-/**
- * Generates marker positions for each game in the match timeline.
- * @param maxGamesCount - The maximum number of games in the match
- * @returns Array of game markers with their position as a percentage
- */
+/** Position of each game on the match timeline as a percentage. */
 export function gameMarkers(maxGamesCount: number): Array<{
 	gameNumber: number;
 	percentage: number;
@@ -53,11 +40,7 @@ export function gameMarkers(maxGamesCount: number): Array<{
 	return markers;
 }
 
-/**
- * Determines the current status of a match based on time and progress.
- * @param params - Object containing elapsed time, games completed, and max games
- * @returns "normal" if on track, "warning" if behind schedule, "error" if overtime
- */
+/** "normal" if on track, "warning" if behind schedule, "error" if overtime. */
 export function matchStatus({
 	elapsedMinutes,
 	gamesCompleted,
diff --git a/app/features/tournament-bracket/core/PickBan.ts b/app/features/tournament-bracket/core/PickBan.ts
index 31311cbe6..1d399f134 100644
--- a/app/features/tournament-bracket/core/PickBan.ts
+++ b/app/features/tournament-bracket/core/PickBan.ts
@@ -268,12 +268,8 @@ export function resolveCurrentStep({
 }
 
 /**
- * Returns the 0-based post-game cycle index for an event position. For an
- * event at `eventIndex`, this is the cycle the event belongs to; for a count
- * of events done so far, this is how many post-game cycles have been at least
- * started past the pre-set.
- *
- * Caller must ensure `eventIndex >= preSetLength` and `postGameLength > 0`.
+ * 0-based post-game cycle of an event index (or, for a count of events done, how many cycles have
+ * started past the pre-set). Caller must ensure `eventIndex >= preSetLength` and `postGameLength > 0`.
  */
 export function postGameCycleIndex({
 	eventIndex,
@@ -296,10 +292,7 @@ export function resolveTeamFromSide({
 	side: WhoSide;
 	teams: [PickBanTeam, PickBanTeam];
 	results: Array<{ winnerTeamId: number }>;
-	/**
-	 * The team index (0 or 1) the per-map coin flip landed on. Required when
-	 * `side` is RANDOM or RANDOM_OTHER. Compute with {@link randomWhoTeamIndex}.
-	 */
+	/** Team index the per-map coin flip landed on. Required when `side` is RANDOM or RANDOM_OTHER, see {@link randomWhoTeamIndex}. */
 	randomTeamIndex?: 0 | 1;
 }): number {
 	switch (side) {
@@ -337,10 +330,8 @@ export function resolveTeamFromSide({
 }
 
 /**
- * Resolves which of the two teams (0 or 1) the "RANDOM" side maps to for the
- * given event via a deterministic per-map coin flip. A single flip covers one
- * decision group: all pre-set steps share one flip, and each post-game cycle
- * (one per map) has its own. "RANDOM_OTHER" is the complement of this index.
+ * Team index (0 or 1) the "RANDOM" side maps to via a deterministic per-map coin flip. All pre-set
+ * steps share one flip, each post-game cycle has its own. "RANDOM_OTHER" is the complement.
  */
 export function randomWhoTeamIndex({
 	matchId,
@@ -362,12 +353,7 @@ export function randomWhoTeamIndex({
 	return randomInteger(2) as 0 | 1;
 }
 
-/**
- * Resolves which team is responsible for the pick/ban event at a given index,
- * across all pick/ban variants (BAN_2, COUNTERPICK, COUNTERPICK_MODE_REPEAT_OK,
- * CUSTOM). Returns null when the setup is not pick/ban or the team cannot be
- * determined (e.g. a CUSTOM ROLL step, or insufficient results).
- */
+/** Team responsible for the pick/ban event at the index, null if not pick/ban or undeterminable (CUSTOM ROLL step, insufficient results). */
 export function teamOfEvent({
 	eventIndex,
 	maps,
@@ -385,8 +371,7 @@ export function teamOfEvent({
 
 	switch (maps.pickBan) {
 		case "BAN_2": {
-			// turnOf uses: [secondPicker, firstPicker] = teams, so teams[1] bans
-			// first (event 0), teams[0] second (event 1).
+			// turnOf uses [secondPicker, firstPicker] = teams, so teams[1] bans first (event 0)
 			if (eventIndex === 0) return teams[1].id;
 			if (eventIndex === 1) return teams[0].id;
 			return null;
@@ -411,8 +396,7 @@ export function teamOfEvent({
 						: null;
 			if (!step?.side) return null;
 
-			// WINNER/LOSER sides are relative to the latest result at the time
-			// of the event, so slice results to the correct post-game cycle.
+			// WINNER/LOSER sides are relative to the latest result at the time of the event
 			if (step.side === "WINNER" || step.side === "LOSER") {
 				const cycleIndex = postGameCycleIndex({
 					eventIndex,
@@ -450,14 +434,10 @@ type TimelineItem =
 	| { kind: "result"; createdAt: number };
 
 /**
- * Resolves the timestamp at which the currently responsible team's pick/ban
- * session started. The session begins when responsibility transitions to that
- * team and continues across multiple consecutive actions by the same team.
- * A game result always ends the prior session, so a team that becomes
- * responsible after a result starts a fresh session at the result's timestamp.
- *
- * Returns `null` when there is no current pick/ban turn or `matchStartedAt` is
- * not available. When no transitions exist yet, returns `matchStartedAt`.
+ * When the currently responsible team's pick/ban session started: on responsibility transitioning to
+ * it (consecutive actions by the same team continue it), or at the latest game result as a result
+ * always ends the prior session. `matchStartedAt` when no transitions exist yet, `null` when there is
+ * no current turn or `matchStartedAt` is unavailable.
  */
 export function currentTurnSessionStartedAt({
 	currentTurn,
diff --git a/app/features/tournament-bracket/core/PreparedMaps.test.ts b/app/features/tournament-bracket/core/PreparedMaps.test.ts
index 0c80d1af1..fa0327683 100644
--- a/app/features/tournament-bracket/core/PreparedMaps.test.ts
+++ b/app/features/tournament-bracket/core/PreparedMaps.test.ts
@@ -277,10 +277,7 @@ describe("PreparedMaps - eliminationTeamCountOptions", () => {
 		});
 	}
 
-	/**
-	 * Names of the rounds that actually get played i.e. what both the bracket and the prepared maps dialog show.
-	 * The third place match is left out because it is trimmed separately when it disappears below four teams.
-	 */
+	/** Round names as both the bracket and the prepared maps dialog show them. Third place match left out as it is trimmed separately. */
 	function playedRoundNames({
 		type,
 		teamCount,
diff --git a/app/features/tournament-bracket/core/PreparedMaps.ts b/app/features/tournament-bracket/core/PreparedMaps.ts
index cc7811596..7f247a7af 100644
--- a/app/features/tournament-bracket/core/PreparedMaps.ts
+++ b/app/features/tournament-bracket/core/PreparedMaps.ts
@@ -10,7 +10,7 @@ import type { BracketData } from "./engine/types";
 import * as Progression from "./Progression";
 import type { BracketMeta, Tournament } from "./Tournament";
 
-/** Returns the prepared maps for one exact bracket index OR maps of a "sibling bracket" i.e. bracket that has the same depth in progression  */
+/** Prepared maps of the bracket, or of a "sibling" bracket at the same progression depth. */
 export function resolvePreparedForTheBracket({
 	preparedByBracket,
 	bracketIdx,
@@ -22,7 +22,6 @@ export function resolvePreparedForTheBracket({
 }) {
 	const bracketMaps = preparedByBracket?.[bracketIdx];
 
-	// maps exactly for this bracket have been prepared, use them
 	if (bracketMaps) {
 		return bracketMaps;
 	}
@@ -31,7 +30,6 @@ export function resolvePreparedForTheBracket({
 	const bracketProgression = tournament.ctx.settings.bracketProgression;
 	const targetDepth = Progression.bracketDepth(bracketIdx, bracketProgression);
 
-	// lets look for an "equivalent" prepared bracket to use
 	// e.g. SoS RR -> 4x SE style the SE brackets can share maps
 	for (const [anotherBracketIdx, bracket] of bracketProgression.entries()) {
 		const depth = Progression.bracketDepth(
@@ -95,7 +93,7 @@ const DOUBLE_ELIMINATION_TEAM_RANGES: readonly TeamCountRange[] = [
 	{ min: 193, max: 256 },
 ];
 
-/** For single elimination and double elimination returns the amount of options that are the "steps" that affect the round count. Takes in currentCount as an argument, filtering out counts below that.  */
+/** Elimination team counts that are the "steps" affecting the round count, from currentCount up. */
 export function eliminationTeamCountOptions({
 	type,
 	currentCount,
@@ -111,7 +109,7 @@ export function eliminationTeamCountOptions({
 	return ranges.filter(({ max }) => max >= currentCount);
 }
 
-/** Validates that given count is a known "max" elimination team count value */
+/** Whether the count is a known "max" elimination team count. */
 export function isValidMaxEliminationTeamCount(count: number) {
 	return [
 		...SINGLE_ELIMINATION_TEAM_RANGES,
@@ -125,10 +123,7 @@ const REGISTRATION_CLOSING_SOON_MS = hoursToMilliseconds(1);
 /** How big a share of a team count range must be unfilled for an estimated count not to be rounded up to the next range. */
 const ESTIMATE_SLACK_RATIO = 0.1;
 
-/**
- * Team count to prefill the "expected teams" selection with when preparing maps for an elimination bracket.
- * Null when it can't be told yet how many teams will play in the bracket e.g. registration is still open.
- */
+/** Prefill for the "expected teams" selection, null when it can't be told yet e.g. registration is still open. */
 export function eliminationTeamCountPrefill({
 	tournament,
 	bracketIdx,
@@ -170,14 +165,13 @@ interface TrimPreparedEliminationMapsAgs {
 	bracket: Bracket;
 }
 
-/** Trim prepared elimination bracket maps to match the actual number. If not prepared or prepared for too few returns null */
+/** Trims prepared elimination maps to the actual team count, null if not prepared or prepared for too few. */
 export function trimPreparedEliminationMaps({
 	preparedMaps,
 	teamCount,
 	...rest
 }: TrimPreparedEliminationMapsAgs) {
 	if (!preparedMaps) {
-		// we did not prepare enough maps
 		return null;
 	}
 
@@ -194,7 +188,6 @@ export function trimPreparedEliminationMaps({
 		!preparedMaps.eliminationTeamCount ||
 		preparedMaps.eliminationTeamCount < teamCount
 	) {
-		// we did not prepared enough maps
 		return null;
 	}
 
@@ -392,7 +385,7 @@ function advancingTeamCount({
 	return { count, isExact };
 }
 
-/** How many teams the given source sends forward, based on the shape the source bracket would have with the given participant count. */
+/** How many teams the source sends forward, given the shape the source bracket would have with the participant count. */
 function advancingFromSource({
 	bracket,
 	participantCount,
diff --git a/app/features/tournament-bracket/core/Progression.test.ts b/app/features/tournament-bracket/core/Progression.test.ts
index fe1c61050..b0edb11d5 100644
--- a/app/features/tournament-bracket/core/Progression.test.ts
+++ b/app/features/tournament-bracket/core/Progression.test.ts
@@ -26,7 +26,7 @@ const SWISS_EARLY_ADVANCE: BracketInput = {
 	settings: { advanceThreshold: 3 },
 };
 
-/** Fills in the ids and names `validatedBrackets` needs so tests only state what they vary. Bracket N is referenced as source bracketId `"N"`. */
+/** Fills in the ids and names `validatedBrackets` needs. Bracket N is referenced as source bracketId `"N"`. */
 const getValidatedBrackets = (brackets: BracketInput[]) =>
 	Progression.validatedBrackets(
 		brackets.map((bracket, i) => ({
@@ -652,7 +652,6 @@ describe("validatedSources - other rules", () => {
 	});
 
 	test("allows Swiss early advance when bracket has destination", () => {
-		// Swiss bracket with early advance that leads to another bracket should be valid
 		const result = getValidatedBrackets([
 			{
 				settings: {
@@ -667,7 +666,6 @@ describe("validatedSources - other rules", () => {
 			},
 		]);
 
-		// Should be valid (no error returned)
 		expect(Array.isArray(result)).toBe(true);
 	});
 
diff --git a/app/features/tournament-bracket/core/Progression.ts b/app/features/tournament-bracket/core/Progression.ts
index 57e59b513..335819d9e 100644
--- a/app/features/tournament-bracket/core/Progression.ts
+++ b/app/features/tournament-bracket/core/Progression.ts
@@ -9,18 +9,17 @@ import {
 import invariant from "../../../utils/invariant";
 
 export interface DBSource {
-	/** Index of the bracket where the teams come from */
 	bracketIdx: number;
-	/** Team placements that join this bracket. E.g. [1, 2] would mean top 1 & 2 teams. [-1] would mean the last placing teams. Can be empty array for Swiss brackets with early advance. */
+	/** E.g. [1, 2] = top 2 teams, [-1] = last placing teams, [] = Swiss early advancers. */
 	placements: number[];
-	/** When true, the highest value in `placements` is treated as "and every placement after that". Set by the "N+" rest syntax. Only valid with positive placements. */
+	/** Highest value in `placements` means "and every placement after that" ("N+" syntax). Only valid with positive placements. */
 	rest?: boolean;
 }
 
 export interface EditableSource {
-	/** Bracket ID that exists in frontend only while editing. Once the sources are set an index is used to identifyer them instead. See DBSource.bracketIdx for more info. */
+	/** Frontend-only id while editing, replaced by an index once set. See DBSource.bracketIdx. */
 	bracketId: string;
-	/** User editable string of placements. For example might be "1-3" or "1,2,3" which both mean same thing. See DBSource.placements for the validated and serialized version. */
+	/** User editable, "1-3" and "1,2,3" mean the same. See DBSource.placements for the validated version. */
 	placements: string;
 }
 
@@ -35,7 +34,7 @@ export interface InputBracket extends BracketBase {
 	id: string;
 	sources?: EditableSource[];
 	startTime?: Date;
-	/** This bracket cannot be edited (because it is already underway) */
+	/** Already underway */
 	disabled?: boolean;
 }
 
@@ -50,7 +49,7 @@ export type ValidationError =
 			type: "PLACEMENTS_PARSE_ERROR";
 			bracketIdx: number;
 	  }
-	// tournament is ending with a format that does not resolve a winner such as round robin or grouped swiss
+	// tournament ends with a format that does not resolve a winner e.g. round robin or grouped swiss
 	| {
 			type: "NOT_RESOLVING_WINNER";
 	  }
@@ -59,12 +58,12 @@ export type ValidationError =
 			type: "SAME_PLACEMENT_TO_MULTIPLE_BRACKETS";
 			bracketIdxs: number[];
 	  }
-	// from one bracket e.g. if 1st goes somewhere and 3rd goes somewhere then 2nd must also go somewhere
+	// e.g. if 1st and 3rd go somewhere then 2nd must also go somewhere
 	| {
 			type: "GAP_IN_PLACEMENTS";
 			bracketIdxs: number[];
 	  }
-	// if round robin groups size is 4 then it doesn't make sense to have destination for 5
+	// e.g. round robin group size 4 can't have a destination for 5th
 	| {
 			type: "TOO_MANY_PLACEMENTS";
 			bracketIdx: number;
@@ -79,7 +78,7 @@ export type ValidationError =
 			type: "DUPLICATE_BRACKET_NAME";
 			bracketIdxs: number[];
 	  }
-	// all brackets must have a name that is not an empty string
+	// bracket name can not be empty
 	| {
 			type: "NAME_MISSING";
 			bracketIdx: number;
@@ -109,7 +108,7 @@ export type ValidationError =
 			type: "AB_DIVISIONS_NOT_STARTING";
 			bracketIdx: number;
 	  }
-	// A/B divisions requires an even teamsPerGroup so each group can be split equally
+	// A/B divisions need an even teamsPerGroup to split each group equally
 	| {
 			type: "AB_DIVISIONS_ODD_TEAMS_PER_GROUP";
 			bracketIdx: number;
@@ -129,13 +128,13 @@ export type ValidationError =
 			type: "CYCLIC_PROGRESSION";
 			bracketIdxs: number[];
 	  }
-	// teams that started in different brackets can never meet, so the routes from many starting brackets can not merge
+	// teams that started in different brackets can never meet
 	| {
 			type: "MERGED_STARTING_BRACKETS";
 			bracketIdx: number;
 	  };
 
-/** Takes validated brackets and returns them in the format that is ready for user input. */
+/** Validated brackets in the format ready for user input. */
 export function validatedBracketsToInputFormat(
 	brackets: ParsedBracket[],
 ): InputBracket[] {
@@ -160,7 +159,7 @@ export function validatedBracketsToInputFormat(
 	});
 }
 
-/** Formats a placements array into the compact user-facing string form, e.g. [1, 2, 3] -> "1-3" and [5, 6] with rest -> "5,6+". */
+/** [1, 2, 3] -> "1-3", [5, 6] with rest -> "5,6+" */
 export function placementsToString(placements: number[], rest = false): string {
 	if (placements.length === 0) return "";
 
@@ -200,7 +199,7 @@ export function placementsToString(placements: number[], rest = false): string {
 	return ranges.join(",");
 }
 
-/** Takes bracket progression as entered by user as input and returns the validated brackets ready for input to the database or errors if any. */
+/** User-entered bracket progression to validated brackets ready for the database, or errors. */
 export function validatedBrackets(
 	brackets: InputBracket[],
 ): ParsedBracket[] | ValidationError {
@@ -227,7 +226,7 @@ export function validatedBrackets(
 	return parsed;
 }
 
-/** Checks parsed brackets for any errors related to how the progression is laid out  */
+/** Errors in how the progression is laid out. */
 export function bracketsToValidationError(
 	brackets: ParsedBracket[],
 ): ValidationError | null {
@@ -493,7 +492,6 @@ function resolvesWinner(brackets: ParsedBracket[]) {
 
 function samePlacementToMultipleBrackets(brackets: ParsedBracket[]) {
 	const map = new Map<string, number[]>();
-	// per source bracketIdx: list of { destinationBracketIdx, restFromPlacement }
 	const restSources = new Map<
 		number,
 		{ destinationBracketIdx: number; restFromPlacement: number }[]
@@ -538,7 +536,6 @@ function samePlacementToMultipleBrackets(brackets: ParsedBracket[]) {
 	}
 
 	for (const [sourceBracketIdx, restList] of restSources) {
-		// multiple "rest" sources from same bracket = conflict
 		if (restList.length > 1) {
 			for (const { destinationBracketIdx } of restList) {
 				result.add(destinationBracketIdx);
@@ -866,7 +863,7 @@ function mergedStartingBrackets(brackets: ParsedBracket[]) {
 	for (const [bracketIdx, bracket] of brackets.entries()) {
 		if (startingAncestors(bracketIdx).size <= 1) continue;
 
-		// the merge already happened earlier in the progression, that bracket is reported instead
+		// merge happened earlier in the progression, that bracket is reported instead
 		const mergedEarlier = (bracket.sources ?? []).some(
 			(source) => startingAncestors(source.bracketIdx).size > 1,
 		);
@@ -878,28 +875,28 @@ function mergedStartingBrackets(brackets: ParsedBracket[]) {
 	return null;
 }
 
-/** Takes the return type of `Progression.validatedBrackets` as an input and narrows the type to a successful validation */
+/** Narrows the return type of `Progression.validatedBrackets` to a successful validation. */
 export function isBrackets(
 	input: ParsedBracket[] | ValidationError,
 ): input is ParsedBracket[] {
 	return Array.isArray(input);
 }
 
-/** Takes the return type of `Progression.validatedBrackets` as an input and narrows the type to a unsuccessful validation */
+/** Narrows the return type of `Progression.validatedBrackets` to a failed validation. */
 export function isError(
 	input: ParsedBracket[] | ValidationError,
 ): input is ValidationError {
 	return !Array.isArray(input);
 }
 
-/** Given bracketIdx and bracketProgression will resolve if this the "final stage" of the tournament that decides the final standings  */
+/** Whether the bracket is the final stage that decides the final standings. */
 export function isFinals(idx: number, brackets: ParsedBracket[]) {
 	invariant(idx < brackets.length, "Bracket index out of bounds");
 
 	return resolveMainBracketProgression(brackets).at(-1) === idx;
 }
 
-/** Returns true if the finals bracket of the tournament is an A/B divisions round robin. */
+/** Whether the finals bracket is an A/B divisions round robin. */
 export function hasAbDivisionsFinals(brackets: ParsedBracket[]): boolean {
 	const finals = brackets.find((_, idx) => isFinals(idx, brackets));
 	if (!finals) return false;
@@ -909,9 +906,7 @@ export function hasAbDivisionsFinals(brackets: ParsedBracket[]): boolean {
 	);
 }
 
-/** Given bracketIdx and bracketProgression will resolve if this an "underground bracket".
- * Underground bracket is defined as a bracket that is not part of the main tournament progression e.g. optional bracket for early losers
- */
+/** Underground bracket = not part of the main progression, e.g. an optional bracket for early losers. */
 export function isUnderground(idx: number, brackets: ParsedBracket[]) {
 	invariant(idx < brackets.length, "Bracket index out of bounds");
 
@@ -923,8 +918,7 @@ export function isUnderground(idx: number, brackets: ParsedBracket[]) {
 
 	if (mainBracketIdxs.has(idx)) return false;
 
-	// a bracket whose top finishers advance (transitively) into the main progression
-	// is a redemption style intermediate bracket, not an underground one
+	// top finishers advancing (transitively) into the main progression makes it a redemption bracket, not underground
 	const queue = [idx];
 	const visited = new Set<number>();
 	while (queue.length > 0) {
@@ -949,11 +943,7 @@ export function isUnderground(idx: number, brackets: ParsedBracket[]) {
 	return true;
 }
 
-/**
- * Returns the depth of a bracket in the tournament progression.
- * Depth is the distance from a starting bracket (bracket with no sources).
- * Starting brackets have depth 0, brackets sourced from them have depth 1, etc.
- */
+/** Distance from a starting bracket (no sources): starting brackets 0, brackets sourced from them 1, etc. */
 export function bracketDepth(idx: number, brackets: ParsedBracket[]): number {
 	invariant(idx < brackets.length, "Bracket index out of bounds");
 
@@ -1004,8 +994,7 @@ function resolveMainBracketProgression(
 			),
 		);
 
-		// -1 = end of the progression, already visited is only possible
-		// with an invalid progression, see CYCLIC_PROGRESSION
+		// -1 = end of the progression, already visited only with an invalid progression (CYCLIC_PROGRESSION)
 		if (bracket === -1 || visited.has(bracket)) break;
 
 		bracketIdxToFind = bracket;
@@ -1016,7 +1005,7 @@ function resolveMainBracketProgression(
 	return result;
 }
 
-/** Considering all fields. Returns array of bracket indexes that were changed */
+/** Indexes of brackets changed in any field. */
 export function changedBracketProgression(
 	oldProgression: ParsedBracket[],
 	newProgression: ParsedBracket[],
@@ -1035,7 +1024,7 @@ export function changedBracketProgression(
 	return changed;
 }
 
-/** Considering only fields that affect the format. Returns true if the tournament bracket format was changed and false otherwise */
+/** Whether any field affecting the format changed. */
 export function changedBracketProgressionFormat(
 	oldProgression: ParsedBracket[],
 	newProgression: ParsedBracket[],
@@ -1059,13 +1048,10 @@ export function changedBracketProgressionFormat(
 }
 
 /**
- * Returns the order of brackets as is to be considered for standings. Teams from the bracket of lower index are considered to be above those from the lower bracket.
- * A participant's standing is the first bracket to appear in order that has the participant in it.
- *
- * The order is so that most significant brackets (i.e. finals) appear first. A bracket always appears after every bracket
- * it advances teams to, so the teams it eliminated end up below the teams that advanced out of it.
- *
- * Underground brackets are omitted as they are only used to break ties within their source bracket, see `tiebrokenByUndergroundBrackets`.
+ * Bracket order for standings: a participant's standing comes from the first bracket in this order they
+ * are in. Finals first; a bracket always comes after every bracket it advances teams to, so teams it
+ * eliminated end up below those that advanced. Underground brackets are omitted as they only break
+ * ties within their source bracket, see `tiebrokenByUndergroundBrackets`.
  */
 export function bracketIdxsForStandings(progression: ParsedBracket[]) {
 	const bracketsToConsider = bracketsReachableFrom(0, progression);
@@ -1087,11 +1073,10 @@ export function bracketIdxsForStandings(progression: ParsedBracket[]) {
 }
 
 /**
- * Orders the given brackets so that every bracket appears after all the brackets it is a source of.
- * Among the brackets that are free to be placed next, the one whose teams placed the highest in the
- * deepest bracket they have in common (e.g. a top cut over a consolation bracket) goes first. The comparison
- * follows the whole route the teams took, so e.g. a bracket taking the low placements of a redemption bracket
- * can still rank above a bracket taking mid placements straight from the pools that fed that redemption bracket.
+ * Every bracket comes after all the brackets it is a source of. Among the brackets free to be placed
+ * next, the one whose teams placed highest in the deepest bracket they have in common goes first (e.g.
+ * a top cut over a consolation bracket). The whole route counts, so a bracket taking low placements
+ * of a redemption bracket can rank above one taking mid placements straight from the pools that fed it.
  */
 function destinationsFirstOrder(
 	bracketIdxs: number[],
@@ -1210,10 +1195,7 @@ export function destinationsFromBracketIdx(
 	return destinations;
 }
 
-/**
- * Returns the indexes of the underground brackets sourced from the given bracket.
- * An underground bracket is one that takes teams eliminated from its source bracket (negative placements).
- */
+/** Underground brackets (taking eliminated teams, negative placements) sourced from the given bracket. */
 export function undergroundBracketIdxs(
 	bracketIdx: number,
 	progression: ParsedBracket[],
@@ -1268,12 +1250,9 @@ export function startingBrackets(progression: ParsedBracket[]): number[] {
 }
 
 /**
- * Orders a bracket's sources for seeding purposes. Teams sourced with a better placement
- * in a shared ancestor bracket seed above teams that took a longer route there, e.g. if the top cut
- * sources both the top 2 of "Day 1 Pools" directly and the winners of a "Redemption" bracket
- * (itself sourcing pools placements 3-4), the direct pools source is ordered first.
- *
- * Sources that share no ancestor bracket keep their original relative order.
+ * Orders sources for seeding: a better placement in a shared ancestor bracket seeds above a longer
+ * route there, e.g. the top 2 of pools directly over the winners of a redemption bracket sourcing pools
+ * placements 3-4. Sources sharing no ancestor keep their relative order.
  */
 export function sortedSourcesForSeeding(
 	sources: DBSource[],
diff --git a/app/features/tournament-bracket/core/Seeding.ts b/app/features/tournament-bracket/core/Seeding.ts
index 2bb4d3f54..3a9595d74 100644
--- a/app/features/tournament-bracket/core/Seeding.ts
+++ b/app/features/tournament-bracket/core/Seeding.ts
@@ -1,7 +1,7 @@
 import { ordering } from "./engine/create/seeding";
 
 export interface FollowUpBracketSource {
-	/** Standings of the source bracket, best placements first. Tied placements (e.g. the winner of each group) form the tiers that seeding keeps intact. */
+	/** Best placements first. Tied placements (e.g. the winner of each group) form the tiers seeding keeps intact. */
 	standings: Array<{
 		tournamentTeamId: number;
 		placement: number;
@@ -27,21 +27,16 @@ interface Constraints {
 const MAX_SEARCH_NODES = 10_000;
 
 /**
- * Reorders teams advancing into a single or double elimination bracket so that:
+ * Reorders teams advancing into an elimination bracket so that:
  *
- * - teams sharing a source group spread evenly across the bracket's sections and can
- *   meet again only as late as the bracket allows (e.g. 4 groups of 4 into a 16 bracket:
- *   every quarter holds one team per group, so rivals can rematch in the semis at the earliest)
- * - teams that already faced each other do not rematch in round 1 (relevant e.g. when
- *   a single Swiss group feeds a top cut)
- * - placement tiers stay intact: a team never takes a seed reserved for a better
- *   placement, keeping byes and favorable lines with the top placing teams. The
- *   exception is the bottom half of a bracket sourced from a single group, where
- *   placements may be swapped to avoid round 1 rematches.
+ * - teams sharing a source group spread evenly and can rematch only as late as the bracket allows
+ *   (e.g. 4 groups of 4 into a 16 bracket: one team per group in every quarter, rematch in the semis at earliest)
+ * - teams that already faced each other do not rematch in round 1 (e.g. a single Swiss group feeding a top cut)
+ * - placement tiers stay intact: a team never takes a seed reserved for a better placement, except in
+ *   the bottom half of a bracket sourced from a single group, where placements may swap to avoid rematches
  *
- * Within those constraints the incoming order changes as little as possible. When the
- * constraints cannot all be satisfied they are relaxed step by step, and as the last
- * resort the teams are returned in the incoming order.
+ * The incoming order changes as little as possible. Unsatisfiable constraints are relaxed step by
+ * step, as the last resort the incoming order is returned.
  */
 export function forFollowUpBracket({
 	teams,
@@ -129,10 +124,10 @@ function resolveTeamMeta(teams: number[], sources: FollowUpBracketSource[]) {
 	return metaByTeamId;
 }
 
-/** When one group feeds the whole bracket its placements are all distinct and there
- * would be no freedom to avoid rematches. Mirroring how brackets are commonly
- * re-seeded by hand, the top half keeps its exact placements while the bottom half
- * placements become interchangeable. */
+/**
+ * One group feeding the whole bracket has all distinct placements, leaving no freedom to avoid rematches.
+ * As brackets are commonly re-seeded by hand, the top half keeps its placements, the bottom half's are interchangeable.
+ */
 function poolSingleGroupBottomHalf(
 	teams: number[],
 	sources: FollowUpBracketSource[],
@@ -178,9 +173,7 @@ function resolveClasses(teams: number[], metaByTeamId: Map<number, TeamMeta>) {
 	return classes;
 }
 
-/** The largest aligned lineup block a group's teams can be kept from sharing: with T
- * teams of a group in the bracket they fit into T disjoint blocks of bracketSize / T
- * slots, delaying their meetings the furthest the bracket structure allows. */
+/** With T teams of a group in the bracket they fit into T disjoint blocks of bracketSize / T slots, delaying their meetings the furthest. */
 function resolveIdealBlockSizes(
 	teams: number[],
 	metaByTeamId: Map<number, TeamMeta>,
@@ -228,9 +221,7 @@ function* relaxationLadder(
 	}
 }
 
-/** Depth-first search assigning the seeds best first, always trying the highest
- * ranked remaining team of the seed's tier first: the first solution found is the
- * one closest to the incoming order. */
+/** DFS assigning seeds best first, trying the highest ranked remaining team of the tier first, so the first solution is closest to the incoming order. */
 function search({
 	teams,
 	classes,
diff --git a/app/features/tournament-bracket/core/Tournament.server.ts b/app/features/tournament-bracket/core/Tournament.server.ts
index ed7c95d1b..8703e7e16 100644
--- a/app/features/tournament-bracket/core/Tournament.server.ts
+++ b/app/features/tournament-bracket/core/Tournament.server.ts
@@ -35,9 +35,7 @@ import {
 	type TournamentStream,
 } from "./Tournament";
 
-/**
- * Everything a tournament is made of including brackets and streams.
- */
+/** Everything a tournament is made of including brackets and streams. */
 export async function tournamentData(tournamentId: number) {
 	const ctx = await TournamentRepository.findById(tournamentId);
 	if (!ctx) return null;
@@ -74,11 +72,7 @@ export async function tournamentData(tournamentId: number) {
 	};
 }
 
-/**
- * Live streams of the tournament read fresh from the database, bypassing the tournament
- * data cache. The streams view and bracket views ship these; the cached copy (read once
- * per cache fill) only serves the server-side consumers of running tournaments.
- */
+/** Read fresh, bypassing the cache whose copy (read once per fill) only serves server-side consumers. */
 export async function fetchTournamentStreams(
 	tournamentId: number,
 ): Promise<TournamentStream[]> {
@@ -117,27 +111,20 @@ export async function fetchTournamentStreams(
 
 export type TournamentData = NonNullable<Unwrapped<typeof tournamentData>>;
 
-/**
- * What the tournament layout ships: everything every view needs and nothing a single view
- * needs. Match data is loaded per bracket by the views that render brackets.
- */
+/** What the layout ships: everything every view needs. Match data is loaded per bracket by the bracket views. */
 export type TournamentLayoutData = {
 	ctx: TournamentData["ctx"];
 	bracketsMeta: BracketDerivedMeta[];
 };
 
-/**
- * A tournament team as the tournament layout ships it: no per member profile data,
- * map pool or invite code. See {@link tournamentTeamsFullCached} for those.
- */
+/** No per member profile data, map pool or invite code, see {@link tournamentTeamsFullCached} for those. */
 export type TournamentDataTeam = Omit<
 	TournamentRepository.FindById["teams"][number],
 	"teamLogoUrl" | "pickupAvatarUrl" | "inviteCode"
 > & {
 	/**
-	 * Logo of the linked team, falling back to the pickup avatar once the tournament has
-	 * started. The views that show pickup avatars before that (own team, organizer views)
-	 * read them off {@link tournamentTeamsFullCached}, which censors per viewer.
+	 * Linked team logo, falling back to the pickup avatar once started. Views showing pickup avatars
+	 * before that (own team, organizer) read them off {@link tournamentTeamsFullCached}, censored per viewer.
 	 */
 	logoUrl: string | null;
 };
@@ -149,12 +136,8 @@ type TournamentVisibilityCtx = Pick<
 >;
 
 /**
- * Ensures the tournament may be seen by the given user. Draft tournaments are only visible
- * to their organizers.
- *
- * Every loader under the tournament layout route must run this (normally via
- * {@link tournamentFromParams}). They are each reachable on their own via single fetch,
- * without the layout loader (and its check) ever running.
+ * Every loader under the tournament layout must run this (normally via {@link tournamentFromParams}):
+ * single fetch reaches each without the layout loader's check.
  *
  * @throws {Response} 404 if the tournament is a draft the user is not an organizer of
  */
@@ -171,11 +154,7 @@ export function requireTournamentVisible({
 	throw new Response(null, { status: 404 });
 }
 
-/**
- * Throws an error toast unless the user is an organizer of the tournament. For guarding
- * a single `_action` branch; whole-route guards use {@link tournamentFromParams} with
- * `for: "organizer"` instead.
- */
+/** Guards a single `_action` branch; whole-route guards use {@link tournamentFromParams} with `for: "organizer"`. */
 export function requireTournamentOrganizer(
 	tournament: Tournament,
 	user: AuthenticatedUser,
@@ -184,7 +163,7 @@ export function requireTournamentOrganizer(
 	errorToastIfFalsy(tournament.isOrganizer(user), message);
 }
 
-/** Throws an error toast unless the user is an admin of the tournament. */
+/** Throws an error toast unless the user is an admin. */
 export function requireTournamentAdmin(
 	tournament: Tournament,
 	user: AuthenticatedUser,
@@ -197,15 +176,11 @@ type TournamentFromParamsOptions = {
 };
 
 /**
- * The shared preamble of `to.$id.*` loaders and actions: parses the tournament id from the
- * route params (404 on invalid), loads the tournament and runs the access guard.
+ * Preamble of `to.$id.*` loaders and actions: parses the id (404 on invalid), loads and guards.
  *
- * - `view`: anyone the tournament is visible to; cached read. The tournament is the same
- *   for every viewer, so one shared instance serves them all, amortizing bracket building.
- * - `action`: any logged-in user; fresh read from the database for actions that do their
- *   own per `_action` authorization.
- * - `organizer` / `admin`: like `action` but non-organizers/non-admins are redirected to
- *   the tournament front page.
+ * - `view`: anyone the tournament is visible to; shared cached instance, amortizing bracket building.
+ * - `action`: any logged-in user; fresh read for actions doing their own per `_action` authorization.
+ * - `organizer` / `admin`: like `action` but others are redirected to the tournament front page.
  */
 export async function tournamentFromParams(
 	params: Params<string>,
@@ -267,11 +242,9 @@ const TOURNAMENT_DATA_CACHE_TTL_MS = IN_MILLISECONDS.HALF_HOUR;
 
 type TournamentDataCacheEntry = {
 	storedAt: number;
-	// caching promise ensures that if many requests are made for the same tournament
-	// at the same time they reuse the same resolving promise
+	// concurrent requests for the same tournament reuse the same resolving promise
 	data: ReturnType<typeof tournamentData>;
-	// what the brackets derive from is the same for every viewer, so building them once
-	// per cache fill serves every request
+	// brackets are the same for every viewer, build once per cache fill
 	tournament?: Tournament;
 };
 
@@ -287,11 +260,7 @@ export async function tournamentDataCached(tournamentId: number) {
 	return notFoundIfNullish(await tournamentDataCacheEntry(tournamentId).data);
 }
 
-/**
- * A `Tournament` shared by every request for the lifetime of the cache entry. The bracket
- * level derivations (bracket state, standings, one bracket's data) are the same for every
- * viewer, so building the brackets happens once per cache fill instead of once per request.
- */
+/** Shared by every request for the lifetime of the cache entry, so brackets are built once per fill. */
 export async function tournamentSharedCached(tournamentId: number) {
 	if (ServerConfig.disableCache) {
 		return new Tournament(
@@ -308,7 +277,7 @@ export async function tournamentSharedCached(tournamentId: number) {
 	return entry.tournament;
 }
 
-/** State of every bracket of the tournament, without any of the match data it derives from. */
+/** State of every bracket without the match data it derives from. */
 export async function bracketsMetaCached(
 	tournamentId: number,
 ): Promise<BracketDerivedMeta[]> {
@@ -316,9 +285,8 @@ export async function bracketsMetaCached(
 }
 
 /**
- * One bracket with its match data, in the shape {@link Tournament.withBrackets} revives.
- * With a `groupId` only that group's rounds and matches are included, every group of the
- * bracket still being listed so that the view can offer switching to the others.
+ * In the shape {@link Tournament.withBrackets} revives. With a `groupId` only that group's rounds and
+ * matches are included, every group still listed so the view can offer switching.
  */
 export function serializeBracket(
 	bracket: Bracket,
@@ -376,7 +344,7 @@ function tournamentDataCacheEntry(tournamentId: number) {
 	return entry;
 }
 
-/** A tournament team with its full roster, as the views that render rosters get it. */
+/** Team with its full roster. */
 export type TournamentTeamFull = Unwrapped<typeof tournamentTeamsFullCached>;
 
 type TournamentTeamsCacheEntry = {
@@ -389,10 +357,7 @@ const tournamentTeamsCache = new LRUCache<number, TournamentTeamsCacheEntry>({
 	max: TOURNAMENT_DATA_CACHE_MAX_ENTRIES,
 });
 
-/**
- * Full rosters of a tournament's teams, censored for the given viewer. Its own cache
- * slice so that the (much smaller) tournament layout data does not have to carry them.
- */
+/** Full rosters censored for the viewer. Own cache slice so the much smaller layout data needn't carry them. */
 export async function tournamentTeamsFullCached({
 	user,
 	tournamentId,
@@ -427,10 +392,7 @@ export async function tournamentTeamsFullCached({
 	return entry.anonymousCensored;
 }
 
-/**
- * {@link tournamentTeamsFullCached} in the tournament's own seed order, which is not
- * the order the team rows come back in.
- */
+/** {@link tournamentTeamsFullCached} in seed order, which is not the order the rows come back in. */
 export async function tournamentTeamsFullInSeedOrder({
 	tournament,
 	user,
@@ -528,11 +490,7 @@ function isTournamentLive(tournament: Tournament) {
 	return Boolean(latestStartTime && latestStartTime >= cutoff);
 }
 
-/**
- * Re-evaluates liveness of every tournament in the running tournaments registry,
- * evicting those that are no longer live (e.g. abandoned tournaments whose latest
- * day started over 6 hours ago and no page load has triggered a re-sync).
- */
+/** Evicts no longer live tournaments (e.g. abandoned ones whose latest day started over 6 hours ago). */
 export function evictStaleRunningTournaments() {
 	for (const tournament of RunningTournaments.all) {
 		syncTournamentToRegistry(tournament);
@@ -556,11 +514,7 @@ function syncTournamentToRegistry(tournament: Tournament) {
 	}
 }
 
-/**
- * Rebuilds the running tournaments registry from the database, forgetting the
- * tournaments it held. E2E workers call this (via `/refresh-caches`) after
- * writing tournaments straight into the database file.
- */
+/** E2E workers call this (via `/refresh-caches`) after writing tournaments straight into the database file. */
 export async function refreshRunningTournaments() {
 	RunningTournaments.clear();
 
diff --git a/app/features/tournament-bracket/core/Tournament.test.ts b/app/features/tournament-bracket/core/Tournament.test.ts
index c482411fe..b5f92cda5 100644
--- a/app/features/tournament-bracket/core/Tournament.test.ts
+++ b/app/features/tournament-bracket/core/Tournament.test.ts
@@ -691,11 +691,7 @@ describe("teamById division seeds", () => {
 	});
 });
 
-/**
- * Plays a 4 team, 5 round, advance threshold 3 swiss all the way to its end.
- * Team 1 wins rounds 1-3 locking their top cut spot, after which the pairing
- * excludes them from the remaining rounds.
- */
+/** 4 teams, 5 rounds, advance threshold 3. Team 1 wins rounds 1-3 locking their spot, after which the pairing excludes them. */
 function playOutEarlyAdvanceSwiss(
 	progression: Progression.ParsedBracket[],
 ): BracketData {
diff --git a/app/features/tournament-bracket/core/Tournament.timezone.test.ts b/app/features/tournament-bracket/core/Tournament.timezone.test.ts
index 6fc2cb9c4..9ebb20261 100644
--- a/app/features/tournament-bracket/core/Tournament.timezone.test.ts
+++ b/app/features/tournament-bracket/core/Tournament.timezone.test.ts
@@ -2,8 +2,7 @@ import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { dateToDatabaseTimestamp } from "~/utils/dates";
 import { testTournament } from "./tests/test-utils";
 
-// in its own file because changing the process timezone affects every Date
-// operation of the worker while these tests run
+// own file because changing the process timezone affects every Date operation of the worker
 describe("regularCheckInStartsAt in a DST observing timezone", () => {
 	const ORIGINAL_TZ = process.env.TZ;
 
diff --git a/app/features/tournament-bracket/core/Tournament.ts b/app/features/tournament-bracket/core/Tournament.ts
index 3651f9dbf..de3d95d4e 100644
--- a/app/features/tournament-bracket/core/Tournament.ts
+++ b/app/features/tournament-bracket/core/Tournament.ts
@@ -28,10 +28,7 @@ import type { TournamentData } from "./Tournament.server";
 
 export type OptionalIdObject = { id: number } | undefined;
 
-/**
- * The state of one bracket that can only be derived from its match data. Shipped to the
- * views that render a tournament without loading any of its match data.
- */
+/** Bracket state derivable only from its match data, shipped to views that render without it. */
 export type BracketDerivedMeta = {
 	/** Stage id of a started bracket, placeholder id of a bracket that has not been started. */
 	id: number;
@@ -112,7 +109,7 @@ export type TournamentTeamMemberProgressStatus = NonNullable<
 	ReturnType<Tournament["teamMemberOfProgressStatus"]>
 >;
 
-/** Utility functions on top of the tournament's data. Updating the bracket data after the bracket has started is the responsibility of the bracket engine (`core/engine`). */
+/** Utilities on top of the tournament's data. Updating started bracket data is the engine's job (`core/engine`). */
 export class Tournament {
 	ctx;
 	/** See {@link TournamentArgs.participatedUsers}, null when this view did not get them. */
@@ -159,10 +156,7 @@ export class Tournament {
 		}
 	}
 
-	/**
-	 * The same tournament with the match data of the given brackets available. Used by the views
-	 * that load one bracket's data of their own, the layout only shipping {@link bracketsMeta}.
-	 */
+	/** Same tournament with the given brackets' match data, for views that load one bracket on top of {@link bracketsMeta}. */
 	withBrackets(
 		brackets: SerializedBracket[],
 		extras?: {
@@ -179,10 +173,7 @@ export class Tournament {
 		});
 	}
 
-	/**
-	 * Every bracket of the tournament. Building a bracket is expensive (preview brackets
-	 * are generated from scratch) so prefer {@link bracketByIdx} when only one is needed.
-	 */
+	/** Building a bracket is expensive (previews are generated from scratch), prefer {@link bracketByIdx} when only one is needed. */
 	get brackets(): Bracket[] {
 		if (!this._allBrackets) {
 			this._allBrackets = this.ctx.settings.bracketProgression.map(
@@ -193,10 +184,7 @@ export class Tournament {
 		return this._allBrackets;
 	}
 
-	/**
-	 * State of every bracket without its match data. Available in every view, unlike
-	 * {@link brackets} which needs the match data the bracket views load.
-	 */
+	/** State of every bracket without its match data. Available in every view, unlike {@link brackets}. */
 	get bracketsMeta(): BracketMeta[] {
 		if (this._bracketsMeta) return this._bracketsMeta;
 
@@ -225,20 +213,14 @@ export class Tournament {
 		return this._bracketsMeta;
 	}
 
-	/**
-	 * {@link bracketsMeta} of the brackets the user can switch between. Brackets that never
-	 * started are not shown once the tournament has been finalized.
-	 */
+	/** {@link bracketsMeta} the user can switch between: never started brackets are hidden once finalized. */
 	get visibleBracketsMeta(): BracketMeta[] {
 		return this.bracketsMeta.filter(
 			(bracket) => !this.ctx.isFinalized || !bracket.preview,
 		);
 	}
 
-	/**
-	 * Divisions of a league. Every starting bracket is a division of its own, identified by its
-	 * bracket idx, the brackets it feeds into (its playoffs) belonging to that division as well.
-	 */
+	/** League divisions: every starting bracket (by idx) plus the brackets it feeds into (its playoffs). */
 	get leagueDivisions(): BracketMeta[] {
 		if (!this.isLeague) return [];
 
@@ -463,9 +445,7 @@ export class Tournament {
 				allRelevantMatchesFinished = false;
 			}
 
-			// exclude teams that would be going to this bracket according
-			// to the bracket progression rules, but have been overridden
-			// by the TO to go somewhere else or get eliminated (in the case of destinationBracketIdx = -1)
+			// exclude teams the TO overrode to go elsewhere or be eliminated (destinationBracketIdx = -1)
 			const withOverriddenTeamsExcluded = sourcedTeams.filter(
 				(teamId) =>
 					!this.ctx.bracketProgressionOverrides.some(
@@ -517,7 +497,6 @@ export class Tournament {
 			})
 			.map(({ id }) => id);
 
-		// Filter out dropped teams from advancing to follow-up brackets
 		const allTeams = teams.concat(overridesWithoutRepeats);
 		const activeTeams = allTeams.filter((teamId) => {
 			const team = this.teamById(teamId);
@@ -565,7 +544,7 @@ export class Tournament {
 			type: Tables["TournamentStage"]["type"];
 		},
 	) {
-		// nothing to adjust for starting brackets, and group stages pair via their own logic
+		// starting brackets need no adjusting, group stages pair via their own logic
 		if (!bracket.sources || bracket.sources.length === 0) return teams;
 		if (bracket.type === "round_robin" || bracket.type === "swiss") {
 			return teams;
@@ -659,7 +638,7 @@ export class Tournament {
 		);
 	}
 
-	/** Is tournament ranked (affects SP/Skill). For tournament to be ranked the organizer needs to enable it and it needs to fit the conditions e.g. it needs to happen when a ranked season is active. */
+	/** Affects SP/Skill. Needs the organizer to enable it and conditions like an active ranked season. */
 	get ranked() {
 		return tournamentIsRanked({
 			isSetAsRanked: this.ctx.settings.isRanked,
@@ -669,12 +648,12 @@ export class Tournament {
 		});
 	}
 
-	/** Run as test tournament which don't show on calendar, give out results etc., default false */
+	/** Test tournaments don't show on the calendar, give out results etc. */
 	get isTest() {
 		return this.ctx.settings.isTest ?? false;
 	}
 
-	/** Draft tournament that is hidden during preparation, must be opened before bracket start */
+	/** Hidden during preparation, must be opened before bracket start. */
 	get isDraft() {
 		return this.ctx.settings.isDraft ?? false;
 	}
@@ -693,12 +672,12 @@ export class Tournament {
 		return null;
 	}
 
-	/** What is the format of the tournament 4v4 (default), 3v3, 2v2 or 1v1. */
+	/** Format: 4v4 (default), 3v3, 2v2 or 1v1. */
 	get minMembersPerTeam() {
 		return this.ctx.settings.minMembersPerTeam ?? 4;
 	}
 
-	/** Do teams need to pick map during registration, or is this TO's responsibility */
+	/** Teams pick maps during registration instead of the TO. */
 	get teamsPrePickMaps() {
 		return this.ctx.mapPickingStyle !== "TO";
 	}
@@ -708,7 +687,7 @@ export class Tournament {
 		return modesIncluded(this.ctx.mapPickingStyle, this.ctx.toSetMapPool);
 	}
 
-	/** Should the rules page (and its nav item) be shown. True if there are rules or any map pool to show. */
+	/** Rules page (and its nav item) is shown if there are rules or any map pool. */
 	get hasRulesPage() {
 		return (
 			this.ctx.hasRules ||
@@ -717,7 +696,7 @@ export class Tournament {
 		);
 	}
 
-	/** Generates a Splatoon 3 pool code to join the tournament match. It tries to make it so that teams don't need to change the pool all the time, but provides different ones not to run into the in-game limit of max people in a pool at a time. */
+	/** Splatoon 3 pool code for the match: stable so teams rarely change pools, varied enough to avoid the in-game pool size limit. */
 	resolvePoolCode({
 		hostingTeamId,
 		groupLetters,
@@ -738,16 +717,14 @@ export class Tournament {
 			.toUpperCase()
 			.slice(0, 3);
 
-		// handle tournament name not having letters by using a default prefix
+		// tournament name without letters
 		if (!prefix) {
 			prefix = ["AB", "CD", "EF", "GH", "IJ", "KL", "MN", "OP", "QR", "ST"][
 				this.ctx.id % 10
 			];
 		}
 
-		// for small tournaments there should be no risk that the pool gets full
-		// so to make it more convenient just use same suffix every match
-		// pool numbers are kept in the 1-9 range (0 is not used)
+		// small tournaments can't fill a pool so use the same suffix every match, kept in 1-9 (0 is not used)
 		const globalSuffix =
 			this.ctx.teams.length <= 20 ? (this.ctx.id % 9) + 1 : null;
 
@@ -761,7 +738,7 @@ export class Tournament {
 		};
 	}
 
-	/** Has tournament started, meaning that at least one bracket has started. Also finalized tournaments are considered started. */
+	/** At least one bracket has started. Finalized tournaments count as started. */
 	get hasStarted() {
 		return this.bracketsMeta.some((bracket) => !bracket.preview);
 	}
@@ -837,9 +814,8 @@ export class Tournament {
 		return idx;
 	}
 
-	/** Should it be possible for the given user to finalize this tournament at this time? */
 	canFinalize(user: OptionalIdObject) {
-		// can skip underground bracket
+		// underground bracket can be skipped
 		const relevantBrackets = this.bracketsMeta.filter(
 			(b) => !b.preview || !b.isUnderground,
 		);
@@ -851,9 +827,7 @@ export class Tournament {
 		);
 	}
 
-	/**
-	 * Checks if a team fulfills all the conditions to check-in. Returns the reason, if not.
-	 */
+	/** Returns the reason if the team can't check in. */
 	checkInConditionsFulfilledByTeamId(tournamentTeamId: number) {
 		const team = this.teamById(tournamentTeamId);
 		invariant(team, "Team not found");
@@ -876,12 +850,12 @@ export class Tournament {
 		return { isFulfilled: true, reason: null };
 	}
 
-	/** Is the tournament invitational meaning the organizer adds all teams and there is no public registration. */
+	/** Organizer adds all teams, no public registration. */
 	get isInvitational() {
 		return this.ctx.settings.isInvitational ?? false;
 	}
 
-	/** Does this tournament have the option for teams to look for more members via the integrated LFG-solution. Also applies to solo subs view (after registration is closed) */
+	/** Teams can look for members via the integrated LFG. Also applies to the solo subs view after registration closes. */
 	get lfgEnabled() {
 		return this.ctx.settings.enableSubs ?? true;
 	}
@@ -900,8 +874,7 @@ export class Tournament {
 		);
 	}
 
-	/** Can the organizer add a new sub post on behalf of a user at this time? Unlike users
-	 * the organizer is not limited by the registration closing early. */
+	/** Unlike users, the organizer is not limited by the registration closing early. */
 	get canAddNewSubPostAsOrganizer() {
 		if (!this.lfgEnabled) return false;
 		if (this.isInvitational) return false;
@@ -909,9 +882,8 @@ export class Tournament {
 		return !this.everyBracketOver;
 	}
 
-	/** what is the max amount of members teams can add in total? This limit doesn't apply to the organizer adding members to a team. */
+	/** Does not limit the organizer adding members to a team. */
 	get maxMembersPerTeam() {
-		// special format
 		if (this.minMembersPerTeam !== 4) return this.minMembersPerTeam;
 
 		if (this.ctx.settings.maxMembersPerTeam) {
@@ -921,7 +893,7 @@ export class Tournament {
 		return 6;
 	}
 
-	/** Is the regular check-in (check-in for the whole tournament) open at this time? */
+	/** Regular check-in = check-in for the whole tournament. */
 	get regularCheckInIsOpen() {
 		return (
 			this.regularCheckInStartsAt < new Date() &&
@@ -929,45 +901,38 @@ export class Tournament {
 		);
 	}
 
-	/** Has the regular check-in (check-in for the whole tournament) ended? */
 	get regularCheckInHasEnded() {
 		return this.ctx.startsAt < new Date();
 	}
 
-	/** Has the regular check-in (check-in for the whole tournament) started? Note it is also considered started if it has ended. */
+	/** Also true once check-in has ended. */
 	get regularCheckInStartInThePast() {
 		return this.regularCheckInStartsAt < new Date();
 	}
 
-	/** Date when the regular check-in is scheduled to start. */
 	get regularCheckInStartsAt() {
-		// elapsed time math instead of wall clock math so that the window
-		// stays one hour long across a DST transition
+		// elapsed time math so the window stays one hour long across a DST transition
 		return new Date(this.ctx.startsAt.getTime() - 60 * 60 * 1000);
 	}
 
-	/** Date when the regular check-in is scheduled to start. */
 	get regularCheckInEndsAt() {
 		return this.ctx.startsAt;
 	}
 
-	/** Date when the tournament registration is scheduled to end. This can be set by the organizer. */
+	/** Set by the organizer, defaults to the start time. */
 	get registrationClosesAt() {
 		return this.ctx.settings.regClosesAt
 			? databaseTimestampToDate(this.ctx.settings.regClosesAt)
 			: this.ctx.startsAt;
 	}
 
-	/** Is the tournament registration open at this time? */
 	get registrationOpen() {
 		if (this.isInvitational) return false;
 
 		return this.registrationClosesAt > new Date();
 	}
 
-	/** Can participants submit/undo their own weapon reports right now?
-	 * Always open while the tournament is running; once finalized it stays open only for tournaments
-	 * whose start time is inside the current-season-plus-adjacent-off-season window. */
+	/** Always open while running; once finalized only while the start time is inside the current season plus adjacent off-season. */
 	get weaponReportingOpen() {
 		if (!this.ctx.isFinalized) return true;
 		return tournamentInWeaponReportingWindow({
@@ -975,23 +940,17 @@ export class Tournament {
 		});
 	}
 
-	/**
-	 * Does this tournament have autonomous subs feature enabled?
-	 * If enabled, teams can add members to their roster while tournament is in progress without having to request the organizer to do it.
-	 * */
+	/** Teams can add members to their roster while the tournament is in progress without asking the organizer. */
 	get autonomousSubs() {
 		return this.ctx.settings.autonomousSubs ?? true;
 	}
 
-	/**
-	 * Is this tournament a league? A league is played over many weeks, each starting bracket
-	 * being a division that teams are placed in by the organizer.
-	 * */
+	/** Played over many weeks, each starting bracket a division the organizer places teams in. */
 	get isLeague() {
 		return this.ctx.settings.isLeague === true;
 	}
 
-	/** Does this tournament have many brackets that act as the first bracket? In this format many bracket progressions advance independently from each other (so not all teams can meet). */
+	/** Many first brackets whose progressions advance independently (so not all teams can meet). */
 	get isMultiStartingBracket() {
 		let count = 0;
 		for (const bracket of this.ctx.settings.bracketProgression) {
@@ -1001,7 +960,6 @@ export class Tournament {
 		return count > 1;
 	}
 
-	/** Can the given user's team check in to the bracket at this time? */
 	canCheckInToBracket(bracketIdx: number, user: OptionalIdObject) {
 		const bracket = this.bracketMetaByIdx(bracketIdx);
 		// using regular check-in
@@ -1021,10 +979,7 @@ export class Tournament {
 		return bracket.teamsPendingCheckIn.includes(team.id);
 	}
 
-	/** Returns the bracket and round names for the given match ID.
-	 * @example
-	 * tournament.matchNameById(123) // { bracketName: "Groups Stage", roundName: "Round 1.1", roundNameWithoutMatchIdentifier: "Round 1" }
-	 */
+	/** @example matchContextNamesById(123) // { bracketName: "Groups Stage", roundName: "Round 1.1", roundNameWithoutMatchIdentifier: "Round 1" } */
 	matchContextNamesById(matchId: number) {
 		let bracketName: string | undefined;
 		let roundName: string | undefined;
@@ -1124,26 +1079,21 @@ export class Tournament {
 		};
 	}
 
-	/** Returns a `Bracket` with the given index or null if not found. */
 	bracketByIdx(idx: number) {
 		if (!this.ctx.settings.bracketProgression[idx]) return null;
-		// a bracket that sources teams from itself (directly or via another bracket) can't be built
+		// a bracket sourcing teams from itself (directly or via another bracket) can't be built
 		if (this.bracketIdxsBeingBuilt.has(idx)) return null;
 
 		return this.builtBracketByIdx(idx);
 	}
 
-	/** Returns the team that the user is the owner of, or null if not found. */
 	ownedTeamByUser(user: OptionalIdObject) {
 		if (!user) return null;
 
 		return this.ctx.teams.find((team) => team.ownerUserId === user.id) ?? null;
 	}
 
-	/**
-	 * Returns the team that the user is a member of, or null if not found.
-	 * Note that user can be a member of multiple teams, this returns the team that the user joined most recently.
-	 */
+	/** A user can be a member of multiple teams, this returns the most recently joined one. */
 	teamMemberOfByUser(user: OptionalIdObject) {
 		if (!user) return null;
 
@@ -1156,15 +1106,7 @@ export class Tournament {
 		return teams.find((team) => team.id === latestTeamId) ?? teams[0];
 	}
 
-	/**
-	 * Returns the progress status of the user in the tournament, or null if not participating.
-	 * e.g. might return "WAITING_FOR_MATCH" if the user is waiting for their next match or "WAITING_FOR_CAST" if the match is ready to be played but locked waiting for the cast.
-	 */
-	/**
-	 * The started brackets, built without generating the previews of the others.
-	 * Generating a preview bracket is expensive, so prefer this over filtering
-	 * {@link brackets} when only the started ones are needed.
-	 */
+	/** Generating a preview bracket is expensive, prefer this over filtering {@link brackets} for the started ones. */
 	private get startedBrackets(): Bracket[] {
 		const data = this.data;
 		if (!data) return this.brackets.filter((bracket) => !bracket.preview);
@@ -1177,6 +1119,7 @@ export class Tournament {
 		);
 	}
 
+	/** Null if not participating. e.g. "WAITING_FOR_MATCH", or "WAITING_FOR_CAST" when ready but locked for the cast. */
 	teamMemberOfProgressStatus(user: OptionalIdObject) {
 		const team = this.teamMemberOfByUser(user);
 		if (!team) return null;
@@ -1255,8 +1198,7 @@ export class Tournament {
 
 		for (const bracket of startedBrackets) {
 			if (bracket.type !== "swiss") continue;
-			// dropped out teams and teams whose run ended early via the advance
-			// threshold are excluded from the pairing, so no round is coming for them
+			// dropped out teams and runs ended early by the advance threshold get no further rounds
 			if (bracket.everyMatchOver || team.droppedOut) continue;
 
 			// TODO: both seeding and participantTournamentTeamIds are used for the same thing
@@ -1322,15 +1264,12 @@ export class Tournament {
 		return { type: "THANKS_FOR_PLAYING" } as const;
 	}
 
-	/**
-	 * Can the given match be reopened? This is used to allow reopening matches were the wrong score was reported.
-	 * In principle match can be reopened as long as no match that follows it has started.
-	 */
+	/** For fixing wrongly reported scores. A match can be reopened as long as no match following it has started. */
 	matchCanBeReopened(matchId: number) {
 		if (this.ctx.isFinalized) return false;
 
 		const allMatches = this.brackets.flatMap((bracket) =>
-			// preview matches don't even have real id's and anyway don't prevent anything
+			// preview matches have no real ids and don't block anything
 			bracket.preview ? [] : bracket.data.match,
 		);
 		const match = allMatches.find((match) => match.id === matchId);
@@ -1369,10 +1308,8 @@ export class Tournament {
 
 		const anotherMatchBlocking = this.followingMatches(matchId).some(
 			(match) =>
-				// in swiss matches are generated round by round and the existence
-				// of a following match in itself is blocking even if they didn't start yet
+				// swiss rounds are generated one by one so a following match blocks even if not started
 				bracket.type === "swiss" ||
-				// match is not in progress in un-swiss bracket, ok to reopen
 				(match.opponent1?.score && match.opponent1.score > 0) ||
 				(match.opponent2?.score && match.opponent2.score > 0),
 		);
@@ -1409,7 +1346,7 @@ export class Tournament {
 		return participantInAnotherBracket;
 	}
 
-	/** Returns matches that follow the given match in the same bracket and stage, but only if they have the same participants and come after the given match. */
+	/** Later matches of the same bracket & stage sharing a participant with the given match. */
 	followingMatches(matchId: number) {
 		const match = this.brackets
 			.flatMap((bracket) => bracket.data.match)
@@ -1428,7 +1365,6 @@ export class Tournament {
 
 		return bracket.data.match
 			.filter(
-				// only interested in matches of the same bracket & not the match  itself
 				(match2) => match2.stageId === match.stageId && match2.id !== match.id,
 			)
 			.filter((match2) => {
@@ -1445,27 +1381,23 @@ export class Tournament {
 			});
 	}
 
-	/** Checks if the given user is an admin of the tournament. */
 	isAdmin(user: OptionalIdObject) {
 		return hasPermission(this.ctx, "ADMIN", user);
 	}
 
-	/** Checks if the given user can edit the tournament's calendar event info. */
 	canEditEventInfo(user: OptionalIdObject) {
 		return hasPermission(this.ctx, "EDIT_EVENT_INFO", user);
 	}
 
-	/** Checks if the given user can set the in-game names of the tournament's players. */
+	/** In-game names of the tournament's players. */
 	canEditTournamentNames(user: OptionalIdObject) {
 		return hasPermission(this.ctx, "EDIT_IN_GAME_NAMES", user);
 	}
 
-	/** Checks if the given user is an organizer of the tournament. */
 	isOrganizer(user: OptionalIdObject) {
 		return hasPermission(this.ctx, "ORGANIZE", user);
 	}
 
-	/** Checks if the given user is an organizer or streamer of the tournament. */
 	isOrganizerOrStreamer(user: OptionalIdObject) {
 		return hasPermission(this.ctx, "MANAGE_MATCHES", user);
 	}
diff --git a/app/features/tournament-bracket/core/engine/create/builder.ts b/app/features/tournament-bracket/core/engine/create/builder.ts
index 09ef4aa60..a36e6d13b 100644
--- a/app/features/tournament-bracket/core/engine/create/builder.ts
+++ b/app/features/tournament-bracket/core/engine/create/builder.ts
@@ -19,12 +19,7 @@ import {
 	padSeedingToPowerOfTwo,
 } from "./seeding";
 
-/**
- * Accumulates the rows of a stage being created. Pure port of the old
- * brackets-manager `Create` class: same call order, same inserted values, but
- * rows are collected into arrays with local ids (0..n-1 per table) instead of
- * being written to storage.
- */
+/** Accumulates the rows of a stage being created, with local ids (0..n-1 per table). */
 export class StageCreator {
 	readonly input: ResolvedCreateBracketInput;
 	settings: StageSettings;
@@ -61,11 +56,7 @@ export class StageCreator {
 		return id;
 	}
 
-	/**
-	 * Creates a round-robin group.
-	 *
-	 * This will make as many rounds as needed to let each participant match every other once.
-	 */
+	/** As many rounds as needed for each participant to play every other once. */
 	createRoundRobinGroup(
 		stageId: number,
 		number: number,
@@ -76,11 +67,8 @@ export class StageCreator {
 			number,
 		});
 
-		// Groups can be padded with empty slots when teams don't divide evenly
-		// (`null`) or by the seed ordering (`undefined`). An empty slot is just an
-		// absent team, so drop it to round-robin only the present teams — otherwise
-		// the padding becomes BYE rounds that strand real matches in later rounds.
-		// TBD slots (`{ id: null }`) are kept; only nullish placeholders are removed.
+		// padding slots (`null` from uneven teams, `undefined` from seed ordering) would become BYE rounds
+		// that strand real matches in later rounds, so drop them. TBD slots (`{ id: null }`) are kept.
 		const presentSlots = slots.filter(
 			(slot) => slot !== null && slot !== undefined,
 		);
@@ -91,9 +79,7 @@ export class StageCreator {
 			this.createRound(stageId, groupId, i + 1, rounds[0].length, rounds[i]);
 	}
 
-	/**
-	 * Creates a bipartite round-robin group where every A team plays every B team exactly once.
-	 */
+	/** Bipartite round-robin: every A team plays every B team exactly once. */
 	createAbDivisionRoundRobinGroup(
 		stageId: number,
 		number: number,
@@ -111,11 +97,7 @@ export class StageCreator {
 			this.createRound(stageId, groupId, i + 1, rounds[0].length, rounds[i]);
 	}
 
-	/**
-	 * Creates a standard bracket, which is the only one in single elimination and the upper one in double elimination.
-	 *
-	 * This will make as many rounds as needed to end with one winner.
-	 */
+	/** The only bracket in single elimination, the upper one in double elimination. */
 	createStandardBracket(
 		stageId: number,
 		number: number,
@@ -142,12 +124,7 @@ export class StageCreator {
 		return { losers, winner: helpers.byeWinner(duels[0]) };
 	}
 
-	/**
-	 * Creates a lower bracket, alternating between major and minor rounds.
-	 *
-	 * - A major round is a regular round.
-	 * - A minor round matches the previous (major) round's winners against upper bracket losers of the corresponding round.
-	 */
+	/** Alternates major (regular) rounds and minor rounds where the major round's winners meet upper bracket losers. */
 	createLowerBracket(
 		stageId: number,
 		number: number,
@@ -195,9 +172,7 @@ export class StageCreator {
 		return helpers.byeWinnerToGrandFinal(duels[0]);
 	}
 
-	/**
-	 * Creates a bracket with rounds that only have 1 match each. Used for finals.
-	 */
+	/** Rounds of 1 match each, used for finals. */
 	createUniqueMatchBracket(
 		stageId: number,
 		number: number,
@@ -212,9 +187,6 @@ export class StageCreator {
 			this.createRound(stageId, groupId, i + 1, 1, [duels[i]]);
 	}
 
-	/**
-	 * Creates a round, which contain matches.
-	 */
 	createRound(
 		stageId: number,
 		groupId: number,
@@ -233,9 +205,6 @@ export class StageCreator {
 		}
 	}
 
-	/**
-	 * Creates a match of the stage.
-	 */
 	createMatch(
 		stageId: number,
 		groupId: number,
@@ -246,7 +215,7 @@ export class StageCreator {
 		const opponent1 = helpers.toResultWithPosition(opponents[0]);
 		const opponent2 = helpers.toResultWithPosition(opponents[1]);
 
-		// Round-robin matches can easily be removed. Prevent BYE vs. BYE matches.
+		// no BYE vs. BYE matches in round robin
 		if (
 			this.input.type === "round_robin" &&
 			opponent1 === null &&
@@ -265,11 +234,7 @@ export class StageCreator {
 		});
 	}
 
-	/**
-	 * Gets the duels for the current round based on the previous one. No ordering is done for
-	 * major rounds, it must be done beforehand for the first round. Ordering is done for LB
-	 * minor rounds via the given method.
-	 */
+	/** No ordering for major rounds (the first round must be ordered beforehand), LB minor rounds use the given method. */
 	getCurrentDuels(previousDuels: Duel[], currentDuelCount: number): Duel[];
 	getCurrentDuels(
 		previousDuels: Duel[],
@@ -303,14 +268,10 @@ export class StageCreator {
 			return helpers.transitionToMajor(previousDuels);
 		}
 
-		// From major to minor (LB).
-		// Losers and method won't be undefined.
+		// From major to minor (LB). Losers and method won't be undefined.
 		return helpers.transitionToMinor(previousDuels, losers!, method);
 	}
 
-	/**
-	 * Returns the list of slots from the seeding.
-	 */
 	getSlots(): ParticipantSlot[] {
 		helpers.ensureValidSize(this.input.type, this.seeding.length);
 		helpers.ensureNoDuplicates(this.seeding);
@@ -318,9 +279,6 @@ export class StageCreator {
 		return this.getSlotsUsingIds(this.seeding);
 	}
 
-	/**
-	 * Returns the list of slots with a seeding containing IDs.
-	 */
 	private getSlotsUsingIds(seeding: Seeding): ParticipantSlot[] {
 		return seeding.map((slot, i) => {
 			if (slot === null) return null; // BYE.
@@ -329,30 +287,22 @@ export class StageCreator {
 		});
 	}
 
-	/**
-	 * The only major ordering for the lower bracket.
-	 */
+	/** The only major ordering for the lower bracket. */
 	private getMajorOrdering(participantCount: number): SeedOrdering {
 		return defaultMinorOrdering[participantCount]?.[0] || "natural";
 	}
 
-	/**
-	 * A minor ordering for the lower bracket by its index.
-	 */
 	private getMinorOrdering(
 		participantCount: number,
 		index: number,
 		minorRoundCount: number,
 	): SeedOrdering | undefined {
-		// No ordering for the last minor round. There is only one participant to order.
+		// the last minor round has only one participant to order
 		if (index === minorRoundCount - 1) return undefined;
 
 		return defaultMinorOrdering[participantCount]?.[1 + index] || "natural";
 	}
 
-	/**
-	 * Creates the stage row.
-	 */
 	createStage(): StageData {
 		const stage: StageData = {
 			id: 0,
diff --git a/app/features/tournament-bracket/core/engine/create/double-elimination.ts b/app/features/tournament-bracket/core/engine/create/double-elimination.ts
index f55b6b752..87148bd50 100644
--- a/app/features/tournament-bracket/core/engine/create/double-elimination.ts
+++ b/app/features/tournament-bracket/core/engine/create/double-elimination.ts
@@ -3,12 +3,7 @@ import type { StageCreator } from "./builder";
 import * as helpers from "./helpers";
 import { ordering, STANDARD_BRACKET_FIRST_ROUND_ORDERING } from "./seeding";
 
-/**
- * Creates a double elimination stage.
- *
- * One upper bracket (winner bracket, WB), one lower bracket (loser bracket, LB) and a double grand final
- * between the winner of both brackets.
- */
+/** Winner bracket (WB), loser bracket (LB) and a double grand final between the winners of both. */
 export function createDoubleElimination(creator: StageCreator): void {
 	const slots = creator.getSlots();
 	const stage = creator.createStage();
@@ -26,9 +21,7 @@ export function createDoubleElimination(creator: StageCreator): void {
 	}
 }
 
-/**
- * Creates a double grand final for winners of both brackets in a double elimination stage.
- */
+/** Double grand final for the winners of both brackets. */
 function createGrandFinal(
 	creator: StageCreator,
 	stageId: number,
diff --git a/app/features/tournament-bracket/core/engine/create/helpers.test.ts b/app/features/tournament-bracket/core/engine/create/helpers.test.ts
index ab61de344..d47484e30 100644
--- a/app/features/tournament-bracket/core/engine/create/helpers.test.ts
+++ b/app/features/tournament-bracket/core/engine/create/helpers.test.ts
@@ -334,12 +334,6 @@ describe("Seed ordering methods", () => {
 	});
 });
 
-/**
- * A helper to assert our generated round-robin is correct.
- *
- * @param input The input seeding.
- * @param output The resulting distribution of seeds in groups.
- */
 function assertRoundRobin(input: number[], output: [number, number][][]): void {
 	const n = input.length;
 	const matchPerRound = Math.floor(n / 2);
@@ -378,13 +372,6 @@ function assertRoundRobin(input: number[], output: [number, number][][]): void {
 	}
 }
 
-/**
- * A helper to assert our generated bipartite round-robin is correct.
- *
- * @param divisionA Seeds in division A (ordered by seed).
- * @param divisionB Seeds in division B (ordered by seed).
- * @param output The resulting rounds of matches.
- */
 function assertAbDivisionRoundRobin(
 	divisionA: number[],
 	divisionB: number[],
diff --git a/app/features/tournament-bracket/core/engine/create/helpers.ts b/app/features/tournament-bracket/core/engine/create/helpers.ts
index 971238ee6..1d9a2a7e6 100644
--- a/app/features/tournament-bracket/core/engine/create/helpers.ts
+++ b/app/features/tournament-bracket/core/engine/create/helpers.ts
@@ -1,11 +1,7 @@
 import type { Duel, ParticipantSlot, SeedOrdering, StageType } from "../types";
 import { ordering } from "./seeding";
 
-/**
- * Makes a list of rounds containing the matches of a round-robin group.
- *
- * @param participants The participants to distribute.
- */
+/** Rounds of matches for a round-robin group. */
 export function makeRoundRobinMatches<T>(participants: T[]): [T, T][][] {
 	const n = participants.length;
 	const n1 = n % 2 === 0 ? n : n + 1;
@@ -38,18 +34,10 @@ export function makeRoundRobinMatches<T>(participants: T[]): [T, T][][] {
 }
 
 /**
- * Makes a list of rounds containing the matches of a bipartite (A/B divisions) round-robin group.
- *
- * Every A team plays every B team exactly once; there are no A-vs-A or B-vs-B matches.
- * Round 1 is cross-seeded (strongest A vs weakest B), and B is rotated cyclically downward
- * in each subsequent round.
- *
- * When the divisions have different sizes, the shorter side is padded with bye slots so the
- * rotation still works. Those bye pairings are filtered out of the output, so each round has
- * exactly `min(|A|, |B|)` real matches and the total is `|A| * |B|`.
- *
- * @param divisionA Participants in division A, ordered by seed.
- * @param divisionB Participants in division B, ordered by seed.
+ * Rounds of matches for a bipartite (A/B divisions) round-robin group: every A team plays every
+ * B team exactly once. Round 1 is cross-seeded (strongest A vs weakest B), B rotates downward each
+ * round. Uneven divisions are padded with byes that are filtered out, so each round has
+ * `min(|A|, |B|)` matches and the total is `|A| * |B|`. Both divisions ordered by seed.
  */
 export function makeAbDivisionRoundRobinMatches<T>(
 	divisionA: T[],
@@ -84,16 +72,8 @@ export function makeAbDivisionRoundRobinMatches<T>(
 }
 
 /**
- * Distributes A/B division participants into groups such that each group has an
- * equal number of A and B participants.
- *
- * The snake ordering used by `groups.seed_optimized` is applied independently to
- * each pool, so that relative seed order within each pool is preserved within
- * every group.
- *
- * @param divisionA Participants in division A, ordered by seed.
- * @param divisionB Participants in division B, ordered by seed.
- * @param groupCount Number of groups to distribute into.
+ * Distributes A/B division participants (ordered by seed) into groups with an equal number of A
+ * and B in each. `groups.seed_optimized` snake ordering is applied to each division independently.
  */
 export function makeAbDivisionGroups<T>(
 	divisionA: T[],
@@ -130,12 +110,7 @@ export function makeAbDivisionGroups<T>(
 	return groups;
 }
 
-/**
- * Distributes elements in groups of equal size.
- *
- * @param elements A list of elements to distribute in groups.
- * @param groupCount The group count.
- */
+/** Distributes elements in groups of equal size. */
 export function makeGroups<T>(elements: T[], groupCount: number): T[][] {
 	const groupSize = Math.ceil(elements.length / groupCount);
 	const result: T[][] = [];
@@ -149,23 +124,14 @@ export function makeGroups<T>(elements: T[], groupCount: number): T[][] {
 	return result;
 }
 
-/**
- * Makes pairs with each element and its next one.
- *
- * @example [1, 2, 3, 4] --> [[1, 2], [3, 4]]
- * @param array A list of elements.
- */
+/** [1, 2, 3, 4] --> [[1, 2], [3, 4]] */
 export function makePairs<T>(array: T[]): [T, T][] {
 	return array
 		.map((_, i) => (i % 2 === 0 ? [array[i], array[i + 1]] : []))
 		.filter((v): v is [T, T] => v.length === 2);
 }
 
-/**
- * Ensures there are no duplicates in a list of elements.
- *
- * @param array A list of elements.
- */
+/** Throws if the seeding has a duplicate participant. */
 export function ensureNoDuplicates<T>(array: (T | null)[]): void {
 	const nonNull = getNonNull(array);
 	const unique = nonNull.filter((item, index) => {
@@ -180,12 +146,7 @@ export function ensureNoDuplicates<T>(array: (T | null)[]): void {
 		throw new Error("The seeding has a duplicate participant.");
 }
 
-/**
- * Ensures that the participant count is valid.
- *
- * @param stageType Type of the stage to test.
- * @param participantCount The number to test.
- */
+/** Throws if the participant count is invalid for the stage type. */
 export function ensureValidSize(
 	stageType: StageType,
 	participantCount: number,
@@ -194,7 +155,6 @@ export function ensureValidSize(
 		throw Error("Impossible to create a stage with less than 2 participants.");
 
 	if (stageType === "round_robin") {
-		// Round robin supports any number of participants.
 		return;
 	}
 
@@ -204,11 +164,7 @@ export function ensureValidSize(
 		);
 }
 
-/**
- * Converts a participant slot to a result stored in storage, with the position the participant is coming from.
- *
- * @param slot A participant slot.
- */
+/** Participant slot as a stored result, with the position the participant is coming from. */
 export function toResultWithPosition(slot: ParticipantSlot): ParticipantSlot {
 	return (
 		slot && {
@@ -218,59 +174,38 @@ export function toResultWithPosition(slot: ParticipantSlot): ParticipantSlot {
 	);
 }
 
-/**
- * Returns the pre-computed winner for a match because of BYEs.
- *
- * @param opponents Two opponents.
- */
+/** Pre-computed winner of a match because of BYEs. */
 export function byeWinner(opponents: Duel): ParticipantSlot {
 	if (opponents[0] === null && opponents[1] === null)
 		// Double BYE.
-		return null; // BYE.
+		return null;
 
 	if (opponents[0] === null && opponents[1] !== null)
-		// opponent1 BYE.
-		return { id: opponents[1].id }; // opponent2.
+		return { id: opponents[1].id };
 
 	if (opponents[0] !== null && opponents[1] === null)
-		// opponent2 BYE.
-		return { id: opponents[0].id }; // opponent1.
+		return { id: opponents[0].id };
 
-	return { id: null }; // Normal.
+	return { id: null };
 }
 
-/**
- * Returns the pre-computed winner for a match because of BYEs in a lower bracket.
- *
- * @param opponents Two opponents.
- */
+/** Pre-computed winner of a lower bracket match because of BYEs. */
 export function byeWinnerToGrandFinal(opponents: Duel): ParticipantSlot {
 	const winner = byeWinner(opponents);
 	if (winner) winner.position = 1;
 	return winner;
 }
 
-/**
- * Returns the pre-computed loser for a match because of BYEs.
- *
- * Only used for loser bracket.
- *
- * @param opponents Two opponents.
- * @param index The index of the duel in the round.
- */
+/** Pre-computed loser of a match because of BYEs. Only used for loser bracket. */
 export function byeLoser(opponents: Duel, index: number): ParticipantSlot {
 	if (opponents[0] === null || opponents[1] === null)
 		// At least one BYE.
-		return null; // BYE.
+		return null;
 
-	return { id: null, position: index + 1 }; // Normal.
+	return { id: null, position: index + 1 };
 }
 
-/**
- * Makes the transition to a major round for duels of the previous round. The duel count is divided by 2.
- *
- * @param previousDuels The previous duels to transition from.
- */
+/** Transition to a major round: the duel count is halved. */
 export function transitionToMajor(previousDuels: Duel[]): Duel[] {
 	const currentDuelCount = previousDuels.length / 2;
 	const currentDuels: Duel[] = [];
@@ -286,13 +221,7 @@ export function transitionToMajor(previousDuels: Duel[]): Duel[] {
 	return currentDuels;
 }
 
-/**
- * Makes the transition to a minor round for duels of the previous round. The duel count stays the same.
- *
- * @param previousDuels The previous duels to transition from.
- * @param losers Losers from the previous major round.
- * @param method The ordering method for the losers.
- */
+/** Transition to a minor round: the duel count stays the same, losers of the previous major round join. */
 export function transitionToMinor(
 	previousDuels: Duel[],
 	losers: ParticipantSlot[],
@@ -313,44 +242,24 @@ export function transitionToMinor(
 	return currentDuels;
 }
 
-/**
- * Returns the number of rounds an upper bracket has given the number of participants in the stage.
- *
- * @param participantCount The number of participants in the stage.
- */
+/** Number of rounds in an upper bracket. */
 export function getUpperBracketRoundCount(participantCount: number): number {
 	return Math.log2(participantCount);
 }
 
-/**
- * Returns the count of round pairs (major & minor) in a loser bracket.
- *
- * @param participantCount The number of participants in the stage.
- */
+/** Count of round pairs (major & minor) in a loser bracket. */
 export function getRoundPairCount(participantCount: number): number {
 	return getUpperBracketRoundCount(participantCount) - 1;
 }
 
-/**
- * Determines whether a double elimination stage is really necessary.
- *
- * If the size is only two (less is impossible), then a lower bracket and a grand final are not necessary.
- *
- * @param participantCount The number of participants in the stage.
- */
+/** With only two participants a lower bracket and a grand final are not necessary. */
 export function isDoubleEliminationNecessary(
 	participantCount: number,
 ): boolean {
 	return participantCount > 2;
 }
 
-/**
- * Returns only the non null elements.
- *
- * @param array The array to process.
- */
 function getNonNull<T>(array: (T | null)[]): T[] {
-	// Use a TS type guard to exclude null from the resulting type.
 	const nonNull = array.filter((element): element is T => element !== null);
 	return nonNull;
 }
diff --git a/app/features/tournament-bracket/core/engine/create/index.ts b/app/features/tournament-bracket/core/engine/create/index.ts
index 224d07ec5..69d4fc76a 100644
--- a/app/features/tournament-bracket/core/engine/create/index.ts
+++ b/app/features/tournament-bracket/core/engine/create/index.ts
@@ -14,10 +14,8 @@ import { createSingleElimination } from "./single-elimination";
 import { createSwiss } from "./swiss";
 
 /**
- * Generates the full structure for a new bracket of any type from the
- * user-selected settings. Pure function: returns rows with local ids
- * (0..n-1 per table); the repository maps them to real row ids on insert.
- * For swiss this includes the empty future rounds + round 1 matches.
+ * Full structure of a new bracket with local ids (0..n-1 per table) the repository maps to row ids on
+ * insert. Swiss gets its empty future rounds + round 1 matches.
  */
 export function create(input: CreateBracketInput): BracketData {
 	const data = createResolved({
@@ -35,11 +33,7 @@ export function create(input: CreateBracketInput): BracketData {
 	return data;
 }
 
-/**
- * Engine-internal `create` taking already-resolved internal stage settings.
- * Tests use this to control knobs that are an implementation detail to the
- * app (seed ordering, byes balancing).
- */
+/** `create` with resolved internal settings, letting tests control seed ordering and byes balancing. */
 export function createResolved(input: ResolvedCreateBracketInput): BracketData {
 	if (input.type === "swiss") return createSwiss(input);
 
@@ -76,8 +70,7 @@ function attachRoundMaps(
 	};
 
 	if (type === "round_robin" || type === "swiss") {
-		// groups share one map list per round number, and groups can have
-		// different round counts when teams divide unevenly
+		// groups share one map list per round number and can have different round counts
 		const distinctRoundNumberCount = new Set(
 			data.round.map((round) => round.number),
 		).size;
diff --git a/app/features/tournament-bracket/core/engine/create/round-robin.test.ts b/app/features/tournament-bracket/core/engine/create/round-robin.test.ts
index 7d6bdaa99..40e3bbda9 100644
--- a/app/features/tournament-bracket/core/engine/create/round-robin.test.ts
+++ b/app/features/tournament-bracket/core/engine/create/round-robin.test.ts
@@ -33,9 +33,7 @@ describe("Create a round-robin stage", () => {
 	});
 
 	test("does not pad a short group with empty rounds when teams divide unevenly", () => {
-		// 5 teams in 2 groups -> groups of 3 and 2. The 2-team group must be a
-		// clean single-round single-match group, not padded with BYE-only rounds
-		// that strand the real match in a later round.
+		// the 2-team group must be a single-round single-match group, not padded with BYE-only rounds
 		const data = createResolved({
 			type: "round_robin",
 			seeding: [1, 2, 3, 4, 5],
diff --git a/app/features/tournament-bracket/core/engine/create/round-robin.ts b/app/features/tournament-bracket/core/engine/create/round-robin.ts
index 024f6a515..68c233bcd 100644
--- a/app/features/tournament-bracket/core/engine/create/round-robin.ts
+++ b/app/features/tournament-bracket/core/engine/create/round-robin.ts
@@ -3,11 +3,7 @@ import type { StageCreator } from "./builder";
 import * as helpers from "./helpers";
 import { ordering } from "./seeding";
 
-/**
- * Creates a round-robin stage.
- *
- * Group count must be given. It will distribute participants in groups and rounds.
- */
+/** Distributes participants in groups (count must be given) and rounds. */
 export function createRoundRobin(creator: StageCreator): void {
 	if (creator.settings.hasAbDivisions) {
 		createAbDivisionRoundRobin(creator);
@@ -21,12 +17,7 @@ export function createRoundRobin(creator: StageCreator): void {
 		creator.createRoundRobinGroup(stage.id, i + 1, groups[i]);
 }
 
-/**
- * Creates a bipartite (A/B divisions) round-robin stage.
- *
- * Participants are partitioned into two pools by `abDivisions` (parallel to the seeding).
- * Each group receives equal A and B teams, and matches only pair A against B.
- */
+/** A/B divisions (`abDivisions`, parallel to the seeding): equal A and B teams per group, matches only pair A against B. */
 function createAbDivisionRoundRobin(creator: StageCreator): void {
 	const groups = getAbDivisionGroups(creator);
 	const stage = creator.createStage();
@@ -40,9 +31,7 @@ function createAbDivisionRoundRobin(creator: StageCreator): void {
 		);
 }
 
-/**
- * Gets the slots in groups for a round-robin stage.
- */
+/** Slots in groups for a round-robin stage. */
 function getRoundRobinGroups(creator: StageCreator): ParticipantSlot[][] {
 	if (
 		creator.settings.groupCount === undefined ||
@@ -61,10 +50,7 @@ function getRoundRobinGroups(creator: StageCreator): ParticipantSlot[][] {
 	return helpers.makeGroups(ordered, creator.settings.groupCount);
 }
 
-/**
- * Partitions the seeded slots into A and B pools then distributes them into groups
- * such that each group has an equal number of A and B participants.
- */
+/** A and B pools distributed into groups with an equal number of each. */
 function getAbDivisionGroups(creator: StageCreator): {
 	a: ParticipantSlot[];
 	b: ParticipantSlot[];
diff --git a/app/features/tournament-bracket/core/engine/create/seeding.ts b/app/features/tournament-bracket/core/engine/create/seeding.ts
index ebc38eb04..69f3827f3 100644
--- a/app/features/tournament-bracket/core/engine/create/seeding.ts
+++ b/app/features/tournament-bracket/core/engine/create/seeding.ts
@@ -87,31 +87,15 @@ export const defaultMinorOrdering: { [key: number]: SeedOrdering[] } = {
 	],
 };
 
-/**
- * Pads the seeding with BYEs (`null`) until its length is a power of two.
- *
- * @param seeding The seeding of the stage.
- */
+/** Pads the seeding with BYEs (`null`) until its length is a power of two. */
 export function padSeedingToPowerOfTwo(seeding: Seeding): Seeding {
 	return setArraySize(seeding, getNearestPowerOfTwo(seeding.length), null);
 }
 
-/**
- * Sets the size of an array with a placeholder if the size is bigger.
- *
- * @param array The original array.
- * @param length The new length.
- * @param placeholder A placeholder to use to fill the empty space.
- */
 function setArraySize<T>(array: T[], length: number, placeholder: T): T[] {
 	return Array.from(Array(length), (_, i) => array[i] || placeholder);
 }
 
-/**
- * Returns the nearest power of two **greater than** or equal to the given number.
- *
- * @param input The input number.
- */
 function getNearestPowerOfTwo(input: number): number {
 	return 2 ** Math.ceil(Math.log2(input));
 }
diff --git a/app/features/tournament-bracket/core/engine/create/settings.ts b/app/features/tournament-bracket/core/engine/create/settings.ts
index 8e5a4283b..be4d901d7 100644
--- a/app/features/tournament-bracket/core/engine/create/settings.ts
+++ b/app/features/tournament-bracket/core/engine/create/settings.ts
@@ -8,10 +8,7 @@ import type {
 	StageType,
 } from "../types";
 
-/**
- * Resolves the user-selected settings into the engine's internal stage
- * settings, applying our defaults (seed ordering, group counts etc.).
- */
+/** User-selected settings to internal stage settings, applying defaults (seed ordering, group counts etc.). */
 export function resolveStageSettings(input: CreateBracketInput): StageSettings {
 	const { type, settings, seeding } = input;
 
@@ -49,19 +46,14 @@ export function resolveStageSettings(input: CreateBracketInput): StageSettings {
 	}
 }
 
-/**
- * How many rounds a swiss bracket was created with. Read off the stage's own
- * settings (resolved and persisted when the bracket was created) so that later
- * edits to the tournament's bracket progression can't change the advance and
- * elimination math of a bracket that already exists.
- */
+/** Off the stage's own persisted settings so later progression edits can't change an existing bracket's advance/elimination math. */
 export function swissRoundCount(data: BracketData): number {
 	return (
 		data.stage[0]?.settings.roundCount ?? TOURNAMENT.SWISS_DEFAULT_ROUND_COUNT
 	);
 }
 
-/** Whether the bracket will include a third place match. Only possible for single elimination with at least 4 participants. */
+/** Only possible for single elimination with at least 4 participants. */
 export function hasThirdPlaceMatch(args: {
 	type: StageType;
 	settings: TournamentStageSettings | null;
@@ -76,7 +68,7 @@ export function hasThirdPlaceMatch(args: {
 	);
 }
 
-/** How many groups a round robin bracket will have, derived from the user-selected teams per group count and the participant count. */
+/** Round robin group count from the user-selected teams per group and the participant count. */
 export function roundRobinGroupCount(
 	settings: TournamentStageSettings | null,
 	participantsCount: number,
diff --git a/app/features/tournament-bracket/core/engine/create/single-elimination.ts b/app/features/tournament-bracket/core/engine/create/single-elimination.ts
index c002ad054..52dad719b 100644
--- a/app/features/tournament-bracket/core/engine/create/single-elimination.ts
+++ b/app/features/tournament-bracket/core/engine/create/single-elimination.ts
@@ -2,11 +2,7 @@ import type { Duel, ParticipantSlot } from "../types";
 import type { StageCreator } from "./builder";
 import { ordering, STANDARD_BRACKET_FIRST_ROUND_ORDERING } from "./seeding";
 
-/**
- * Creates a single elimination stage.
- *
- * One bracket and optionally a consolation final between semi-final losers.
- */
+/** One bracket and optionally a consolation final between semi-final losers. */
 export function createSingleElimination(creator: StageCreator): void {
 	const slots = creator.getSlots();
 	const stage = creator.createStage();
@@ -16,9 +12,7 @@ export function createSingleElimination(creator: StageCreator): void {
 	createConsolationFinal(creator, stage.id, losers);
 }
 
-/**
- * Creates a consolation final for the semi final losers of a single elimination stage.
- */
+/** Consolation final for the semi final losers. */
 function createConsolationFinal(
 	creator: StageCreator,
 	stageId: number,
diff --git a/app/features/tournament-bracket/core/engine/create/swiss.ts b/app/features/tournament-bracket/core/engine/create/swiss.ts
index e16e41bd8..facdeff44 100644
--- a/app/features/tournament-bracket/core/engine/create/swiss.ts
+++ b/app/features/tournament-bracket/core/engine/create/swiss.ts
@@ -7,10 +7,7 @@ import type {
 	ResolvedCreateBracketInput,
 } from "../types";
 
-/**
- * Creates a Swiss bracket data set: all rounds up front, matches for round 1 only.
- * Ported from the old core/Swiss.ts create()/firstRoundMatches().
- */
+/** All rounds up front, matches for round 1 only. */
 export function createSwiss(input: ResolvedCreateBracketInput): BracketData {
 	const groupCount =
 		input.settings.groupCount ?? TOURNAMENT.SWISS_DEFAULT_GROUP_COUNT;
@@ -59,10 +56,7 @@ function firstRoundMatches({
 	groupCount: number;
 	roundCount: number;
 }): MatchData[] {
-	// split the teams to one or more groups. For example with 16 teams and 3 groups this would result in
-	// group 1: 1, 4, 7, 10, 13, 16
-	// group 2: 2, 5, 8, 11, 14
-	// group 3: 3, 6, 9, 12, 15
+	// e.g. 16 teams and 3 groups: 1, 4, 7, 10, 13, 16 / 2, 5, 8, 11, 14 / 3, 6, 9, 12, 15
 	const groups = splitToGroups();
 
 	const result: MatchData[] = [];
@@ -81,14 +75,8 @@ function firstRoundMatches({
 			"firstRoundMatches: halfs not equal",
 		);
 
-		// first round every team plays the matching team "on the opposite side"
-		// so for example with 8 teams match ups look like this:
-		// seed 1 vs. seed 5
-		// seed 2 vs. seed 6
-		// seed 3 vs. seed 7
-		// seed 4 vs. seed 8
-		// ---
-		// this way each match has "equal distance"
+		// every team plays the matching team "on the opposite side" so each match has "equal distance",
+		// e.g. 8 teams: 1 vs. 5, 2 vs. 6, 3 vs. 7, 4 vs. 8
 		const roundId = groupIdx * roundCount;
 		for (let i = 0; i < upperHalf.length; i++) {
 			const upper = upperHalf[i];
diff --git a/app/features/tournament-bracket/core/engine/index.ts b/app/features/tournament-bracket/core/engine/index.ts
index c890c7d00..d5fdc1492 100644
--- a/app/features/tournament-bracket/core/engine/index.ts
+++ b/app/features/tournament-bracket/core/engine/index.ts
@@ -1,8 +1,4 @@
-/**
- * Pure bracket engine. No I/O anywhere in this module tree — callers hydrate
- * BracketData via BracketRepository, call engine functions, persist the
- * returned delta via BracketRepository.
- */
+/** Pure bracket engine, no I/O: callers hydrate BracketData via BracketRepository and persist the returned delta. */
 
 export { create } from "./create";
 export {
diff --git a/app/features/tournament-bracket/core/engine/propagation/dropped-teams.ts b/app/features/tournament-bracket/core/engine/propagation/dropped-teams.ts
index 6272eac38..241106aa1 100644
--- a/app/features/tournament-bracket/core/engine/propagation/dropped-teams.ts
+++ b/app/features/tournament-bracket/core/engine/propagation/dropped-teams.ts
@@ -3,13 +3,8 @@ import { Store } from "./store";
 import { Propagator } from "./traversal";
 
 /**
- * Ends all unfinished matches involving dropped teams by awarding wins to
- * their opponents. Ported from tournament-utils.server.ts. When both teams in
- * a match have dropped, a random winner is picked.
- *
- * Matches that only gain a dropped opponent through propagation caused by this
- * call are not ended (same as the old implementation, which iterated a
- * snapshot); they are picked up by the next call.
+ * Ends unfinished matches of dropped teams by awarding wins to their opponents (random winner when both
+ * dropped). Matches that gain a dropped opponent through this call's propagation are left for the next call.
  */
 export function endDroppedTeamMatches(
 	data: BracketData,
diff --git a/app/features/tournament-bracket/core/engine/propagation/helpers.ts b/app/features/tournament-bracket/core/engine/propagation/helpers.ts
index bf0fcfe50..6d325b833 100644
--- a/app/features/tournament-bracket/core/engine/propagation/helpers.ts
+++ b/app/features/tournament-bracket/core/engine/propagation/helpers.ts
@@ -18,11 +18,7 @@ export type SetNextOpponent = (
 	currentSide?: Side,
 ) => void;
 
-/**
- * Returns the winner side or `null` if no winner.
- *
- * @param match A match's results.
- */
+/** Winner side or `null` if no winner. */
 export function getMatchResult(match: MatchResults): Side | null {
 	if (!isMatchCompleted(match)) return null;
 
@@ -35,30 +31,20 @@ export function getMatchResult(match: MatchResults): Side | null {
 	return null;
 }
 
-/**
- * Gets the other side of a match.
- *
- * @param side The side that we don't want.
- */
+/** The other side of a match. */
 export function getOtherSide(side: Side): Side {
 	return side === "opponent1" ? "opponent2" : "opponent1";
 }
 
-/**
- * Indicates whether a match has at least one BYE or not.
- *
- * @param match A match's results.
- */
+/** Whether a match has at least one BYE. */
 export function hasBye(match: MatchResults): boolean {
 	return match.opponent1 === null || match.opponent2 === null;
 }
 
 /**
- * Updates a match results based on an input.
+ * Updates a match's results in place.
  *
- * @param stored A reference to what will be updated in the storage.
  * @param scores Games won by each side. `undefined` keeps them, `null` clears them.
- * @param winnerSide The resolved winner of the set, if any.
  * @returns `true` if the match was completed or un-completed by the update.
  */
 export function setMatchResults(
@@ -83,21 +69,12 @@ export function setMatchResults(
 	return false;
 }
 
-/**
- * Clears the winner of a match, marking it as not completed.
- *
- * @param stored A reference to what will be updated in the storage.
- */
+/** Clears the winner of a match, marking it as not completed. */
 export function clearWinner(stored: MatchResults): void {
 	stored.winnerSide = null;
 }
 
-/**
- * Completes a match that is decided by a BYE, marking the side that has an
- * opponent as the winner. Does nothing to a match that is not decided by a BYE.
- *
- * @param match A reference to what will be updated in the storage.
- */
+/** Marks the side with an opponent as the winner of a match decided by a BYE, otherwise no-op. */
 export function resolveByeWinner(match: MatchResults): void {
 	if (match.winnerSide) return;
 	if (!isMatchByeCompleted(match)) return;
@@ -109,14 +86,7 @@ export function resolveByeWinner(match: MatchResults): void {
 	}
 }
 
-/**
- * Gets the side the winner of the current match will go to in the next match.
- *
- * @param matchNumber Number of the current match.
- * @param roundNumber Number of the current round.
- * @param roundCount Count of rounds.
- * @param matchLocation Location of the current match.
- */
+/** Side the winner of the current match will go to in the next match. */
 export function getNextSide(
 	matchNumber: number,
 	roundNumber: number,
@@ -134,13 +104,7 @@ export function getNextSide(
 	return getSide(matchNumber);
 }
 
-/**
- * Gets the side the winner of the current match in loser bracket will go in the next match.
- *
- * @param matchNumber Number of the match.
- * @param nextMatch The next match.
- * @param roundNumber Number of the current round.
- */
+/** Side the loser of the current winner bracket match will go to in the loser bracket match. */
 export function getNextSideLoserBracket(
 	matchNumber: number,
 	nextMatch: MatchData,
@@ -155,14 +119,7 @@ export function getNextSideLoserBracket(
 	return "opponent2";
 }
 
-/**
- * Sets an opponent in the next match he has to go.
- *
- * @param nextMatch A match which follows the current one.
- * @param nextSide The side the opponent will be on in the next match.
- * @param match The current match.
- * @param currentSide The side the opponent is currently on.
- */
+/** Moves the opponent at `currentSide` of `match` to `nextSide` of `nextMatch`. */
 export function setNextOpponent(
 	nextMatch: MatchData,
 	nextSide: Side,
@@ -171,35 +128,23 @@ export function setNextOpponent(
 ): void {
 	nextMatch[nextSide] = match![currentSide!] && {
 		// Keep BYE.
-		id: getOpponentId(match!, currentSide!), // This implementation of SetNextOpponent always has those arguments.
-		position: nextMatch[nextSide]?.position, // Keep position.
+		id: getOpponentId(match!, currentSide!),
+		position: nextMatch[nextSide]?.position,
 	};
 	nextMatch.winnerSide = null; // A match whose opponents changed can't keep its winner.
 }
 
-/**
- * Resets an opponent in the match following the current one.
- *
- * @param nextMatch A match which follows the current one.
- * @param nextSide The side the opponent will be on in the next match.
- */
+/** Resets an opponent in the match following the current one. */
 export function resetNextOpponent(nextMatch: MatchData, nextSide: Side): void {
 	nextMatch[nextSide] = nextMatch[nextSide] && {
 		// Keep BYE.
 		id: null,
-		position: nextMatch[nextSide]?.position, // Keep position.
+		position: nextMatch[nextSide]?.position,
 	};
 	nextMatch.winnerSide = null; // A match whose opponents changed can't keep its winner.
 }
 
-/**
- * Returns the real (because of loser ordering) number of a match in a loser bracket.
- *
- * @param participantCount The number of participants in a stage.
- * @param roundNumber Number of the round.
- * @param matchNumber Number of the match.
- * @param method The method used for the round.
- */
+/** Real number (after loser ordering) of a match in a loser bracket. */
 export function findLoserMatchNumber(
 	participantCount: number,
 	roundNumber: number,
@@ -217,12 +162,7 @@ export function findLoserMatchNumber(
 	return matchNumberLB;
 }
 
-/**
- * Returns the ordering method of a round of a loser bracket.
- *
- * @param participantCount The number of participants in the stage.
- * @param roundNumber Number of the round.
- */
+/** Ordering method of a loser bracket round. */
 export function getLoserOrdering(
 	participantCount: number,
 	roundNumber: number,
@@ -230,39 +170,22 @@ export function getLoserOrdering(
 	return defaultMinorOrdering[participantCount]?.[Math.floor(roundNumber / 2)];
 }
 
-/**
- * Returns the match number of the corresponding match in the next round by dividing by two.
- *
- * @param matchNumber The current match number.
- */
+/** Match number of the corresponding match in the next round. */
 export function getDiagonalMatchNumber(matchNumber: number): number {
 	return Math.ceil(matchNumber / 2);
 }
 
-/**
- * Checks if a stage is a round-robin stage.
- *
- * @param stage The stage to check.
- */
+/** Whether a stage is round robin. */
 export function isRoundRobin(stage: StageData): boolean {
 	return stage.type === "round_robin";
 }
 
-/**
- * Checks if a stage is a swiss stage.
- *
- * @param stage The stage to check.
- */
+/** Whether a stage is swiss. */
 export function isSwiss(stage: StageData): boolean {
 	return stage.type === "swiss";
 }
 
-/**
- * Returns the type of group the match is located into.
- *
- * @param stageType Type of the stage.
- * @param groupNumber Number of the group.
- */
+/** Type of group a match is located in. */
 export function getMatchLocation(
 	stageType: StageType,
 	groupNumber: number,
@@ -276,21 +199,11 @@ export function getMatchLocation(
 	return "single_bracket";
 }
 
-/**
- * Gets the side where the winner of the given match will go in the next match.
- *
- * @param matchNumber Number of the match.
- */
 function getSide(matchNumber: number): Side {
 	return matchNumber % 2 === 1 ? "opponent1" : "opponent2";
 }
 
-/**
- * Updates the scores of a match.
- *
- * @param stored A reference to what will be updated in the storage.
- * @param scores Games won by each side. `undefined` keeps them, `null` clears them.
- */
+/** `undefined` scores keep the current ones, `null` clears them. */
 function setScores(
 	stored: MatchResults,
 	scores: MatchResultsInput["scores"],
@@ -301,23 +214,11 @@ function setScores(
 	if (stored.opponent2) stored.opponent2.score = scores?.[1];
 }
 
-/**
- * Gets the id of the opponent at the given side of the given match.
- *
- * @param match The match to get the opponent from.
- * @param side The side where to get the opponent from.
- */
 function getOpponentId(match: MatchResults, side: Side): number | null {
 	const opponent = match[side];
 	return opponent?.id ?? null;
 }
 
-/**
- * Returns the count of matches in a round of a loser bracket.
- *
- * @param participantCount The number of participants in a stage.
- * @param roundNumber Number of the round.
- */
 function getLoserRoundMatchCount(
 	participantCount: number,
 	roundNumber: number,
@@ -328,12 +229,6 @@ function getLoserRoundMatchCount(
 	return matchCount;
 }
 
-/**
- * Returns the count of losers in a round of a loser bracket.
- *
- * @param participantCount The number of participants in a stage.
- * @param roundNumber Number of the round.
- */
 function getLoserRoundLoserCount(
 	participantCount: number,
 	roundNumber: number,
@@ -346,34 +241,16 @@ function getLoserRoundLoserCount(
 	return matchCount; // One per match for LB minor rounds.
 }
 
-/**
- * Checks if a group is a winner bracket.
- *
- * It's not always the opposite of `isLoserBracket()`: it could be the only bracket of a single elimination stage.
- *
- * @param stageType Type of the stage.
- * @param groupNumber Number of the group.
- */
+/** Not the opposite of `isLoserBracket()`: the only bracket of single elimination is neither. */
 function isWinnerBracket(stageType: StageType, groupNumber: number): boolean {
 	return stageType === "double_elimination" && groupNumber === 1;
 }
 
-/**
- * Checks if a group is a loser bracket.
- *
- * @param stageType Type of the stage.
- * @param groupNumber Number of the group.
- */
 function isLoserBracket(stageType: StageType, groupNumber: number): boolean {
 	return stageType === "double_elimination" && groupNumber === 2;
 }
 
-/**
- * Checks if a group is a final group (consolation final or grand final).
- *
- * @param stageType Type of the stage.
- * @param groupNumber Number of the group.
- */
+/** Consolation final or grand final. */
 function isFinalGroup(stageType: StageType, groupNumber: number): boolean {
 	return (
 		(stageType === "single_elimination" && groupNumber === 2) ||
diff --git a/app/features/tournament-bracket/core/engine/propagation/report-result.ts b/app/features/tournament-bracket/core/engine/propagation/report-result.ts
index b42a9bbc8..c4fd29468 100644
--- a/app/features/tournament-bracket/core/engine/propagation/report-result.ts
+++ b/app/features/tournament-bracket/core/engine/propagation/report-result.ts
@@ -3,12 +3,7 @@ import type { BracketData, EngineResult, ReportResultInput } from "../types";
 import { Store } from "./store";
 import { Propagator } from "./traversal";
 
-/**
- * Applies a result to a match and propagates:
- * winner/loser advancement (SE/DE), BYE cascades, grand final + bracket reset,
- * next-round unlocking (RR), no downstream propagation for swiss/RR completed
- * matches. Throws on locked matches.
- */
+/** Applies a result and propagates it (SE/DE advancement, BYE cascades, grand final + reset). Throws on locked matches. */
 export function reportResult(
 	data: BracketData,
 	input: ReportResultInput,
diff --git a/app/features/tournament-bracket/core/engine/propagation/reset-result.ts b/app/features/tournament-bracket/core/engine/propagation/reset-result.ts
index bcb163273..781572fd7 100644
--- a/app/features/tournament-bracket/core/engine/propagation/reset-result.ts
+++ b/app/features/tournament-bracket/core/engine/propagation/reset-result.ts
@@ -8,11 +8,7 @@ import * as helpers from "./helpers";
 import { Store } from "./store";
 import { Propagator } from "./traversal";
 
-/**
- * Clears a match's results and rolls back everything that was propagated
- * from it. 1:1 with the old reset.ts, including the swiss/round_robin early
- * return.
- */
+/** Clears a match's results and rolls back everything propagated from it. */
 export function resetMatchResults(
 	data: BracketData,
 	matchId: number,
diff --git a/app/features/tournament-bracket/core/engine/propagation/round-robin.test.ts b/app/features/tournament-bracket/core/engine/propagation/round-robin.test.ts
index 0f4c4524e..7ed28c64a 100644
--- a/app/features/tournament-bracket/core/engine/propagation/round-robin.test.ts
+++ b/app/features/tournament-bracket/core/engine/propagation/round-robin.test.ts
@@ -60,39 +60,29 @@ describe("Update scores in a round-robin stage", () => {
 	});
 
 	test("unlocks next round matches as soon as both participants are ready", () => {
-		// Round robin with 4 teams: [1, 2, 3, 4]
-		// Round 1: Match 0 (1 vs 2), Match 1 (3 vs 4)
-		// Round 2: Match 2 (1 vs 3), Match 3 (2 vs 4)
-		// Round 3: Match 4 (1 vs 4), Match 5 (2 vs 3)
+		// 4 teams. Round 1: (1 vs 2), (3 vs 4). Round 2: (1 vs 3), (2 vs 4). Round 3: (1 vs 4), (2 vs 3)
 
-		// Initially, only round 1 matches should be ready
 		expect(Engine.matchStatus(data, 0)).toBe("STARTED"); // Ready (1 vs 2)
 		expect(Engine.matchStatus(data, 1)).toBe("STARTED"); // Ready (3 vs 4)
 		expect(Engine.matchStatus(data, 2)).toBe("PENDING"); // Locked (1 vs 3)
 		expect(Engine.matchStatus(data, 3)).toBe("PENDING"); // Locked (2 vs 4)
 
-		// Complete first match of round 1 (1 vs 2)
 		data = Engine.reportResult(data, {
 			matchId: 0,
 			scores: [16, 9], // Team 2 loses
 			winnerSide: "opponent1", // Team 1 wins
 		}).data;
 
-		// Round 2 Match 1 (1 vs 3) should still be locked because team 3 hasn't finished
-		// Round 2 Match 2 (2 vs 4) should still be locked because team 4 hasn't finished
+		// round 2 still locked because teams 3 and 4 haven't finished
 		expect(Engine.matchStatus(data, 2)).toBe("PENDING"); // Still Locked
 		expect(Engine.matchStatus(data, 3)).toBe("PENDING"); // Still Locked
 
-		// Complete second match of round 1 (3 vs 4)
 		data = Engine.reportResult(data, {
 			matchId: 1,
 			scores: [3, 16], // Team 3 loses
 			winnerSide: "opponent2", // Team 4 wins
 		}).data;
 
-		// Now both matches in round 2 should be unlocked
-		// Match 2 (1 vs 3): both team 1 and team 3 have finished round 1
-		// Match 3 (2 vs 4): both team 2 and team 4 have finished round 1
 		expect(Engine.matchStatus(data, 2)).toBe("STARTED"); // Ready
 		expect(Engine.matchStatus(data, 3)).toBe("STARTED"); // Ready
 	});
@@ -193,19 +183,14 @@ describe("Update scores in a round-robin stage", () => {
 	});
 
 	test("unlocks next round matches with BYE participants", () => {
-		// Create a round robin with 3 teams (odd number creates rounds where one team doesn't play)
 		data = createResolved({
 			type: "round_robin",
 			seeding: [1, 2, 3],
 			settings: { groupCount: 1 },
 		});
 
-		// With 3 teams, the rounds look like:
-		// Round 1: Match (teams 3 vs 2) - Team 1 doesn't play
-		// Round 2: Match (teams 1 vs 3) - Team 2 doesn't play
-		// Round 3: Match (teams 2 vs 1) - Team 3 doesn't play
+		// 3 teams, one sits out each round. Round 1: 3 vs 2. Round 2: 1 vs 3. Round 3: 2 vs 1
 
-		// Find the actual match (not BYE vs BYE which doesn't exist)
 		const round1RealMatch = data.match.find(
 			(match) =>
 				match.roundId === data.round[0].id &&
@@ -222,17 +207,13 @@ describe("Update scores in a round-robin stage", () => {
 		expect(Engine.matchStatus(data, round1RealMatch.id)).toBe("STARTED");
 		expect(Engine.matchStatus(data, round2RealMatch.id)).toBe("PENDING"); // initially
 
-		// Complete the only real match in round 1 (teams 3 vs 2)
-		// Team 1 didn't play in round 1
 		data = Engine.reportResult(data, {
 			matchId: round1RealMatch.id,
 			scores: [16, 9],
 			winnerSide: "opponent1",
 		}).data;
 
-		// The real match in round 2 (teams 1 vs 3) should now be unlocked
-		// because team 1 didn't play in round 1 (considered ready)
-		// and team 3 just finished their match
+		// team 1 sat out round 1 (considered ready) and team 3 just finished
 		expect(Engine.matchStatus(data, round2RealMatch.id)).toBe("STARTED");
 	});
 });
diff --git a/app/features/tournament-bracket/core/engine/propagation/set.ts b/app/features/tournament-bracket/core/engine/propagation/set.ts
index 397977e30..c8cd949bd 100644
--- a/app/features/tournament-bracket/core/engine/propagation/set.ts
+++ b/app/features/tournament-bracket/core/engine/propagation/set.ts
@@ -6,11 +6,7 @@ import { resetMatchResults } from "./reset-result";
 
 const SIDES = ["opponent1", "opponent2"] as const satisfies Side[];
 
-/**
- * Records one game win for the given team, resolving from the round's map
- * info (count & best of / play all) whether the set is now over. When it is,
- * the win/loss results are set and propagated (advancements, unlocks etc.).
- */
+/** Records one game win. If the round's map info (count & best of / play all) says the set is over, the result is set and propagated. */
 export function reportGameResult(
 	data: BracketData,
 	input: { matchId: number; winnerTeamId: number },
@@ -32,11 +28,7 @@ export function reportGameResult(
 	};
 }
 
-/**
- * Removes the last played game from a match. If the match goes back to no
- * games played, the whole match result is reset, rolling back anything that
- * was propagated from it.
- */
+/** Removes the last played game. Back at no games played the whole result is reset, rolling back what was propagated. */
 export function undoGameResult(
 	data: BracketData,
 	input: { matchId: number; lastGameWinnerTeamId: number },
@@ -65,11 +57,7 @@ export function undoGameResult(
 	};
 }
 
-/**
- * Ends the set early with the given team as the winner, keeping the current
- * scores as they are (an organizer action; e.g. the opponent can not play out
- * the rest of the set).
- */
+/** Ends the set early with the given winner, keeping the scores (organizer action, e.g. the opponent can't play on). */
 export function endSet(
 	data: BracketData,
 	input: { matchId: number; winnerTeamId: number },
@@ -83,11 +71,8 @@ export function endSet(
 }
 
 /**
- * Reopens a completed match for further reporting, clearing the set result.
- * Resolves from the round's map info whether the set had been force-ended
- * early: if it was, the scores are kept as is; otherwise the deciding game's
- * score is removed (the caller is expected to delete the corresponding game
- * result row, see `endedEarly` in the return value).
+ * Reopens a completed match, clearing the set result. A force-ended set keeps its scores, otherwise
+ * the deciding game's score is removed and the caller deletes its game result row (see `endedEarly`).
  */
 export function reopenMatch(
 	data: BracketData,
diff --git a/app/features/tournament-bracket/core/engine/propagation/store.ts b/app/features/tournament-bracket/core/engine/propagation/store.ts
index dd6daaf8a..e7b11411f 100644
--- a/app/features/tournament-bracket/core/engine/propagation/store.ts
+++ b/app/features/tournament-bracket/core/engine/propagation/store.ts
@@ -6,12 +6,7 @@ import type {
 	StageData,
 } from "../types";
 
-/**
- * A working copy of BracketData. The input is cloned once on construction and
- * every row handed out afterwards is a live reference into that copy, so
- * mutating a row is the write. Callers report the match rows they mutated so
- * that a delta can be emitted.
- */
+/** Working copy of BracketData: rows handed out are live references into the clone, so mutating a row is the write. Callers report mutated match rows for the delta. */
 export class Store {
 	readonly data: BracketData;
 	private readonly stagesById: Map<number, StageData>;
@@ -92,7 +87,7 @@ export class Store {
 		this.changedMatchIds.add(match.id);
 	}
 
-	/** Returns the final version of every match row that was written during this operation. */
+	/** Final version of every match row written during this operation. */
 	changedMatches(): MatchData[] {
 		return this.data.match.filter((match) =>
 			this.changedMatchIds.has(match.id),
diff --git a/app/features/tournament-bracket/core/engine/propagation/traversal.ts b/app/features/tournament-bracket/core/engine/propagation/traversal.ts
index 9759fbdaf..97e38455d 100644
--- a/app/features/tournament-bracket/core/engine/propagation/traversal.ts
+++ b/app/features/tournament-bracket/core/engine/propagation/traversal.ts
@@ -17,11 +17,7 @@ interface RoundPositionalInfo {
 	roundCount: number;
 }
 
-/**
- * Resolves the matches following another match and applies result propagation
- * to them. Port of the old brackets-manager getter + updater, mutating the rows
- * of a Store instead of writing to storage.
- */
+/** Resolves the matches following another match and propagates results to them, mutating Store rows. */
 export class Propagator {
 	readonly store: Store;
 
@@ -29,15 +25,6 @@ export class Propagator {
 		this.store = store;
 	}
 
-	/* ------------------------------------------------------------------ */
-	/* Updater                                                            */
-	/* ------------------------------------------------------------------ */
-
-	/**
-	 * Propagates the results of a match to the matches following it.
-	 *
-	 * @param match A match.
-	 */
 	updateRelatedMatches(match: MatchData): void {
 		const { roundNumber, roundCount } = this.getRoundPositionalInfo(
 			match.roundId,
@@ -54,13 +41,7 @@ export class Propagator {
 		this.updateNext(match, matchLocation, stage, roundNumber, roundCount);
 	}
 
-	/**
-	 * Updates a match based on a reported result.
-	 *
-	 * @param stored The match row of the store that is mutated.
-	 * @param input Input of the update.
-	 * @param force Whether to force update matches that can't be played yet.
-	 */
+	/** @param force Also update matches that can't be played yet. */
 	updateMatch(
 		stored: MatchData,
 		input: MatchResultsInput,
@@ -90,11 +71,7 @@ export class Propagator {
 		}
 	}
 
-	/**
-	 * The winner the scores decide once the input has been applied. `undefined`
-	 * when the set is not over or the round has no map count to decide it by
-	 * (a bracket created without map lists).
-	 */
+	/** `undefined` when the set is not over or the round has no map count (bracket created without map lists). */
 	private winnerSideAfter(
 		stored: MatchData,
 		scores: MatchResultsInput["scores"],
@@ -109,15 +86,6 @@ export class Propagator {
 		});
 	}
 
-	/**
-	 * Updates the match(es) following the current match based on this match results.
-	 *
-	 * @param match Input of the update.
-	 * @param matchLocation Location of the current match.
-	 * @param stage The parent stage.
-	 * @param roundNumber Number of the round.
-	 * @param roundCount Count of rounds.
-	 */
 	private updateNext(
 		match: MatchData,
 		matchLocation: GroupType,
@@ -159,17 +127,6 @@ export class Propagator {
 			);
 	}
 
-	/**
-	 * Applies a SetNextOpponent function to matches following the current match.
-	 *
-	 * @param setNextOpponent The SetNextOpponent function.
-	 * @param match The current match.
-	 * @param matchLocation Location of the current match.
-	 * @param roundNumber Number of the current round.
-	 * @param roundCount Count of rounds.
-	 * @param nextMatches The matches following the current match.
-	 * @param winnerSide Side of the winner in the current match.
-	 */
 	private applyToNextMatches(
 		setNextOpponent: SetNextOpponent,
 		match: MatchData,
@@ -202,8 +159,7 @@ export class Propagator {
 		if (nextMatches.length !== 2) return;
 		if (!nextMatches[1]) throw Error("Second next match is null.");
 
-		// The second match is either the consolation final (single elimination) or a loser bracket match (double elimination).
-
+		// Second match is the consolation final (SE) or a loser bracket match (DE).
 		if (matchLocation === "single_bracket") {
 			setNextOpponent(
 				nextMatches[1],
@@ -228,27 +184,13 @@ export class Propagator {
 		}
 	}
 
-	/**
-	 * Propagates winner against BYEs in related matches.
-	 *
-	 * @param match The current match.
-	 */
 	propagateByeWinners(match: MatchData): void {
-		helpers.resolveByeWinner(match); // BYE propagation is only in non round-robin stages.
+		helpers.resolveByeWinner(match);
 		this.store.markMatchChanged(match);
 
 		if (helpers.hasBye(match)) this.updateRelatedMatches(match);
 	}
 
-	/* ------------------------------------------------------------------ */
-	/* Getter                                                             */
-	/* ------------------------------------------------------------------ */
-
-	/**
-	 * Gets the positional information (number in group and total number of rounds in group) of a round based on its id.
-	 *
-	 * @param roundId ID of the round.
-	 */
 	getRoundPositionalInfo(roundId: number): RoundPositionalInfo {
 		const round = this.store.roundById(roundId);
 		if (!round) throw Error("Round not found.");
@@ -259,15 +201,6 @@ export class Propagator {
 		};
 	}
 
-	/**
-	 * Gets the match(es) where the opponents of the current match will go just after.
-	 *
-	 * @param match The current match.
-	 * @param matchLocation Location of the current match.
-	 * @param stage The parent stage.
-	 * @param roundNumber The number of the current round.
-	 * @param roundCount Count of rounds.
-	 */
 	getNextMatches(
 		match: MatchData,
 		matchLocation: GroupType,
@@ -299,14 +232,6 @@ export class Propagator {
 		}
 	}
 
-	/**
-	 * Gets the match(es) where the opponents of the current match of winner bracket will go just after.
-	 *
-	 * @param match The current match.
-	 * @param stage The parent stage.
-	 * @param roundNumber The number of the current round.
-	 * @param roundCount Count of rounds.
-	 */
 	private getNextMatchesWB(
 		match: MatchData,
 		stage: StageData,
@@ -340,14 +265,6 @@ export class Propagator {
 		];
 	}
 
-	/**
-	 * Gets the match(es) where the opponents of the current match of an upper bracket will go just after.
-	 *
-	 * @param match The current match.
-	 * @param stageType Type of the stage.
-	 * @param roundNumber The number of the current round.
-	 * @param roundCount Count of rounds.
-	 */
 	private getNextMatchesUpperBracket(
 		match: MatchData,
 		stageType: StageType,
@@ -368,14 +285,6 @@ export class Propagator {
 		return [this.getDiagonalMatch(match.groupId, roundNumber, match.number)];
 	}
 
-	/**
-	 * Gets the match(es) where the opponents of the current match of the unique bracket of a single elimination will go just after.
-	 *
-	 * @param match The current match.
-	 * @param stageType Type of the stage.
-	 * @param roundNumber The number of the current round.
-	 * @param roundCount Count of rounds.
-	 */
 	private getNextMatchesUpperBracketSingleElimination(
 		match: MatchData,
 		stageType: StageType,
@@ -395,14 +304,6 @@ export class Propagator {
 		return [this.getDiagonalMatch(match.groupId, roundNumber, match.number)];
 	}
 
-	/**
-	 * Gets the match(es) where the opponents of the current match of loser bracket will go just after.
-	 *
-	 * @param match The current match.
-	 * @param stageType Type of the stage.
-	 * @param roundNumber The number of the current round.
-	 * @param roundCount Count of rounds.
-	 */
 	private getNextMatchesLB(
 		match: MatchData,
 		stageType: StageType,
@@ -420,12 +321,7 @@ export class Propagator {
 		return this.getMatchAfterMinorRoundLB(match, roundNumber);
 	}
 
-	/**
-	 * Gets the first match of the final group (consolation final or grand final).
-	 *
-	 * @param match The current match.
-	 * @param stageType Type of the stage.
-	 */
+	/** First match of the final group (consolation final or grand final). */
 	private getFirstMatchFinal(
 		match: MatchData,
 		stageType: StageType,
@@ -436,13 +332,6 @@ export class Propagator {
 		return this.findMatch(finalGroupId, 1, 1);
 	}
 
-	/**
-	 * Gets the matches following the current match, which is in the final group (consolation final or grand final).
-	 *
-	 * @param match The current match.
-	 * @param roundNumber The number of the current round.
-	 * @param roundCount The count of rounds.
-	 */
 	private getNextMatchesFinal(
 		match: MatchData,
 		roundNumber: number,
@@ -459,12 +348,6 @@ export class Propagator {
 		return [this.findMatch(match.groupId, roundNumber + 1, 1)];
 	}
 
-	/**
-	 * Gets the match(es) where the opponents of the current match of a winner bracket's major round will go just after.
-	 *
-	 * @param match The current match.
-	 * @param roundNumber The number of the current round.
-	 */
 	private getMatchAfterMajorRoundLB(
 		match: MatchData,
 		roundNumber: number,
@@ -472,12 +355,6 @@ export class Propagator {
 		return [this.getParallelMatch(match.groupId, roundNumber, match.number)];
 	}
 
-	/**
-	 * Gets the match(es) where the opponents of the current match of a winner bracket's minor round will go just after.
-	 *
-	 * @param match The current match.
-	 * @param roundNumber The number of the current round.
-	 */
 	private getMatchAfterMinorRoundLB(
 		match: MatchData,
 		roundNumber: number,
@@ -485,12 +362,6 @@ export class Propagator {
 		return [this.getDiagonalMatch(match.groupId, roundNumber, match.number)];
 	}
 
-	/**
-	 * Returns the id of the final group (consolation final or grand final).
-	 *
-	 * @param stageId ID of the stage.
-	 * @param stageType Type of the stage.
-	 */
 	private getFinalGroupId(
 		stageId: number,
 		stageType: StageType,
@@ -504,23 +375,14 @@ export class Propagator {
 		return finalGroup.id;
 	}
 
-	/**
-	 * Gets the upper bracket (the only bracket if single elimination or the winner bracket in double elimination).
-	 *
-	 * @param stageId ID of the stage.
-	 */
+	/** The only bracket in single elimination, the winner bracket in double elimination. */
 	private getUpperBracket(stageId: number): GroupData {
 		const winnerBracket = this.store.groupByNumber(stageId, 1);
 		if (!winnerBracket) throw Error("Winner bracket not found.");
 		return winnerBracket;
 	}
 
-	/**
-	 * Gets the participant count of an elimination stage, derived from its upper
-	 * bracket's first round (two participants per match, BYEs included).
-	 *
-	 * @param stageId ID of the stage.
-	 */
+	/** Derived from the upper bracket's first round (two participants per match, BYEs included). */
 	private participantCount(stageId: number): number {
 		const upperBracket = this.getUpperBracket(stageId);
 		const firstRound = this.store.roundByNumber(upperBracket.id, 1);
@@ -529,24 +391,11 @@ export class Propagator {
 		return this.store.matchCountInRound(firstRound.id) * 2;
 	}
 
-	/**
-	 * Gets the loser bracket.
-	 *
-	 * @param stageId ID of the stage.
-	 */
 	private getLoserBracket(stageId: number): GroupData | null {
 		return this.store.groupByNumber(stageId, 2);
 	}
 
-	/**
-	 * Gets the corresponding match in the next round ("diagonal match") the usual way.
-	 *
-	 * Just like from Round 1 to Round 2 in a single elimination stage.
-	 *
-	 * @param groupId ID of the group.
-	 * @param roundNumber Number of the round in its parent group.
-	 * @param matchNumber Number of the match in its parent round.
-	 */
+	/** Corresponding match in the next round, like Round 1 to Round 2 in single elimination. */
 	private getDiagonalMatch(
 		groupId: number,
 		roundNumber: number,
@@ -559,15 +408,7 @@ export class Propagator {
 		);
 	}
 
-	/**
-	 * Gets the corresponding match in the next round ("parallel match") the "major round to minor round" way.
-	 *
-	 * Just like from Round 1 to Round 2 in the loser bracket of a double elimination stage.
-	 *
-	 * @param groupId ID of the group.
-	 * @param roundNumber Number of the round in its parent group.
-	 * @param matchNumber Number of the match in its parent round.
-	 */
+	/** Same match number in the next round, like major round to minor round in the loser bracket. */
 	private getParallelMatch(
 		groupId: number,
 		roundNumber: number,
@@ -576,13 +417,6 @@ export class Propagator {
 		return this.findMatch(groupId, roundNumber + 1, matchNumber);
 	}
 
-	/**
-	 * Finds a match in a given group. The match must have the given number in a round of which the number in group is given.
-	 *
-	 * @param groupId ID of the group.
-	 * @param roundNumber Number of the round in its parent group.
-	 * @param matchNumber Number of the match in its parent round.
-	 */
 	findMatch(
 		groupId: number,
 		roundNumber: number,
diff --git a/app/features/tournament-bracket/core/engine/propagation/update.test.ts b/app/features/tournament-bracket/core/engine/propagation/update.test.ts
index a7de5cfb6..dd860672f 100644
--- a/app/features/tournament-bracket/core/engine/propagation/update.test.ts
+++ b/app/features/tournament-bracket/core/engine/propagation/update.test.ts
@@ -38,7 +38,6 @@ describe("Update matches", () => {
 		expect(Engine.matchStatus(data, 0)).toBe("STARTED");
 		expect(after.opponent1?.score).toBe(2);
 
-		// Id should stay. It shouldn't be overwritten.
 		expect(after.opponent1?.id).toBe(1);
 	});
 
diff --git a/app/features/tournament-bracket/core/engine/status.ts b/app/features/tournament-bracket/core/engine/status.ts
index 6e79de1c7..c85198185 100644
--- a/app/features/tournament-bracket/core/engine/status.ts
+++ b/app/features/tournament-bracket/core/engine/status.ts
@@ -9,13 +9,9 @@ import type {
 } from "./types";
 
 /**
- * The state of a match. Never persisted, always derived from the opponents of
- * the match and (for round robin) the progress of the previous round.
- *
- * - `PENDING` an opponent is still unknown, the match is a BYE or the teams are
- *   busy playing an earlier round.
- * - `STARTED` the match can be played and might already be in progress.
- * - `COMPLETED` the match has a winner.
+ * Never persisted, derived from the opponents and (round robin) the previous round's progress.
+ * `PENDING`: an opponent is unknown, a BYE or the teams are busy in an earlier round.
+ * `STARTED`: can be played, maybe in progress. `COMPLETED`: has a winner.
  */
 export type MatchStatus = "PENDING" | "STARTED" | "COMPLETED";
 
@@ -28,10 +24,7 @@ export function matchStatuses(data: BracketData): Map<number, MatchStatus> {
 	);
 }
 
-/**
- * Derives the status of one match of the bracket. Prefer {@link matchStatuses}
- * when the status of many matches of the same bracket is needed.
- */
+/** Prefer {@link matchStatuses} when many matches of the same bracket are needed. */
 export function matchStatus(data: BracketData, matchId: number): MatchStatus {
 	const match = data.match.find((match) => match.id === matchId);
 	if (!match) throw new Error(`Match not found: ${matchId}`);
@@ -39,33 +32,19 @@ export function matchStatus(data: BracketData, matchId: number): MatchStatus {
 	return resolveStatus(match, bracketContext(data));
 }
 
-/**
- * Checks if a match has had at least one game reported.
- *
- * @param match A match's results.
- */
+/** Whether at least one game has been reported. */
 export function isMatchStarted(match: MatchResults): boolean {
 	return (
 		match.opponent1?.score !== undefined || match.opponent2?.score !== undefined
 	);
 }
 
-/**
- * Checks if a match is completed.
- *
- * @param match A match's results.
- */
+/** Whether the match is completed. */
 export function isMatchCompleted(match: MatchResults): boolean {
 	return isMatchByeCompleted(match) || Boolean(match.winnerSide);
 }
 
-/**
- * Checks if a match is completed because of at least one BYE.
- *
- * A match "BYE vs. TBD" isn't considered completed yet.
- *
- * @param match A match's results.
- */
+/** Whether the match is completed because of a BYE. "BYE vs. TBD" isn't completed yet. */
 export function isMatchByeCompleted(match: MatchResults): boolean {
 	return (
 		(match.opponent1 === null && match.opponent2?.id !== null) || // BYE vs. someone
@@ -92,10 +71,7 @@ export function isSetOverByScore({
 	return scores[0] === matchOverAtXWins || scores[1] === matchOverAtXWins;
 }
 
-/**
- * The side the scores decide as the winner of the set, `undefined` while the
- * set is not over yet (or a play all set ended in a tie).
- */
+/** `undefined` while the set is not over (or a play all set ended in a tie). */
 export function winnerSideByScore(args: {
 	scores: [number, number];
 	count: number;
@@ -110,7 +86,7 @@ export function winnerSideByScore(args: {
 	return undefined;
 }
 
-/** Whether a completed match was ended before the set was decided by the games played (e.g. by an organizer force-ending it). */
+/** Completed before the games decided the set (e.g. organizer force-ending it). */
 export function matchEndedEarly({
 	opponentOne,
 	opponentTwo,
@@ -146,8 +122,7 @@ function resolveStatus(match: MatchData, context: BracketContext): MatchStatus {
 
 	if (!match.opponent1?.id || !match.opponent2?.id) return "PENDING";
 
-	// a match that is being played can't go back to pending e.g. because the
-	// result of an earlier match was reopened (issue #2690)
+	// a match being played can't go back to pending e.g. by an earlier match being reopened (issue #2690)
 	if (isMatchStarted(match)) return "STARTED";
 
 	if (isWaitingForPreviousRound(match, context)) return "PENDING";
@@ -155,11 +130,7 @@ function resolveStatus(match: MatchData, context: BracketContext): MatchStatus {
 	return "STARTED";
 }
 
-/**
- * In a round robin where the rounds are not independent both opponents are
- * known from the start but they can only play once they are done with the
- * previous round.
- */
+/** Non-independent round robin: opponents are known from the start but play only once done with the previous round. */
 function isWaitingForPreviousRound(
 	match: MatchData,
 	context: BracketContext,
diff --git a/app/features/tournament-bracket/core/engine/swiss/pairing.ts b/app/features/tournament-bracket/core/engine/swiss/pairing.ts
index 99c30b708..c1b9cefb1 100644
--- a/app/features/tournament-bracket/core/engine/swiss/pairing.ts
+++ b/app/features/tournament-bracket/core/engine/swiss/pairing.ts
@@ -11,32 +11,21 @@ import type {
 } from "../types";
 import { calculateTeamStatus } from "./team-status";
 
-/**
- * Weight subtracted for each time a pair has already played each other. Big enough
- * to dwarf every other weight of the whole round, meaning rematches only happen when
- * unavoidable and then as few of them as possible.
- */
+/** Subtracted per prior meeting of a pair. Dwarfs every other weight of the round so rematches happen only when unavoidable, and then as few as possible. */
 const REMATCH_PENALTY = 1_000_000_000;
 
 /**
- * Weight added for each team of a pair that has already received a bye, making
- * previously-byed teams more attractive to pair up. Applied per team (not per pair)
- * so that a matching leaving a bye-less team unpaired always beats one giving a team
- * a second bye: with an odd team count exactly one team is left unpaired, so the
- * matchings differ by exactly one bonus, which is set to dwarf every score-based
- * weight (including HIGH_SCORE_PAIRING_BONUS) while staying far below
- * REMATCH_PENALTY.
+ * Added per team of a pair that already received a bye. Per team, not per pair, so leaving a bye-less
+ * team unpaired always beats a second bye: with an odd count exactly one team is unpaired, so matchings
+ * differ by one bonus, sized to dwarf every score-based weight while staying far below REMATCH_PENALTY.
  */
 const PRIOR_BYE_PAIRING_BONUS = 10_000_000;
 
 /**
- * Weight added per score point of both teams of a pair. Summed over a full matching
- * this contributes the bonus times the total score of all paired teams, so with an
- * odd team count the matching maximizes it by leaving a lowest-score team unpaired —
- * that team receives the bye. Without this term the bye can drift to a top score
- * group team whenever the score group size parities make all-within-group pairings
- * possible only that way. Sized to dwarf the pairing quality weights (< ~100 per
- * pair) while a full round's worth stays far below PRIOR_BYE_PAIRING_BONUS.
+ * Added per score point of both teams of a pair, so with an odd count the matching leaves a lowest-score
+ * team unpaired for the bye. Without it the bye can drift to a top team when score group parities allow
+ * all-within-group pairings only that way. Dwarfs the pairing quality weights (< ~100 per pair) while a
+ * full round's worth stays far below PRIOR_BYE_PAIRING_BONUS.
  */
 const HIGH_SCORE_PAIRING_BONUS = 10_000;
 
@@ -47,19 +36,13 @@ interface GroupArgs {
 }
 
 /**
- * Generates the next round of matchups for a Swiss tournament bracket within a specific group.
- *
- * Considers only the matches and teams within the specified group. Teams that have dropped out are excluded from the pairing process.
- * If the group has an uneven number of teams, the lowest standing team that has not already received a bye is preferred to receive one.
- * A team that is the only one left in the running receives a bye for the round.
- * Matches are generated such that teams do not replay previous opponents if possible.
+ * Next round of a Swiss group. Dropped out teams are excluded. With an uneven count the lowest standing
+ * team without a prior bye gets one; a lone remaining team gets a bye. Rematches are avoided if possible.
  */
 export function generateRound(
 	data: BracketData,
 	args: GroupArgs,
 ): Result<GeneratedRound, string> {
-	// lets consider only this groups matches
-	// in the case that there are more than one group
 	const groupsMatches = data.match.filter((m) => m.groupId === args.groupId);
 
 	if (groupsMatches.length === 0) return err("No matches found for group");
@@ -118,13 +101,7 @@ export function generateRound(
 	});
 }
 
-/**
- * Whether the group still has at least one team that can be paired into a new round.
- *
- * False when every team of the group has dropped out or, with the early advance
- * variation, has already advanced or been eliminated. In that case the remaining
- * rounds of the group can never be started.
- */
+/** False when every team dropped out or (early advance) advanced/got eliminated, so no further round can start. */
 export function groupHasActiveTeams(data: BracketData, args: GroupArgs) {
 	return activeTeamStandings(data, args).length > 0;
 }
@@ -139,12 +116,10 @@ function activeTeamStandings(data: BracketData, args: GroupArgs) {
 		return groupsTeams.some((team) => team?.id === standing.team.id);
 	});
 
-	// teams who have dropped out are not considered
 	const standingsWithoutDropouts = groupsStandings.filter(
 		(s) => !s.team.droppedOut,
 	);
 
-	// filter out teams that have advanced or been eliminated if early advance/elimination is enabled
 	if (typeof args.settings?.advanceThreshold !== "number") {
 		return standingsWithoutDropouts;
 	}
@@ -179,19 +154,15 @@ function everyMatchOver(matches: MatchData[]) {
 
 interface SwissPairingTeam {
 	id: number;
-	/** How many matches has the team won */
 	score: number;
-	/** List of tournament team ids this team already played, one entry per meeting */
+	/** Tournament team ids already played, one entry per meeting */
 	avoid: Array<number>;
 	receivedBye?: boolean;
 }
 
 /**
- * Pairs up teams for a swiss round using maximum weighted matching, avoiding
- * rematches if possible and preferring teams with equal scores to play each other.
- * A team left over (odd amount of teams, or only one team given) receives a bye.
- *
- * Adapted from https://github.com/slashinfty/tournament-pairings
+ * Maximum weighted matching avoiding rematches if possible and preferring equal scores. A team left
+ * over gets a bye. Adapted from https://github.com/slashinfty/tournament-pairings
  */
 export function pairUp(players: SwissPairingTeam[]) {
 	if (players.length === 0) {
@@ -223,8 +194,7 @@ export function pairUp(players: SwissPairingTeam[]) {
 		),
 	].sort((a, b) => a - b);
 
-	// every pair is considered so that the matching always covers as many teams as
-	// possible, rematches are simply weighted down heavily rather than left out
+	// every pair is considered so the matching covers as many teams as possible, rematches are weighted down instead of left out
 	const blossomPairs = blossom(
 		generateWeightedPairs({ playerArray, scoreGroups, scoreSums }),
 		true,
@@ -302,7 +272,7 @@ function generateWeightedPairs({
 
 			wt += 23 / (2 * (scoreGroupDiff + 2));
 
-			// Lower weight for larger score differences, we really want to avoid 2-0 playing 0-2 etc.
+			// really want to avoid 2-0 playing 0-2 etc.
 			if (scoreGroupDiff >= 2) {
 				wt -= 10;
 			}
diff --git a/app/features/tournament-bracket/core/engine/swiss/team-status.ts b/app/features/tournament-bracket/core/engine/swiss/team-status.ts
index d5062930c..ee8356598 100644
--- a/app/features/tournament-bracket/core/engine/swiss/team-status.ts
+++ b/app/features/tournament-bracket/core/engine/swiss/team-status.ts
@@ -1,17 +1,8 @@
 export type SwissTeamStatus = "active" | "advanced" | "eliminated";
 
 /**
- * Calculates whether a team should advance, be eliminated, or remain active
- * in a Swiss tournament with early advance/elimination rules.
- *
- * @returns The team's status: "advanced" if they've secured advancement,
- *          "eliminated" if they can no longer mathematically advance, or "active" if still competing
- *
- * @example
- * // In a 5-round Swiss where teams need 3 wins to advance:
- * calculateTeamStatus({ wins: 3, losses: 1, advanceThreshold: 3, roundCount: 5 }) // "advanced"
- * calculateTeamStatus({ wins: 2, losses: 3, advanceThreshold: 3, roundCount: 5 }) // "eliminated"
- * calculateTeamStatus({ wins: 2, losses: 2, advanceThreshold: 3, roundCount: 5 }) // "active"
+ * Swiss early advance/elimination: "advanced" once the threshold is reached, "eliminated" when it can
+ * no longer be reached, otherwise "active".
  */
 export function calculateTeamStatus({
 	wins,
@@ -19,13 +10,10 @@ export function calculateTeamStatus({
 	advanceThreshold,
 	roundCount,
 }: {
-	/** Number of matches the team has won */
 	wins: number;
-	/** Number of matches the team has lost */
 	losses: number;
-	/** Number of wins required to advance to the next stage */
+	/** Wins required to advance */
 	advanceThreshold: number;
-	/** Total number of rounds in the Swiss stage */
 	roundCount: number;
 }): SwissTeamStatus {
 	if (wins >= advanceThreshold) {
@@ -39,17 +27,12 @@ export function calculateTeamStatus({
 	return "active";
 }
 
-/**
- * Calculates the maximum valid advance threshold for a given round count.
- * The threshold must allow for meaningful play - teams need a chance to both advance and be eliminated.
- */
+/** Teams need a chance to both advance and be eliminated. */
 export function maxAdvanceThreshold({ roundCount }: { roundCount: number }) {
 	return Math.ceil(roundCount / 2) + 1;
 }
 
-/**
- * Calculates the maximum losses allowed before elimination given an advance threshold and round count.
- */
+/** Losses that eliminate a team. */
 export function eliminationThreshold({
 	roundCount,
 	advanceThreshold,
@@ -60,9 +43,7 @@ export function eliminationThreshold({
 	return roundCount - advanceThreshold + 1;
 }
 
-/**
- * Validates if an advance threshold is valid for the given round count.
- */
+/** Whether the advance threshold is valid for the round count. */
 export function isValidAdvanceThreshold({
 	roundCount,
 	advanceThreshold,
@@ -75,10 +56,7 @@ export function isValidAdvanceThreshold({
 	);
 }
 
-/**
- * Returns a list of valid advance threshold options for a given round count.
- * Starts from 2 wins minimum up to the calculated maximum.
- */
+/** From 2 wins up to {@link maxAdvanceThreshold}. */
 export function validAdvanceThresholdOptions({
 	roundCount,
 }: {
diff --git a/app/features/tournament-bracket/core/engine/types.ts b/app/features/tournament-bracket/core/engine/types.ts
index 77fc14335..38910b850 100644
--- a/app/features/tournament-bracket/core/engine/types.ts
+++ b/app/features/tournament-bracket/core/engine/types.ts
@@ -4,21 +4,12 @@ import type {
 	TournamentStageSettings,
 } from "~/db/tables-json";
 
-/**
- * The side of an opponent. Upstream brackets-model also allowed a draw —
- * intentionally dropped, draws are impossible in our formats.
- */
+/** No draw side: draws are impossible in our formats. */
 export type Side = "opponent1" | "opponent2";
 
 export type StageType = Tables["TournamentStage"]["type"];
 
-/**
- * All the possible types of group in an elimination stage.
- *
- * - `single_bracket` for single elimination.
- * - `winner_bracket` and `loser_bracket` for double elimination.
- * - `final_group` for both single and double elimination.
- */
+/** Group types of an elimination stage; `final_group` exists in both single and double elimination. */
 export type GroupType =
 	| "single_bracket"
 	| "winner_bracket"
@@ -37,10 +28,7 @@ export type SeedOrdering =
 /** The seeding for a stage. Each element is a participant id or a BYE: `null`. */
 export type Seeding = (number | null)[];
 
-/**
- * The possible settings for a stage. Same shape as what is persisted in
- * TournamentStage.settings today (the old brackets-model StageSettings).
- */
+/** Same shape as what is persisted in TournamentStage.settings. */
 export interface StageSettings {
 	/** Number of groups in a round robin or swiss stage. */
 	groupCount?: number;
@@ -48,18 +36,12 @@ export interface StageSettings {
 	/** Number of rounds in a swiss stage. */
 	roundCount?: number;
 
-	/**
-	 * Whether to generate a bipartite round-robin where teams are split into two
-	 * A/B divisions and every match pairs one A team with one B team.
-	 */
+	/** Bipartite round-robin: teams split into A/B divisions, every match pairs an A team with a B team. */
 	hasAbDivisions?: boolean;
 
 	/**
-	 * Whether matches in a round-robin stage are playable independently of each other.
-	 *
-	 * - If `false` (default), only round 1 matches start `Ready`; later rounds start
-	 *   `Locked` and unlock as both opponents complete the previous round.
-	 * - If `true`, every match with two opponents starts `Ready`.
+	 * Round robin: `false` (default) starts only round 1 `Ready`, later rounds unlock as both
+	 * opponents complete the previous round; `true` starts every match with two opponents `Ready`.
 	 */
 	independentRounds?: boolean;
 
@@ -74,20 +56,12 @@ export interface ParticipantResult {
 	/** Seed position this slot was filled from. */
 	position?: number;
 
-	/** The current score of the participant. */
 	score?: number;
 
-	/**
-	 * KO win count this set, aggregated on hydrate. Upstream's totalPoints is
-	 * intentionally gone — scoring is KO-only.
-	 */
+	/** KO win count this set, aggregated on hydrate. */
 	totalKos?: number;
 }
 
-/* ------------------------------------------------------------------ */
-/* Bracket data — identical shape to the old BracketData  */
-/* ------------------------------------------------------------------ */
-
 export interface StageData {
 	id: number;
 	/** Only set on stages read from the database, the engine does not create names. */
@@ -118,10 +92,7 @@ export interface MatchResults {
 	opponent1: ParticipantResult | null;
 	opponent2: ParticipantResult | null;
 
-	/**
-	 * The side that won the set, `null` while the match has no winner. A match
-	 * won against a BYE gets it set once the BYE is propagated.
-	 */
+	/** `null` while there is no winner. A match won against a BYE gets it set once the BYE is propagated. */
 	winnerSide: Side | null;
 }
 
@@ -134,11 +105,7 @@ export interface MatchData extends MatchResults {
 	startedAt?: number | null;
 }
 
-/**
- * The whole state of one tournament's brackets. This is the single value the
- * engine reads and returns. Never mutated in place — every engine operation
- * returns a new BracketData.
- */
+/** Whole state of one tournament's brackets. Never mutated in place, every engine operation returns a new one. */
 export interface BracketData {
 	stage: StageData[];
 	group: GroupData[];
@@ -146,35 +113,22 @@ export interface BracketData {
 	match: MatchData[];
 }
 
-/* ------------------------------------------------------------------ */
-/* Engine internals                                                    */
-/* ------------------------------------------------------------------ */
-
-/** Used by the engine to handle placements. Is `null` if is a BYE. Has a `null` id if it's yet to be determined. */
+/** `null` if a BYE, `null` id if yet to be determined. */
 export type ParticipantSlot = { id: number | null; position?: number } | null;
 
-/** The engine only handles duels. It's one participant versus another participant. */
 export type Duel = [ParticipantSlot, ParticipantSlot];
 
-/** Type of an object implementing every ordering method. */
 export type OrderingMap = Record<
 	SeedOrdering,
 	<T>(array: T[], ...args: number[]) => T[]
 >;
 
-/** Contains the losers and the winner of a standard bracket. */
 export interface StandardBracketResults {
-	/** The list of losers for each round of the bracket. */
+	/** Losers of each round. */
 	losers: ParticipantSlot[][];
-
-	/** The winner of the bracket. */
 	winner: ParticipantSlot;
 }
 
-/* ------------------------------------------------------------------ */
-/* Engine inputs                                                       */
-/* ------------------------------------------------------------------ */
-
 export interface CreateBracketInput {
 	type: StageType;
 	/** Team ids in seed order; `null` = BYE. */
@@ -188,10 +142,8 @@ export interface CreateBracketInput {
 	/** Stage number within the tournament. Defaults to 1 (local data; the repository assigns the real number on insert). */
 	number?: number;
 	/**
-	 * Per-round map info to assign onto the created rounds, keyed by the local
-	 * round ids of an identically created bracket (the preview the maps were
-	 * picked against). For round robin and swiss one entry per distinct round
-	 * number — groups share map lists.
+	 * Keyed by the local round ids of an identically created bracket (the preview the maps were
+	 * picked against). Round robin and swiss: one entry per round number, groups share map lists.
 	 */
 	maps?: RoundMapsInput[];
 }
@@ -202,30 +154,19 @@ export type RoundMapsInput = TournamentRoundMaps & {
 	groupId?: number;
 };
 
-/**
- * Engine-internal variant of {@link CreateBracketInput}: settings are the
- * already-resolved internal {@link StageSettings}.
- */
+/** {@link CreateBracketInput} with settings already resolved to internal {@link StageSettings}. */
 export interface ResolvedCreateBracketInput
 	extends Omit<CreateBracketInput, "settings" | "independentRounds"> {
 	settings: StageSettings;
 }
 
-/**
- * A result to apply to a match. The opponents of a match are decided by the
- * bracket, never by a reported result, so only the scores and the winner can be
- * given.
- */
+/** Opponents are decided by the bracket, never by a reported result, so only scores and winner can be given. */
 export interface MatchResultsInput {
-	/**
-	 * Games won by each side. Leaving it out keeps the current scores, `null`
-	 * clears them.
-	 */
+	/** Games won by each side. Omitted keeps the current scores, `null` clears them. */
 	scores?: [number, number] | null;
 	/**
-	 * Ends the set with this side as the winner even when the scores don't
-	 * decide it (an organizer force-ending a set, a team dropping out). Leaving
-	 * it out resolves the winner from the scores and the round's map count.
+	 * Ends the set with this side as winner even when the scores don't decide it (force-end, drop out).
+	 * Omitted resolves the winner from the scores and the round's map count.
 	 */
 	winnerSide?: Side;
 }
@@ -248,15 +189,7 @@ export interface SwissStanding {
 	};
 }
 
-/* ------------------------------------------------------------------ */
-/* Engine outputs                                                      */
-/* ------------------------------------------------------------------ */
-
-/**
- * Every engine mutation returns the full next state plus the delta. The
- * repository persists ONLY the delta; the state is for the caller to keep
- * working with (chained operations, simulations, revalidation payloads).
- */
+/** Full next state plus the delta. The repository persists only the delta. */
 export interface EngineResult {
 	data: BracketData;
 	/** Matches whose row must be UPDATEd (opponents changed). */
diff --git a/app/features/tournament-bracket/core/executeBracketOperation.server.ts b/app/features/tournament-bracket/core/executeBracketOperation.server.ts
index b929b5fa0..7a5d62e66 100644
--- a/app/features/tournament-bracket/core/executeBracketOperation.server.ts
+++ b/app/features/tournament-bracket/core/executeBracketOperation.server.ts
@@ -7,11 +7,7 @@ import * as BracketRepository from "../BracketRepository.server";
 import type * as Engine from "./engine";
 import type { Tournament } from "./Tournament";
 
-/**
- * Runs an engine operation against freshly hydrated bracket data and persists
- * the resulting match changes, all in one transaction: hydrate → operate →
- * (end dropped teams' matches) → apply changes → extra statements.
- */
+/** One transaction: hydrate → operate → (end dropped teams' matches) → apply changes → extra statements. */
 export async function executeBracketOperation<T extends Engine.EngineResult>({
 	tournamentId,
 	tournament,
@@ -22,9 +18,9 @@ export async function executeBracketOperation<T extends Engine.EngineResult>({
 	tournamentId: number;
 	tournament: Tournament;
 	operation: (bracketData: Engine.BracketData) => T;
-	/** Whether unfinished matches of dropped out teams should be ended after the operation (resolved from its result when given a function). */
+	/** End unfinished matches of dropped out teams after the operation (a function resolves it from the result). */
 	endDroppedTeams: boolean | ((result: T) => boolean);
-	/** Extra statements to run inside the same transaction, after the match changes have been applied. */
+	/** Run inside the same transaction after the match changes. */
 	inTransaction?: (result: T, trx: Transaction<DB>) => void | Promise<void>;
 }): Promise<{ result: T; endedMatchIds: number[] }> {
 	let result!: T;
diff --git a/app/features/tournament-bracket/core/finalizeTournament.server.ts b/app/features/tournament-bracket/core/finalizeTournament.server.ts
index e6bb3262c..b7fab3899 100644
--- a/app/features/tournament-bracket/core/finalizeTournament.server.ts
+++ b/app/features/tournament-bracket/core/finalizeTournament.server.ts
@@ -18,8 +18,7 @@ import { summaryRatingTargets, tournamentSummary } from "./summarizer.server";
 import type { Tournament } from "./Tournament";
 import { clearTournamentDataCache } from "./Tournament.server";
 
-/** Finalizes a fully played tournament with a real summary: results, skills, badges,
- * trophies and leaderboard entries. */
+/** Results, skills, badges, trophies and leaderboard entries of a fully played tournament. */
 export async function finalizeTournament({
 	tournament,
 	badgeReceivers,
@@ -132,8 +131,7 @@ function resolveFinalizationSeason(tournament: Tournament) {
 	const season = Seasons.current(attributionDate);
 	if (!season) return undefined;
 
-	// don't allow changing seasons that have already been closed for a long while
-	// even if you were sluggish with finalizing the tournament
+	// seasons closed for a long while can't be changed even by a sluggishly finalized tournament
 	if (differenceInHours(new Date(), season.ends) >= 24) return undefined;
 
 	return season.nth;
diff --git a/app/features/tournament-bracket/core/summarizer.server.ts b/app/features/tournament-bracket/core/summarizer.server.ts
index e90a217b0..6f68c6095 100644
--- a/app/features/tournament-bracket/core/summarizer.server.ts
+++ b/app/features/tournament-bracket/core/summarizer.server.ts
@@ -47,12 +47,8 @@ type RatingWithMatchesCount = {
 };
 
 /**
- * Users and teams whose current ratings `tournamentSummary` may look up, for the caller to
- * load up front.
- *
- * A superset: which of a set's teams and players actually get looked up depends on who
- * played the most maps of the set, and ties there are broken at random. Enumerating every
- * candidate keeps that decision inside `tournamentSummary`.
+ * Superset of the users and teams whose ratings `tournamentSummary` may look up, for the caller to load
+ * up front. Which actually get looked up depends on who played the most maps, ties broken at random.
  */
 export function summaryRatingTargets(results: AllMatchResult[]) {
 	const userIds = new Set<number>();
@@ -139,7 +135,7 @@ export function tournamentSummary({
 
 		if (!endedEarly) return true;
 
-		// Include early-ended sets where a team dropped out (they still affect skills)
+		// early-ended sets where a team dropped out still affect skills
 		return match.opponentOne.droppedOut || match.opponentTwo.droppedOut;
 	});
 
@@ -253,13 +249,8 @@ function calculateIndividualPlayerSkills({
 }
 
 /**
- * Determines the most frequently appearing user IDs for both the winning and losing teams in a match/set.
- *
- * For each team (winner and loser), this function collects all user IDs from the match's map participants,
- * counts their occurrences, and returns the most popular user IDs up to a full team's worth depending on the tournament format (4v4, 3v3 etc.).
- * If there are ties at the cutoff, all tied user IDs are included.
- *
- * For dropped team sets without game results, uses the activeRosterUserIds from the team records.
+ * Most frequent map participants of the winner and loser, up to a full team's worth (4v4, 3v3 etc.), ties
+ * at the cutoff all included. Dropped team sets without game results use the active roster.
  */
 function matchToSetMostPlayedUsers(match: AllMatchResult) {
 	const winner =
@@ -267,7 +258,7 @@ function matchToSetMostPlayedUsers(match: AllMatchResult) {
 	const loser =
 		match.winnerSide === "opponent1" ? match.opponentTwo : match.opponentOne;
 
-	// Handle dropped team sets without game results - use active roster or member list
+	// dropped team set without game results
 	if (match.maps.length === 0) {
 		const winnerRoster =
 			winner.activeRosterUserIds ?? winner.memberUserIds ?? [];
@@ -294,8 +285,7 @@ function matchToSetMostPlayedUsers(match: AllMatchResult) {
 		const result: number[] = [];
 		let previousCount = 0;
 		for (const [userId, count] of sorted) {
-			// take target amount of most popular users
-			// or more if there are ties
+			// target amount of most popular users, or more if there are ties
 			if (result.length >= targetAmount && count < previousCount) break;
 
 			result.push(userId);
@@ -343,13 +333,11 @@ function calculateTeamSkills({
 		const loser =
 			match.winnerSide === "opponent1" ? match.opponentTwo : match.opponentOne;
 
-		// Handle dropped team sets without game results - use active roster or member list
 		let winnerTeamIdentifier: SkillTeamIdentifier;
 		let loserTeamIdentifier: SkillTeamIdentifier;
 
 		if (match.maps.length === 0) {
-			// Use activeRosterUserIds if set, otherwise fall back to memberUserIds
-			// (teams without subs have their roster trivially inferred from members)
+			// dropped team set without game results, teams without subs have their roster inferred from members
 			const winnerRoster =
 				winner.activeRosterUserIds ?? winner.memberUserIds ?? [];
 			const loserRoster =
diff --git a/app/features/tournament-bracket/core/tests/test-utils.ts b/app/features/tournament-bracket/core/tests/test-utils.ts
index f9d5464dd..7757332ed 100644
--- a/app/features/tournament-bracket/core/tests/test-utils.ts
+++ b/app/features/tournament-bracket/core/tests/test-utils.ts
@@ -122,11 +122,7 @@ export const testTournament = ({
 	});
 };
 
-/**
- * Combines separately created brackets into the bracket data of one tournament,
- * offsetting the local ids of every bracket after the first the same way the
- * database does when a new stage is added to an existing tournament.
- */
+/** Combines brackets into one tournament's data, offsetting local ids the way the database does on adding a stage. */
 export const mergeStages = (...brackets: BracketData[]): BracketData => {
 	const merged: BracketData = { stage: [], group: [], round: [], match: [] };
 
diff --git a/app/features/tournament-bracket/core/toMapList.ts b/app/features/tournament-bracket/core/toMapList.ts
index 5722b0e34..8be6e3eea 100644
--- a/app/features/tournament-bracket/core/toMapList.ts
+++ b/app/features/tournament-bracket/core/toMapList.ts
@@ -1,4 +1,4 @@
-/** Map list generation logic for "TO pick" as in the map list is defined beforehand by TO and teams don't pick */
+/** Map list generation for "TO pick": the map list is defined beforehand by the TO. */
 
 import type { Tables } from "~/db/tables";
 import type { TournamentRoundMaps } from "~/db/tables-json";
@@ -34,12 +34,10 @@ export type TournamentRoundMapList = ReturnType<
 export function generateTournamentRoundMaplist(
 	args: GenerateTournamentRoundMaplistArgs,
 ) {
-	// in round robin different group ids represent different groups
-	// but they share the map list
+	// round robin groups share the map list
 	const filteredRounds = getFilteredRounds(args.rounds, args.type);
 
-	// sort rounds in a way that allows us to space maps out
-	// so in the typical order that people play out the tournament
+	// in the typical play order, so maps can be spaced out
 	const sortedRounds = sortRounds(filteredRounds, args.type);
 
 	//                roundId
@@ -98,9 +96,8 @@ function getFilteredRounds(
 ) {
 	if (type !== "round_robin" && type !== "swiss") return rounds;
 
-	// Groups can have different round counts when teams don't divide evenly
-	// (e.g. groups of 3 and 2). Use the group with the most rounds: it covers
-	// every round number and its map list is shared with the smaller groups.
+	// groups can have different round counts (e.g. groups of 3 and 2), the one with the most rounds
+	// covers every round number and its map list is shared with the smaller groups
 	const fullestGroupId = fullestGroupIdByRounds(rounds);
 	return rounds.filter((x) => x.groupId === fullestGroupId);
 }
@@ -159,8 +156,7 @@ function resolveRoundMapCount(
 	counts: BracketMapCounts,
 	type: Tables["TournamentStage"]["type"],
 ) {
-	// with rr/swiss every group shares the same map list, so use the group with
-	// the most rounds since it is the one that covers every round number
+	// rr/swiss groups share the map list, the one with the most rounds covers every round number
 	const groupId =
 		type === "round_robin" || type === "swiss"
 			? fullestGroupIdByCounts(counts)
diff --git a/app/features/tournament-bracket/loaders/to.$id.brackets.server.ts b/app/features/tournament-bracket/loaders/to.$id.brackets.server.ts
index 17a2fac14..37962e67d 100644
--- a/app/features/tournament-bracket/loaders/to.$id.brackets.server.ts
+++ b/app/features/tournament-bracket/loaders/to.$id.brackets.server.ts
@@ -15,12 +15,9 @@ import { showsOneGroupAtATime } from "../tournament-bracket-utils";
 export type TournamentBracketsLoaderData = SerializeFrom<typeof loader>;
 
 /**
- * Match data of the one bracket the view renders, selected by the `idx` search param.
- * The other brackets are represented by the layout's bracket state alone. Of a swiss
- * bracket only the group the view renders, selected by the `group` search param.
- *
- * Of a league only the brackets of one division are shown, selected by the `division`
- * search param. Reaching the page without one lands on the divisions page instead.
+ * Match data of the one bracket (`idx` param; swiss: one group, `group` param) the view renders, the
+ * others are represented by the layout's bracket state. A league shows one division (`division`
+ * param), without one the divisions page is shown instead.
  */
 export const loader = async ({ params, request }: LoaderFunctionArgs) => {
 	const { tournament, user } = await tournamentFromParams(params, {
@@ -77,10 +74,7 @@ export const loader = async ({ params, request }: LoaderFunctionArgs) => {
 	};
 };
 
-/**
- * The division to show the brackets of, of a league. Falls back to the division of the selected
- * bracket, so that a link to one bracket of a division works without naming the division.
- */
+/** Falls back to the selected bracket's division, so a link to one bracket works without naming it. */
 function resolveDivisionIdx(
 	tournament: Tournament,
 	searchParams: { division: number | null; idx: number | null },
@@ -99,11 +93,7 @@ function resolveDivisionIdx(
 		: null;
 }
 
-/**
- * The bracket to show, always one of the brackets the view actually renders a tab for. Without
- * a valid `idx` the first bracket, unless it is over and followed by a bracket the tournament
- * actually continues in.
- */
+/** Always one with a tab. Without a valid `idx` the first bracket, unless it is over and followed by one the tournament continues in. */
 function resolveBracketIdx(
 	tournament: Tournament,
 	idx: number | null,
diff --git a/app/features/tournament-bracket/routes/to.$id.brackets.tsx b/app/features/tournament-bracket/routes/to.$id.brackets.tsx
index bf7b3e096..dbc2847ca 100644
--- a/app/features/tournament-bracket/routes/to.$id.brackets.tsx
+++ b/app/features/tournament-bracket/routes/to.$id.brackets.tsx
@@ -113,8 +113,7 @@ function TournamentBracketsView() {
 		tournamentChannel(tournament.ctx.id),
 		!tournament.ctx.isFinalized,
 	);
-	// results of the loaded bracket (and group) broadcast to their own room, so that
-	// another bracket's or group's live scores do not make this view refetch
+	// own room per bracket (and group) so another's live scores do not make this view refetch
 	useTopicRevalidation(
 		tournamentBracketChannel({
 			tournamentId: tournament.ctx.id,
@@ -275,11 +274,7 @@ export interface BracketsPageState {
 	scrollToMatchId?: number;
 }
 
-/**
- * Scrolls the match referenced by the navigation `state` into view on load, so
- * returning from a match page lands the user at that match's spot in the bracket
- * instead of the top.
- */
+/** Returning from a match page lands at that match's spot in the bracket instead of the top. */
 function useScrollToMatchOnLoad() {
 	const location = useLocation();
 	const scrollToMatchId = (location.state as BracketsPageState | null)
@@ -494,10 +489,8 @@ function SubsPopover({ children }: { children: React.ReactNode }) {
 }
 
 /**
- * Bracket switcher. Only the bracket the loader shipped the match data of is rendered;
- * switching navigates so that the newly selected bracket's data gets loaded, the
- * previously loaded bracket staying up until it arrives. Of a league only the brackets
- * of the division the loader resolved can be switched between.
+ * Only the bracket the loader shipped is rendered; switching navigates to load the new one, the previous
+ * staying up until it arrives. A league switches only within the loader's division.
  */
 function BracketTabs({
 	loadedBracketIdx,
diff --git a/app/features/tournament-bracket/tournament-bracket-utils.ts b/app/features/tournament-bracket/tournament-bracket-utils.ts
index 6e7a3143f..27d9bc274 100644
--- a/app/features/tournament-bracket/tournament-bracket-utils.ts
+++ b/app/features/tournament-bracket/tournament-bracket-utils.ts
@@ -11,10 +11,8 @@ export const tournamentChannel = (tournamentId: number) =>
 	`${CHANNEL_PREFIX.tournament}${tournamentId}`;
 
 /**
- * Channel of the slice of the brackets page one bracket's (for the types viewed one group at
- * a time, one group's) match data is rendered in. Broadcasts that can only have changed
- * that match data go here rather than to the whole tournament's channel, so that the viewers
- * of the other brackets and groups do not refetch.
+ * Channel of one bracket's (or, for types viewed one group at a time, one group's) match data.
+ * Broadcasts only affecting that data go here instead of the tournament's channel so other viewers don't refetch.
  */
 export const tournamentBracketChannel = ({
 	tournamentId,
@@ -34,18 +32,10 @@ export const tournamentBracketChannel = ({
 export const showsOneGroupAtATime = (type: Tables["TournamentStage"]["type"]) =>
 	type === "swiss";
 
-/**
- * Converts a group number to its corresponding letter representation.
- *
- * The function takes a one-based group number and converts it to a string
- * of uppercase letters, similar to how Excel columns are labeled (e.g., 1 -> 'A', 26 -> 'Z', 27 -> 'AA').
- *
- * @param groupNumber - The one-based group number to convert.
- * @returns The letter representation of the group number.
- */
+/** One-based group number to Excel column style letters: 1 -> 'A', 26 -> 'Z', 27 -> 'AA'. */
 export function groupNumberToLetters(groupNumber: number) {
 	let letters = "";
-	let num = groupNumber - 1; // Adjust for one-based input
+	let num = groupNumber - 1;
 	while (num >= 0) {
 		letters = String.fromCharCode((num % 26) + 65) + letters;
 		num = Math.floor(num / 26) - 1;
@@ -92,14 +82,8 @@ export function ensureOneStandingPerUser(standings: Standing[]) {
 }
 
 /**
- * Validates the assignment of badges to receivers in a tournament finalization context.
- *
- * Checks the following conditions:
- * - Each badge receiver references a valid badge from the provided list.
- * - Every badge has at least one assigned receiver (both team and at least one user).
- * - No duplicate tournament team IDs exist among the badge receivers.
- *
- *   Returns `null` if all validations pass.
+ * Every receiver references a given badge, every badge has a team and at least one user, no team
+ * receives twice. Returns `null` when valid.
  */
 export function validateBadgeReceivers({
 	badgeReceivers,
diff --git a/app/features/tournament-lfg/TournamentLFGRepository.server.test.ts b/app/features/tournament-lfg/TournamentLFGRepository.server.test.ts
index 267b5c690..9830f93ce 100644
--- a/app/features/tournament-lfg/TournamentLFGRepository.server.test.ts
+++ b/app/features/tournament-lfg/TournamentLFGRepository.server.test.ts
@@ -410,8 +410,7 @@ describe("mergeTeams", () => {
 			maxGroupSize: 4,
 		});
 
-		// the loser's room is gone; only the survivor's (possibly reusing the
-		// freed rowid) remains
+		// the loser's room is gone; only the survivor's (possibly reusing the freed rowid) remains
 		const rooms = await db.selectFrom("ChatRoom").select("id").execute();
 		expect(rooms).toHaveLength(1);
 		expect(rooms[0].id).toBe(await chatRoomIdOf(team1.id));
@@ -449,8 +448,8 @@ describe("mergeTeams", () => {
 		const team1 = await createPlaceholder(tournament.id, users.id(1));
 		const team2 = await createPlaceholder(tournament.id, users.id(2));
 
-		// user 2 was looking before user 1 i.e. has an older createdAt. The column
-		// defaults in SQL, and the table has no id of its own for `backdate` to key on
+		// user 2 was looking before user 1 (older createdAt); the column defaults in SQL and the table
+		// has no id for `backdate` to key on
 		// biome-ignore lint/plugin: no production write sets the timestamp
 		await db
 			.updateTable("TournamentTeamMember")
diff --git a/app/features/tournament-lfg/TournamentLFGRepository.server.ts b/app/features/tournament-lfg/TournamentLFGRepository.server.ts
index 380510846..7a803cf17 100644
--- a/app/features/tournament-lfg/TournamentLFGRepository.server.ts
+++ b/app/features/tournament-lfg/TournamentLFGRepository.server.ts
@@ -186,8 +186,7 @@ export function mergeTeams({
 
 		await ensurePickupChatRoom(survivingTeamId, chatRoomExpiresAt, trx);
 
-		// the merged-in members either lost their old room or gained the
-		// surviving team's, and the surviving members may have just gained theirs
+		// merged-in members lost their old room or gained the surviving team's, which may itself be new
 		return memberUserIds;
 	});
 }
diff --git a/app/features/tournament-match/TournamentMatchRepository.server.test.ts b/app/features/tournament-match/TournamentMatchRepository.server.test.ts
index 66e6d4603..87b24942d 100644
--- a/app/features/tournament-match/TournamentMatchRepository.server.test.ts
+++ b/app/features/tournament-match/TournamentMatchRepository.server.test.ts
@@ -33,8 +33,7 @@ describe("findByTournamentTeamId", () => {
 	});
 
 	test("preserves stage order: matches from an earlier stage come first even when later stage has lower group numbers", async () => {
-		// the pools stage numbers its groups 1..2 while the final is group 1 of its
-		// own stage, so the team page has to order by stage before group
+		// pools are groups 1..2 while the final is group 1 of its own stage, so order by stage before group
 		const tournament = await TournamentFactory.createPlayed(
 			{
 				authorId: users.id(1),
diff --git a/app/features/tournament-match/TournamentMatchRepository.server.ts b/app/features/tournament-match/TournamentMatchRepository.server.ts
index ea71b1302..0054cb663 100644
--- a/app/features/tournament-match/TournamentMatchRepository.server.ts
+++ b/app/features/tournament-match/TournamentMatchRepository.server.ts
@@ -268,7 +268,7 @@ export interface AllMatchResult {
 		mode: ModeShort;
 		winnerTeamId: number;
 		participants: Array<{
-			// in the DB this can actually also be null, but for new tournaments it should always be a number
+			// nullable in the DB, but always a number for new tournaments
 			tournamentTeamId: number;
 			userId: number;
 		}>;
@@ -323,8 +323,7 @@ export async function findAllResultsByTournamentId(
 					.select("TournamentTeamMember.userId")
 					.whereRef("TournamentTeamMember.tournamentTeamId", "=", "Team2.id"),
 			).as("opponentTwoMembers"),
-			// participants are fetched flat below: nesting them in here made SQLite build
-			// and re-parse a JSON document per game for tens of thousands of rows
+			// participants are fetched flat below: nesting made SQLite build and re-parse a JSON document per game
 			jsonArrayFrom(
 				eb
 					.selectFrom("TournamentMatchGameResult")
@@ -344,7 +343,7 @@ export async function findAllResultsByTournamentId(
 		])
 		.where("TournamentStage.tournamentId", "=", tournamentId)
 		.where("TournamentMatch.winnerSide", "is not", null)
-		// strictly speaking the order by condition is not accurate, future improvement would be to add order conditions that match the tournament structure
+		// not strictly accurate, ordering by the tournament structure would be an improvement
 		.orderBy("TournamentMatch.id", "asc")
 		.execute();
 
diff --git a/app/features/tournament-match/actions/to.$id.matches.$mid.server.ts b/app/features/tournament-match/actions/to.$id.matches.$mid.server.ts
index 82d004b48..fc3e156fa 100644
--- a/app/features/tournament-match/actions/to.$id.matches.$mid.server.ts
+++ b/app/features/tournament-match/actions/to.$id.matches.$mid.server.ts
@@ -93,8 +93,7 @@ export const action: ActionFunction = async ({ params, request }) => {
 
 	let emitMatchUpdate = false;
 	let emitTournamentUpdate = false;
-	// true when nothing outside match data (scores, pick/ban events) changed, letting
-	// broadcast receivers skip revalidating the tournament layout and root loaders
+	// lets broadcast receivers skip revalidating the tournament layout and root loaders
 	let onlyMatchResultsChanged = false;
 	let setIsOver = false;
 	let endedDroppedMatchIds: number[] = [];
@@ -120,8 +119,7 @@ export const action: ActionFunction = async ({ params, request }) => {
 
 			emitMatchUpdate = true;
 			emitTournamentUpdate = true;
-			// a set ending (or dropped teams' matches ending) changes bracket state
-			// the layout ships (bracketsMeta), so only mid-set reports are scoped
+			// a set ending (or dropped teams' matches ending) changes the layout's bracketsMeta
 			onlyMatchResultsChanged = !setIsOver && endedDroppedMatchIds.length === 0;
 
 			break;
@@ -412,8 +410,7 @@ export const action: ActionFunction = async ({ params, request }) => {
 
 			const eventType = (() => {
 				if (match.roundMaps.pickBan === "CUSTOM") {
-					// a no-mode-repeat pick is stored as a regular map pick; the
-					// restriction only applies while choosing, not to the stored event
+					// the no-mode-repeat restriction only applies while choosing, not to the stored event
 					return actionType === "PICK_NO_MODE_REPEAT"
 						? ("PICK" as const)
 						: actionType;
@@ -432,15 +429,13 @@ export const action: ActionFunction = async ({ params, request }) => {
 					type: eventType,
 				});
 			} catch (error) {
-				// another request already recorded this pick/ban in the race window,
-				// let their page refresh to pick up the already-recorded event
+				// another request already recorded this pick/ban, let their page refresh to pick it up
 				if (errorIsSqliteUniqueConstraintFailure(error)) {
 					return null;
 				}
 				throw error;
 			}
 
-			// Chain roll after action for CUSTOM flow
 			if (match.roundMaps.pickBan === "CUSTOM" && match.roundMaps.customFlow) {
 				const updatedEvents =
 					await TournamentRepository.findPickBanEventsByMatchId(match.id);
@@ -481,7 +476,7 @@ export const action: ActionFunction = async ({ params, request }) => {
 				operation: (bracketData) => Engine.reopenMatch(bracketData, match.id),
 				endDroppedTeams: false,
 				inTransaction: async (result, trx) => {
-					// edge case but for round robin we can just leave the match as is, lock it then unlock later to continue where they left off (should not really ever happen)
+					// round robin edge case: leave the match as is, lock it and unlock later to continue (should not really ever happen)
 					if (bracketFormat !== "round_robin") {
 						for (const followingMatch of followingMatches) {
 							await TournamentMatchRepository.deletePickBanEventsByMatchId(
@@ -491,9 +486,8 @@ export const action: ActionFunction = async ({ params, request }) => {
 						}
 					}
 
-					// when the set was force-ended early no extra result was inserted for
-					// the forced win, so the last result is a genuinely played game and must
-					// be kept to avoid desyncing the score from the results
+					// a force-ended set inserted no result for the forced win, so its last result is a
+					// played game that must stay or the score desyncs from the results
 					if (!result.endedEarly) {
 						invariant(lastResult, "Last result is missing");
 						await TournamentMatchRepository.deleteResultById(
@@ -508,8 +502,7 @@ export const action: ActionFunction = async ({ params, request }) => {
 				`Reopening match: User ID: ${user.id}; Match ID: ${match.id}; Ended early: ${reopened.endedEarly}`,
 			);
 
-			// the teams advanced into following matches are being pulled back out,
-			// so those "waiting for teams" pages need to revalidate too
+			// teams pulled back out of following matches: their "waiting for teams" pages revalidate too
 			followingMatchIds = followingMatches.map(
 				(followingMatch) => followingMatch.id,
 			);
@@ -588,7 +581,6 @@ export const action: ActionFunction = async ({ params, request }) => {
 			);
 			errorToastIfFalsy(!match.winnerSide, "Match is already over");
 
-			// Determine winner (random if not specified)
 			const winnerTeamId = (() => {
 				if (data.winnerTeamId) {
 					errorToastIfFalsy(
@@ -599,7 +591,6 @@ export const action: ActionFunction = async ({ params, request }) => {
 					return data.winnerTeamId;
 				}
 
-				// Random winner: true 50/50 selection
 				return Math.random() < 0.5
 					? match.opponentOne.id
 					: match.opponentTwo.id;
@@ -621,8 +612,7 @@ export const action: ActionFunction = async ({ params, request }) => {
 			});
 			endedDroppedMatchIds = endedMatchIds;
 
-			// the set ended early so no further games will be played; trim weapons
-			// reported in advance for map indexes beyond the games actually played
+			// no further games: trim weapons reported in advance for maps beyond the games played
 			const playedResults =
 				await TournamentMatchRepository.findResultsByMatchId(matchId);
 			await ReportedWeaponRepository.deleteExtraByTournamentMatchId({
@@ -679,12 +669,10 @@ export const action: ActionFunction = async ({ params, request }) => {
 
 	clearTournamentDataCache(tournamentId);
 
-	// update RunningTournaments to make sure sidebar is not showing stale matches at the end
-	// of the tournament in case the TO is not finalizing the tournament right away
+	// refresh RunningTournaments so the sidebar doesn't show stale matches while the TO delays finalizing
 	if (setIsOver) {
 		const refreshedTournament = await tournamentFromDB(tournamentId);
-		// the teams that just advanced now populate following matches, so their
-		// "waiting for teams" pages need to revalidate too
+		// teams just advanced into following matches: their "waiting for teams" pages revalidate too
 		followingMatchIds = refreshedTournament
 			.followingMatches(match.id)
 			.map((followingMatch) => followingMatch.id);
@@ -724,11 +712,7 @@ export const action: ActionFunction = async ({ params, request }) => {
 	return null;
 };
 
-/**
- * Room of the brackets page views that render this match, i.e. the ones a change of its
- * results can be seen in. Falls back to the whole tournament's room if the match's bracket
- * can not be resolved.
- */
+/** Room of the brackets page views rendering this match; the whole tournament's room if its bracket can't be resolved. */
 function matchResultsRoom(
 	tournament: Tournament,
 	match: NonNullable<FindMatchById>,
diff --git a/app/features/tournament-match/components/TournamentMatchActionTab.tsx b/app/features/tournament-match/components/TournamentMatchActionTab.tsx
index bedcbafc9..66614667d 100644
--- a/app/features/tournament-match/components/TournamentMatchActionTab.tsx
+++ b/app/features/tournament-match/components/TournamentMatchActionTab.tsx
@@ -40,8 +40,7 @@ export function TournamentMatchActionTab({
 		weaponReportingOpen: tournament.weaponReportingOpen,
 	});
 
-	// during pick/ban there is no current map to report, but a wrongly reported
-	// score from a previous game can still be undone (not once the set is over)
+	// no current map to report during pick/ban, but a previous game's score can still be undone (not once the set is over)
 	if (!currentMap) {
 		const canUndo = scoreSum > 0 && !data.matchIsOver;
 		return (
@@ -196,8 +195,7 @@ function useTournamentWeaponReport({
 	function viewerPlayedMap(mapIndex: number) {
 		if (viewerUserId === undefined) return false;
 
-		// a played map remembers the roster it was played with, the map still to be
-		// played goes by the roster as it stands now
+		// a played map remembers its roster, the map still to be played goes by the roster as it stands now
 		const result = data.results[mapIndex];
 		if (result) {
 			return result.participants.some((p) => p.userId === viewerUserId);
diff --git a/app/features/tournament-match/components/TournamentMatchAdminTab.tsx b/app/features/tournament-match/components/TournamentMatchAdminTab.tsx
index e727eb680..5d21cf294 100644
--- a/app/features/tournament-match/components/TournamentMatchAdminTab.tsx
+++ b/app/features/tournament-match/components/TournamentMatchAdminTab.tsx
@@ -140,9 +140,8 @@ function CastChannelChipRadio({
 	const { submit, fetcher } = useActionSubmit(matchSchema);
 	const previousStateRef = React.useRef(fetcher.state);
 
-	// the action can still reject (e.g. "Not an organizer or streamer"), so the
-	// success toast waits for the round trip; on failure the action's data stays
-	// unset and only the error toast shows
+	// the action can still reject (e.g. "Not an organizer or streamer"), so the success toast waits
+	// for the round trip; on failure its data stays unset and only the error toast shows
 	React.useEffect(() => {
 		if (
 			previousStateRef.current !== "idle" &&
@@ -373,9 +372,8 @@ function EditReportedScoreRow({
 	const fetcher = useFetcher();
 	const [editing, setEditing] = React.useState(false);
 
-	// close the form once our own submit round trip succeeds (action returns
-	// null); on failure the action redirects with an error toast and data stays
-	// unset, keeping the form open
+	// close once our own submit succeeds (action returns null); on failure the action redirects
+	// with an error toast and data stays unset, keeping the form open
 	const [previousFetcherState, setPreviousFetcherState] = React.useState(
 		fetcher.state,
 	);
diff --git a/app/features/tournament-match/components/TournamentMatchBanner.tsx b/app/features/tournament-match/components/TournamentMatchBanner.tsx
index 449394c6a..38b09bca0 100644
--- a/app/features/tournament-match/components/TournamentMatchBanner.tsx
+++ b/app/features/tournament-match/components/TournamentMatchBanner.tsx
@@ -395,12 +395,7 @@ function resolveCurrentMinutes({
 	);
 }
 
-/**
- * Resolves the database timestamp that the current "session" (the thing the
- * sub-timer counts up from) started at. For pick/ban matches this is the start
- * of the current pick/ban turn, otherwise it is the time the most recently
- * reported game finished, falling back to the match start.
- */
+/** Start of what the sub-timer counts from: the current pick/ban turn, else the last reported game's end, else match start. */
 function resolveCurrentSessionStartedAt({
 	data,
 	tournament,
diff --git a/app/features/tournament-match/components/TournamentMatchTabs.tsx b/app/features/tournament-match/components/TournamentMatchTabs.tsx
index dd089ba8f..6d8bea990 100644
--- a/app/features/tournament-match/components/TournamentMatchTabs.tsx
+++ b/app/features/tournament-match/components/TournamentMatchTabs.tsx
@@ -40,7 +40,7 @@ export function TournamentMatchTabs({
 		isPickBanStep,
 	} = useMatch();
 
-	// When waiting on team(s) only a subset of tabs can be rendered
+	// waiting on team(s): only a subset of tabs can be rendered
 	if (!teamOne || !teamTwo) {
 		return tabs.length > 0 ? (
 			<MatchTabs tabs={tabs}>
diff --git a/app/features/tournament-match/core/mapList.server.ts b/app/features/tournament-match/core/mapList.server.ts
index 35645faa7..3fc1a22c7 100644
--- a/app/features/tournament-match/core/mapList.server.ts
+++ b/app/features/tournament-match/core/mapList.server.ts
@@ -36,14 +36,13 @@ interface ResolveCurrentMapListArgs {
 		stageId: StageId | null;
 		type: Tables["TournamentMatchPickBanEvent"]["type"];
 	}>;
-	/** Maps that both teams (interleaved) have recently played in the tournament with the most recent being first. */
+	/** Both teams' recently played maps interleaved, most recent first. */
 	recentlyPlayedMaps?: Array<{ mode: ModeShort; stageId: StageId }>;
 }
 
 export function resolveMapList(
 	args: ResolveCurrentMapListArgs,
 ): TournamentMapListMap[] {
-	// CUSTOM flow: map list is built from pick/ban events
 	if (args.maps.pickBan === "CUSTOM") {
 		return resolveCustomMapList(args);
 	}
@@ -93,10 +92,8 @@ export function resolveMapList(
 }
 
 /**
- * The map list the given match is played on, `null` when it does not yet have both
- * of its teams. Resolves the arguments {@link resolveMapList} needs out of the match
- * and its tournament: the teams' map pools, the pick/ban events so far and, for the
- * picking styles that avoid repeats, the maps the teams recently played.
+ * The match's map list, `null` without both teams. Resolves what {@link resolveMapList} needs
+ * from the match and tournament: map pools, pick/ban events and, for repeat-avoiding styles, recent maps.
  */
 export async function resolveMatchMapList({
 	match,
@@ -172,7 +169,7 @@ export function mapListFromResults(
 		mode: result.mode,
 		stageId: result.stageId,
 		source: parseMaplistSource(result.source),
-		// Banned maps are not relevant for completed matches
+		// not relevant for completed matches
 		bannedByTournamentTeamId: undefined,
 	}));
 }
diff --git a/app/features/tournament-match/core/reportScore.server.ts b/app/features/tournament-match/core/reportScore.server.ts
index f2338e332..d6543aee2 100644
--- a/app/features/tournament-match/core/reportScore.server.ts
+++ b/app/features/tournament-match/core/reportScore.server.ts
@@ -20,13 +20,10 @@ export interface ReportScoreResult {
 }
 
 /**
- * Records the winner of one game of a tournament match, advancing the bracket and
- * storing who played it. `position` is the index of the game within the set, and a
- * report for any other index is a page that has fallen behind — those return `null`
- * rather than erroring, as does a game another request recorded first.
- *
- * The reporter must be an organizer or a member of one of the two teams. Both teams
- * must have an active roster; a team with no subs has one implicitly.
+ * Records the winner of one game, advancing the bracket and storing who played. `position` is
+ * the game's index in the set; any other index is a page that fell behind and returns `null`
+ * rather than erroring, as does a game another request recorded first. The reporter must be an
+ * organizer or on one of the teams; both teams need an active roster (implicit without subs).
  */
 export async function reportScore({
 	match,
@@ -50,8 +47,7 @@ export async function reportScore({
 		match.opponentTwo?.score ?? 0,
 	];
 
-	// they are trying to report score that was already reported
-	// assume that it was already reported and make their page refresh
+	// already reported, make their page refresh
 	if (position !== scores[0] + scores[1]) {
 		return null;
 	}
@@ -158,8 +154,7 @@ export async function reportScore({
 		setOver = operated.result.setOver;
 		endedMatchIds = operated.endedMatchIds;
 	} catch (error) {
-		// another request already reported this game in the race window,
-		// let their page refresh to pick up the already-recorded result
+		// another request already reported this game, let their page refresh to pick it up
 		if (errorIsSqliteUniqueConstraintFailure(error)) {
 			return null;
 		}
@@ -167,8 +162,7 @@ export async function reportScore({
 	}
 
 	if (setOver) {
-		// the set ended, so weapons reported in advance for map indexes
-		// beyond the games actually played are trimmed
+		// trim weapons reported in advance for maps beyond the games played
 		await ReportedWeaponRepository.deleteExtraByTournamentMatchId({
 			tournamentMatchId: match.id,
 			gameCount: position + 1,
diff --git a/app/features/tournament-match/loaders/to.$id.matches.$mid.server.ts b/app/features/tournament-match/loaders/to.$id.matches.$mid.server.ts
index 80e677044..86f59280e 100644
--- a/app/features/tournament-match/loaders/to.$id.matches.$mid.server.ts
+++ b/app/features/tournament-match/loaders/to.$id.matches.$mid.server.ts
@@ -106,8 +106,7 @@ export const loader = async ({ params }: LoaderFunctionArgs) => {
 		}
 	}
 
-	// cached so that some user changing their noScreen preference doesn't
-	// change the selection once the match has started
+	// cached so a noScreen preference change doesn't change the selection once the match has started
 	const noScreen =
 		match.opponentOne?.id && match.opponentTwo?.id
 			? await cachified({
diff --git a/app/features/tournament-match/match-page-context.tsx b/app/features/tournament-match/match-page-context.tsx
index 96e8f0241..6d416a3ff 100644
--- a/app/features/tournament-match/match-page-context.tsx
+++ b/app/features/tournament-match/match-page-context.tsx
@@ -12,10 +12,7 @@ import {
 import type { TournamentMatchLoaderData } from "./loaders/to.$id.matches.$mid.server";
 import { matchIsLocked, resolveHostingTeam } from "./tournament-match-utils";
 
-/**
- * One of the match's two teams: the tournament wide lite team (with its resolved seed)
- * plus the roster and map pool that the match loader ships for these two teams only.
- */
+/** The tournament wide lite team (resolved seed) plus the roster and map pool the match loader ships for its two teams. */
 export type MatchPageTeam = NonNullable<ReturnType<Tournament["teamById"]>> &
 	Pick<TournamentMatchLoaderData["teams"][number], "members" | "mapPool">;
 
@@ -218,8 +215,7 @@ function resolveVisibleTabs({
 	if (isAdminEligible) {
 		tabs.push(TAB_KEYS.ADMIN);
 	}
-	// matchIsOver with no reports nor pick/ban events = drop-out / forfeit;
-	// no results to show
+	// over with no reports nor pick/ban events = drop-out / forfeit, no results to show
 	if (hasReportedMaps || hasPickBanEvents) {
 		tabs.push(TAB_KEYS.RESULT);
 	}
@@ -227,10 +223,8 @@ function resolveVisibleTabs({
 	return tabs;
 }
 
-// Derived from the match loader's data instead of the tournament loader's
-// bracket data — the latter can be stale on the client (its revalidation is
-// aborted if the user navigates mid-flight and same-tournament navigations
-// skip it), which would hide the action tab on an already-ready match.
+// from the match loader's data, as the tournament loader's bracket data can be stale on the
+// client (revalidation aborted mid-flight, skipped by same-tournament navigations) and hide the action tab
 function resolveCanReportScore({
 	tournament,
 	user,
diff --git a/app/features/tournament-match/routes/to.$id.matches.$mid.test.ts b/app/features/tournament-match/routes/to.$id.matches.$mid.test.ts
index 72ec56e03..b82799aab 100644
--- a/app/features/tournament-match/routes/to.$id.matches.$mid.test.ts
+++ b/app/features/tournament-match/routes/to.$id.matches.$mid.test.ts
@@ -279,8 +279,7 @@ describe("Tournament match page", () => {
 	describe("locked match", () => {
 		test("returns error when reporting score for a match waiting on previous matches", async () => {
 			await setActiveRosterAction();
-			// the state under test is one an earlier match of a larger bracket puts this
-			// row in, not one the match was created in
+			// a state an earlier match of a larger bracket puts this row in, not one it was created in
 			// biome-ignore lint/plugin: written rather than seeded, see above
 			await db
 				.updateTable("TournamentMatch")
@@ -295,8 +294,7 @@ describe("Tournament match page", () => {
 	});
 
 	describe("BYE matches", () => {
-		// as above: a BYE and a TBD opponent are states the surrounding bracket
-		// produces, so they are written here rather than seeded
+		// as above: a BYE and a TBD opponent are states the surrounding bracket produces, so written not seeded
 		test("404s when accessing a BYE match", async () => {
 			// biome-ignore lint/plugin: as above
 			await db
diff --git a/app/features/tournament-match/tournament-match-utils.ts b/app/features/tournament-match/tournament-match-utils.ts
index c525b20c9..0cab18398 100644
--- a/app/features/tournament-match/tournament-match-utils.ts
+++ b/app/features/tournament-match/tournament-match-utils.ts
@@ -106,6 +106,5 @@ export function isSetOverByResults({
 
 	const maxWins = Math.max(...Object.values(winCounts));
 
-	// best of
 	return maxWins >= Math.ceil(count / 2);
 }
diff --git a/app/features/tournament-organization/TournamentOrganizationRepository.server.test.ts b/app/features/tournament-organization/TournamentOrganizationRepository.server.test.ts
index 90997608a..0b61d5fcf 100644
--- a/app/features/tournament-organization/TournamentOrganizationRepository.server.test.ts
+++ b/app/features/tournament-organization/TournamentOrganizationRepository.server.test.ts
@@ -97,8 +97,7 @@ describe("findEventsByMonth", () => {
 	});
 
 	test("includes an event starting within the timezone margin after the month", async () => {
-		// Jan 31, 6 PM in America/Los_Angeles — the org page calendar renders
-		// this into the January grid for viewers west of UTC
+		// Jan 31, 6 PM in America/Los_Angeles: rendered into the January grid for viewers west of UTC
 		const org = await seedOrgEventAt(new Date("2025-02-01T02:00:00Z"));
 
 		const events = await TournamentOrganizationRepository.findEventsByMonth({
diff --git a/app/features/tournament-organization/TournamentOrganizationRepository.server.ts b/app/features/tournament-organization/TournamentOrganizationRepository.server.ts
index dd8b96e76..14ee8314f 100644
--- a/app/features/tournament-organization/TournamentOrganizationRepository.server.ts
+++ b/app/features/tournament-organization/TournamentOrganizationRepository.server.ts
@@ -386,9 +386,8 @@ export function findAllSeries() {
 }
 
 /**
- * How many teams each organization's already started tournaments drew within the
- * given window, oldest first. Counts what the tournament's own page shows:
- * placeholder teams excluded, dropped out ones included.
+ * Team counts of each organization's started tournaments within the window, oldest first.
+ * Counts what the tournament page shows: placeholder teams excluded, dropped out ones included.
  */
 export function findAllOrganizedTournamentTeamCounts({
 	startedAfter,
@@ -476,9 +475,8 @@ export async function findPaginatedEventsBySeries({
 }
 
 /**
- * Every event of the series, newest first. Selects only what the leaderboard and the series header
- * need - the winners of {@link findPaginatedEventsBySeries} are far too costly across a whole
- * series.
+ * Every event of the series, newest first, with only what the leaderboard and series header need:
+ * the winners of {@link findPaginatedEventsBySeries} are far too costly across a whole series.
  */
 export async function findAllEventsBySeries({
 	organizationId,
@@ -535,9 +533,8 @@ export async function findAllSeriesByOrganizationIds(
 }
 
 /**
- * Events of the series that the user won, oldest first. Both tournaments hosted on the site
- * and events whose results were reported by hand count. Only finalized tournaments have
- * results, so an event that is still ongoing is never included.
+ * Events of the series the user won, oldest first, hosted tournaments and hand-reported results
+ * alike. Only finalized tournaments have results, so ongoing events are never included.
  */
 export async function findAllSeriesWinsByUserId({
 	organizationId,
@@ -624,12 +621,8 @@ export async function findAllSeriesWinsByUserId({
 }
 
 /**
- * Counts the distinct players who participated in at least one match of a
- * tournament hosted by the organization, whose event started within the
- * `[startTime, endTime]` range. Only players belonging to teams that checked
- * in (and did not check out) are included.
- *
- * `startTime` and `endTime` are database timestamps (seconds).
+ * Distinct players on checked-in (not checked out) teams who played at least one match of the
+ * organization's tournaments starting within `[startTime, endTime]` (database timestamps, seconds).
  */
 export async function countActiveParticipants({
 	organizationId,
@@ -705,8 +698,7 @@ export function update({
 				.where("id", "=", id)
 				.executeTakeFirst();
 
-			// the logo got removed or replaced, so the old submitted image row is
-			// no longer referenced by anything and is cleaned up
+			// a removed or replaced logo leaves its submitted image row unreferenced
 			if (current?.avatarImgId && current.avatarImgId !== avatarImgId) {
 				await trx
 					.deleteFrom("UnvalidatedUserSubmittedImage")
@@ -837,9 +829,7 @@ export function deleteOwnMembership(organizationId: number) {
 		.execute();
 }
 
-/**
- * Inserts a user to the banned list for a tournament organization or updates the existing entry if already exists.
- */
+/** Bans a user from the organization, updating the entry if they already are. */
 export function upsertBannedUser(
 	args: Omit<TablesInsertable["TournamentOrganizationBannedUser"], "updatedAt">,
 ) {
@@ -849,9 +839,7 @@ export function upsertBannedUser(
 		.execute();
 }
 
-/**
- * Removes a user from the banned list for a tournament organization
- */
+/** Removes a user from the organization's banned list. */
 export function unbanUser({
 	organizationId,
 	userId,
@@ -866,9 +854,7 @@ export function unbanUser({
 		.execute();
 }
 
-/**
- * Returns all banned users for a specific tournament organization
- */
+/** All users banned by the organization. */
 export function findAllBannedUsersByOrganizationId(organizationId: number) {
 	return db
 		.selectFrom("TournamentOrganizationBannedUser")
@@ -888,9 +874,7 @@ export function findAllBannedUsersByOrganizationId(organizationId: number) {
 		.execute();
 }
 
-/**
- * Checks if a user is banned by a specific organization
- */
+/** Whether the organization has banned the user. */
 export async function isUserBannedByOrganization({
 	organizationId,
 	userId,
@@ -912,9 +896,7 @@ export async function isUserBannedByOrganization({
 	return isFuture(databaseTimestampToDate(result.expiresAt));
 }
 
-/**
- * Returns the number of organizations a user is a member of.
- */
+/** How many organizations the user is a member of. */
 export async function countOrganizationsByUserId(userId: number) {
 	const result = await db
 		.selectFrom("TournamentOrganizationMember")
@@ -925,9 +907,7 @@ export async function countOrganizationsByUserId(userId: number) {
 	return Number(result.count);
 }
 
-/**
- * Updates the isEstablished status for a tournament organization.
- */
+/** Sets the organization's `isEstablished` flag. */
 export function updateIsEstablished(
 	organizationId: number,
 	isEstablished: boolean,
diff --git a/app/features/tournament-organization/actions/org.$slug.edit.server.ts b/app/features/tournament-organization/actions/org.$slug.edit.server.ts
index c77059e22..f1c32fa9c 100644
--- a/app/features/tournament-organization/actions/org.$slug.edit.server.ts
+++ b/app/features/tournament-organization/actions/org.$slug.edit.server.ts
@@ -52,11 +52,10 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
 		badges: data.badges,
 	});
 
-	// in case members changed...
-	// 1) clear the participation info map (front page)
+	// members may have changed: clear the participation info map (front page)
 	ShowcaseTournaments.clearParticipationInfoMap();
 
-	// 2) clear tournament data caches (so permission changes are shown immediately)
+	// and tournament data caches so permission changes show immediately
 	for (const tournament of await TournamentOrganizationRepository.findAllUnfinalizedEvents(
 		organization.id,
 	)) {
diff --git a/app/features/tournament-organization/core/Series.ts b/app/features/tournament-organization/core/Series.ts
index a35b81cd8..0d1a43cbb 100644
--- a/app/features/tournament-organization/core/Series.ts
+++ b/app/features/tournament-organization/core/Series.ts
@@ -1,7 +1,4 @@
-/**
- * Finds the series that the event belongs to, matched by any of the series'
- * substrings appearing in the event's name.
- */
+/** The series whose substring appears in the event's name. */
 export function findByEventName<T extends { substringMatches: string[] }>({
 	series,
 	eventName,
diff --git a/app/features/tournament-organization/core/SeriesTeamCount.server.ts b/app/features/tournament-organization/core/SeriesTeamCount.server.ts
index dccb26015..3ec819cac 100644
--- a/app/features/tournament-organization/core/SeriesTeamCount.server.ts
+++ b/app/features/tournament-organization/core/SeriesTeamCount.server.ts
@@ -23,11 +23,7 @@ interface SeriesTeamCounts {
 	teamCounts: Array<number>;
 }
 
-/**
- * Resolves the team count a tournament is *expected* to draw: its registered
- * count raised to the median of the last {@link EDITIONS_CONSIDERED} editions of
- * its series, never lowered.
- */
+/** Team count a tournament is *expected* to draw: registered count raised (never lowered) to the median of the last {@link EDITIONS_CONSIDERED} editions. */
 export async function lookup() {
 	const seriesByOrganizationId = await cachedSeriesTeamCounts();
 
diff --git a/app/features/tournament-organization/loaders/org.$slug.edit.server.ts b/app/features/tournament-organization/loaders/org.$slug.edit.server.ts
index 023a876d8..b2f208e2a 100644
--- a/app/features/tournament-organization/loaders/org.$slug.edit.server.ts
+++ b/app/features/tournament-organization/loaders/org.$slug.edit.server.ts
@@ -13,8 +13,7 @@ export async function loader({ params }: LoaderFunctionArgs) {
 			organization.members.map((member) => member.id),
 		);
 
-		// handles edge case where the badge is not managed by the org anymore for whatever reason
-		// -> let's still keep it still deletable
+		// a badge the org no longer manages stays deletable
 		for (const badge of organization.badges) {
 			if (!result.find((b) => b.id === badge.id)) {
 				result.push(badge);
diff --git a/app/features/tournament-organization/loaders/org.$slug.stats.server.ts b/app/features/tournament-organization/loaders/org.$slug.stats.server.ts
index 472c22df6..319868cb9 100644
--- a/app/features/tournament-organization/loaders/org.$slug.stats.server.ts
+++ b/app/features/tournament-organization/loaders/org.$slug.stats.server.ts
@@ -40,8 +40,7 @@ export async function loader({ params }: LoaderFunctionArgs) {
 	};
 }
 
-/** The `count` most recent full months
- * (excluding the current month), most recent first. */
+/** The `count` most recent full months (excluding the current), most recent first. */
 function recentFullMonths(count: number) {
 	const months: Date[] = [];
 	const thisMonthStart = startOfMonth(new Date());
diff --git a/app/features/tournament-organization/routes/org.$slug.stats.test.ts b/app/features/tournament-organization/routes/org.$slug.stats.test.ts
index 5c6e68d13..5e5807e11 100644
--- a/app/features/tournament-organization/routes/org.$slug.stats.test.ts
+++ b/app/features/tournament-organization/routes/org.$slug.stats.test.ts
@@ -53,8 +53,7 @@ describe("org stats loader", () => {
 			params: { slug: org.slug },
 		});
 
-		// system time is Jan 2026 -> most recent finished month is Dec 2025,
-		// and the current (ongoing) month is not included
+		// system time is Jan 2026: the most recent finished month is Dec 2025, the ongoing month is not included
 		expect(data.monthlyStats.map((m) => m.month)).toEqual([
 			"2025-12",
 			"2025-11",
diff --git a/app/features/tournament-organization/test-utils.ts b/app/features/tournament-organization/test-utils.ts
index 730d4e62f..0c44ae763 100644
--- a/app/features/tournament-organization/test-utils.ts
+++ b/app/features/tournament-organization/test-utils.ts
@@ -4,14 +4,9 @@ import { withUserId } from "~/utils/Test";
 import * as TournamentTeamRepository from "../tournament/TournamentTeamRepository.server";
 
 /**
- * Seeds a played tournament hosted by `organizationId`, starting at `startTime`
- * (a database timestamp in seconds), with one team whose roster is
- * `participantUserIds`. The team is checked in by default.
- *
- * The bracket is started and its one match played out, because a participant of
- * the organization's events is somebody who appears in a game result.
- *
- * Only meant for use in tests.
+ * Seeds a played tournament of `organizationId` starting at `startTime` (database timestamp,
+ * seconds) with one team of `participantUserIds`, checked in by default. Its one match is played
+ * out, because a participant of the organization's events is somebody in a game result.
  */
 export async function seedOrgEventWithParticipants({
 	organizationId,
@@ -44,8 +39,7 @@ export async function seedOrgEventWithParticipants({
 		{ teamRosters: [participantUserIds, opponentUserIds] },
 	);
 
-	// the opponent exists only to give the participants somebody to play, so it
-	// leaves no check in behind to be counted as one of the event's own teams
+	// the opponent only gives the participants somebody to play, so it leaves no check in to be counted
 	await asOwner(() =>
 		TournamentTeamRepository.checkOut({
 			tournamentTeamId: opponent.id,
@@ -63,8 +57,7 @@ export async function seedOrgEventWithParticipants({
 	}
 
 	if (checkIn === "out") {
-		// a check out leaves a row of its own only when it concerns one bracket,
-		// otherwise checking out simply undoes the check in
+		// a check out only leaves a row of its own for one bracket, otherwise it undoes the check in
 		await asOwner(async () => {
 			await TournamentTeamRepository.checkOut({
 				tournamentTeamId: team.id,
diff --git a/app/features/tournament/TournamentAuditLogRepository.server.ts b/app/features/tournament/TournamentAuditLogRepository.server.ts
index 3936b366a..659e2d865 100644
--- a/app/features/tournament/TournamentAuditLogRepository.server.ts
+++ b/app/features/tournament/TournamentAuditLogRepository.server.ts
@@ -21,11 +21,8 @@ interface InsertArgs {
 }
 
 /**
- * Inserts an audit log event within the caller's transaction (so it commits or
- * rolls back atomically with the mutation it records). The acting user is resolved
- * from request context via `actorId()`. Ensures a stable `TournamentTeamHistory`
- * row exists for the team, so the event remains readable even after the team is
- * hard-deleted.
+ * Inserts an audit log event in the caller's transaction, actor from `actorId()`. Ensures a
+ * `TournamentTeamHistory` row exists so the event stays readable after the team is hard-deleted.
  */
 export async function insert(args: InsertArgs, trx: Transaction<DB>) {
 	const team = await trx
@@ -63,10 +60,8 @@ export async function insert(args: InsertArgs, trx: Transaction<DB>) {
 }
 
 /**
- * Inserts a fresh history row for a team and links it back from the team, so a
- * `TournamentTeam.id` reused by SQLite after a hard-deletion always gets its own
- * history row instead of inheriting the deleted team's identity. Returns the new
- * history id.
+ * Fresh history row linked from the team, so a `TournamentTeam.id` SQLite reuses after a
+ * hard-deletion never inherits the deleted team's identity. Returns the history id.
  */
 async function insertTeamHistory(
 	{
@@ -91,11 +86,7 @@ async function insertTeamHistory(
 	return id;
 }
 
-/**
- * Keeps the team's preserved name current after a rename. No-op when the team
- * has no history row yet (it will be created with the up-to-date name on its
- * first audited event).
- */
+/** Keeps the preserved name current after a rename. No-op without a history row (created on the first audited event). */
 export function updateTeamHistoryName(
 	trx: Transaction<DB>,
 	{ tournamentTeamId, name }: { tournamentTeamId: number; name: string },
@@ -112,11 +103,7 @@ export function updateTeamHistoryName(
 		.execute();
 }
 
-/**
- * Returns a page of audit log events for a tournament, newest first, optionally
- * filtered by event type and/or team. Resolves the actor, the affected member
- * (when present) and the team name (preserved even for deleted teams).
- */
+/** A page of events, newest first, optionally filtered by type and/or team, with actor, affected member and (preserved) team name. */
 export function findByTournamentId({
 	tournamentId,
 	type,
@@ -184,7 +171,7 @@ export function findByTournamentId({
 	return query.execute();
 }
 
-/** Counts audit log events for a tournament matching the same optional filters as {@link findByTournamentId}. Used for pagination. */
+/** Event count under the same filters as {@link findByTournamentId}, for pagination. */
 export async function countByTournamentId({
 	tournamentId,
 	type,
@@ -227,7 +214,7 @@ export function deleteOld() {
 		.executeTakeFirst();
 }
 
-/** Returns every team (including deleted ones) that has appeared in the tournament's audit log, for the team filter dropdown. */
+/** Every team (deleted ones included) in the tournament's audit log, for the team filter. */
 export function findTeamsByTournamentId(tournamentId: number) {
 	return db
 		.selectFrom("TournamentTeamHistory")
diff --git a/app/features/tournament/TournamentRepository.finalize.test.ts b/app/features/tournament/TournamentRepository.finalize.test.ts
index f75699475..38d6e5d50 100644
--- a/app/features/tournament/TournamentRepository.finalize.test.ts
+++ b/app/features/tournament/TournamentRepository.finalize.test.ts
@@ -8,12 +8,10 @@ import type { TournamentSummary } from "../tournament-bracket/core/summarizer.se
 import * as TournamentRepository from "./TournamentRepository.server";
 import * as TournamentTeamRepository from "./TournamentTeamRepository.server";
 
-/** SQLite binds at most 32,766 parameters per statement and `PlayerResult` has
- * eight columns, so one multi-row insert fits this many rows at most. */
+/** SQLite binds at most 32,766 parameters per statement and `PlayerResult` has eight columns. */
 const PLAYER_RESULT_ROWS_PER_STATEMENT = Math.floor(32766 / 8);
 
-/** Enough users that every ordered pair of them, for both types, is over
- * {@link PLAYER_RESULT_ROWS_PER_STATEMENT}. */
+/** Enough that every ordered pair, for both types, is over {@link PLAYER_RESULT_ROWS_PER_STATEMENT}. */
 const USER_COUNT = 46;
 
 const users = UserFactory.pool();
diff --git a/app/features/tournament/TournamentRepository.server.ts b/app/features/tournament/TournamentRepository.server.ts
index 97532f2c0..b6f7e0ec9 100644
--- a/app/features/tournament/TournamentRepository.server.ts
+++ b/app/features/tournament/TournamentRepository.server.ts
@@ -366,9 +366,8 @@ function permissionsOf(tournament: {
 }
 
 /**
- * User ids of everyone on multiple teams' rosters mapped to the team they joined
- * most recently. Nearly always empty, allowing the teams to drop per member join
- * timestamps that only this tiebreak needed.
+ * Users on multiple rosters mapped to the team they joined most recently. Nearly always
+ * empty, which lets the teams drop the per member join timestamps only this tiebreak needs.
  */
 function latestTeamIdByDuplicatedUserId(
 	teams: Array<{
@@ -405,10 +404,7 @@ function latestTeamIdByDuplicatedUserId(
 	return result;
 }
 
-/**
- * Live streams of the tournament: streams of checked-in participants and the streams
- * of the tournament's cast Twitch accounts.
- */
+/** Live streams of checked-in participants and of the tournament's cast Twitch accounts. */
 export async function findStreamsByTournamentId(tournamentId: number) {
 	const [participantStreams, castStreams] = await Promise.all([
 		db
@@ -672,9 +668,7 @@ export async function findDescriptionById(tournamentId: number) {
 	return row?.description ?? null;
 }
 
-/**
- * Loads a tournament's seeding snapshot.
- */
+/** Loads a tournament's seeding snapshot. */
 export async function findSeedingSnapshotById(tournamentId: number) {
 	const row = await db
 		.selectFrom("Tournament")
@@ -685,10 +679,7 @@ export async function findSeedingSnapshotById(tournamentId: number) {
 	return row?.seedingSnapshot ?? null;
 }
 
-/**
- * Per-user results of a finalized tournament as persisted at finalization time.
- * Empty for tournaments that have not been finalized.
- */
+/** Per-user results persisted at finalization time. Empty for tournaments not yet finalized. */
 export function findResultsByTournamentId(tournamentId: number) {
 	return db
 		.selectFrom("TournamentResult")
@@ -704,12 +695,10 @@ export function findResultsByTournamentId(tournamentId: number) {
 }
 
 /**
- * Participants of the latest finalized league of the given organization, along with the bracket
- * progression that tells what division (= starting bracket) each of them played in.
- *
- * Only participants eligible for a division placement are included: they have a result, were on a
- * team that did not drop out, and played at least one match. Null if the organization has no
- * finalized league.
+ * Participants of the organization's latest finalized league, with the bracket progression that
+ * tells what division (= starting bracket) each played in. Only participants eligible for a
+ * division placement: have a result, team did not drop out, played at least one match. Null if
+ * the organization has no finalized league.
  */
 export async function findLatestFinalizedLeagueParticipants(args: {
 	organizationId: number;
@@ -926,10 +915,7 @@ function databaseTimestampWeekAgo() {
 	return dateToDatabaseTimestamp(now);
 }
 
-/**
- * Resolves the team & participant counts of one tournament exactly like {@link findAllForShowcase}
- * does, meant for refreshing those counts of an already cached showcase tournament.
- */
+/** Team & participant counts of one tournament as {@link findAllForShowcase} computes them, for refreshing a cached showcase tournament. */
 export function findShowcaseCountsById(tournamentId: number) {
 	return db
 		.selectFrom("Tournament")
@@ -968,11 +954,7 @@ export function findAllBetweenTwoTimestamps({
 		.execute();
 }
 
-/**
- * `ORGANIZE` and `MANAGE_MATCHES` holders per tournament, keyed by tournament id.
- * For callers that need the ids of many tournaments' organizers without loading
- * the tournaments themselves.
- */
+/** `ORGANIZE` and `MANAGE_MATCHES` holders keyed by tournament id, without loading the tournaments themselves. */
 export async function findOrganizerPermissionsByTournamentIds(
 	tournamentIds: number[],
 ) {
@@ -1114,7 +1096,6 @@ export function updateProgression({
 					.execute()
 			).map((t) => t.id);
 
-			// delete all bracket check-ins
 			await trx
 				.deleteFrom("TournamentTeamCheckIn")
 				.where("TournamentTeamCheckIn.bracketIdx", "is not", null)
@@ -1333,16 +1314,14 @@ export function unlockMatch({
 			.where("id", "=", tournamentId)
 			.execute();
 
-		// Make sure that a match is not marked as started when it is unlocked
-		// as we use this timestamp to determine the "deadline" for the match
-		// so it doesn't make sense for that timer to run if players can't play yet
+		// startedAt drives the match deadline, which must not run while locked: restart it now
+		// (but only if it was ever set)
 		await trx
 			.updateTable("TournamentMatch")
 			.set({
 				startedAt: databaseTimestampNow(),
 			})
 			.where("id", "=", matchId)
-			// ensure we don't set startedAt if it was never set before
 			.where("TournamentMatch.startedAt", "is not", null)
 			.execute();
 	});
@@ -1425,16 +1404,12 @@ export function reopenTournament(tournamentId: number) {
 	});
 }
 
-/** How many rows one multi-row insert of the summary binds at a time. SQLite
- * rejects any statement binding over 32,766 parameters, a ceiling a big
- * tournament's deltas cross when inserted as a single statement. */
+/** SQLite rejects statements binding over 32,766 parameters, which a big tournament's deltas cross in one insert. */
 const SUMMARY_INSERT_CHUNK_SIZE = 1000;
 
 /**
- * Finalizes a tournament, recording the full summary: skills, seeding skills,
- * map/player result deltas, badge owners and placements. Use
- * {@link finalizeWithoutSummary} for test tournaments that should be marked as
- * finalized without recording any stats.
+ * Finalizes a tournament, recording the full summary: skills, seeding skills, map/player
+ * result deltas, badge owners and placements. See {@link finalizeWithoutSummary} for test tournaments.
  */
 export function finalize({
 	tournamentId,
@@ -1455,13 +1430,10 @@ export function finalize({
 		const skillTeamUsers: Array<{ skillId: number; userId: number }> = [];
 		for (const skill of summary.skills) {
 			invariant(seasonValue !== null, "Season missing for skill");
-			// A skill row keys on either userId (solo) or identifier (team), never
-			// both. The matchesCount subquery filters by whichever is present so it
-			// references exactly one indexed column — a combined
-			// `where "userId" = ? or "identifier" = ?` triggers a stat4-driven
-			// misestimate when one parameter is NULL (the planner treats NULL as a
-			// frequent indexed value, ~900K rows for Skill.identifier) and picks a
-			// pathological MULTI-INDEX OR plan.
+			// A skill row keys on either userId (solo) or identifier (team), never both. The
+			// matchesCount subquery filters by whichever is present so it hits exactly one index:
+			// `where "userId" = ? or "identifier" = ?` with a NULL parameter makes the planner
+			// (stat4, NULL ~900K rows for Skill.identifier) pick a pathological MULTI-INDEX OR plan.
 			const insertedSkill = await trx
 				.insertInto("Skill")
 				.values((eb) => ({
@@ -1670,10 +1642,7 @@ export function finalize({
 	});
 }
 
-/**
- * Marks a tournament as finalized without recording any summary stats. Used for
- * test tournaments. See {@link finalize} for the normal path.
- */
+/** Marks a test tournament as finalized without recording any summary stats. See {@link finalize}. */
 export function finalizeWithoutSummary(tournamentId: number) {
 	return db
 		.updateTable("Tournament")
@@ -1685,11 +1654,7 @@ export function finalizeWithoutSummary(tournamentId: number) {
 /** How close to its start time a tournament counts as happening right now. */
 const TOURNAMENT_ONGOING_WINDOW_IN_SECONDS = 24 * 60 * 60;
 
-/**
- * Searches tournaments whose calendar event name contains the query, hidden events excluded.
- *
- * Ordered so that the tournaments most likely being looked for come first
- */
+/** Tournaments whose calendar event name contains the query, hidden excluded, most likely matches first. */
 export async function searchByName({
 	query,
 	limit,
@@ -1703,8 +1668,7 @@ export async function searchByName({
 }) {
 	const now = databaseTimestampNow();
 	const distanceFromNow = sql<number>`abs("CalendarEventDate"."startsAt" - ${now})`;
-	// window function so that the next tournament up is the next one of all the matches,
-	// not only of the ones that happen to fit in the limit
+	// window function: next up is the next of all matches, not only of those within the limit
 	const nextUpStartsAt = sql<number>`min(case when "CalendarEventDate"."startsAt" - ${now} >= ${TOURNAMENT_ONGOING_WINDOW_IN_SECONDS} then "CalendarEventDate"."startsAt" end) over ()`;
 
 	let sqlQuery = db
@@ -1811,9 +1775,8 @@ export function updateTeamSeeds({
 }
 
 /**
- * Records the tier of one division (= starting bracket), calculated from the teams that checked in
- * to it, and updates the tournament's own tier to the best tier of its divisions. Tournaments where
- * every team plays the same bracket have one division, making the two the same.
+ * Records the tier of one division (= starting bracket) from its checked-in teams and sets the
+ * tournament's own tier to the best of its divisions (the same thing when there is one division).
  */
 export async function upsertDivisionTier({
 	tournamentId,
@@ -1883,10 +1846,7 @@ export async function findRunningTournamentIds() {
 	return rows.map((row) => row.id);
 }
 
-/**
- * Tier the trophy was won at: the tier of the division the winning team played in, falling back to
- * the tournament's own tier when the team is not known or its division was never tiered.
- */
+/** Tier of the winning team's division, falling back to the tournament's tier when unknown or never tiered. */
 async function trophyTier(
 	trx: Transaction<DB>,
 	{
diff --git a/app/features/tournament/TournamentTeamRepository.server.test.ts b/app/features/tournament/TournamentTeamRepository.server.test.ts
index 2d28b6b0f..008af015c 100644
--- a/app/features/tournament/TournamentTeamRepository.server.test.ts
+++ b/app/features/tournament/TournamentTeamRepository.server.test.ts
@@ -361,9 +361,8 @@ describe("TournamentTeamRepository", () => {
 
 	describe("findRecentlyPlayedMapsByIds", () => {
 		test("leaves out the games of the match the maps are resolved for", async () => {
-			// the map list of an in-progress set is regenerated whenever its cache entry
-			// is lost, so counting the set's own games as recently played would change
-			// the maps the teams have left to play under them
+			// an in-progress set's map list is regenerated when its cache entry is lost, so counting its
+			// own games as recently played would change the maps left to play under the teams
 			const players = await UserFactory.createMany(TEAM_COUNT);
 			const tournament = await TournamentFactory.createPlayed(
 				{
diff --git a/app/features/tournament/TournamentTeamRepository.server.ts b/app/features/tournament/TournamentTeamRepository.server.ts
index b6babdb0f..c54f415df 100644
--- a/app/features/tournament/TournamentTeamRepository.server.ts
+++ b/app/features/tournament/TournamentTeamRepository.server.ts
@@ -141,13 +141,8 @@ export function updateMemberInGameName({
 	});
 }
 
-/**
- * Updates the in-game name of a tournament team member for tournaments that have not started yet.
- *
- * @returns A promise that resolves to an array of tournament IDs where the user's in-game name was updated.
- */
+/** Updates the acting user's in-game name in tournaments not yet started, returning the ids of those tournaments. */
 export async function updateOwnMemberInGameNameForNonStarted(
-	/** The new in-game name to be set for the acting user. */
 	inGameName: string,
 ): Promise<number[]> {
 	const userId = actorId();
@@ -157,13 +152,13 @@ export async function updateOwnMemberInGameNameForNonStarted(
 		.updateTable("TournamentTeamMember")
 		.set({ inGameName })
 		.where("TournamentTeamMember.userId", "=", userId)
-		// after they have checked in no longer can update their IGN from here
+		// IGN can't be updated from here after check-in
 		.where(
 			"TournamentTeamMember.tournamentTeamId",
 			"in",
 			tournamentTeams.map((t) => t.tournamentTeamId),
 		)
-		// if the tournament doesn't have the setting to require IGN, ignore
+		// null when the tournament doesn't require IGN
 		.where("TournamentTeamMember.inGameName", "is not", null)
 		.execute();
 
@@ -261,16 +256,11 @@ export function insert({
 }
 
 /**
- * Creates a new registration or applies a full-state edit to an existing one in a
- * single transaction: team name, linked sendou.ink team, owner assignment/transfer,
- * member adds/removes, in-game name updates, tournament name updates and the
- * counterpick map pool. Pass `tournamentTeamId` to edit an existing team, or omit it
- * to create a new one (all members are then "added" and `ownerUserId` becomes the
- * owner). The caller is responsible for validating the derived ops and for any side
- * effects (cache updates, notifications) outside the transaction.
- *
- * Returns the tournament name changes that were actually applied (submitted values
- * equal to the user's current one are no-ops), for the caller to log.
+ * Creates a registration or applies a full-state edit to an existing one (`tournamentTeamId`)
+ * in one transaction: name, linked team, owner, members, in-game names, tournament names and
+ * counterpick map pool. The caller validates the ops and handles side effects (caches,
+ * notifications). Returns the tournament name changes actually applied (values equal to the
+ * current one are no-ops), for the caller to log.
  */
 export function upsertRegistration({
 	tournamentTeamId,
@@ -505,11 +495,7 @@ export function upsertRegistration({
 	});
 }
 
-/**
- * Whether the tournament's registration is closed at the current moment, based on
- * the organizer-set `regClosesAt` if present, otherwise the tournament start time.
- * Members added while registration is closed are persisted as subs.
- */
+/** Registration is closed after `regClosesAt`, or the start time without it. Members added after that are subs. */
 async function registrationClosedNow(
 	trx: Transaction<DB>,
 	tournamentId: number,
@@ -644,11 +630,7 @@ export function updateAbDivisions(
 	});
 }
 
-/**
- * Checks in a tournament team. Clears any existing check-out records before inserting the check-in.
- * When called without `bracketIdx`, checks in for the whole tournament.
- * When called with `bracketIdx`, checks in for a specific bracket (e.g. after progression).
- */
+/** Checks a team in to the whole tournament, or to one bracket with `bracketIdx`. Clears existing check-outs first. */
 export function checkIn(
 	tournamentTeamId: number,
 	options?: { bracketIdx?: number },
@@ -796,9 +778,8 @@ export function join({
 	/** Team to delete as the user joins, e.g. a solo team they leave behind. */
 	previousTeamIdToDelete?: number;
 	newTeamId: number;
-	/** The user joining the team. */
 	userId: number;
-	/** Was the user added to the team by the tournament organizer instead of joining on their own? */
+	/** Added by the organizer rather than joining on their own. */
 	isOrganizerAdded?: boolean;
 }): Promise<number[]> {
 	return db.transaction().execute(async (trx) => {
@@ -886,7 +867,7 @@ export function deleteById(tournamentTeamId: number): Promise<number[]> {
 	});
 }
 
-/** Was the user's membership in the given team added by the tournament organizer instead of the user joining on their own? */
+/** Whether the organizer added the user to the team rather than the user joining on their own. */
 export async function isOrganizerAddedMember({
 	tournamentTeamId,
 	userId,
@@ -904,14 +885,7 @@ export async function isOrganizerAddedMember({
 	return Boolean(member?.isOrganizerAdded);
 }
 
-export function leave({
-	teamId,
-	userId,
-}: {
-	teamId: number;
-	/** The member leaving the team. */
-	userId: number;
-}) {
+export function leave({ teamId, userId }: { teamId: number; userId: number }) {
 	return db.transaction().execute(async (trx) => {
 		await TournamentAuditLogRepository.insert(
 			{
@@ -990,14 +964,10 @@ async function findTeamRecentMaps(
 }
 
 /**
- * Tournament registrations of the given users whose event start falls within
- * the given window, one row per registered member per event date. Dropped-out
- * teams and hidden events (test and draft tournaments) are excluded. Used to
- * resolve availability commitments, so alongside the event's name and start
- * the rows carry what estimating the tournament's duration needs: the
- * settings and how many teams have registered so far. `excludeTournamentId`
- * leaves one tournament's own registrations out, for surfaces asking "busy
- * elsewhere" while looking at that tournament.
+ * Registrations of the given users starting within the window, one row per member per event
+ * date; dropped-out teams and hidden events excluded. Rows also carry what estimating the
+ * tournament's duration needs (settings, registered team count) for availability commitments.
+ * `excludeTournamentId` leaves one tournament out, for "busy elsewhere" views of that tournament.
  */
 export function findAllRegistrationsByUserIds({
 	userIds,
@@ -1106,16 +1076,10 @@ export async function findRecentlyPlayedMapsByIds({
 	excludeMatchId,
 	limit = 5,
 }: {
-	/** Team IDs to retrieve recent maps for */
 	teamIds: [number, number];
-	/** Match whose own games are left out, being the match the maps are resolved for.
-	 * Without it a set's map list changes under the teams mid-set, as the games they
-	 * already played would count as recently played when it is regenerated. */
+	/** The match the maps are resolved for, left out so its own played games don't change the map list mid-set. */
 	excludeMatchId: number;
-	/** Limit of recent maps to retrieve per team
-	 *
-	 * @default 5
-	 */
+	/** Recent maps per team, default 5. */
 	limit?: number;
 }): Promise<Array<{ mode: ModeShort; stageId: StageId }>> {
 	const [teamOneMaps, teamTwoMaps] = await Promise.all([
diff --git a/app/features/tournament/actions/to.$id.register.server.test.ts b/app/features/tournament/actions/to.$id.register.server.test.ts
index 5e0ebca3b..27157429d 100644
--- a/app/features/tournament/actions/to.$id.register.server.test.ts
+++ b/app/features/tournament/actions/to.$id.register.server.test.ts
@@ -38,10 +38,7 @@ const memberCountOfOnlyTeam = async (tournamentId: number) => {
 	return count;
 };
 
-/**
- * A tournament open for registration with one team of `rosterSize` captained by the
- * user the action submits as, and a friend of theirs available to be added to it.
- */
+/** Open tournament with one team of `rosterSize` captained by the submitting user, plus a friend to add. */
 const scenario = async ({
 	rosterSize,
 	requireInGameNames = false,
@@ -49,11 +46,10 @@ const scenario = async ({
 	rosterSize: number;
 	requireInGameNames?: boolean;
 }) => {
-	// the captain, who submits the request
 	const captain = await UserFactory.createRegular({
 		profile: requireInGameNames ? { inGameName: "Captain#1234" } : null,
 	});
-	// the player they try to add, without an in-game name of their own
+	// without an in-game name of their own
 	const friend = await UserFactory.create({ profile: null });
 	const teammates = await UserFactory.createMany(rosterSize - 1);
 
diff --git a/app/features/tournament/actions/to.$id.register.server.ts b/app/features/tournament/actions/to.$id.register.server.ts
index c4ffd071d..1a7beb166 100644
--- a/app/features/tournament/actions/to.$id.register.server.ts
+++ b/app/features/tournament/actions/to.$id.register.server.ts
@@ -159,8 +159,7 @@ export const action: ActionFunction = async ({ request, params }) => {
 			);
 			errorToastIfFalsy(data.userId !== user.id, "Can't kick yourself");
 
-			// making sure they aren't unfilling one checking in condition i.e. having full roster
-			// and then having members kicked without it affecting the checking in status
+			// a full roster is a check-in condition, so kicking below it after checking in is not allowed
 			errorToastIfFalsy(
 				!ownTeamCheckedIn ||
 					ownTeam.memberUserIds.length > tournament.minMembersPerTeam,
diff --git a/app/features/tournament/components/TournamentNav.tsx b/app/features/tournament/components/TournamentNav.tsx
index 967811a85..7fbcadc7d 100644
--- a/app/features/tournament/components/TournamentNav.tsx
+++ b/app/features/tournament/components/TournamentNav.tsx
@@ -149,8 +149,7 @@ function useNavItems({
 
 	const items: Partial<Record<NavItemKey, NavItem>> = {};
 
-	// invitational teams are added by the organizer so registration is never "open",
-	// but their captains still need to reach this page to set their roster & map pool
+	// invitational registration is never "open", but captains still need the page for roster & map pool
 	const showRegisterForInvitationalCaptain =
 		tournament.isInvitational &&
 		!tournament.hasStarted &&
@@ -289,9 +288,7 @@ function NavItemLink({
 	);
 }
 
-// horizontal space reserved on the right for the overflow hamburger: its big icon
-// box (var(--button-icon-big) = 28px) plus breathing room before the last item.
-// The hamburger is positioned absolutely so it never shrinks the measured container.
+// space for the absolutely positioned overflow hamburger: its icon box (var(--button-icon-big) = 28px) plus breathing room
 const HAMBURGER_WIDTH = 36;
 
 function useNavOverflow(totalItems: number) {
@@ -309,8 +306,7 @@ function useNavOverflow(totalItems: number) {
 		const computeVisible = () => {
 			const containerWidth = container.getBoundingClientRect().width;
 			const listLeft = list.getBoundingClientRect().left;
-			// actual rendered right edge of each slot relative to the list start,
-			// so the real flex gaps are accounted for without re-deriving them
+			// rendered right edges relative to the list start, so the real flex gaps are accounted for
 			const rightEdges = slots.map(
 				(slot) => slot.getBoundingClientRect().right - listLeft,
 			);
diff --git a/app/features/tournament/core/Standings.test.ts b/app/features/tournament/core/Standings.test.ts
index bdf5e1761..f8aa18ae2 100644
--- a/app/features/tournament/core/Standings.test.ts
+++ b/app/features/tournament/core/Standings.test.ts
@@ -89,8 +89,7 @@ describe("tournamentStandings", () => {
 		const result = tournamentStandings(tournament);
 
 		invariant(result.type === "single");
-		// teams 5-8 all lost the quarterfinals so they are tied in the main bracket,
-		// the underground bracket (won by 8, then 7, 6, 5) decides their order
+		// teams 5-8 are tied as quarterfinal losers, the underground bracket (won by 8, then 7, 6, 5) orders them
 		expect(result.standings.map((s) => s.team.id)).toEqual([
 			1, 2, 3, 4, 8, 7, 6, 5,
 		]);
@@ -116,8 +115,7 @@ describe("tournamentStandings", () => {
 	});
 
 	test("does not break ties with an underground bracket that is still in progress", () => {
-		// only the semi-finals of the underground bracket have been played so the two teams
-		// still alive there have no placement yet
+		// only the underground semi-finals were played, the two teams still alive have no placement yet
 		const tournament = singleEliminationWithUndergroundTournament({
 			undergroundConsolationFinal: false,
 			undergroundMatchesPlayed: 2,
@@ -126,8 +124,7 @@ describe("tournamentStandings", () => {
 		const result = tournamentStandings(tournament);
 
 		invariant(result.type === "single");
-		// teams 5-8 keep the order & tied placement they have in the main bracket,
-		// the teams eliminated from the underground bracket are not sorted above those still in it
+		// teams 5-8 keep their main bracket tie: eliminated underground teams don't sort above those still in it
 		expect(result.standings.map((s) => s.team.id)).toEqual([
 			1, 2, 3, 4, 8, 5, 7, 6,
 		]);
@@ -142,8 +139,7 @@ describe("tournamentStandings", () => {
 		const result = tournamentStandings(tournament);
 
 		invariant(result.type === "single");
-		// team 3 lost the redemption bracket, which it reached by placing 3rd in the groups,
-		// so it is above the teams that placed 5th-8th there and went to the consolation bracket
+		// team 3 lost redemption (reached by placing 3rd in groups), so it is above the 5th-8th consolation teams
 		expect(result.standings.map((s) => s.team.id)).toEqual([
 			1, 2, 4, 3, 5, 6, 7, 8,
 		]);
@@ -294,8 +290,7 @@ describe("matchesPlayedByTeamId", () => {
 
 		const matches = matchesPlayedByTeamId(tournament).get(1) ?? [];
 
-		// team 1 plays 3 round robin matches (bracket idx 0)
-		// and 1 single elimination match (bracket idx 1)
+		// team 1 plays 3 round robin matches (bracket idx 0) and 1 single elimination match (bracket idx 1)
 		const roundRobinMatches = matches.filter((m) => m.bracketIdx === 0);
 		const singleEliminationMatches = matches.filter((m) => m.bracketIdx === 1);
 
diff --git a/app/features/tournament/core/Standings.ts b/app/features/tournament/core/Standings.ts
index e09ae5460..0db55cd0b 100644
--- a/app/features/tournament/core/Standings.ts
+++ b/app/features/tournament/core/Standings.ts
@@ -27,13 +27,8 @@ export function flattenStandings(
 }
 
 /**
- * Re-numbers placements in a sorted standings array so that tied placements stay
- * grouped (e.g. `[1, 1, 3, 3, 5]`) while non-tied positions reflect the true
- * number of teams above them. Useful after filtering or merging standings where
- * the original placement numbers no longer match the team count.
- *
- * Pass `offset` to shift every placement downwards — used when the returned
- * standings will be appended below standings from another bracket.
+ * Re-numbers placements of sorted standings keeping ties grouped (`[1, 1, 3, 3, 5]`), for after
+ * filtering or merging. `offset` shifts every placement down, for appending below another bracket's standings.
  */
 export function reNumberPlacements<T extends { placement: number }>(
 	standings: T[],
@@ -75,7 +70,6 @@ export function sprByTeamId(standings: Standing[]): Map<number, number> {
 			: undefined;
 		const actualIndex = indexByPlacement.get(standing.placement);
 
-		// defensive check to avoid crashing
 		if (typeof expectedIndex !== "number" || typeof actualIndex !== "number") {
 			result.set(standing.team.id, 0);
 			continue;
@@ -112,7 +106,6 @@ export function matchesPlayedByTeamId(
 		const cached = seeds.get(teamId);
 		if (typeof cached === "number") return cached;
 
-		// defensive fallback
 		const seed = tournament.teamById(teamId)?.seed ?? 0;
 		seeds.set(teamId, seed);
 
@@ -156,11 +149,9 @@ type PersistedResultRow = {
 };
 
 /**
- * Standings of a finalized tournament reconstructed from the per-user results persisted at
- * finalization, instead of recomputing them from bracket match data. Returns null when the
- * persisted rows cannot back the standings (no rows, a team no longer in the tournament
- * context, or a division label the progression no longer produces) so the caller can fall
- * back to {@link tournamentStandings}.
+ * Standings of a finalized tournament from the per-user results persisted at finalization. Null
+ * when those can't back the standings (no rows, a team no longer in the tournament, a division
+ * label the progression no longer produces) so the caller can fall back to {@link tournamentStandings}.
  */
 export function standingsFromPersistedResults({
 	tournament,
@@ -217,15 +208,9 @@ export function standingsFromPersistedResults({
 }
 
 /**
- * Computes the standings for a given tournament by aggregating results from relevant brackets.
- *
- * For example if the tournament format is round robin (where 2 out of 4 teams per group advance) to single elimination,
- * the top teams are decided by the single elimination bracket, and the teams who failed to make the bracket are ordered
- * by their performance in the round robin group stage.
- *
- * Returns a discriminated union:
- * - For tournaments with a single starting bracket, returns type 'single' with overall standings
- * - For tournaments with multiple starting brackets, returns type 'multi' with standings per division
+ * Standings aggregated across brackets: e.g. in RR → SE the top teams come from the SE bracket and
+ * the teams that missed it are ordered by their group performance. Type `single` with overall
+ * standings for one starting bracket, `multi` with standings per division for several.
  */
 export function tournamentStandings(
 	tournament: Tournament,
@@ -271,11 +256,7 @@ export function tournamentStandings(
 	};
 }
 
-/**
- * Computes the standings for a given tournament starting from a specific bracket.
- * If bracketIdx is undefined, computes overall standings for the entire tournament.
- * Otherwise, only includes brackets that are reachable from the given bracketIdx.
- */
+/** Standings over the brackets reachable from `bracketIdx`, or the whole tournament when undefined. */
 function tournamentStandingsForBracket(
 	tournament: Tournament,
 	bracketIdx: number | undefined,
@@ -312,7 +293,7 @@ function tournamentStandingsForBracket(
 		const bracket = tournament.bracketByIdx(idx);
 		invariant(bracket);
 
-		// sometimes a bracket might not be played so then we ignore it from the standings
+		// a bracket that never got played is left out
 		if (isSingleStartingBracket && finalBracketIsOver && bracket.preview) {
 			continue;
 		}
@@ -340,11 +321,9 @@ function tournamentStandingsForBracket(
 }
 
 /**
- * Underground brackets are left out of the standings but the teams playing them are tied in their source
- * bracket (e.g. everyone who lost the quarterfinals shares the same placement), so their underground run
- * decides the order within each such tie. Teams that skipped the underground bracket stay tied last.
- *
- * An underground bracket that is still in progress is ignored, as the teams still alive in it have no
+ * Underground brackets are left out of the standings, but their teams are tied in the source bracket
+ * (e.g. all quarterfinal losers), so the underground run orders each such tie; teams that skipped it
+ * stay tied last. An underground bracket still in progress is ignored: its live teams have no
  * placement yet and would sort below the teams it already eliminated.
  */
 function tiebrokenByUndergroundBrackets({
diff --git a/app/features/tournament/core/layout-payload.ts b/app/features/tournament/core/layout-payload.ts
index 13fa2f8ab..80e60b80d 100644
--- a/app/features/tournament/core/layout-payload.ts
+++ b/app/features/tournament/core/layout-payload.ts
@@ -1,10 +1,6 @@
 import type { TournamentLoaderData } from "../loaders/to.$id.server";
 
-/**
- * Team keys that {@link serializeTournamentLoaderData} drops when null and
- * {@link parseTournamentLoaderData} restores. Null for most teams, so dropping
- * them trims the layout payload of big tournaments by a few gzipped kilobytes.
- */
+/** Team keys dropped when null and restored on parse; null for most teams, saving big tournaments a few gzipped kB. */
 const NULL_COMPACTED_TEAM_KEYS = [
 	"seed",
 	"logoUrl",
@@ -17,15 +13,11 @@ const NULL_COMPACTED_TEAM_KEYS = [
 
 type LayoutTeam = TournamentLoaderData["tournament"]["ctx"]["teams"][number];
 
-/**
- * Serializes the tournament layout loader data, omitting null-valued team keys.
- * Counterpart of {@link parseTournamentLoaderData}, the only way the payload
- * should be read.
- */
+/** Serializes the layout loader data omitting null team keys; read only via {@link parseTournamentLoaderData}. */
 export function serializeTournamentLoaderData(
 	data: TournamentLoaderData,
 ): string {
-	// JSON.stringify so that we skip expensive rr7 data serialization (hot path loader)
+	// plain JSON.stringify skips the expensive rr7 data serialization (hot path loader)
 	return JSON.stringify({
 		...data,
 		tournament: {
@@ -38,10 +30,7 @@ export function serializeTournamentLoaderData(
 	});
 }
 
-/**
- * Parses the tournament layout loader data serialized by
- * {@link serializeTournamentLoaderData}, restoring the null team keys it omitted.
- */
+/** Parses {@link serializeTournamentLoaderData} output, restoring the omitted null team keys. */
 export function parseTournamentLoaderData(raw: string): TournamentLoaderData {
 	const data = JSON.parse(raw) as TournamentLoaderData;
 
diff --git a/app/features/tournament/core/permissions.ts b/app/features/tournament/core/permissions.ts
index 6bd40ac40..a3e1fe68f 100644
--- a/app/features/tournament/core/permissions.ts
+++ b/app/features/tournament/core/permissions.ts
@@ -3,14 +3,9 @@ import type { TournamentStaffRole } from "~/features/tournament/tournament-const
 import type { TournamentOrganizationRole } from "~/features/tournament-organization/tournament-organization-constants";
 
 /**
- * Who may run the tournament, following the convention in docs/dev/permissions.md.
- * The half of a tournament's permissions that only depends on the author, the
- * organization's members and the staff, shared with callers that resolve those
- * rows without loading the whole tournament.
- *
- * - `ADMIN`: full control of the tournament
- * - `ORGANIZE`: running the tournament
- * - `MANAGE_MATCHES`: casting, locking and admining individual matches
+ * The half of a tournament's permissions (docs/dev/permissions.md) depending only on author,
+ * organization members and staff, for callers not loading the whole tournament. `ADMIN`: full
+ * control, `ORGANIZE`: running it, `MANAGE_MATCHES`: casting, locking and admining matches.
  */
 export function organizerPermissions(args: {
 	authorId: number;
diff --git a/app/features/tournament/core/sets.server.test.ts b/app/features/tournament/core/sets.server.test.ts
index 2a3ed7289..8b651c6a2 100644
--- a/app/features/tournament/core/sets.server.test.ts
+++ b/app/features/tournament/core/sets.server.test.ts
@@ -15,8 +15,7 @@ describe("winCounts", () => {
 	});
 
 	test("counts a set the team won on the bracket but lost on maps as a win", () => {
-		// e.g. a set the opponent forfeited after winning games, awarded 2-1 by the
-		// organizer — the bracket, and so the set score, says the team won it
+		// e.g. the opponent forfeited after winning games and the organizer awarded it 2-1
 		const result = winCounts([
 			{
 				tournamentMatchId: 1,
@@ -123,8 +122,7 @@ describe("tournamentTeamSets", () => {
 	});
 
 	test("takes the set result from the bracket winner even when the maps disagree", () => {
-		// organizer overrode the winner after the games were reported, so the team
-		// won the set on the bracket while losing 1-2 on the maps
+		// organizer overrode the winner after reports: won on the bracket, lost 1-2 on the maps
 		const [set] = tournamentTeamSets({
 			sets: [playedSetRow({ teamSide: "opponent1", winnerSide: "opponent1" })],
 			allRounds: ALL_ROUNDS,
diff --git a/app/features/tournament/core/sets.server.ts b/app/features/tournament/core/sets.server.ts
index 7e757b85f..2b049fd69 100644
--- a/app/features/tournament/core/sets.server.ts
+++ b/app/features/tournament/core/sets.server.ts
@@ -16,11 +16,7 @@ export interface AllRoundsItem {
 export interface PlayedSet {
 	tournamentMatchId: number;
 	score: [teamBeingViewed: number, opponent: number];
-	/**
-	 * Who won the set according to the bracket. Can disagree with the maps and
-	 * the score e.g. when an organizer overrode the winner after games were
-	 * already reported.
-	 */
+	/** Per the bracket; can disagree with the maps and score, e.g. an organizer overrode the winner after reports. */
 	result: "win" | "loss";
 	round: {
 		type: "winners" | "losers" | "single_elim" | "round_robin" | "swiss";
@@ -36,7 +32,6 @@ export interface PlayedSet {
 	opponent: {
 		id: number;
 		name: string;
-		/** Team's roster that played in this set */
 		roster: Array<
 			Pick<
 				Tables["User"],
diff --git a/app/features/tournament/core/tiering.ts b/app/features/tournament/core/tiering.ts
index a191d538e..cd15599d7 100644
--- a/app/features/tournament/core/tiering.ts
+++ b/app/features/tournament/core/tiering.ts
@@ -1,7 +1,4 @@
-/**
- * Tournament tier calculation based on top teams' average SeedingSkill ordinal.
- * Lower tier number = better tier (like placements).
- */
+/** Tier from the top teams' average SeedingSkill ordinal. Lower tier number = better (like placements). */
 
 export const TIER_THRESHOLDS = {
 	X: 32,
diff --git a/app/features/tournament/routes/to.$id.register.tsx b/app/features/tournament/routes/to.$id.register.tsx
index 4051391f5..283d135b7 100644
--- a/app/features/tournament/routes/to.$id.register.tsx
+++ b/app/features/tournament/routes/to.$id.register.tsx
@@ -1152,10 +1152,8 @@ function SelectedTeamAvailability() {
 		return status === "available" || status === "partial";
 	};
 
-	// with a team selected the panel shows its full roster, every status
-	// included; signing up as a pickup it instead lists everyone the viewer
-	// could recruit (all their teams' members and friends) in one list, kept
-	// to those actually free during the event
+	// with a team selected the panel shows its full roster; as a pickup it lists everyone the viewer
+	// could recruit (all their teams' members and friends) that is free during the event
 	const roster = teamId
 		? (data?.friendPlayers?.friends ?? []).filter(
 				(friend) => friend.teamId === teamId,
diff --git a/app/features/tournament/routes/to.$id.tsx b/app/features/tournament/routes/to.$id.tsx
index 648468db2..3d698c54a 100644
--- a/app/features/tournament/routes/to.$id.tsx
+++ b/app/features/tournament/routes/to.$id.tsx
@@ -74,9 +74,7 @@ export const handle: SendouRouteHandle = {
 export default function TournamentLayoutShell() {
 	const isHydrated = useHydrated();
 
-	// tournaments are something that people like to refresh a lot
-	// which can cause spikes that are hard for the server to handle
-	// this is just making sure the SSR for this page is as fast as possible in prod
+	// tournament pages get refreshed a lot causing spikes, so keep the SSR as fast as possible in prod
 	if (!isHydrated)
 		return (
 			<Main bigger>
@@ -99,7 +97,7 @@ export function TournamentLayout() {
 	);
 	const [bracketExpanded, setBracketExpanded] = React.useState(true);
 
-	// this is nice to debug with tournament in browser console
+	// for debugging in the browser console
 	if (process.env.NODE_ENV === "development") {
 		React.useEffect(() => {
 			// @ts-expect-error for dev purposes
@@ -126,8 +124,7 @@ export function TournamentLayout() {
 		</>
 	);
 
-	// Always render within the breakout container so the nav (and content) keep a
-	// consistent width across routes, avoiding a layout shift when switching tabs.
+	// always in the breakout container so the nav keeps its width across routes, avoiding a layout shift
 	return (
 		<Main breakoutContainer>
 			<div className={containerClassName("wide")}>{content}</div>
diff --git a/app/features/tournament/tournament-constants.ts b/app/features/tournament/tournament-constants.ts
index e8ae253c5..3513d7cfa 100644
--- a/app/features/tournament/tournament-constants.ts
+++ b/app/features/tournament/tournament-constants.ts
@@ -10,7 +10,7 @@ export const TOURNAMENT = {
 	MAX_BRACKETS_PER_TOURNAMENT: 10,
 	BRACKET_NAME_MAX_LENGTH: 32,
 	PLACEMENT_MAX: 100,
-	// just a fallback, normally this should be set by user explicitly
+	// fallback, normally set by the user explicitly
 	RR_DEFAULT_TEAM_COUNT_PER_GROUP: 4,
 	RR_TEAMS_PER_GROUP_OPTIONS: [3, 4, 5, 6, 7, 8],
 	RR_AB_DIVISIONS_TEAMS_PER_GROUP_OPTIONS: [4, 6, 8, 10, 12],
@@ -39,11 +39,7 @@ export const TOURNAMENT_STAGE_TYPES = [
 	"swiss",
 ] as const;
 
-/**
- * AUTO = teams pick their map pool ahead of time and the map lists are made
- * automatically for each round. TO = the traditional style where the TO picks
- * the maps.
- */
+/** AUTO = teams pick map pools ahead and each round's map list is made automatically, TO = the TO picks the maps. */
 export type TournamentMapPickingStyle =
 	| "TO"
 	| "AUTO_ALL"
diff --git a/app/features/tournament/tournament-context.tsx b/app/features/tournament/tournament-context.tsx
index b2fc00a2d..2efa7f94f 100644
--- a/app/features/tournament/tournament-context.tsx
+++ b/app/features/tournament/tournament-context.tsx
@@ -1,16 +1,11 @@
 import * as React from "react";
 import type { Tournament } from "~/features/tournament-bracket/core/Tournament";
 
-// Lives outside the to.$id route module on purpose: a context created inside a
-// route module gets a new identity when HMR re-executes that module, leaving
-// consumers in sibling route modules reading the stale context (null).
+// outside the to.$id route module on purpose: HMR re-executing a route module gives a context
+// created there a new identity, leaving sibling route modules reading the stale one (null)
 const TournamentContext = React.createContext<Tournament | null>(null);
 
-/**
- * Provides the tournament of the subtree. Rendered by the tournament layout,
- * and rendered again by views that load bracket match data of their own to
- * override the layout's tournament.
- */
+/** Rendered by the tournament layout, and again by views loading their own bracket match data to override it. */
 export function TournamentProvider({
 	tournament,
 	children,
diff --git a/app/features/tournament/tournament-register-schemas.server.ts b/app/features/tournament/tournament-register-schemas.server.ts
index 006a7e23a..78a398c2a 100644
--- a/app/features/tournament/tournament-register-schemas.server.ts
+++ b/app/features/tournament/tournament-register-schemas.server.ts
@@ -5,12 +5,7 @@ import { superRefineAsync } from "~/utils/schema";
 import { registerTeamFormSchema } from "./tournament-register-schemas";
 import { tournamentTeamNameTaken } from "./tournament-utils.server";
 
-/**
- * Extends the client {@link registerTeamFormSchema} with the server-only unique team
- * name check, surfaced as a field error. Shares the uniqueness rule with the admin
- * registration form ({@link adminRegistrationFormSchemaServer}) via
- * {@link tournamentTeamNameTaken}.
- */
+/** {@link registerTeamFormSchema} plus the server-only unique name check ({@link tournamentTeamNameTaken}) as a field error. */
 export function registerTeamFormSchemaServer({
 	tournament,
 	ownTeamId,
diff --git a/app/features/tournament/tournament-utils.server.ts b/app/features/tournament/tournament-utils.server.ts
index df745fad2..2c767e929 100644
--- a/app/features/tournament/tournament-utils.server.ts
+++ b/app/features/tournament/tournament-utils.server.ts
@@ -37,12 +37,8 @@ export async function isBannedByOrganization({
 }
 
 /**
- * Whether the given team name is already used by another team in the tournament.
- * Single source of truth for the uniqueness rule shared by the player registration
- * ({@link registerTeamFormSchemaServer}) and admin registration
- * ({@link adminRegistrationFormSchemaServer}) forms.
- *
- * @param exceptTournamentTeamId - the team being edited, excluded from the comparison
+ * Whether another team in the tournament already uses the name, shared by the player and admin
+ * registration forms. `exceptTournamentTeamId` is the team being edited.
  */
 export function tournamentTeamNameTaken({
 	tournament,
@@ -85,14 +81,8 @@ export async function fulfillsSendouQParticipation({
 }
 
 /**
- * Ends all unfinished matches involving dropped teams by awarding wins to their opponents.
- * If both teams in a match have dropped, a random winner is selected. Pure over the given
- * bracket data — the caller persists the returned changedMatches.
- *
- * @param tournament - The tournament instance
- * @param data - The bracket data to end matches in (fresh rows or the previous engine result)
- * @param droppedTeamId - Optional team ID to filter matches for a specific dropped team.
- *                        If omitted, processes all matches with any dropped team.
+ * Ends unfinished matches of dropped teams (of `droppedTeamId` only when given) by awarding the
+ * opponent the win, random when both dropped. Pure over `data` — the caller persists changedMatches.
  */
 export function endDroppedTeamMatches({
 	tournament,
diff --git a/app/features/tournament/tournament-utils.test.ts b/app/features/tournament/tournament-utils.test.ts
index b5b9084d6..105deb264 100644
--- a/app/features/tournament/tournament-utils.test.ts
+++ b/app/features/tournament/tournament-utils.test.ts
@@ -39,11 +39,7 @@ const teamForOrdering = (
 
 const MIN_MEMBERS = 4;
 
-/**
- * Every ordering rule, stated as the order callers actually see: what
- * `sortTeamsBySeeding` produces. `compareTeamsForOrdering` is only checked
- * against its antisymmetry contract over the same rows.
- */
+/** Every ordering rule as `sortTeamsBySeeding` output; `compareTeamsForOrdering` is only checked for antisymmetry over the same rows. */
 const ORDERING_RULES: {
 	rule: string;
 	teams: TeamForOrdering[];
diff --git a/app/features/tournament/tournament-utils.ts b/app/features/tournament/tournament-utils.ts
index 5d3c69f2d..f707064dc 100644
--- a/app/features/tournament/tournament-utils.ts
+++ b/app/features/tournament/tournament-utils.ts
@@ -40,7 +40,6 @@ export function modesIncluded(
 
 	const pickedModes = R.unique(toSetMapPool.map((map) => map.mode));
 
-	// fallback
 	if (pickedModes.length === 0) {
 		return [...rankedModesShort];
 	}
@@ -157,11 +156,8 @@ export function tournamentIsRanked({
 }
 
 /**
- * Whether a tournament's start time falls inside the active weapon-reporting window
- * for late (post-finalization) reporting.
- *
- * - In-season: window is `(previousSeason.ends, now]` — current season plus the off-season immediately before it.
- * - Off-season: window is `[previousSeason.starts, now]` — previous full season plus the current off-season.
+ * Whether a tournament's start time allows late (post-finalization) weapon reporting.
+ * In-season the window is `(previousSeason.ends, now]`, off-season `[previousSeason.starts, now]`.
  */
 export function tournamentInWeaponReportingWindow({
 	tournamentStartTime,
@@ -264,11 +260,8 @@ export type TeamForOrdering = {
 };
 
 /**
- * Compares two teams pairwise for ordering purposes. Not a strict weak order
- * when one team has a seed and the other does not (the seed is ignored in
- * favor of the skill comparison), so it must not be used as a raw `sort`
- * comparator over a mixed seeded/unseeded field — {@link sortTeamsBySeeding}
- * handles that case.
+ * Pairwise team comparison. Not a strict weak order when only one team has a seed (skill is
+ * compared instead), so never a raw `sort` comparator over a mixed field — see {@link sortTeamsBySeeding}.
  */
 export function compareTeamsForOrdering(
 	a: TeamForOrdering,
@@ -313,13 +306,10 @@ export function compareTeamsForOrdering(
 }
 
 /**
- * Orders tournament teams into their effective seed order. Within each
- * starting bracket manually seeded teams keep the organizer's seed order,
- * while unseeded teams (e.g. registered after the seeds were last saved) are
- * slotted in by skill: below every seeded team with a higher skill ordinal,
- * above the rest. Unseeded teams that are not full or have no skill ordinal
- * go below all seeded teams. The result is deterministic regardless of the
- * input order.
+ * Effective seed order. Within each starting bracket seeded teams keep the organizer's order;
+ * unseeded teams (e.g. registered after seeds were saved) slot in by skill below every seeded team
+ * with a higher ordinal. Unseeded teams that are not full or have no ordinal go last. Deterministic
+ * regardless of input order.
  */
 export function sortTeamsBySeeding<T extends TeamForOrdering>(
 	teams: T[],
@@ -446,20 +436,13 @@ export function getBracketProgressionLabel(
 const LEADING_SEPARATOR_REGEX = /^[\s_-]+/;
 
 /**
- * Splits a tournament name into its series name and a trailing "subtext"
- * (e.g. an edition number like `"54"` or a date like `"May 2026"`) based on the
- * names of the organization's tournament series.
- *
- * The longest series name that the tournament name starts with (case-insensitive)
- * is treated as the base name and whatever follows it becomes the subtext. If the
- * tournament name does not start with any of the series names, the whole name is
- * returned with no subtext.
+ * Splits a tournament name into the longest series name it starts with (case-insensitive) and
+ * the trailing subtext; the whole name with no subtext when no series matches.
  *
  * @example
  * // series: [{ name: "In The Zone" }]
- * splitTournamentName("In The Zone 54", series)     // { name: "In The Zone", subtext: "54" }
- * splitTournamentName("In The Zone Winter", series) // { name: "In The Zone", subtext: "Winter" }
- * splitTournamentName("Picnic Weekly", series)      // { name: "Picnic Weekly" }
+ * splitTournamentName("In The Zone 54", series) // { name: "In The Zone", subtext: "54" }
+ * splitTournamentName("Picnic Weekly", series)  // { name: "Picnic Weekly" }
  */
 export function splitTournamentName(
 	tournamentName: string,
@@ -485,12 +468,7 @@ export function splitTournamentName(
 	return { name: matchingSeries.name, subtext };
 }
 
-/**
- * Resolves the display name and subtext for a tournament's identity, based on
- * the organization's tournament series.
- *
- * @see {@link splitTournamentName}
- */
+/** Display name and subtext of a tournament based on its organization's series, see {@link splitTournamentName}. */
 export function tournamentNameParts(tournament: TournamentClass): {
 	name: string;
 	subtext?: string;
@@ -512,20 +490,10 @@ const STAGE_TYPE_TO_SHORT_CODE: Record<
 };
 
 /**
- * Builds a compact label describing the bracket progression of a tournament,
- * derived from `settings.bracketProgression`.
- *
- * Each main progression stage is rendered as a short code (`RR`, `SE`, `DE`, `SW`), arrow-separated
- * with consecutive duplicates collapsed (e.g. two single-elimination stages still render as a
- * single `SE`).
- *
- * Underground brackets are not part of the main progression — they give early losers another chance
- * to play. They are left out of the label and instead reported via `hasUnderground` so that the
- * caller can render a `+ UG` suffix. Their type and where they branch off from is deliberately not
- * conveyed, keeping the label to one shape no matter how the underground brackets are set up.
- *
- * Starting brackets that lead to the same shape (a league's divisions) are described once, as they
- * are played in parallel rather than one after the other.
+ * Compact bracket progression label: main stages as short codes (`RR`, `SE`, `DE`, `SW`), arrow
+ * separated, consecutive duplicates collapsed. Underground brackets are left out of the label and
+ * only reported via `hasUnderground` (for a `+ UG` suffix) so the label has one shape however they
+ * are set up. Parallel starting brackets leading to the same shape (league divisions) are described once.
  *
  * @example
  * // [{type: "round_robin"}, {type: "single_elimination"}, ...underground SE brackets]
@@ -559,10 +527,7 @@ function labelOfBrackets(bracketIdxs: number[], progression: ParsedBracket[]) {
 	return codes.join(" → ");
 }
 
-/**
- * Brackets the label describes: every one of them, or the brackets of one starting bracket when
- * the tournament has many that all lead to the same shape.
- */
+/** Every bracket, or those of one starting bracket when many lead to the same shape. */
 function labeledBracketIdxs(progression: ParsedBracket[]) {
 	const everyBracketIdx = progression.map((_, idx) => idx);
 
@@ -579,9 +544,8 @@ function labeledBracketIdxs(progression: ParsedBracket[]) {
 }
 
 /**
- * Returns a new `CastedMatchesInfo` with the cast assignment applied. Tracks history of streamed set per channel.
- * Deduplicates history by `matchId` so that correcting a wrong channel replaces the previous entry.
- *
+ * New `CastedMatchesInfo` with the cast assignment applied. History is deduplicated by `matchId`
+ * so correcting a wrong channel replaces the previous entry.
  */
 export function updatedCastedMatchesInfo(
 	current: CastedMatchesInfo,
@@ -608,9 +572,7 @@ export function updatedCastedMatchesInfo(
 		castedMatches: current.castedMatches
 			.filter(
 				(cm) =>
-					// currently a match can only be streamed by one account
-					// and a cast can only stream one match at a time
-					// these can change in the future
+					// for now one account per match and one match per account at a time
 					cm.matchId !== matchId && cm.twitchAccount !== twitchAccount,
 			)
 			.concat([{ twitchAccount, matchId }]),
diff --git a/app/features/trophies/TrophyRepository.server.ts b/app/features/trophies/TrophyRepository.server.ts
index 9b7b506a8..04922d8f1 100644
--- a/app/features/trophies/TrophyRepository.server.ts
+++ b/app/features/trophies/TrophyRepository.server.ts
@@ -450,10 +450,7 @@ export async function findOrganizationIdById(trophyId: number) {
 	return row?.organizationId ?? null;
 }
 
-/**
- * Checks whether a trophy name is taken by an existing trophy or a submission still
- * awaiting review. Accepted submissions don't count.
- */
+/** Whether the name is taken by a trophy or a submission still awaiting review. */
 export async function existsByName(args: {
 	name: string;
 	excludeTrophyId?: number;
@@ -507,10 +504,7 @@ export async function findAllForEditing() {
 		.execute();
 }
 
-/**
- * Recomputes ownership of every special trophy (supporter, XP).
- * Existing owner rows that are still eligible keep their original `createdAt`.
- */
+/** Recomputes special trophy (supporter, XP) ownership; still-eligible owners keep their `createdAt`. */
 export function syncSpecialTrophies() {
 	return db.transaction().execute(async (trx) => {
 		await syncSupporterTrophyOwners(trx);
diff --git a/app/features/trophies/components/Trophy.tsx b/app/features/trophies/components/Trophy.tsx
index c88556a29..8937e716e 100644
--- a/app/features/trophies/components/Trophy.tsx
+++ b/app/features/trophies/components/Trophy.tsx
@@ -25,23 +25,11 @@ type TrophyCtxValue =
 const TrophyCtx = createContext<TrophyCtxValue | undefined>(undefined);
 
 /**
- * Shares one PicoCAD2 WebGL context across every `Trophy` rendered inside.
- *
- * `Trophy` falls back to creating its own internal context when no provider is
- * used, but browsers cap active WebGL contexts at 16 so any grid bigger than
- * that, or rapid mounting/unmounting, triggers a warning and broken rendering.
- *
- * We use two implementations to stay under the limit:
- *
- * 1. One page wide `PicoCAD2Context` singleton.
- * 	  Creating a new one per mount can stack contexts faster than the browser
- *    can remove them. Holding one for the page lifetime is cheaper in comparison.
- *
- * 2. The provider always renders its children so surrounding layout doesn't shift
- *    but uses an additional `isLoading` bool while `useState` is still `undefined`
- *    before the first effect fires. Descendant `Trophy` components read the bool
- *    and render an empty spacer instead of mounting a canvas that would create
- *    their own internal context.
+ * Shares one PicoCAD2 WebGL context across every `Trophy` inside. Without a provider each `Trophy`
+ * creates its own, but browsers cap active WebGL contexts at 16, so big grids or rapid remounts
+ * break rendering. One page-wide singleton is held for the page lifetime (per-mount contexts stack
+ * faster than the browser frees them), and while it is loading descendants render a spacer instead
+ * of a canvas that would create their own context.
  */
 
 let sharedContext: PicoCAD2Context | undefined;
@@ -119,9 +107,7 @@ export function Trophy({
 
 	const modelState = decompressTrophyModel(model);
 
-	// useCallback is needed to keep the ref callback identity stable.
-	// A new identity each render would make React detach and re-attach,
-	// disposing and rebuilding the viewer on every re-render
+	// stable ref callback identity, else React re-attaches and rebuilds the viewer every render
 	const canvasRef = useCallback(
 		(canvas: HTMLCanvasElement | null) => {
 			if (!canvas) {
@@ -146,10 +132,8 @@ export function Trophy({
 				return;
 			}
 
-			// continuous render loops starve the main thread when WebGL is
-			// software rendered, so e2e runs (which always render on CPU) draw a
-			// single static frame, as do surfaces showing many loops at once on
-			// devices without GPU acceleration
+			// render loops starve the main thread on software WebGL, so e2e (always CPU) and surfaces
+			// showing many trophies without GPU acceleration draw a single static frame
 			if (
 				preview ||
 				IS_E2E_TEST_RUN ||
diff --git a/app/features/trophies/core/model-analysis.ts b/app/features/trophies/core/model-analysis.ts
index b8d9a4792..093ee7c52 100644
--- a/app/features/trophies/core/model-analysis.ts
+++ b/app/features/trophies/core/model-analysis.ts
@@ -55,10 +55,7 @@ export function analyzeTrophyModel(model: string): TrophyModelAnalysis | null {
 	}
 }
 
-/**
- * Animations can toggle meshes on and off, so the peak across frames
- * is what the draw call and poly metrics should show.
- */
+/** Animations toggle meshes, so draw call and poly metrics show the peak across frames. */
 export function mergePeakRenderStats(
 	previous: RenderStats | null,
 	frame: RenderStats,
diff --git a/app/features/user-card/UserCardRepository.server.ts b/app/features/user-card/UserCardRepository.server.ts
index 0a4e7cbb2..1eddedf3d 100644
--- a/app/features/user-card/UserCardRepository.server.ts
+++ b/app/features/user-card/UserCardRepository.server.ts
@@ -33,15 +33,9 @@ import type {
 import { isValidUnverifiedXp } from "./user-card-utils";
 
 /**
- * Loads `UserCardData` for many users at once, keyed by user id. The single batched DB query (see
- * {@link userCardDataJsonObject}) is merged with the in-memory SEASON caches (tier from
- * `userSkills`, leaderboard placement from `cachedFullUserLeaderboard`) in this app-layer enrich
- * pass, producing the fully-formed `stats` array each card renders. The acting user viewing the
- * cards (resolved from request context via `actorIdOrNull()`, or `null` when anonymous) scopes the
- * per-viewer `privateNote`.
- *
- * Designed to be spread into a route loader (`{ ...(await findAllByUserIds(...)) }`) so the `UserCard`
- * component can resolve its own data from the route tree by id.
+ * `UserCardData` for many users, keyed by user id. One batched query ({@link userCardDataJsonObject})
+ * merged with the in-memory SEASON caches (`userSkills`, `cachedFullUserLeaderboard`); `privateNote`
+ * is scoped to the acting user. Spread the result into a route loader so `UserCard` can find it.
  */
 export async function findAllByUserIds({
 	userIds,
@@ -49,12 +43,9 @@ export async function findAllByUserIds({
 	includeHiddenStats = false,
 }: {
 	userIds: Array<number>;
-	/** Opt-in fields skipped from the query by default; defaults to `false` each. */
+	/** Opt-in fields skipped from the query by default. */
 	include?: { friendCode?: boolean };
-	/**
-	 * Keep stats the user has hidden in the resolved `stats` array. Off by default so hidden stat
-	 * values never reach a viewer; the edit page opts in to render (and un-hide) its own toggles.
-	 */
+	/** Keep hidden stats in `stats`; only the edit page opts in, so hidden values never reach a viewer. */
 	includeHiddenStats?: boolean;
 }): Promise<{ userCards: Map<number, UserCardData> }> {
 	if (userIds.length === 0) return { userCards: new Map() };
@@ -77,23 +68,16 @@ const cardCache = new LRUCache<
 >({ max: CARD_CACHE_MAX_ENTRIES });
 
 /**
- * Like {@link findAllByUserIds} but serves the viewer-independent card data from a
- * short-lived in-memory cache, querying only users whose entry is missing or stale.
- * The per-viewer `privateNote` and the opt-in `friendCode` are overlaid fresh on
- * every call so a cached card is never viewer- or caller-specific. For high-frequency
- * views (the SendouQ looking page) where broadcast-driven revalidation makes many
- * clients rebuild the same cards at once; cards may be up to 30 seconds stale.
- *
- * The cache holds the in-flight query rather than its result, so concurrent misses for
- * the same user (exactly what a revalidation burst causes) await one shared query
- * instead of each firing their own.
+ * Like {@link findAllByUserIds} but viewer-independent card data comes from a 30s in-memory cache
+ * (for revalidation bursts on the SendouQ looking page); `privateNote` and `friendCode` are overlaid
+ * fresh per call. The cache holds the in-flight query so concurrent misses share one query.
  */
 export async function findAllByUserIdsCached({
 	userIds,
 	include,
 }: {
 	userIds: Array<number>;
-	/** Opt-in fields skipped by default; defaults to `false` each. */
+	/** Opt-in fields skipped from the query by default. */
 	include?: { friendCode?: boolean };
 }): Promise<{ userCards: Map<number, UserCardData> }> {
 	if (ServerConfig.disableCache) return findAllByUserIds({ userIds, include });
@@ -141,7 +125,7 @@ export async function findAllByUserIdsCached({
 	return { userCards };
 }
 
-/** Forgets every cached card, so the next read builds them from the database again. */
+/** Drops every cached card. */
 export function clearUserCardCache() {
 	cardCache.clear();
 }
@@ -211,7 +195,6 @@ async function queryUserCards({
 	return userCards;
 }
 
-/** The acting user's private notes about the given users, keyed by their user id. */
 async function findPrivateNotesByTargetIds(userIds: Array<number>) {
 	const notes = new Map<number, NonNullable<UserCardData["privateNote"]>>();
 
@@ -237,10 +220,7 @@ async function findPrivateNotesByTargetIds(userIds: Array<number>) {
 	return notes;
 }
 
-/**
- * Latest friend code of each given user, keyed by their user id. Scanned oldest to newest so the
- * newest code is the one left in the map, matching {@link friendCodeScalar}.
- */
+/** Latest friend code per user; scanned oldest to newest so the newest wins, like {@link friendCodeScalar}. */
 async function findFriendCodesByUserIds(userIds: Array<number>) {
 	const friendCodes = new Map<number, string>();
 	if (userIds.length === 0) return friendCodes;
@@ -259,11 +239,7 @@ async function findFriendCodesByUserIds(userIds: Array<number>) {
 	return friendCodes;
 }
 
-/**
- * Raw card fields the edit form needs that are not part of {@link UserCardData}: the uploaded banner
- * image (id + preview url, for the image field's default value), the self-reported peak XP, the
- * picked XP division, and the hidden stat types (to pre-check the visibility toggles).
- */
+/** Raw card fields the edit form needs that are not part of {@link UserCardData}. */
 export async function findCardEditExtrasByUserId(userId: number) {
 	const row = await db
 		.selectFrom("User")
@@ -287,9 +263,8 @@ export async function findCardEditExtrasByUserId(userId: number) {
 }
 
 /**
- * The verified XP the user's card shows if their XP division were `xpDivision`, resolved exactly as
- * {@link findAllByUserIds} does (see {@link verifiedXp}). `null` when they have no X Rank placements.
- * Lets the edit form judge a self-reported peak XP against the very value it will sit on top of.
+ * Verified XP the card would show with `xpDivision` (see {@link verifiedXp}), so the edit form can
+ * judge a self-reported peak against it. `null` without X Rank placements.
  */
 export async function findVerifiedXpByUserId(
 	userId: number,
@@ -304,10 +279,7 @@ export async function findVerifiedXpByUserId(
 	return verifiedXp(row?.xpPeaks ?? null, xpDivision);
 }
 
-/**
- * Updates the editable user card fields of the acting user (their own card), dropping their
- * cached card so they are not shown their pre-edit one by {@link findAllByUserIdsCached}.
- */
+/** Updates the acting user's own card and drops it from the cache. */
 export async function updateOwnCard(args: {
 	shortBio: string | null;
 	bannerPresetImg: string | null;
@@ -319,8 +291,7 @@ export async function updateOwnCard(args: {
 }) {
 	const userId = actorId();
 	await db.transaction().execute(async (trx) => {
-		// a removed or replaced uploaded banner is no longer referenced by anything,
-		// so its submitted image row is cleaned up (mirrors custom avatar handling)
+		// a removed or replaced uploaded banner's image row is cleaned up (mirrors custom avatar handling)
 		const current = await trx
 			.selectFrom("User")
 			.select("User.bannerImgId")
@@ -362,15 +333,9 @@ const BANNER_PRESET_COLOR_CASE = `case "User"."id" % ${PRESET_COLORS.length}\n${
 ).join("\n")}\nend`;
 
 /**
- * Kysely expression building the JSON object for all DB-resident `UserCard` fields of a single user.
- * Designed to be composed both standalone (one user) and inside a batched list query (see
- * {@link findAllByUserIds}). `"User"` must be in scope at the call site.
- *
- * SEASON stats (tier + leaderboard placement) are NOT included here — they live in the in-memory
- * `userSkills`/leaderboard caches and are merged in an app-layer enrich pass. `banner` is returned as
- * loosely-typed fields (narrow to the discriminated union there). `friendCode` is opt-in via
- * `include.friendCode` (defaults to off, resolving to `null`) so callers that never surface it skip
- * the extra correlated subquery.
+ * JSON object of all DB-resident card fields of one user; `"User"` must be in scope. SEASON stats
+ * come from in-memory caches and are merged in the enrich pass, which also narrows `banner`.
+ * `friendCode` is opt-in so callers that never surface it skip the correlated subquery.
  */
 function userCardDataJsonObject(
 	eb: ExpressionBuilder<Tables, "User">,
@@ -409,11 +374,8 @@ type RawUserCardData =
 		: never;
 
 /**
- * Loosely-typed banner. A supporter-uploaded image (`User.bannerImgId`) takes precedence and yields
- * a `URL` banner; otherwise it is pulled from the `User.bannerPresetImg` column ("hex code or stage
- * id") where a numeric value is a stage id (`STAGE`) and anything else a `COLOR` hex code. When both
- * are null (no explicit choice) a preset color is derived from the user id. Narrow to the
- * `{ URL | COLOR | STAGE }` union in the enrich pass.
+ * Uploaded image (`bannerImgId`) wins; else `bannerPresetImg` holds a stage id (numeric) or a hex
+ * color; with neither set a preset color is derived from the user id.
  */
 function bannerJson(eb: ExpressionBuilder<Tables, "User">) {
 	return jsonBuildObject({
@@ -436,7 +398,6 @@ function bannerJson(eb: ExpressionBuilder<Tables, "User">) {
 	});
 }
 
-/** Full URL of the supporter-uploaded banner image (resolved from `User.bannerImgId`), or null. */
 function bannerImageUrl(eb: ExpressionBuilder<Tables, "User">) {
 	return concatUserSubmittedImagePrefix(
 		eb
@@ -481,11 +442,7 @@ function privateNoteJson(
 	);
 }
 
-/**
- * Id of the user's most recent non-expired "looking for team" LFG post, which marks them as a free
- * agent. `null` when they have no such post. Mirrors the LFG page's freshness cutoff so the id always
- * points at a post that is still listed there.
- */
+/** Latest non-expired "looking for team" post (uses the LFG page's freshness cutoff), marking a free agent. */
 function freeAgentPostIdScalar(eb: ExpressionBuilder<Tables, "User">) {
 	return eb
 		.selectFrom("LFGPost")
@@ -514,11 +471,7 @@ function plusTierScalar(eb: ExpressionBuilder<Tables, "User">) {
 
 type XpPeaks = Record<XRankPlacementRegion, number | null> | null;
 
-/**
- * Highest X Rank power placement (verified XP) per division. Both are read because the division the
- * card settles on is resolved in the app layer (see {@link verifiedXp}); with no placements at all
- * the aggregates simply come back null.
- */
+/** Peak X Rank power per division; the division shown is picked in the app layer (see {@link verifiedXp}). */
 function xpPeaksJson(eb: ExpressionBuilder<Tables, "User">) {
 	return jsonObjectFrom(
 		eb
@@ -544,9 +497,6 @@ function xpPeaksJson(eb: ExpressionBuilder<Tables, "User">) {
 	);
 }
 
-/**
- * Self-reported peak XP from the `User.unverifiedPeakXP` column.
- */
 function xpUnverifiedPointsScalar() {
 	return sql<number | null>`"User"."unverifiedPeakXP" ->> '$.overall'`;
 }
@@ -557,10 +507,8 @@ type SeasonResult = {
 };
 
 /**
- * Resolves one finished season's data for the requested users. `userSkills` is an in-memory
- * cache, so we read tiers first and only fetch the (DB-backed) leaderboard when at least
- * one requested user reached Leviathan+ that season—placements are surfaced for that rank only, so
- * the common case of regular users never touches the leaderboard cache at all.
+ * Placements are shown for Leviathan+ only, so the DB-backed leaderboard is fetched only when one
+ * of the users reached it; tiers come from the in-memory `userSkills`.
  */
 async function seasonResult(
 	season: number,
@@ -585,10 +533,8 @@ async function seasonResult(
 const placementsBySeason = new Map<number, Map<number, number>>();
 
 /**
- * Leaderboard placements of a finished season, keyed by user id. Cached for the process lifetime:
- * a finished season's leaderboard is immutable, matching how `userSkills` already holds finished
- * seasons' tiers permanently. This keeps cards off `cachedFullUserLeaderboard`'s TTL, whose
- * synchronous rebuild would otherwise stall the first Leviathan+ card render after a quiet period.
+ * Cached for the process lifetime since a finished season's leaderboard is immutable; avoids
+ * `cachedFullUserLeaderboard`'s TTL rebuild stalling the first Leviathan+ card after a quiet period.
  */
 async function finishedSeasonPlacements(
 	season: number,
@@ -611,10 +557,8 @@ const isLeviathanPlus = (tier: TieredSkill["tier"]) =>
 	tier.name === "LEVIATHAN" && tier.isPlus;
 
 /**
- * Comparable strength of a tier (higher = better). Based on the tier's position in `TIERS` rather
- * than the raw ordinal, because each season sets its own ordinal thresholds—the same ordinal can
- * map to different tiers across seasons—so only the tier itself is comparable. `isPlus` (top half of
- * a tier) breaks ties within the same tier name.
+ * Higher = better. Uses the position in `TIERS`, not the ordinal, since ordinal thresholds differ per
+ * season; `isPlus` breaks ties within a tier.
  */
 const tierStrength = (tier: TieredSkill["tier"]) => {
 	const index = TIERS.findIndex((t) => t.name === tier.name);
@@ -622,10 +566,8 @@ const tierStrength = (tier: TieredSkill["tier"]) => {
 };
 
 /**
- * Reduces a user's results across the last two finished seasons into the single result their card
- * shows: the highest tier they reached (ignoring `approximate` tiers, which lack enough matches to
- * count), and—only when that includes the very top Leviathan+ rank—their best (lowest) leaderboard
- * placement among the Leviathan+ seasons.
+ * Highest non-approximate tier across the given seasons, plus the best leaderboard placement among
+ * the Leviathan+ seasons.
  */
 function bestSeasonResult(
 	userId: number,
@@ -699,11 +641,7 @@ function enrichUserCardData(
 	};
 }
 
-/**
- * The verified XP a card shows: the peak of the division the user picked, since the two divisions
- * are separate ladders and a peak in one says nothing about the other. Falls back to their highest
- * across both when they picked no division or have never placed in the one they picked.
- */
+/** Peak of the picked division (the divisions are separate ladders); else the highest across both. */
 function verifiedXp(
 	peaks: XpPeaks,
 	xpDivision: XRankPlacementRegion | null,
@@ -767,8 +705,7 @@ function userCardStats({
 		});
 
 		const xpValues: Array<UserCardStatXPValue> = unverified ? [unverified] : [];
-		// the verified peak joins the claim only when it is from the division the claim was made in;
-		// in another division it is a peak on a ladder the card is not about
+		// the verified peak is shown beside the claim only when it is from the same division
 		if (!unverified || unverified.region === xpVerified.region) {
 			xpValues.push({
 				isVerified: true,
diff --git a/app/features/user-card/components/AddPrivateNoteDialog.tsx b/app/features/user-card/components/AddPrivateNoteDialog.tsx
index a0c018149..9043ca321 100644
--- a/app/features/user-card/components/AddPrivateNoteDialog.tsx
+++ b/app/features/user-card/components/AddPrivateNoteDialog.tsx
@@ -8,10 +8,8 @@ import { userCardNoteSaveSchema } from "../user-card-schemas";
 type PrivateNote = Pick<Tables["PrivateUserNote"], "text" | "sentiment">;
 
 /**
- * Modal for adding/editing the viewer's private note about a user, posting to the
- * `/user-card/:id/note` resource route. Closes once the save succeeds (automatic revalidation
- * refreshes the card). Clearing the text with a neutral sentiment and saving deletes the note
- * (handled by the route). Rendered wherever a `UserCard` lives.
+ * Posts to the `/user-card/:id/note` resource route and closes on success. Saving empty text with
+ * a neutral sentiment deletes the note (handled by the route).
  */
 export function AddPrivateNoteDialog({
 	userId,
diff --git a/app/features/user-card/components/UserCard.tsx b/app/features/user-card/components/UserCard.tsx
index 886e951f4..c31722fb9 100644
--- a/app/features/user-card/components/UserCard.tsx
+++ b/app/features/user-card/components/UserCard.tsx
@@ -69,15 +69,9 @@ const STAT_ORDER: Record<UserCardStat["type"], number> = {
 };
 
 /**
- * Click-to-open trigger that shows a popover with the user's card. Card data is resolved from the
- * route tree by `userId` (a parent loader spreads `{ userCards }` from `UserCardRepository.findAllByUserIds`);
- * pass `data` directly to bypass the lookup (e.g. the components showcase). When no card data exists
- * for the user, the `children` are rendered plain without a trigger.
- *
- * Viewer-relative friendship data (`isFriend`) is lazy-loaded from the `/user-card/:id/friendship`
- * route the first time the card opens. Mutual friends are only fetched and shown when
- * `withMutualFriends` is set (e.g. the SendouQ looking page); other views (e.g. match pages) skip
- * both the extra query and the row.
+ * Popover trigger showing the user's card. Data is resolved from the route tree by `userId` (a
+ * parent loader spread `{ userCards }`) or passed as `data`; without data `children` render plain.
+ * Friendship data is lazy-loaded from `/user-card/:id/friendship` on first open.
  */
 export function UserCard({
 	userId,
@@ -95,16 +89,14 @@ export function UserCard({
 	const lookedUpData = useUserCardData(userId);
 	const data = dataProp ?? lookedUpData;
 
-	// beside the trigger there is no room for the card on a narrow viewport, so it is placed
-	// vertically instead where React Aria can shift it horizontally to keep it on-screen
+	// on narrow viewports the card is placed vertically so React Aria can shift it to stay on-screen
 	const placement = useLayoutSize() === "mobile" ? "bottom" : "right";
 
 	const user = useUser();
 	const isOwnCard = user?.id === data?.id;
 
 	const [isOpen, setIsOpen] = React.useState(false);
-	// kept at this level (outside the popover) so the modals survive the popover closing when they
-	// take focus; the note view inside the card opens them
+	// outside the popover so the modals survive it closing when they take focus
 	const [isNoteDialogOpen, setIsNoteDialogOpen] = React.useState(false);
 	const [isDeleteConfirmOpen, setIsDeleteConfirmOpen] = React.useState(false);
 	const [isReportDialogOpen, setIsReportDialogOpen] = React.useState(false);
@@ -195,11 +187,7 @@ export function UserCard({
 	);
 }
 
-/**
- * Resolves a user's `UserCardData` from any matched route loader that spread `{ userCards }`
- * (see `UserCardRepository.findAllByUserIds`). Returns `undefined` when no loader on the current route
- * tree carries data for the given user.
- */
+/** `UserCardData` from any matched route loader that spread `{ userCards }`, or `undefined`. */
 export function useUserCardData(
 	userId: number | undefined,
 ): UserCardData | undefined {
@@ -419,12 +407,7 @@ function NoteView({
 	);
 }
 
-/**
- * Friend request action on the card, submitting to the `/friends` route action. Normally sends a
- * request and shows a checkmark once one is pending (server-known or just sent); when the shown
- * user has already sent the viewer a request, the same add-friend press accepts it instead.
- * Cancelling a pending request is done on the `/friends` page.
- */
+/** Sends a friend request, or accepts one the shown user already sent; cancelling happens on `/friends`. */
 function FriendRequestButton({
 	targetUserId,
 	sentFriendRequest,
@@ -447,11 +430,8 @@ function FriendRequestButton({
 	const previousStateRef = React.useRef(fetcher.state);
 	const acceptsIncomingRequest = incomingFriendRequestId !== null;
 
-	// Sending a request keeps this button mounted (it becomes the pending checkmark), so the
-	// success toast can wait for the server round-trip here — the action can still reject with
-	// "Maximum pending friend requests reached". The accept path instead unmounts the button as
-	// soon as the revalidated friendship data arrives, which can race the toast render, so that
-	// toast is fired directly from the press handler below.
+	// the send toast waits for the round-trip (the action can still reject on the pending limit); the
+	// accept path unmounts this button on revalidation, so its toast fires from the press handler
 	React.useEffect(() => {
 		if (
 			!acceptsIncomingRequest &&
@@ -520,7 +500,6 @@ function FriendRequestButton({
 	);
 }
 
-/** Development only shortcut for logging in as the shown user. */
 function ImpersonateButton({ userId }: { userId: number }) {
 	const location = useLocation();
 
@@ -542,10 +521,7 @@ function ImpersonateButton({ userId }: { userId: number }) {
 	);
 }
 
-/**
- * Mutual friends row with reserved height so the card does not shift when the lazy friendship fetch
- * resolves: empty while loading, "No mutual friends" when there are none, the avatar stack otherwise.
- */
+/** Has reserved height so the card does not shift when the lazy friendship fetch resolves. */
 function CardMutualFriends({
 	friendship,
 }: {
diff --git a/app/features/user-card/routes/user-card.$id.friendship.ts b/app/features/user-card/routes/user-card.$id.friendship.ts
index 089dc8430..19e434874 100644
--- a/app/features/user-card/routes/user-card.$id.friendship.ts
+++ b/app/features/user-card/routes/user-card.$id.friendship.ts
@@ -8,11 +8,8 @@ import type { UserCardFriendship } from "../user-card-types";
 export type UserCardFriendshipLoaderData = SerializeFrom<typeof loader>;
 
 /**
- * Viewer-relative friendship data for a single user, lazy-loaded by the `UserCard`
- * popover when it opens (keeps `isFriend` + `mutualFriends` out of the batched card
- * query). Resolves to empty values when there is no logged-in viewer. Mutual friends
- * are only resolved when the card opts in via the `mutuals=true` query param (some
- * views, e.g. match pages, don't surface them), so the extra query is otherwise skipped.
+ * Viewer-relative friendship data, lazy-loaded when a `UserCard` opens. Empty without a logged-in
+ * viewer; mutual friends only with the `mutuals=true` param, skipping that query otherwise.
  */
 export const loader = async ({
 	params,
diff --git a/app/features/user-card/routes/user-card.edit.tsx b/app/features/user-card/routes/user-card.edit.tsx
index c0c1deb82..da781a6f9 100644
--- a/app/features/user-card/routes/user-card.edit.tsx
+++ b/app/features/user-card/routes/user-card.edit.tsx
@@ -58,8 +58,7 @@ export default function UserCardEditPage() {
 function defaultValues(data: Awaited<ReturnType<typeof loader>>) {
 	const { card, extras } = data;
 	const banner = card.banner;
-	// a stored self-reported peak XP is only autofilled while it's still a valid claim on top of a
-	// verified placement; otherwise the field is left blank rather than showing an unsubmittable value
+	// a stored self-reported peak XP is only autofilled while it's still a valid (submittable) claim
 	const peakXp =
 		extras.unverifiedPeakXP &&
 		isValidUnverifiedXp({
diff --git a/app/features/user-card/user-card-constants.ts b/app/features/user-card/user-card-constants.ts
index 4c180d026..f4b672dcb 100644
--- a/app/features/user-card/user-card-constants.ts
+++ b/app/features/user-card/user-card-constants.ts
@@ -1,8 +1,5 @@
 export const USER_CARD = {
 	SHORT_BIO_MAX_LENGTH: 64,
-	/**
-	 * Most a self-reported unverified peak XP may exceed the user's verified X Rank XP. The claim has
-	 * to be higher than the verified value, but by no more than this.
-	 */
+	/** Most a self-reported peak XP may exceed the verified one. */
 	MAX_UNVERIFIED_XP_ABOVE_VERIFIED: 200,
 } as const;
diff --git a/app/features/user-card/user-card-types.ts b/app/features/user-card/user-card-types.ts
index 2a4df76a5..a8451f80c 100644
--- a/app/features/user-card/user-card-types.ts
+++ b/app/features/user-card/user-card-types.ts
@@ -10,9 +10,7 @@ export interface UserCardData extends CommonUser {
 	shortBio: string | null;
 	customTheme: CustomTheme | null;
 	friendCode: string | null;
-	/** Id of the user's free agent LFG post, or `null` if they have none. */
 	freeAgentPostId: number | null;
-	/** The viewer's private note about this user, or `null` when they have none. */
 	privateNote: Pick<
 		Tables["PrivateUserNote"],
 		"text" | "sentiment" | "updatedAt"
@@ -20,16 +18,10 @@ export interface UserCardData extends CommonUser {
 	stats: Array<UserCardStat>;
 }
 
-/**
- * Viewer-relative card fields lazy-loaded when the card opens (see the
- * `/user-card/:id/friendship` resource route), kept out of the batched `UserCardData`
- * query because they are only needed for the one card a viewer actually opens.
- */
+/** Viewer-relative fields lazy-loaded from `/user-card/:id/friendship` when a card opens. */
 export interface UserCardFriendship {
 	isFriend: boolean;
-	/** Whether the viewer has a pending friend request sent to this user. */
 	sentFriendRequest: boolean;
-	/** Id of this user's pending friend request to the viewer, or `null` when there is none. */
 	incomingFriendRequestId: number | null;
 	mutualFriends: Array<CommonUser>;
 }
@@ -67,7 +59,6 @@ export type UserCardStat =
 			top: number | null;
 	  };
 
-/** Card stat types that a user can hide from their card. */
 export type HideableUserCardStat = Extract<UserCardStat["type"], "XP" | "DIV">;
 
 export interface UserCardStatXPValue {
diff --git a/app/features/user-card/user-card-utils.ts b/app/features/user-card/user-card-utils.ts
index 298bf86b1..cd7a9a365 100644
--- a/app/features/user-card/user-card-utils.ts
+++ b/app/features/user-card/user-card-utils.ts
@@ -1,10 +1,7 @@
 import { USER_CARD } from "./user-card-constants";
 
 /**
- * Whether a self-reported unverified peak XP is a valid claim on top of the user's verified XP: the
- * user must have a verified XP, and the claim must be higher than it but by no more than
- * {@link USER_CARD.MAX_UNVERIFIED_XP_ABOVE_VERIFIED}. Shared by the edit action (to validate) and the
- * card query (to decide whether the value is surfaced), so both apply the exact same rule.
+ * The claim must exceed the verified XP by no more than {@link USER_CARD.MAX_UNVERIFIED_XP_ABOVE_VERIFIED}.
  */
 export function isValidUnverifiedXp({
 	unverified,
diff --git a/app/features/user-page/UserRepository.server.ts b/app/features/user-page/UserRepository.server.ts
index b0f920c31..ac838afca 100644
--- a/app/features/user-page/UserRepository.server.ts
+++ b/app/features/user-page/UserRepository.server.ts
@@ -150,8 +150,7 @@ export function findLayoutDataByIdentifier(
 				)
 				.whereRef("VideoMatchPlayer.playerUserId", "=", "User.id")
 				.as("vodsCount"),
-			// authored and tagged art counted via an indexed union: an OR spanning
-			// Art and ArtUserMetadata would make SQLite scan the whole Art table
+			// indexed union: an OR spanning Art and ArtUserMetadata would scan the whole Art table
 			eb
 				.selectFrom("Art")
 				.innerJoin("UserSubmittedImage", "UserSubmittedImage.id", "Art.imgId")
@@ -255,9 +254,7 @@ export async function findProfileByIdentifier(
 		return null;
 	}
 
-	// queried separately with a constant userId instead of correlating to
-	// "User"."id" so that SQLite can push the predicate down into both arms
-	// of the BadgeOwner view
+	// queried separately with a constant userId, see findOwnedBadgesByUserId
 	const badges = await findOwnedBadgesByUserId(row.id);
 
 	return {
@@ -274,11 +271,8 @@ export async function findProfileByIdentifier(
 }
 
 /**
- * Badges owned by the user (tournament wins + patreon supporter badges).
- *
- * Kept as its own query taking a constant userId on purpose: correlating
- * to an outer "User"."id" would prevent SQLite from pushing the predicate
- * down into both arms of the BadgeOwner view, materializing the full view.
+ * Takes a constant userId on purpose: correlating to an outer "User"."id" would stop SQLite
+ * pushing the predicate into both arms of the BadgeOwner view, materializing the full view.
  */
 export function findOwnedBadgesByUserId(userId: number) {
 	return db
@@ -520,7 +514,7 @@ export function findAllPatrons() {
 		.execute();
 }
 
-/** Patrons for the footer marquee, in an order that is shuffled anew each UTC day. Slimmed to the fields the chip renders: no `patronTier` and only the custom theme vars the chip's colors resolve from. */
+/** Patrons for the footer marquee, reshuffled each UTC day and slimmed to the fields the chip renders. */
 export async function findAllPatronsForFooter() {
 	const rows = await db
 		.selectFrom("User")
@@ -1008,8 +1002,7 @@ export async function search({
 	query: string;
 	limit: number;
 }) {
-	// single scan over User with exact matches ranked first instead of two
-	// separate scans (exact pass + fuzzy pass excluding exact ids)
+	// one scan over User with exact matches ranked first instead of an exact pass + a fuzzy pass
 	const exactConditions = (eb: ExpressionBuilder<DB, "User">) => [
 		eb("User.username", "like", query),
 		eb("User.inGameName", "like", query),
@@ -1026,8 +1019,7 @@ export async function search({
 
 	const includeExactMatches = query.length > 1;
 
-	// the trigram index needs at least 3 characters and can't replicate
-	// LIKE wildcard semantics, those queries fall back to scanning User
+	// the trigram index needs 3+ characters and can't do LIKE wildcards; those queries scan User
 	const canUseSearchIndex =
 		query.length >= 3 && !query.includes("%") && !query.includes("_");
 
@@ -1044,9 +1036,7 @@ export async function search({
 		);
 
 	if (canUseSearchIndex) {
-		// UserSearch match prefilters candidates via the trigram index (it
-		// matches a superset of the LIKE conditions, which stay above as the
-		// source of truth so results are identical to the fallback path)
+		// the trigram index prefilters a superset; the LIKE conditions above stay the source of truth
 		const ftsPhrase = `"${query.replaceAll('"', '""')}"`;
 		dbQuery = dbQuery
 			.innerJoin("UserSearch", "UserSearch.rowid", "User.id")
@@ -1131,7 +1121,7 @@ export async function findCurrentFriendCodeByUserId(userId: number) {
 		.executeTakeFirst();
 }
 
-/** Returns all friend codes submitted by a user (both present and past) */
+/** All friend codes a user has ever submitted. */
 export async function findFriendCodesByUserId(userId: number) {
 	return db
 		.selectFrom("UserFriendCode")
@@ -1291,8 +1281,7 @@ export function updateOwnProfile(args: UpdateProfileArgs) {
 	return db.transaction().execute(async (trx) => {
 		await trx.deleteFrom("UserWeapon").where("userId", "=", userId).execute();
 
-		// a removed or replaced custom avatar is no longer referenced by anything,
-		// so its submitted image row is cleaned up
+		// a removed or replaced custom avatar's image row is cleaned up
 		const current = await trx
 			.selectFrom("User")
 			.select("User.customAvatarImgId")
@@ -1591,7 +1580,7 @@ export function findIdsByTwitchUsernames(twitchUsernames: string[]) {
 		.execute();
 }
 
-/** Returns weapon pool entries with ten-star status for the given user. */
+/** Weapon pool entries with ten-star status. */
 export function findWeaponPoolByUserId(userId: number) {
 	return db
 		.selectFrom("UserWeaponPool")
diff --git a/app/features/user-page/actions/u.$identifier.art.server.ts b/app/features/user-page/actions/u.$identifier.art.server.ts
index 56851ed31..ad9efe31f 100644
--- a/app/features/user-page/actions/u.$identifier.art.server.ts
+++ b/app/features/user-page/actions/u.$identifier.art.server.ts
@@ -20,9 +20,7 @@ export const action: ActionFunction = async ({ request }) => {
 
 	switch (data._action) {
 		case "DELETE_ART": {
-			// this actually doesn't delete the image itself from the static hosting
-			// but the idea is that storage is cheap anyway and if needed later
-			// then we can have a routine that checks all the images still current and nukes the rest
+			// the image stays on static hosting; storage is cheap and a cleanup routine can come later
 			const artToDelete = badRequestIfFalsy(
 				await ArtRepository.findById(data.id),
 			);
diff --git a/app/features/user-page/bio-json.server.test.ts b/app/features/user-page/bio-json.server.test.ts
index 374824ac3..87fbabccb 100644
--- a/app/features/user-page/bio-json.server.test.ts
+++ b/app/features/user-page/bio-json.server.test.ts
@@ -13,10 +13,7 @@ describe("profile bio is always a string", () => {
 			String(user.id),
 		);
 
-		// `User.bio` is a text column; the loader types it as `string | null` and the
-		// profile page renders it directly as a React child. If it comes back as an
-		// object, `<article>{data.user.bio}</article>` throws "Objects are not valid
-		// as a React child" and the whole profile page 500s.
+		// the profile page renders bio directly as a React child; an object would 500 the page
 		expect(typeof profile?.bio).toBe("string");
 	});
 });
diff --git a/app/features/user-page/components/MutualFriends.tsx b/app/features/user-page/components/MutualFriends.tsx
index 35adfbe9b..286ad9999 100644
--- a/app/features/user-page/components/MutualFriends.tsx
+++ b/app/features/user-page/components/MutualFriends.tsx
@@ -13,7 +13,7 @@ export function MutualFriends({
 	withoutPopover = false,
 }: {
 	mutualFriends: Array<CommonUser>;
-	/** When true renders a static avatar stack without the interactive popover, e.g. on the user card. */
+	/** Static avatar stack without the popover, e.g. on the user card. */
 	withoutPopover?: boolean;
 }) {
 	if (mutualFriends.length === 0) return null;
diff --git a/app/features/user-page/components/UserResultsTable.tsx b/app/features/user-page/components/UserResultsTable.tsx
index bddc42c77..958f9c818 100644
--- a/app/features/user-page/components/UserResultsTable.tsx
+++ b/app/features/user-page/components/UserResultsTable.tsx
@@ -52,10 +52,7 @@ export function UserResultsTable({
 						? `tournament-${result.teamId}`
 						: `event-${result.teamId}`;
 
-					// We are trying to construct a reasonable label for the checkbox
-					// which shouldn't contain the whole information of the table row as
-					// that can be also accessed when needed.
-					// e.g. "20xx Placing 2nd", "Big House 10 Placing 20th"
+					// short checkbox label e.g. "Big House 10 Placing 20th" rather than the whole row
 					const placementCellId = `${id}-${rowId}-placement`;
 					const nameCellId = `${id}-${rowId}-name`;
 					const checkboxLabelIds = `${nameCellId} ${placementHeaderId} ${placementCellId}`;
diff --git a/app/features/user-page/core/build-sorting.server.test.ts b/app/features/user-page/core/build-sorting.server.test.ts
index d04e5bade..a9d95cc56 100644
--- a/app/features/user-page/core/build-sorting.server.test.ts
+++ b/app/features/user-page/core/build-sorting.server.test.ts
@@ -75,8 +75,6 @@ describe("sortBuilds()", () => {
 		expect(sortedBuilds[1].id).toBe(3);
 	});
 
-	// Add other test cases similarly...
-
 	test("sorts by both PUBLIC_BUILD and PRIVATE_BUILD", () => {
 		const builds = [
 			mockBuild({ id: 1, isPrivate: 1 }),
diff --git a/app/features/user-page/core/widgets/leaderboard-cache.test.ts b/app/features/user-page/core/widgets/leaderboard-cache.test.ts
index b94966b4a..95e0e78e0 100644
--- a/app/features/user-page/core/widgets/leaderboard-cache.test.ts
+++ b/app/features/user-page/core/widgets/leaderboard-cache.test.ts
@@ -12,9 +12,7 @@ import { cachedUserSQLeaderboardTopData } from "./utils.server";
 
 describe("SendouQ leaderboard widget cache", () => {
 	test("counts a season once when the cache is filled concurrently", async () => {
-		// This is exactly how UserRepository.findWidgetsByUserId drives it: the
-		// top-10-seasons and top-100-seasons widgets both call the cache inside the
-		// same Promise.all, so a cold cache is populated by two concurrent callers.
+		// mirrors UserRepository.findWidgetsByUserId: two widgets hit a cold cache concurrently
 		const [cache] = await Promise.all([
 			cachedUserSQLeaderboardTopData(),
 			cachedUserSQLeaderboardTopData(),
diff --git a/app/features/user-page/core/widgets/utils.server.ts b/app/features/user-page/core/widgets/utils.server.ts
index af6182597..4b3d888b8 100644
--- a/app/features/user-page/core/widgets/utils.server.ts
+++ b/app/features/user-page/core/widgets/utils.server.ts
@@ -18,7 +18,7 @@ type UserSQLeaderboardTopData = Map<
 
 const SQ_LEADERBOARD_TOP_CACHE_KEY = "sq-leaderboard-top";
 
-/** How many times & in what seasons each user placed in the SendouQ leaderboard top 10 and top 100. */
+/** Per user: seasons placed in the SendouQ leaderboard top 10 and top 100. */
 export function cachedUserSQLeaderboardTopData() {
 	return cachified({
 		key: SQ_LEADERBOARD_TOP_CACHE_KEY,
diff --git a/app/features/user-page/custom-theme-json.server.test.ts b/app/features/user-page/custom-theme-json.server.test.ts
index 71b62e6dc..bb1c7df91 100644
--- a/app/features/user-page/custom-theme-json.server.test.ts
+++ b/app/features/user-page/custom-theme-json.server.test.ts
@@ -29,8 +29,7 @@ describe("supporter custom theme on the profile layout", () => {
 			String(user.id),
 		);
 
-		// `root.tsx` spreads `Object.entries(customTheme)` into the page's CSS
-		// variables, so a raw string here renders as garbage instead of the theme
+		// `root.tsx` spreads the object into CSS variables, so a raw string renders as garbage
 		expect(layoutData?.customTheme?.["--_acc-h"]).toBe(
 			CUSTOM_THEME["--_acc-h"],
 		);
diff --git a/app/features/user-page/in-game-name.ts b/app/features/user-page/in-game-name.ts
index 209474fa2..cf4d5fbfa 100644
--- a/app/features/user-page/in-game-name.ts
+++ b/app/features/user-page/in-game-name.ts
@@ -9,9 +9,7 @@ export const IN_GAME_NAME = {
 export const IN_GAME_NAME_MAX_LENGTH =
 	IN_GAME_NAME.NAME_MAX_LENGTH + 1 + IN_GAME_NAME.DISCRIMINATOR_MAX_LENGTH;
 
-/**
- * @see {@link https://github.com/kjhf/NintendoSwitchKeyboard}
- */
+/** @see {@link https://github.com/kjhf/NintendoSwitchKeyboard} */
 export const IN_GAME_NAME_CHARACTER_CATEGORIES = [
 	{
 		id: "symbols",
@@ -72,15 +70,11 @@ const ALLOWED_CHARACTERS = new Set<string>([
 	...PICKER_CHARACTERS,
 ]);
 
-/**
- * Letters of every script a Nintendo Switch keyboard can produce. Notably this
- * includes kanji/hanzi and hangul, which are too numerous to enumerate in the
- * character picker but are perfectly valid to paste in.
- */
+/** Every script a Switch keyboard can produce, incl. kanji/hanzi and hangul which the picker can't enumerate. */
 const ALLOWED_SCRIPTS_REGEXP =
 	/^[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Han}\p{Script=Hangul}]$/u;
 
-/** Punctuation & symbol code point ranges not covered by any of the scripts above. */
+/** Punctuation & symbols not covered by the scripts above. */
 const ALLOWED_CODE_POINT_RANGES = [
 	[0x3000, 0x303f], // CJK symbols and punctuation
 	[0x3099, 0x309c], // Kana voiced sound marks
@@ -94,17 +88,17 @@ const IN_GAME_NAME_REGEXP = new RegExp(
 	"u",
 );
 
-/** Length of a string counted in code points (so astral characters count as one). */
+/** Length in code points, so astral characters count as one. */
 export function inGameNameLength(value: string): number {
 	return [...value].length;
 }
 
-/** Normalizes the in-game name and drops every character the game does not allow. */
+/** Normalizes and drops every character the game does not allow. */
 export function sanitizeInGameName(value: string): string {
 	return [...normalizeInGameName(value)].filter(characterIsAllowed).join("");
 }
 
-/** Unicode normalization applied to in-game names before they are validated or stored. */
+/** Unicode normalization applied before validating or storing. */
 export function normalizeInGameName(value: string): string {
 	return value.normalize("NFC");
 }
diff --git a/app/features/user-page/loaders/u.$identifier.seasons.summary-graphic.server.ts b/app/features/user-page/loaders/u.$identifier.seasons.summary-graphic.server.ts
index 2b781bbc3..6dbe6b3b6 100644
--- a/app/features/user-page/loaders/u.$identifier.seasons.summary-graphic.server.ts
+++ b/app/features/user-page/loaders/u.$identifier.seasons.summary-graphic.server.ts
@@ -210,8 +210,7 @@ async function findTeamEntry({
 	if (rankedEntry)
 		return { entry: rankedEntry, rank: rankedEntry.placementRank ?? undefined };
 
-	// rosters that only show up on the "all entries" leaderboard have no
-	// placement comparable to the one shown on the main team leaderboard
+	// "all entries" only rosters have no placement comparable to the main team leaderboard's
 	const unrankedEntry = (
 		await LeaderboardRepository.findTeamLeaderboardBySeason({
 			season,
diff --git a/app/features/user-page/routes/u.$identifier.builds.tsx b/app/features/user-page/routes/u.$identifier.builds.tsx
index 589686f0c..03a2da8c5 100644
--- a/app/features/user-page/routes/u.$identifier.builds.tsx
+++ b/app/features/user-page/routes/u.$identifier.builds.tsx
@@ -58,8 +58,7 @@ export default function UserBuildsPage() {
 		"sorting",
 	);
 	const changingSorting = sorting && isOwnPage;
-	// lives here so closing the dialog mid-submit doesn't unmount the fetcher,
-	// which would discard the action's redirect and skip revalidation
+	// here so closing the dialog mid-submit doesn't unmount the fetcher and drop the redirect
 	const sortingFetcher = useFetcher();
 
 	const closeSortingDialog = () => setChangingSorting(false);
diff --git a/app/features/user-page/routes/u.$identifier.seasons.stats.tsx b/app/features/user-page/routes/u.$identifier.seasons.stats.tsx
index c3b0f4f2a..6badeddc3 100644
--- a/app/features/user-page/routes/u.$identifier.seasons.stats.tsx
+++ b/app/features/user-page/routes/u.$identifier.seasons.stats.tsx
@@ -277,8 +277,7 @@ function Players({
 	return (
 		<div className="stack md horizontal justify-center flex-wrap">
 			{players.map((player) => {
-				// a player only met on maps of a set someone else's team was fielded
-				// for has no set record to show a win rate of
+				// a player only met on maps of another team's set has no set record
 				const setWinRate = winPercentage(player.setWins, player.setLosses);
 				const mapWinRate = winPercentage(player.mapWins, player.mapLosses);
 				return (
diff --git a/app/features/user-page/user-page-constants.ts b/app/features/user-page/user-page-constants.ts
index 4d4c6789f..87c65d810 100644
--- a/app/features/user-page/user-page-constants.ts
+++ b/app/features/user-page/user-page-constants.ts
@@ -66,13 +66,7 @@ export const OBJECT_PRONOUNS = [
 
 export type ObjectPronoun = (typeof OBJECT_PRONOUNS)[number];
 
-/**
- * An array of ISO 3166-1 alpha-2 country codes.
- * Each entry is a two-letter uppercase string representing a country or territory. Sorted alphabetically.
- *
- * @see {@link https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2}
- * @see {@link https://github.com/annexare/Countries}
- */
+/** ISO 3166-1 alpha-2 codes, sorted. @see {@link https://github.com/annexare/Countries} */
 export const COUNTRY_CODES = [
 	"AD",
 	"AE",
diff --git a/app/features/user-report/UserReportRepository.server.ts b/app/features/user-report/UserReportRepository.server.ts
index 20a24c719..ea964fe37 100644
--- a/app/features/user-report/UserReportRepository.server.ts
+++ b/app/features/user-report/UserReportRepository.server.ts
@@ -3,11 +3,7 @@ import { db } from "~/db/sql";
 import type { TablesInsertable } from "~/db/tables";
 import { databaseTimestampNow, dateToDatabaseTimestamp } from "~/utils/dates";
 
-/**
- * Inserts a report or, when the (reporter, reported) pair already has one, overwrites
- * its category and description bumping `createdAt`. Returns whether an existing report
- * was updated instead of a new one created.
- */
+/** Inserts, or overwrites the pair's existing report (bumping `createdAt`). Returns whether it was an update. */
 export function upsert(
 	args: Omit<TablesInsertable["UserReport"], "createdAt">,
 ) {
@@ -37,7 +33,7 @@ export function upsert(
 	});
 }
 
-/** Returns how many reports have been made against the given user in the last month and in the last year. */
+/** Reports against the user in the last month and in the last year. */
 export async function countRecentByReportedUserId(reportedUserId: number) {
 	const monthAgo = dateToDatabaseTimestamp(subMonths(new Date(), 1));
 	const yearAgo = dateToDatabaseTimestamp(subYears(new Date(), 1));
@@ -58,7 +54,7 @@ export async function countRecentByReportedUserId(reportedUserId: number) {
 	return { lastMonth: row.lastMonth, lastYear: row.lastYear };
 }
 
-/** Returns all reports made against the given user, newest first, with the reporter's identifying info. */
+/** Reports against the user, newest first, with reporter info. */
 export function findAllByReportedUserId(reportedUserId: number) {
 	return db
 		.selectFrom("UserReport")
diff --git a/app/features/user-report/components/ReportUserDialog.tsx b/app/features/user-report/components/ReportUserDialog.tsx
index 56d6b247c..fc653048b 100644
--- a/app/features/user-report/components/ReportUserDialog.tsx
+++ b/app/features/user-report/components/ReportUserDialog.tsx
@@ -17,11 +17,7 @@ type ReportFormFieldComponent = FormRenderProps<
 	typeof reportUserSchema.entries
 >["FormField"];
 
-/**
- * Modal for reporting a user to the staff, posting to the `/user-report/:id` resource
- * route. Re-reporting the same user overwrites the previous report. Rendered wherever
- * a `UserCard` lives.
- */
+/** Posts to the `/user-report/:id` resource route; re-reporting the same user overwrites the previous report. */
 export function ReportUserDialog({
 	userId,
 	username,
@@ -65,10 +61,7 @@ export function ReportUserDialog({
 	);
 }
 
-/**
- * The report itself, replaced by instructions when the selected category is one the
- * staff can't act on.
- */
+/** Replaced by instructions when the selected category is one the staff can't act on. */
 function ReportFields({ FormField }: { FormField: ReportFormFieldComponent }) {
 	const { t } = useTranslation(["user"]);
 	const category = useFormValue("category");
@@ -105,10 +98,7 @@ function InappropriateNicknameInstructions() {
 	);
 }
 
-/**
- * Reads the SendouQ match id from the current route so a report opened from a match page
- * prefills its "Match ID" field. Returns `undefined` on any other page.
- */
+/** SendouQ match id from the current route to prefill "Match ID"; `undefined` elsewhere. */
 function useSendouQMatchIdFromRoute() {
 	const matches = useMatches();
 
diff --git a/app/features/user-report/components/ReportsBarChart.tsx b/app/features/user-report/components/ReportsBarChart.tsx
index 70f89534e..0423e5ed1 100644
--- a/app/features/user-report/components/ReportsBarChart.tsx
+++ b/app/features/user-report/components/ReportsBarChart.tsx
@@ -13,10 +13,7 @@ import styles from "./ReportsBarChart.module.css";
 
 ChartJS.register(CategoryScale, LinearScale, BarElement, Tooltip);
 
-/**
- * Bar graph of reports made against a user, one bar per calendar month.
- * Theme colors are read from CSS variables like `app/components/Chart.tsx` does.
- */
+/** One bar per calendar month. Theme colors come from CSS variables like `app/components/Chart.tsx`. */
 export function ReportsBarChart({
 	monthlyCounts,
 }: {
diff --git a/app/features/user-report/core/discord-webhook.server.ts b/app/features/user-report/core/discord-webhook.server.ts
index accbab0ab..158f2ac8c 100644
--- a/app/features/user-report/core/discord-webhook.server.ts
+++ b/app/features/user-report/core/discord-webhook.server.ts
@@ -9,10 +9,7 @@ import {
 import { SENDOU_INK_BASE_URL, sendouQMatchPage } from "~/utils/urls";
 import { USER_REPORT_CATEGORY_LABELS } from "../user-report-constants";
 
-/**
- * Posts a rich embed about a new/updated user report to the mod channel Discord webhook.
- * Fire-and-forget (see `sendModDiscordWebhook`).
- */
+/** Fire-and-forget embed to the mod channel webhook. */
 export function sendUserReportWebhook(args: {
 	reportedUser: WebhookUser;
 	reporter: WebhookUser;
diff --git a/app/features/user-report/user-report-constants.ts b/app/features/user-report/user-report-constants.ts
index 160c8179d..7c4b45cf6 100644
--- a/app/features/user-report/user-report-constants.ts
+++ b/app/features/user-report/user-report-constants.ts
@@ -3,11 +3,7 @@ export const USER_REPORT = {
 	MATCH_ID_MAX_LENGTH: 10,
 };
 
-/**
- * Category offered in the report dialog but never stored: nicknames are not set on
- * sendou.ink, so picking it points the user to Splatoon 3 / Discord instead of
- * letting them send a report.
- */
+/** Offered in the dialog but never stored: picking it points the user to Splatoon 3 / Discord instead. */
 export const INAPPROPRIATE_NICKNAME_CATEGORY = "INAPPROPRIATE_NICKNAME";
 
 export const USER_REPORT_CATEGORIES = [
@@ -20,7 +16,7 @@ export const USER_REPORT_CATEGORIES = [
 
 export type UserReportCategory = (typeof USER_REPORT_CATEGORIES)[number];
 
-/** English display names, shown on the staff-only admin tab and in the Discord webhook embed. */
+/** English names for the staff-only admin tab and the Discord webhook embed. */
 export const USER_REPORT_CATEGORY_LABELS: Record<UserReportCategory, string> = {
 	INAPPROPRIATE_CONTENT: "Inappropriate content",
 	ALTING: "Alting",
diff --git a/app/features/user-report/user-report-schemas.server.ts b/app/features/user-report/user-report-schemas.server.ts
index c61990af1..25859ea5a 100644
--- a/app/features/user-report/user-report-schemas.server.ts
+++ b/app/features/user-report/user-report-schemas.server.ts
@@ -7,8 +7,7 @@ export const reportUserSchemaServer = v.objectAsync({
 	...reportUserSchema.entries,
 	// the dialog also offers a category that only shows guidance, never a report
 	category: v.picklist(USER_REPORT_CATEGORIES),
-	// cast to the concrete value type: the field's nullability makes its inferred
-	// type a union the async pipe can't resolve
+	// cast: the field's nullability makes its inferred type a union the async pipe can't resolve
 	matchId: v.pipeAsync(
 		reportUserSchema.entries.matchId as v.GenericSchema<unknown, string | null>,
 		v.checkAsync(async (matchId) => {
diff --git a/app/features/vods/VodRepository.server.ts b/app/features/vods/VodRepository.server.ts
index cad2cee69..acb05a5ef 100644
--- a/app/features/vods/VodRepository.server.ts
+++ b/app/features/vods/VodRepository.server.ts
@@ -322,8 +322,7 @@ async function save(
 			.returning("VideoMatch.id")
 			.execute();
 
-		// SQLite assigns ids in insertion order, but RETURNING makes no ordering
-		// promise, so sort to line the new ids back up with args.matches
+		// RETURNING makes no ordering promise, so sort to line the ids up with args.matches
 		const matchIds = insertedMatches
 			.map((match) => match.id)
 			.sort((a, b) => a - b);
diff --git a/app/features/vods/loaders/vods.new.server.ts b/app/features/vods/loaders/vods.new.server.ts
index 688eb5e19..b9e975173 100644
--- a/app/features/vods/loaders/vods.new.server.ts
+++ b/app/features/vods/loaders/vods.new.server.ts
@@ -40,11 +40,8 @@ export interface VodPrefill {
 }
 
 /**
- * Maps the `ingest` search param the scanner VoD tab's "Add VoD" button
- * fills (an ingestVodPrefillSchema payload, see
- * ~/features/scanner-ingest/scanner-ingest-vod-schemas) into form-prefill data. Detection
- * misses stay null for the user to fill; a malformed param has already
- * decoded to null.
+ * `ingest` param (an ingestVodPrefillSchema payload from the scanner VoD tab's "Add VoD" button)
+ * to form-prefill data. Detection misses stay null; a malformed param has already decoded to null.
  */
 function vodPrefillFromIngestParam(
 	ingest: IngestVodPrefill | null,
diff --git a/app/features/vods/routes/vods.new.module.css b/app/features/vods/routes/vods.new.module.css
index d41559c11..42dc08238 100644
--- a/app/features/vods/routes/vods.new.module.css
+++ b/app/features/vods/routes/vods.new.module.css
@@ -6,12 +6,9 @@
 	margin-block: var(--s-2);
 }
 
-/* When the form's left margin can fit the embed (measured in JS so it accounts
-   for the side nav being collapsed and the chat sidebar being open), float it
-   just left of the form. The rail is anchored to the form's own left edge, so
-   the side nav offset cancels out and it never overlaps the nav. Its width is
-   set inline by the same JS. The rail spans the full form height while the
-   embed sticks within it, so it stays in view while scrolling the long form. */
+/* floated left of the form when its left margin fits the embed (measured and width set by JS).
+   Anchored to the form's own left edge so it never overlaps the side nav; spans the full form
+   height while the embed sticks within it, staying in view while scrolling the long form. */
 .embedRail.floating {
 	position: absolute;
 	top: 0;
diff --git a/app/features/vods/routes/vods.new.tsx b/app/features/vods/routes/vods.new.tsx
index 5710f02f9..96e69395f 100644
--- a/app/features/vods/routes/vods.new.tsx
+++ b/app/features/vods/routes/vods.new.tsx
@@ -140,12 +140,9 @@ function vodToEditToFormValues(vodToEdit: VodToEdit) {
 type VodPrefill = NonNullable<Awaited<ReturnType<typeof loader>>["vodPrefill"]>;
 
 /**
- * Prefill from the emberz VoD parser's `ingest` search param (see the loader):
- * detected matches with anything the detectors missed left at the blank form's
- * defaults for the user to fill. CAST weapons are the alpha team's four slots
- * then bravo's; unread slots are dropped so the remaining empty (required)
- * selects surface them. A non-CAST VoD instead takes the POV player's weapon,
- * which the scan only knows when a scoreboard identified their seat.
+ * Prefill from the emberz VoD parser's `ingest` param; what the detectors missed stays at the blank
+ * defaults. CAST weapons are alpha's four slots then bravo's, unread slots dropped so the empty
+ * required selects surface them. A non-CAST VoD takes the POV player's weapon when their seat is known.
  */
 function vodPrefillToFormValues(prefill: VodPrefill) {
 	const teamSize = 4;
@@ -209,11 +206,8 @@ const EMBED_RAIL_GAP = 24; // mirrors var(--s-6)
 const EMBED_FLOAT_WIDTHS = [400, 320] as const;
 
 /**
- * Returns the width to float the embed at when the form's left margin can fit
- * it (widest that fits), or `null` to leave it in flow above the fields.
- * Measures the form's actual left margin so it accounts for the side nav being
- * collapsed and the chat sidebar being open, neither of which a media query can
- * see.
+ * Widest embed width the form's left margin fits, or `null` to leave it in flow. Measures the
+ * actual margin since a media query can't see the collapsed side nav or open chat sidebar.
  */
 function useFloatingEmbedWidth(): number | null {
 	const [leftMargin, setLeftMargin] = useState(0);
@@ -296,8 +290,7 @@ function VodFormFields({
 function TeamSizeField({ FormField }: { FormField: VodFormFieldComponent }) {
 	const context = useOptionalFormFieldContext();
 
-	// The weapon count per match is tied to the team size, so any already picked
-	// weapons would no longer fit the new size.
+	// the weapon count per match is tied to the team size
 	const clearMatchWeapons = () => {
 		context?.setValueFromPrev("matches", (prev) =>
 			((prev ?? []) as Array<Record<string, unknown>>).map((match) => ({
diff --git a/app/features/vods/vods-constants.ts b/app/features/vods/vods-constants.ts
index 0461aa6c6..954f8710e 100644
--- a/app/features/vods/vods-constants.ts
+++ b/app/features/vods/vods-constants.ts
@@ -1,4 +1,4 @@
-/** The `type` column of `UnvalidatedVideo` and the `Video` view is typed off this. */
+/** Types `UnvalidatedVideo.type`. */
 export const videoMatchTypes = [
 	"TOURNAMENT",
 	"CAST",
diff --git a/app/features/vods/vods-utils.test.ts b/app/features/vods/vods-utils.test.ts
index b19f87aec..fcb899bd8 100644
--- a/app/features/vods/vods-utils.test.ts
+++ b/app/features/vods/vods-utils.test.ts
@@ -223,10 +223,8 @@ describe("generateYoutubeTimestamps", () => {
 });
 
 describe("vodToVideoBeingAdded", () => {
-	// youtubePublishedAt is stored as noon UTC of the chosen day (see
-	// dayMonthYearToDatabaseTimestamp), so reading the day/month/year back out
-	// must also use UTC. Force a timezone east of UTC+12 where local time has
-	// already rolled over to the next day, making the bug deterministic.
+	// youtubePublishedAt is noon UTC of the chosen day, so it must be read back in UTC; a timezone
+	// east of UTC+12 has already rolled over to the next day, making the bug deterministic
 	const originalTimezone = process.env.TZ;
 	beforeAll(() => {
 		process.env.TZ = "Pacific/Kiritimati";
diff --git a/app/form/FormField.tsx b/app/form/FormField.tsx
index 437b96148..857a941ef 100644
--- a/app/form/FormField.tsx
+++ b/app/form/FormField.tsx
@@ -48,8 +48,7 @@ import {
 	validateField,
 } from "./utils";
 
-// lazy loaded so the trophies field's WebGL renderer stays out of the eager
-// bundle of every page rendering a form
+// keeps the trophies field's WebGL renderer out of every form-rendering page's eager bundle
 const TrophiesFormField = React.lazy(() =>
 	import("./fields/TrophiesFormField").then((module) => ({
 		default: module.TrophiesFormField,
@@ -73,14 +72,10 @@ interface FormFieldProps {
 	children?:
 		| ((props: CustomFieldRenderProps) => React.ReactNode)
 		| ((props: ArrayItemRenderContext) => React.ReactNode);
-	/** Field-specific options */
 	options?: unknown;
 	/** For `array` fields: hide the remove button for items where this returns false. */
 	canRemoveItem?: (itemValue: unknown, index: number) => boolean;
-	/**
-	 * Runs after the new value has been stored. For side effects on other fields;
-	 * to change what gets stored use the field schema's own options instead.
-	 */
+	/** Runs after the value is stored, for side effects on other fields; to change what is stored use the schema's options. */
 	onValueChange?: (newValue: unknown) => void;
 }
 
@@ -164,10 +159,8 @@ export function FormField({
 		context.setClientError(name, validationError);
 	};
 
-	// After the first submit, changes revalidate the whole form — except array
-	// appends, which stay silent so a freshly added empty item doesn't error
-	// immediately. Blur is the moment the user leaves such an item, so
-	// revalidating here surfaces its error without waiting for the next submit.
+	// after the first submit array appends don't revalidate (a fresh empty item shouldn't error at once),
+	// so blur is where such an item's error surfaces
 	const handleBlur = (latestValue?: unknown) => {
 		if (!context) return;
 		if (hasSubmitted) {
@@ -177,8 +170,7 @@ export function FormField({
 		runValidation(latestValue ?? value);
 	};
 
-	// Read through a ref so an inline `onValueChange` does not destabilize
-	// `handleChange`, which fields rely on to skip re-rendering.
+	// a ref so an inline `onValueChange` doesn't destabilize `handleChange`, which fields rely on to skip re-renders
 	const latestOnValueChange = React.useRef(onValueChange);
 	latestOnValueChange.current = onValueChange;
 
@@ -620,12 +612,8 @@ interface ArrayItemCustomRenderProps {
 }
 
 /**
- * One custom-rendered array item, memoized so that a form edit re-renders only
- * the item whose slice of the array changed — the array field itself re-renders
- * on every write to the array. For this to hold, anything the item render reads
- * from the form outside its own item must be subscribed to via `useFormValue`.
- * The callbacks read the current array through the store instead of closing
- * over it so a skipped re-render can never make them act on stale values.
+ * Memoized so an edit re-renders only the item whose slice changed. Anything the render reads outside its
+ * own item must go through `useFormValue`; callbacks read the array via the store so a skipped render never acts on stale values.
  */
 const ArrayItemCustomRender = React.memo(function ArrayItemCustomRender({
 	arrayName,
diff --git a/app/form/SendouForm.browser.test.tsx b/app/form/SendouForm.browser.test.tsx
index e2eb079b3..837f19fc2 100644
--- a/app/form/SendouForm.browser.test.tsx
+++ b/app/form/SendouForm.browser.test.tsx
@@ -906,8 +906,7 @@ describe("SendouForm", () => {
 		test("clicking add creates new item", async () => {
 			const screen = await renderForm(TEXT_FIELD_ARRAY);
 
-			// Adding from the single empty starter row materializes it and appends a
-			// new one, so one click goes from 1 visible row to 2.
+			// adding from the single empty starter row materializes it and appends a new one
 			await screen.getByRole("button", { name: "Add" }).click();
 			expect(
 				screen.container.querySelectorAll('input[type="text"]').length,
@@ -981,8 +980,7 @@ describe("SendouForm", () => {
 
 			await expect.element(screen.getByText("#1")).toBeVisible();
 
-			// The remove button is rendered but hidden (so the header keeps a stable
-			// height) since a single starter row can't be removed.
+			// rendered but hidden so the header keeps a stable height
 			const removeButtons = screen.container.querySelectorAll(
 				'button[aria-label="Remove item"]',
 			);
@@ -1065,8 +1063,7 @@ describe("SendouForm", () => {
 		});
 
 		test("removing an added fieldset row returns to a single non-removable row", async () => {
-			// Mirrors the staff form: a select field gives the row a non-empty default
-			// (role), so a freshly added row isn't "blank" yet is still pristine.
+			// like the staff form: the select gives a fresh row a non-empty default yet it is still pristine
 			const schema = v.object({
 				staff: array({
 					label: "labels.members",
@@ -1105,8 +1102,7 @@ describe("SendouForm", () => {
 				expect(button.classList.contains("invisible")).toBe(false);
 			}
 
-			// Removing the second row collapses back to the single starter row with a
-			// hidden remove button - not a lingering blank row that still shows one.
+			// back to the single starter row, not a lingering blank row with a visible remove button
 			await userEvent.click(removeButtonEls()[1]);
 
 			await expect.element(screen.getByText("#1")).toBeVisible();
@@ -1127,10 +1123,7 @@ describe("SendouForm", () => {
 		});
 
 		test("editing a starter row commits its select default on submit", async () => {
-			// Regression: editing one field of the empty-array starter row must seed the
-			// item's other fieldset defaults (e.g. a required select's first option),
-			// rather than leaving them only displayed as a fallback and failing
-			// validation on submit.
+			// regression: editing one field of the starter row must seed its other fieldset defaults
 			const onApply = vi.fn();
 			const schema = v.object({
 				staff: array({
@@ -1409,8 +1402,7 @@ describe("SendouForm", () => {
 			await screen.getByRole("button", { name: "Add" }).click();
 			await screen.getByRole("button", { name: "Remove member 1" }).click();
 
-			// A stale remove would have filtered the pre-add two-item array and
-			// dropped the freshly added row along with Alice.
+			// a stale remove would filter the pre-add array, dropping the fresh row along with Alice
 			expect(memberTestIds(screen).length).toBe(2);
 			await expect
 				.element(screen.getByTestId("member-0"))
@@ -1430,8 +1422,7 @@ describe("SendouForm", () => {
 				onApply,
 			});
 
-			// Editing item 1 does not re-render the memoized item 3, so its remove
-			// callback must read the current array instead of a stale closure.
+			// editing item 1 doesn't re-render memoized item 3, whose remove must not read a stale closure
 			await screen.getByRole("button", { name: "Edit member 1" }).click();
 			await screen.getByRole("button", { name: "Remove member 3" }).click();
 
@@ -1576,16 +1567,14 @@ describe("SendouForm", () => {
 
 			const screen = await render(<RouterProvider router={router} />);
 
-			// Verify initial state - 5 members rendered
 			const removeButtons = screen.container.querySelectorAll(
 				'button[aria-label="Remove item"]',
 			);
 			expect(removeButtons.length).toBe(5);
 
-			// Remove the 3rd member (index 2, userId: 30)
+			// the 3rd member, userId 30
 			await userEvent.click(removeButtons[2]);
 
-			// Wait for React effects to settle
 			await new Promise((resolve) => setTimeout(resolve, 200));
 
 			const members = latestValues.members as Array<{
diff --git a/app/form/SendouForm.tsx b/app/form/SendouForm.tsx
index 4e6b86be5..ee00b30d1 100644
--- a/app/form/SendouForm.tsx
+++ b/app/form/SendouForm.tsx
@@ -51,12 +51,7 @@ export interface FormContextValue<T extends v.ObjectEntries = v.ObjectEntries> {
 	fetcherState: "idle" | "loading" | "submitting";
 }
 
-/**
- * Holds the frequently-changing form state (values and client errors) outside
- * React state so that a change to one field does not re-render the whole form.
- * Fields subscribe to their own slice via `useSyncExternalStore` and only
- * re-render when that slice changes.
- */
+/** Values and client errors live outside React state; fields subscribe to their own slice via `useSyncExternalStore`. */
 interface FormStore {
 	values: Record<string, unknown>;
 	clientErrors: Partial<Record<string, string>>;
@@ -99,56 +94,29 @@ type BaseFormProps<T extends v.ObjectEntries> = {
 	submitButtonVariant?: SendouButtonProps["variant"];
 	submitButtonSize?: SendouButtonProps["size"];
 	revalidateRoot?: boolean;
-	/**
-	 * Replaces the default form layout classes entirely (it does not merge with
-	 * them), so `fullWidth` has no effect when this is set.
-	 */
+	/** Replaces the default layout classes entirely, so `fullWidth` has no effect when set. */
 	className?: string;
-	/**
-	 * When true, opts out of the default centered, max-width layout so the form
-	 * expands to fill its parent container. Use when embedding a form inside a
-	 * layout that already controls width/alignment.
-	 */
+	/** Opts out of the default centered max-width layout to fill the parent. */
 	fullWidth?: boolean;
-	/**
-	 * When true, renders the form for viewing only: every field is disabled and
-	 * the submit button is hidden.
-	 */
+	/** Every field disabled and the submit button hidden. */
 	readOnly?: boolean;
 	secondarySubmit?: React.ReactNode;
-	/**
-	 * Hides the submit button while the current values match, for forms with a
-	 * branch that has nothing to submit (e.g. a choice that only shows guidance).
-	 */
+	/** Hides the submit button while the values match, for branches with nothing to submit. */
 	hideSubmitButtonWhen?: (
 		values: Partial<v.InferInput<v.ObjectSchema<T, undefined>>>,
 	) => boolean;
-	/**
-	 * Called once after a server submission completes successfully (the action
-	 * returned without field errors). Useful for collapsing an inline edit form
-	 * back to a read-only view.
-	 */
+	/** Called once after the action returns without field errors. */
 	onSuccess?: () => void;
-	/**
-	 * Hides the built-in submit button, for forms that render their own submit
-	 * control inside `children` (e.g. the chat composer's send button).
-	 */
+	/** For forms that render their own submit control inside `children`. */
 	hideSubmitButton?: boolean;
-	/**
-	 * When false, navigating away with unsaved edits is not blocked. For forms
-	 * whose value is ephemeral by nature, like a chat message draft.
-	 */
+	/** When false, navigating away with unsaved edits is not blocked (e.g. a chat draft). */
 	guardUnsavedChanges?: boolean;
 };
 
 /**
- * How submitting works:
- * - `"submit"` (default): the user submits via the submit button. Values go to
- *   the server, or to `onApply` when provided.
- * - `"autoSubmit"`: no submit button; every change that passes validation is
- *   sent to the server.
- * - `"client"`: no submit button and no `<form>` element; every change is
- *   passed to `onApply` and field errors are computed already on mount.
+ * `"submit"` (default): submit button sends values to the server, or to `onApply` when provided.
+ * `"autoSubmit"`: no button; every valid change is sent to the server.
+ * `"client"`: no button or `<form>`; every change goes to `onApply` and errors are computed on mount.
  */
 type FormModeProps<T extends v.ObjectEntries> =
 	| {
@@ -188,7 +156,7 @@ interface LatestFormProps {
 export function SendouForm<T extends v.ObjectEntries>(
 	props: SendouFormProps<T>,
 ) {
-	// Remounting on URL change resets all form state (handles edit → new transitions)
+	// remount on URL change resets form state (edit → new transitions)
 	const location = useLocation();
 
 	return (
@@ -417,10 +385,7 @@ function SubmitRow({
 	);
 }
 
-/**
- * Split out of {@link SubmitRow} so that only forms that opt in subscribe to the
- * form's values (and re-render on every edit).
- */
+/** Split out of {@link SubmitRow} so only forms that opt in subscribe to the values (re-rendering on every edit). */
 function ConditionalSubmitRow({
 	hideWhen,
 	children,
@@ -489,11 +454,8 @@ interface FormActionDeps {
 }
 
 /**
- * Creates the form's action functions once per form instance. They read the
- * current values/props through the store and the `latest` ref, so their
- * identities stay stable across renders — this keeps the form context
- * referentially stable, which is what lets fields skip re-rendering when an
- * unrelated field changes.
+ * Created once per form instance, reading current values/props through the store and `latest` ref,
+ * so the form context stays referentially stable and fields skip re-rendering on unrelated changes.
  */
 function createFormActions({
 	store,
@@ -561,11 +523,9 @@ function createFormActions({
 		store.setClientErrors({ ...store.clientErrors, [name]: error });
 	};
 
-	// Server errors are keyed by positional path (e.g. `members[2].userId`). When
-	// the user edits a field, the server's verdict for that field — and for any
-	// nested descendants when an array/object changes — is stale, so drop it.
-	// Without this, removing an array item and re-adding one at the same index
-	// would resurrect the previous item's server error.
+	// server errors are keyed by positional path (e.g. `members[2].userId`); an edit makes the verdict for
+	// that field and its descendants stale, otherwise re-adding an array item at the same index would
+	// resurrect the previous item's error
 	const clearServerError = (name: string) => {
 		setVisibleServerErrors((prev) => {
 			const isStale = (key: string) =>
@@ -614,9 +574,8 @@ function createFormActions({
 	const submitToServer = (valuesToSubmit: Record<string, unknown>) => {
 		if (!validateAndPrepare()) return;
 
-		// Cleared before `onApply` because it may navigate synchronously (e.g.
-		// calendar filters set search params) — the blocker would otherwise still
-		// see the form as dirty and block that navigation.
+		// before `onApply` since it may navigate synchronously (e.g. calendar filters) and the blocker
+		// would still see the form as dirty
 		store.setDirty(false);
 		latest.current.onApply?.(store.values);
 
@@ -647,9 +606,7 @@ function createFormActions({
 
 		const { onApply } = latest.current;
 		if (onApply) {
-			// Cleared before `onApply` because it may navigate synchronously (e.g.
-			// calendar filters set search params) — the blocker would otherwise
-			// still see the form as dirty and block that navigation.
+			// see the same note in autoSubmit above
 			store.setDirty(false);
 			onApply(store.values);
 		} else {
@@ -670,11 +627,8 @@ function createFormActions({
 }
 
 /**
- * Derives all client errors from a single full-schema parse. Each issue is
- * attributed both to its top-level field (single-control composites like
- * dual-select or weapon-pool read their error keyed by their own name even
- * when the issue points inside the value) and to its full nested path
- * (array/fieldset children render their own error slots).
+ * One full-schema parse; each issue is keyed both by its top-level field (single-control composites
+ * like weapon-pool read errors by their own name) and its full nested path (array/fieldset children).
  */
 function computeFieldErrors(
 	schema: FormObjectSchema,
@@ -733,8 +687,7 @@ function buildInitialValues<T extends v.ObjectEntries>(
 		const defaultValue = defaultValues?.[key as keyof typeof defaultValues];
 		if (defaultValue !== undefined) {
 			if (formField?.type === "array" && Array.isArray(defaultValue)) {
-				// only object-array (fieldset) items get a stable `_key`; spreading would
-				// collapse non-plain objects like `Date` into `{}`, so leave those intact
+				// only fieldset items get a `_key`; spreading would collapse e.g. `Date` into `{}`
 				result[key] = (defaultValue as unknown[]).map((item) =>
 					isPlainObject(item)
 						? {
@@ -798,12 +751,7 @@ export function useOptionalFormFieldContext() {
 	return React.useContext(FormContext);
 }
 
-/**
- * Subscribes to a single form value by (possibly nested) path, e.g. `"type"`
- * or `"matches[2].mode"`. Unlike `useFormFieldContext` this re-renders only
- * when that value changes, so prefer it for reading form state in components
- * that should not re-render on every form edit.
- */
+/** Subscribes to one value by path (e.g. `"matches[2].mode"`), re-rendering only when it changes, unlike `useFormFieldContext`. */
 export function useFormValue(name: string): unknown {
 	const context = React.useContext(FormContext);
 	const store = context?.store ?? EMPTY_FORM_STORE;
@@ -812,11 +760,7 @@ export function useFormValue(name: string): unknown {
 	return React.useSyncExternalStore(store.subscribe, getValue, getValue);
 }
 
-/**
- * "First" error means first in DOM order, not first in error-map insertion
- * order — validation collects errors in schema order which does not have to
- * match the rendered field order.
- */
+/** DOM order, not error-map order: schema order need not match rendered order. */
 function findFirstErrorElementInDomOrder(errorFieldNames: string[]) {
 	const errorElements = errorFieldNames.flatMap((name) => {
 		const element = document.getElementById(errorMessageId(name));
@@ -833,12 +777,7 @@ function findFirstErrorElementInDomOrder(errorFieldNames: string[]) {
 	return errorElements.at(0);
 }
 
-/**
- * Moves focus to the failing field so keyboard and screen reader users are
- * taken to the problem, not just scrolled past it. Prefers the control that
- * references the error via `aria-errormessage`, then any focusable control in
- * the same wrapper, and as a last resort the error message element itself.
- */
+/** Focuses the control referencing the error via `aria-errormessage`, else any focusable in the wrapper, else the message itself. */
 function focusAndScrollToError({
 	name,
 	element,
diff --git a/app/form/UnsavedChangesGuard.tsx b/app/form/UnsavedChangesGuard.tsx
index d923a95b3..11ec4678f 100644
--- a/app/form/UnsavedChangesGuard.tsx
+++ b/app/form/UnsavedChangesGuard.tsx
@@ -4,12 +4,7 @@ import { type Location, useBlocker } from "react-router";
 import { SendouButton } from "~/components/elements/Button";
 import { SendouDialog } from "~/components/elements/Dialog";
 
-/**
- * Reports whether the registering component has unsaved changes. For an in-app
- * navigation the blocked locations are passed, so a checker whose state
- * survives same-route navigations can ignore those; a full page unload passes
- * nothing and every dirty checker should warn.
- */
+/** In-app navigations pass the locations so same-route ones can be ignored; a page unload passes nothing. */
 type UnsavedChangesChecker = (navigation?: {
 	currentLocation: Location;
 	nextLocation: Location;
@@ -17,12 +12,7 @@ type UnsavedChangesChecker = (navigation?: {
 
 const dirtyCheckers = new Set<UnsavedChangesChecker>();
 
-/**
- * Confirms navigating away when any mounted form has unsaved changes.
- * Rendered once in the root layout because react-router supports only a
- * single active blocker at a time — individual forms register a checker via
- * `useUnsavedChangesChecker` instead of calling `useBlocker` themselves.
- */
+/** Rendered once in root since react-router allows one active blocker; forms register via `useUnsavedChangesChecker`. */
 export function UnsavedChangesGuard() {
 	const { t } = useTranslation(["common", "forms"]);
 
@@ -70,11 +60,7 @@ export function UnsavedChangesGuard() {
 	);
 }
 
-/**
- * Registers a callback reporting whether the calling form currently has
- * unsaved changes. The ref indirection lets the callback read the latest
- * form state without re-registering on every render.
- */
+/** Registers a dirty checker; the ref lets it read the latest state without re-registering every render. */
 export function useUnsavedChangesChecker(
 	checkerRef: React.RefObject<UnsavedChangesChecker>,
 ) {
diff --git a/app/form/fields.ts b/app/form/fields.ts
index bcfaaa968..c4c60071e 100644
--- a/app/form/fields.ts
+++ b/app/form/fields.ts
@@ -42,10 +42,7 @@ import type {
 
 export const formRegistry = new WeakMap<object, FormField>();
 
-/**
- * Attaches form field metadata to a schema. Clones the schema first so shared
- * schema instances (e.g. `id`, `stageId`) each get their own registry entry.
- */
+/** Clones the schema first so shared instances (e.g. `id`, `stageId`) each get their own registry entry. */
 function register<T extends AnySyncSchema>(schema: T, metadata: FormField): T {
 	const clone = { ...schema };
 	formRegistry.set(clone, metadata);
@@ -63,8 +60,7 @@ export type RequiresDefault<T extends AnySyncSchema> = T & {
 	_requiresDefault: true;
 };
 
-// A builder declares on its signature what `defaultValues` must supply for the
-// field and returns `as never`; parsing itself always starts from `unknown`.
+// a builder's signature declares what `defaultValues` must supply and returns `as never`; parsing starts from `unknown`
 
 type WithTypedTranslationKeys<T> = Omit<
 	T,
@@ -157,8 +153,7 @@ type TextFieldArgs = WithTypedTranslationKeys<
 export function textFieldOptional(
 	args: TextFieldArgs,
 ): v.GenericSchema<string | null, string | null> {
-	// a url field is validated as a plain string, so unlike the other optional
-	// text fields it has no null to fall back to and its key stays required
+	// validated as a plain string, so unlike other optional text fields it has no null fallback and its key stays required
 	if (args.validate === "url") {
 		return registerTextField(
 			v.pipe(v.string(), v.url()),
@@ -292,8 +287,7 @@ export function numberField(
 ): v.GenericSchema<number> {
 	let schema: v.GenericSchema<number> = numberSchema();
 
-	// an empty field coerces to 0, so `min` is also what makes a required number
-	// field reject being left blank
+	// an empty field coerces to 0, so `min` is also what rejects a blank required field
 	if (typeof args.min === "number") {
 		schema = v.pipe(
 			schema,
@@ -395,10 +389,8 @@ export function toggle(
 }
 
 /**
- * Makes a nullable field tolerate a missing key: `v.object` requires every key
- * whose entry schema is not itself optional, and a `preprocess` pipe hides the
- * nullable wrapper behind its own type. The `null` default is fed through the
- * schema, so an absent field parses exactly like an explicitly `null` one.
+ * `v.object` requires every key whose schema isn't optional, and a `preprocess` pipe hides the nullable
+ * wrapper; the `null` default goes through the schema so an absent field parses like an explicit `null`.
  */
 function optionalKey<TSchema extends v.GenericSchema<any, any>>(
 	schema: TSchema,
@@ -406,12 +398,7 @@ function optionalKey<TSchema extends v.GenericSchema<any, any>>(
 	return v.optional(schema, null);
 }
 
-/**
- * Item value type of a field builder, shielded from inference. Without it,
- * calling a builder inline inside `v.object({...})` lets valibot's entry
- * constraint drive `V` from the return position and widen the item literals to
- * `string`.
- */
+/** Without `NoInfer`, a builder inline in `v.object({...})` has `V` driven from the return position, widening literals to `string`. */
 type ItemValue<V extends string> = NoInfer<V>;
 
 function itemsSchema<V extends string>(items: FormFieldItems<V>) {
@@ -526,8 +513,7 @@ export function dualSelectOptional<V extends string>(
 		>
 	>,
 ): v.OptionalSchema<DualSelectSchema<ItemValue<V>>, undefined> {
-	// the `optional` wrapper stays outermost so `v.object` still reads the key as
-	// optional (a pipe reports its first item's type, hiding the wrapper)
+	// `optional` stays outermost so `v.object` reads the key as optional (a pipe would hide the wrapper)
 	const tuple = v.tuple([
 		clearableItemsSchema(args.fields[0].items),
 		clearableItemsSchema(args.fields[1].items),
@@ -665,8 +651,7 @@ export function datetime(args: DateTimeArgs): v.GenericSchema<Date> {
 export function datetimeOptional(
 	args: DateTimeArgs,
 ): v.NullishSchema<v.GenericSchema<Date>, undefined> {
-	// the `nullish` wrapper stays outermost so `v.object` still reads the key as
-	// optional (a pipe reports its first item's type, hiding the wrapper)
+	// `nullish` stays outermost so `v.object` reads the key as optional (a pipe would hide the wrapper)
 	return register(
 		v.nullish(preprocess(date, boundedDate(args, v.date()))),
 		datetimeMetadata(args, { type: "datetime", required: false }),
@@ -768,11 +753,8 @@ export function weaponPool(
 }
 
 /**
- * Field that renders no control at all. Use it for values the form needs to
- * submit but the user never edits, e.g. a discriminator seeded from the loader.
- *
- * Pass `initialValue` to hardcode the starting value. Omitting it makes the
- * field require a matching entry in the form's `defaultValues`.
+ * Renders no control, for values the user never edits (e.g. a discriminator from the loader). Without
+ * `initialValue` the field requires an entry in the form's `defaultValues`.
  */
 export function hidden<T extends AnySyncSchema>(
 	schema: T,
diff --git a/app/form/fields/ArrayFormField.tsx b/app/form/fields/ArrayFormField.tsx
index 441ee989c..896bc747f 100644
--- a/app/form/fields/ArrayFormField.tsx
+++ b/app/form/fields/ArrayFormField.tsx
@@ -43,9 +43,7 @@ export function ArrayFormField({
 		useTranslatedTexts({ label, bottomText, error });
 
 	const count = value.length;
-	// Always render at least one item so an empty array still shows an input
-	// the user can fill, rather than only an "Add" button. The underlying value
-	// stays empty until edited, so submitting an untouched field sends nothing.
+	// an empty array still shows one input; the value stays empty until edited
 	const minVisible = Math.max(min, 1);
 	const visibleCount = Math.max(count, minVisible);
 
@@ -65,9 +63,7 @@ export function ArrayFormField({
 	};
 
 	const handleAdd = () => {
-		// While the array is empty we still render one placeholder row that isn't
-		// part of `value` yet. Pad `value` up to the number of visible rows first so
-		// the added item appears below them instead of only backing the placeholder.
+		// pad up to the visible rows first so the added item appears below the placeholder row
 		const padded = [...value];
 		while (padded.length < visibleCount) {
 			padded.push(makeNewItem());
@@ -75,8 +71,7 @@ export function ArrayFormField({
 		onChange([...padded, makeNewItem()]);
 	};
 
-	// An item the user hasn't touched still equals the freshly added template, so
-	// it's indistinguishable from the placeholder shown for an empty array.
+	// an untouched item still equals the template, like the empty-array placeholder
 	const isPristineItem = (item: unknown) => {
 		const template = itemInitialValue;
 		if (typeof template === "object" && template !== null) {
@@ -91,9 +86,7 @@ export function ArrayFormField({
 			: isDeepEqual(item, template);
 	};
 
-	// A single pristine row is indistinguishable from the empty-array placeholder,
-	// so it shouldn't offer a remove button (you can't go below one visible row
-	// anyway). A lone edited row stays removable so the only item can be cleared.
+	// a single pristine row is the placeholder, so no remove button; a lone edited row stays removable
 	const canRemoveAt = (index: number) =>
 		!disabled &&
 		(canRemoveItem ? canRemoveItem(value[index], index) : true) &&
@@ -102,9 +95,7 @@ export function ArrayFormField({
 
 	const handleRemoveAt = (index: number) => {
 		const next = value.filter((_, i) => i !== index);
-		// Removing down to a single pristine row would leave a stray entry that
-		// looks untouched but still fails validation on submit; collapse it back to
-		// an empty array so it matches the pristine state.
+		// a lone pristine row would still fail validation on submit, so collapse to empty
 		onChange(next.length === 1 && isPristineItem(next[0]) ? [] : next);
 	};
 
@@ -113,8 +104,7 @@ export function ArrayFormField({
 		return ((value[idx] as Record<string, unknown>)?._key as string) ?? idx;
 	};
 
-	// Sorting is only offered for object arrays; primitive arrays are rendered
-	// inline without the fieldset header that carries the reorder controls.
+	// primitive arrays render inline without the fieldset header that carries the reorder controls
 	const isSortable = Boolean(sortable) && isObjectArray && !disabled;
 
 	const handleMoveAt = (index: number, direction: 1 | -1) => {
diff --git a/app/form/fields/FormFieldWrapper.tsx b/app/form/fields/FormFieldWrapper.tsx
index bd464ebe1..c3e3338a0 100644
--- a/app/form/fields/FormFieldWrapper.tsx
+++ b/app/form/fields/FormFieldWrapper.tsx
@@ -118,10 +118,7 @@ export function FormFieldWrapper({
 	);
 }
 
-/**
- * Wrapper for the entity-search fields (user, team, tournament), which render
- * their own label through the search component instead of taking one here.
- */
+/** For the entity-search fields, which render their own label through the search component. */
 export function SearchFormFieldWrapper({
 	children,
 }: {
diff --git a/app/form/fields/InputGroupFormField.tsx b/app/form/fields/InputGroupFormField.tsx
index 12927727c..4e1944b62 100644
--- a/app/form/fields/InputGroupFormField.tsx
+++ b/app/form/fields/InputGroupFormField.tsx
@@ -107,8 +107,7 @@ export function CheckboxGroupFormField<V extends string>({
 			? [...value, itemValue]
 			: value.filter((v) => v !== itemValue);
 		onChange(newValue);
-		// validate with the value the click produced — the click event would
-		// otherwise validate the pre-click value and show a stale error
+		// the click event would otherwise validate the pre-click value and show a stale error
 		onBlur?.(newValue);
 	};
 
diff --git a/app/form/fields/SelectFormField.tsx b/app/form/fields/SelectFormField.tsx
index 1ce504c65..3505e712c 100644
--- a/app/form/fields/SelectFormField.tsx
+++ b/app/form/fields/SelectFormField.tsx
@@ -154,9 +154,7 @@ function CustomSelect<V extends string>({
 
 	const hasDescriptions = items.some((item) => item.description);
 
-	// the Autocomplete wrapper of searchable selects drops falsy keys, so only
-	// plain selects render the clear choice as a list item like the native
-	// select's "—" option; searchable ones keep the clear button
+	// searchable selects' Autocomplete drops falsy keys, so only plain selects get a "—" clear item
 	const hasEmptyItem = Boolean(clearable && !searchPlaceholder);
 
 	const selectItems = [
diff --git a/app/form/fields/TextareaFormField.tsx b/app/form/fields/TextareaFormField.tsx
index 92328c6d8..b5497af45 100644
--- a/app/form/fields/TextareaFormField.tsx
+++ b/app/form/fields/TextareaFormField.tsx
@@ -57,11 +57,7 @@ export function TextareaFormField({
 	);
 }
 
-/**
- * Autofocusing a textarea leaves the caret before any existing text, which is the wrong place when
- * editing something already written. Defined at module level so the ref identity stays stable and
- * React only runs it on mount.
- */
+/** Autofocus leaves the caret before existing text. Module level so the ref identity is stable and runs only on mount. */
 function moveCaretToEnd(element: HTMLTextAreaElement | null) {
 	element?.setSelectionRange(element.value.length, element.value.length);
 }
diff --git a/app/form/image-field.ts b/app/form/image-field.ts
index 4afeac104..5c4c1fc02 100644
--- a/app/form/image-field.ts
+++ b/app/form/image-field.ts
@@ -1,25 +1,13 @@
 import * as v from "valibot";
 import { id } from "~/utils/schema";
 
-/**
- * Allowed prefixes for a {@link imageValue} `NEW` data URL. The client compresses to webp,
- * but browsers without canvas webp encoding (Safari, Brave with fingerprint protection)
- * silently fall back to png per the HTML spec.
- */
+/** The client compresses to webp, but browsers without canvas webp encoding (Safari, Brave) silently fall back to png. */
 const IMAGE_FIELD_DATA_URL_PREFIX_REGEX = /^data:image\/(webp|png);base64,/;
 
-/**
- * Hard ceiling for a `NEW` data URL's length. Caps the JSON body size so a malicious or
- * oversized payload can't bloat the request. A `thick-banner` webp base64-encodes to ~200KB,
- * so this leaves comfortable headroom.
- */
+/** Caps the JSON body size; a `thick-banner` webp base64-encodes to ~200KB, so this leaves comfortable headroom. */
 const IMAGE_FIELD_MAX_DATA_URL_LENGTH = 3_000_000;
 
-/**
- * JSON-serializable value of a SendouForm `image` field. Covers every state an edit form needs:
- * `null` (none / removed), an unchanged `EXISTING` image (only the id reference + a preview url
- * ride in JSON, never bytes), or a newly picked `NEW` image as a base64 webp/png data URL.
- */
+/** `null` (none / removed), an unchanged `EXISTING` image (id + preview url, never bytes), or a `NEW` base64 webp/png data URL. */
 export const imageValue = v.nullable(
 	v.union([
 		v.object({
@@ -40,10 +28,7 @@ export const imageValue = v.nullable(
 
 export type ImageFieldValue = v.InferOutput<typeof imageValue>;
 
-/**
- * Builds an `EXISTING` {@link ImageFieldValue} for an edit form's default values, or `null`
- * when either the id or preview url is missing.
- */
+/** `EXISTING` {@link ImageFieldValue} for an edit form's defaults, or `null` when the id or preview url is missing. */
 export function existingImage(
 	imgId: number | null | undefined,
 	url: string | null | undefined,
diff --git a/app/form/index.ts b/app/form/index.ts
index 057534713..49a475a93 100644
--- a/app/form/index.ts
+++ b/app/form/index.ts
@@ -1,4 +1,2 @@
-// Form system exports
-
 export { SendouForm } from "./SendouForm";
 export type { ArrayItemRenderContext, CustomFieldRenderProps } from "./types";
diff --git a/app/form/parse.server.ts b/app/form/parse.server.ts
index 18a992f1e..c4534d7bc 100644
--- a/app/form/parse.server.ts
+++ b/app/form/parse.server.ts
@@ -11,17 +11,10 @@ export type ParseResult<T> =
 	| { success: true; data: T }
 	| { success: false; fieldErrors: Record<string, string> };
 
-/**
- * Ceiling for a request body, in bytes. Sized to fit a form with a couple of `image()` fields (each
- * capped at ~3M base64 characters) plus its other fields. Forms that legitimately submit more (e.g.
- * art) pass their own `maxBodyBytes`.
- */
+/** Fits a couple of `image()` fields (~3M base64 chars each) plus the rest; forms needing more (e.g. art) pass `maxBodyBytes`. */
 const DEFAULT_MAX_BODY_BYTES = 8 * 1024 * 1024;
 
-/**
- * Maps validation issues to field-level errors keyed by form field name
- * (e.g. `members[0].userId`), keeping the first error per field.
- */
+/** Errors keyed by field name (e.g. `members[0].userId`), first error per field. */
 function fieldErrorsFromIssues(
 	issues: v.BaseIssue<unknown>[],
 ): Record<string, string> {
@@ -36,11 +29,7 @@ function fieldErrorsFromIssues(
 	return fieldErrors;
 }
 
-/**
- * Parses request body against a schema.
- * Handles both JSON (SendouForm) and form data (FormWithConfirm) based on Content-Type.
- * Returns parsed data on success, or field-level errors on validation failure.
- */
+/** Parses a JSON (SendouForm) or form data (FormWithConfirm) body by Content-Type into data or field errors. */
 export async function parseFormData<T extends AnySchema>({
 	request,
 	schema,
@@ -71,11 +60,9 @@ type ResolvedImages<T> = T extends unknown
 	: never;
 
 /**
- * Like {@link parseFormData}, but additionally resolves every `image()` field in the schema to the
- * image id to store on the consuming FK column (`number | null`) via {@link imageFieldValueToImgId}
- * — uploading newly picked images, keeping unchanged ones, and clearing removed ones. The schema
- * may be a single object or a union of objects (e.g. an `_action` discriminated form). The
- * consuming action receives a plain id per image field and only writes it to its own entity.
+ * {@link parseFormData} plus every `image()` field resolved to the image id for the FK column via
+ * {@link imageFieldValueToImgId} (uploading new, keeping unchanged, clearing removed). The schema may be an
+ * object or a union of objects (e.g. `_action` discriminated).
  */
 export async function parseFormDataWithImages<T extends AnySchema>({
 	request,
@@ -103,10 +90,7 @@ export async function parseFormDataWithImages<T extends AnySchema>({
 	return { success: true, data: data as ResolvedImages<v.InferOutput<T>> };
 }
 
-/**
- * Collects every `image()` field across a schema object or union/variant of objects, along with each
- * field's `autoValidate` flag (whether its uploads bypass the moderator queue).
- */
+/** Every `image()` field across an object or union/variant of objects, with its `autoValidate` flag. */
 function imageFields(
 	schema: AnySchema,
 ): Array<{ key: string; autoValidate: boolean }> {
@@ -132,11 +116,7 @@ function imageFields(
 	return [...fields].map(([key, autoValidate]) => ({ key, autoValidate }));
 }
 
-/**
- * Reads the request body into the plain object the schema parses, refusing anything over
- * `maxBytes`. `Content-Length` is checked up front so an oversized body is rejected before a byte
- * of it is read.
- */
+/** Body → plain object, refusing over `maxBytes`. `Content-Length` is checked up front to reject before reading. */
 async function requestBodyToObject(request: Request, maxBytes: number) {
 	if (Number(request.headers.get("Content-Length")) > maxBytes) {
 		throw payloadTooLarge();
@@ -149,11 +129,7 @@ async function requestBodyToObject(request: Request, maxBytes: number) {
 	return formDataToObject(await request.formData());
 }
 
-/**
- * Reads the body as text, aborting the stream as soon as `maxBytes` is exceeded. The running total
- * is enforced (rather than trusting `Content-Length`) so a chunked body that omits or understates
- * the header can't be buffered in full either.
- */
+/** Aborts the stream past `maxBytes`, enforcing the running total so a chunked body understating `Content-Length` can't be buffered. */
 async function readBodyText(request: Request, maxBytes: number) {
 	const reader = request.body?.getReader();
 	if (!reader) return "";
diff --git a/app/form/types.ts b/app/form/types.ts
index e4e01eef8..620cdadad 100644
--- a/app/form/types.ts
+++ b/app/form/types.ts
@@ -26,10 +26,7 @@ interface FormFieldText<T extends string> extends FormFieldBase<T> {
 	minLength?: number;
 	maxLength: number;
 	toLowerCase?: boolean;
-	/**
-	 * Normalizes what the user types before it is stored, e.g. reducing a pasted
-	 * full URL down to the part the field actually holds.
-	 */
+	/** Normalizes input before storing, e.g. reducing a pasted full URL to the part the field holds. */
 	transformValue?: (value: string) => string;
 	leftAddon?: string;
 	placeholder?: string;
@@ -115,11 +112,10 @@ export interface FormFieldDatetime<T extends string> extends FormFieldBase<T> {
 interface FormFieldWeaponPool<T extends string> extends FormFieldBase<T> {
 	minCount?: number;
 	maxCount: number;
-	/** Does the weapon pool have an ordering? If true, the order is fixed and cannot be changed by the user (order ASC by weapon id) */
+	/** Fixes the order to weapon id ASC instead of user-sortable */
 	disableSorting?: boolean;
-	/** Can user favorite weapons in the pool? If disabled, all weapons have isFavorite: false */
+	/** If set, all weapons have isFavorite: false */
 	disableFavorites?: boolean;
-	/** Allow duplicate weapon IDs in the pool */
 	allowDuplicates?: boolean;
 	/** Treat alt-skin variants of an already-picked weapon as duplicates (e.g. picking Splattershot also disables Hero Shot Replica) */
 	disableAltSkinDuplicates?: boolean;
@@ -261,10 +257,7 @@ export type SelectOption = {
 /** Brand type to encode required options directly in schema types */
 export type FieldWithOptions<TOptions> = { _requiredOptions: TOptions };
 
-/**
- * Custom render props for FormField children.
- * Generic type parameter allows for type-safe value handling when the type is known.
- */
+/** Render props for FormField children */
 export type CustomFieldRenderProps<TValue = unknown> = {
 	name: string;
 	error: string | undefined;
@@ -283,7 +276,6 @@ type FormFieldChildrenProps = {
 	disabled?: boolean;
 };
 
-/** Props for a typed FormField based on field name and schema */
 export type TypedFormFieldProps<
 	TSchema extends v.ObjectEntries,
 	TName extends keyof TSchema & string,
@@ -303,10 +295,9 @@ export type TypedFormFieldProps<
 	? { options: TOptions }
 	: { options?: never });
 
-/** Nested path pattern for array/object traversal */
 type NestedPath = `${string}.${string}` | `${string}[${string}`;
 
-/** Props for FormField with flexible (string) name - used for nested paths like `${itemName}.field` */
+/** FormField props with a free-form name, for nested paths like `${itemName}.field` */
 export type FlexibleFormFieldProps = {
 	name: NestedPath;
 	label?: string;
@@ -322,7 +313,6 @@ export type FlexibleFormFieldProps = {
 	options?: unknown;
 };
 
-/** Typed FormField component type for a specific schema */
 export type TypedFormFieldComponent<TSchema extends v.ObjectEntries> = {
 	<TName extends keyof TSchema & string>(
 		props: TypedFormFieldProps<TSchema, TName>,
@@ -331,35 +321,20 @@ export type TypedFormFieldComponent<TSchema extends v.ObjectEntries> = {
 };
 
 /**
- * Runtime config consumed only by the `team-search` field. Passed via the
- * `options` prop (the same channel `badges`/`select-dynamic` use), so it stays
- * scoped to this field type instead of polluting every `FormField`.
- *
- * `initialTeam` carries the selected team's display data (name, avatar) for the
- * edit/prefill case — that metadata is not part of the stored form value (a
- * plain team id), so it cannot come from `defaultValues`.
+ * `options` prop config of the `team-search` field. `initialTeam` carries the prefilled team's display
+ * data (name, avatar), which the stored value (a plain team id) lacks.
  */
 export type TeamSearchFieldOptions = {
 	onTeamSelected?: (team: TeamSearchResult | null) => void;
 	initialTeam?: { id: number; name: string; avatarUrl?: string | null };
 };
 
-/**
- * Runtime config consumed only by the `user-search` field, passed via the
- * `options` prop (the same channel `team-search` uses).
- *
- * `onUserSelected` exposes the resolved user (with its username) on selection —
- * the stored form value is only the user id, so callers that need to display the
- * picked user's name elsewhere capture it here.
- */
+/** `options` prop config of the `user-search` field. `onUserSelected` exposes the resolved user; the stored value is only the id. */
 export type UserSearchFieldOptions = {
 	onUserSelected?: (user: UserSearchResult | null) => void;
 };
 
-/**
- * Runtime config consumed only by the `tournament-search` field, passed via the
- * `options` prop (the same channel `team-search` uses).
- */
+/** `options` prop config of the `tournament-search` field. */
 export type TournamentSearchFieldOptions = {
 	/** Restrict results to tournaments that have already started (finished/past). */
 	pastOnly?: boolean;
@@ -367,11 +342,7 @@ export type TournamentSearchFieldOptions = {
 	onTournamentSelected?: (tournament: TournamentSearchItem | null) => void;
 };
 
-/**
- * Object schema of a whole form or a fieldset, whether plain or wrapped in a
- * pipe (e.g. a cross-field `superRefine`). Value types are inferred from
- * `entries`, which such a pipe leaves untouched.
- */
+/** Object schema of a form or fieldset, plain or wrapped in a pipe (e.g. a cross-field `superRefine`). */
 export type FormObjectSchema<
 	TEntries extends v.ObjectEntries = v.ObjectEntries,
 > = AnySyncSchema & { readonly entries: TEntries };
diff --git a/app/form/utils.ts b/app/form/utils.ts
index 0f366dcb7..bd3de8022 100644
--- a/app/form/utils.ts
+++ b/app/form/utils.ts
@@ -7,11 +7,7 @@ export function infoMessageId(fieldId: string) {
 	return `${fieldId}-info`;
 }
 
-/**
- * Builds a form field name (e.g. `members[0].userId`) from a validation issue
- * path so that server- and client-side validation errors key fields
- * identically.
- */
+/** Builds a field name (e.g. `members[0].userId`) from an issue path so server and client errors key fields identically. */
 export function buildFieldPath(path: PropertyKey[]): string | null {
 	if (path.length === 0) return null;
 
@@ -101,11 +97,7 @@ export function setNestedValue(
 	};
 }
 
-/**
- * The default value object for a `fieldset` field, built from each sub-field's
- * own `initialValue` (e.g. a `select`'s first option). Returns `{}` for
- * non-fieldset fields.
- */
+/** Default value of a `fieldset` field built from its sub-fields' `initialValue`s. `{}` for non-fieldset fields. */
 export function fieldsetDefaults(
 	fieldsetMeta: FormField,
 ): Record<string, unknown> {
@@ -121,13 +113,9 @@ export function fieldsetDefaults(
 }
 
 /**
- * When a leaf field inside an array-of-fieldset item is edited (e.g.
- * `staff[0].userId`), the enclosing item is created on demand. Without this the
- * item would only contain the touched field, dropping defaults that were merely
- * shown as a fallback (e.g. a required `select`'s first option) and failing
- * validation on submit. This seeds the item with its fieldset defaults, keeping
- * any values it already has. Untouched items are never created, so this doesn't
- * affect submitting a pristine form.
+ * Editing a leaf inside an array-of-fieldset item (e.g. `staff[0].userId`) creates the item on demand;
+ * seeds it with its fieldset defaults (keeping existing values) so fallback-only defaults like a
+ * required `select`'s first option aren't dropped and fail validation. Untouched items are never created.
  */
 export function seedArrayItemDefaults(
 	schema: FormObjectSchema,
@@ -135,8 +123,7 @@ export function seedArrayItemDefaults(
 	name: string,
 ): Record<string, unknown> {
 	const lastBracket = name.lastIndexOf("]");
-	// No enclosing array item (`-1`) or the leaf is the array element itself
-	// (path ends in `]`, i.e. a primitive array) — nothing to seed.
+	// no enclosing array item, or the leaf is a primitive array element itself
 	if (lastBracket === -1 || lastBracket === name.length - 1) return values;
 
 	const itemPath = name.slice(0, lastBracket + 1);
@@ -183,12 +170,7 @@ export function getNestedSchema(
 	return current;
 }
 
-/**
- * Unwraps optional/nullable/nullish wrappers and pipes (e.g. `preprocess`)
- * down to the schema that carries the structural properties (`entries`/`item`).
- * A pipe over a plain schema needs no unwrapping since it spreads that
- * schema's own properties.
- */
+/** Unwraps optional/nullable/nullish wrappers and pipes down to the schema carrying `entries`/`item`. */
 function unwrapSchema(schema: AnySyncSchema): AnySyncSchema {
 	if (
 		(schema.type === "optional" ||
@@ -231,11 +213,8 @@ export function validateField(
 	const result = v.safeParse(fieldSchema, value);
 	if (result.success) return undefined;
 
-	// `array`/`fieldset` fields render each child as its own FormField with its
-	// own error slot, so a nested issue (e.g. an empty member inside a `members`
-	// array) belongs to that child — attributing it to the parent would surface
-	// the wrong message at the wrong field. Other composite fields (e.g. a custom
-	// tuple) render as a single control, so their nested issues belong to them.
+	// `array`/`fieldset` children render their own error slots, so nested issues belong to the child;
+	// other composites (e.g. a custom tuple) render as one control and own their nested issues
 	const fieldMeta = getFormFieldMetadata(fieldSchema);
 	const childrenRenderOwnErrors =
 		fieldMeta?.type === "array" || fieldMeta?.type === "fieldset";
@@ -265,12 +244,9 @@ export function validateField(
 }
 
 /**
- * Accessibility attributes for a form control. Ids are derived from the field
- * `name` because the error/info messages render with name-based ids
- * (`errorMessageId`/`infoMessageId`) — a `useId()` value would point at
- * elements that don't exist. The error id is also included in
- * `aria-describedby` since `aria-errormessage` support in screen readers is
- * still inconsistent.
+ * Accessibility attributes for a form control. Ids derive from the field `name` to match the
+ * name-based `errorMessageId`/`infoMessageId`. The error id is also in `aria-describedby` since
+ * screen reader support for `aria-errormessage` is inconsistent.
  */
 export function ariaAttributes({
 	name,
diff --git a/app/hooks/intl/useDateTimeFormat.ts b/app/hooks/intl/useDateTimeFormat.ts
index 50a08a58c..9652f6083 100644
--- a/app/hooks/intl/useDateTimeFormat.ts
+++ b/app/hooks/intl/useDateTimeFormat.ts
@@ -1,11 +1,7 @@
 import { databaseTimestampToDate } from "~/utils/dates";
 import { useUserIntlPreference } from "./useUserIntlPreference";
 
-/**
- * Zero-width space rendered (hidden via `invisible`) during SSR so the element
- * reserves exactly one normal text line, avoiding layout shift on hydration
- * without an empty box's baseline quirks.
- */
+/** Rendered (via `invisible`) during SSR to reserve one text line without an empty box's baseline quirks. */
 const SSR_PLACEHOLDER = "\u200b";
 
 const SSR_FORMATTER = {
@@ -14,21 +10,13 @@ const SSR_FORMATTER = {
 };
 
 /**
- * SSR-safe wrapper around `Intl.DateTimeFormat`.
- *
- * Uses the user's locale and hour cycle preferences via `useUserIntlPreference`.
- * Before hydration the returned formatter's methods return a zero-width space
- * placeholder so that server output matches the initial client render while
- * reserving one text line.
- *
- * Inputs accept either a `Date` or a database timestamp (`number`); numbers
- * are converted via `databaseTimestampToDate`.
+ * SSR-safe `Intl.DateTimeFormat` using `useUserIntlPreference`. Before hydration the methods return a
+ * zero-width space placeholder. Inputs are a `Date` or a database timestamp (`number`).
  */
 export function useDateTimeFormat(options: Intl.DateTimeFormatOptions) {
 	const { language, hourCycle, isLoaded } = useUserIntlPreference();
 
-	// constructing an Intl.DateTimeFormat is expensive, so it is deferred until
-	// a format call actually happens (never on the server) and cached
+	// constructing an Intl.DateTimeFormat is expensive, so deferred to the first format call and cached
 	const formatter = () =>
 		cachedDateTimeFormat(language, {
 			...options,
diff --git a/app/hooks/intl/useFormatDistanceToNow.ts b/app/hooks/intl/useFormatDistanceToNow.ts
index e8f7381ea..c624cdfab 100644
--- a/app/hooks/intl/useFormatDistanceToNow.ts
+++ b/app/hooks/intl/useFormatDistanceToNow.ts
@@ -6,16 +6,9 @@ import {
 } from "~/utils/dates";
 
 /**
- * Hook that returns a `formatDistanceToNow` function (date-fns) bound to the
- * current site language, for locale-aware "x ago" / "in x" output.
- *
- * Accepts either a `Date` or a database timestamp (`number`); numbers are
- * converted via `databaseTimestampToDate`.
- *
- * Note: this intentionally does NOT honor the user's "always use browser
- * language" preference (unlike `useDateTimeFormat`). The browser may be set to
- * a language we have not loaded a date-fns locale for, so we use the
- * site language to guarantee a translated result.
+ * date-fns `formatDistanceToNow` bound to the site language, taking a `Date` or database timestamp. Unlike
+ * `useDateTimeFormat` it ignores the "always use browser language" preference: that language may have no
+ * date-fns locale loaded.
  */
 export function useFormatDistanceToNow() {
 	const { i18n } = useTranslation();
diff --git a/app/hooks/intl/useUserIntlPreference.ts b/app/hooks/intl/useUserIntlPreference.ts
index 5bbd479c6..bce127eca 100644
--- a/app/hooks/intl/useUserIntlPreference.ts
+++ b/app/hooks/intl/useUserIntlPreference.ts
@@ -4,11 +4,8 @@ import { useUser } from "~/features/auth/core/user";
 import { useHydrated } from "../useHydrated";
 
 /**
- * Resolves the language and hour cycle to use when formatting dates and times
- * for the current user. Prefers a browser language sharing a base tag with the
- * active i18n language (e.g. `en-GB` over site `en`) for regional formatting.
- * `isLoaded` is `false` until hydration; gate locale-dependent output on it to
- * avoid hydration mismatches.
+ * Language and hour cycle for formatting dates. Prefers a browser language sharing the site language's base
+ * tag (`en-GB` over `en`). `isLoaded` is `false` until hydration; gate locale-dependent output on it.
  */
 export function useUserIntlPreference() {
 	const { i18n } = useTranslation();
@@ -17,7 +14,6 @@ export function useUserIntlPreference() {
 
 	const browserLanguages = hydrated ? navigator.languages : [];
 
-	// does the user want to use their browser language even if the site is in another language?
 	const language =
 		browserLanguages.find((lang) => compareLanguages(lang, i18n.language)) ??
 		i18n.language;
diff --git a/app/hooks/useActionSubmit.ts b/app/hooks/useActionSubmit.ts
index f5a6bd9dd..01756dc00 100644
--- a/app/hooks/useActionSubmit.ts
+++ b/app/hooks/useActionSubmit.ts
@@ -16,12 +16,8 @@ interface UseActionSubmitOptions {
 }
 
 /**
- * Programmatic counterpart of `<ActionButton>`: submits an `_action` mutation
- * from an event handler, type checked against the route's action schema.
- *
- * @example
- * const { submit } = useActionSubmit(deleteFriendSchema);
- * submit("DELETE_FRIEND", { friendshipId });
+ * Programmatic `<ActionButton>`: submits an `_action` mutation type checked against the route's schema,
+ * e.g. `submit("DELETE_FRIEND", { friendshipId })`.
  */
 export function useActionSubmit<TSchema extends AnySchema>(
 	_schema: TSchema,
diff --git a/app/hooks/useAutoRerender.ts b/app/hooks/useAutoRerender.ts
index b1cc9290f..3290fbdd3 100644
--- a/app/hooks/useAutoRerender.ts
+++ b/app/hooks/useAutoRerender.ts
@@ -55,16 +55,8 @@ function getTickStore(everyMs: number, alignToMs: number): TickStore {
 }
 
 /**
- * Forces the component to rerender periodically. Returns the `Date` of the
- * latest tick — callers should consume this value (e.g. pass it to date-fns)
- * so React Compiler can see the state is observable and won't memoize the
- * rerender away.
- *
- * Backed by a shared tick store: all components subscribed to the same
- * interval (and `alignTo` reference time) share a single timer. Ticks are
- * aligned via a self-rescheduling `setTimeout`, so with `every: "minute"` the
- * component rerenders at exactly `alignTo + N*60s` rather than at arbitrary
- * offsets from mount.
+ * Rerenders periodically, returning the latest tick's `Date`: consume it so React Compiler can't memoize the
+ * rerender away. Components on the same interval and `alignTo` share one timer, ticking at exactly `alignTo + N*interval`.
  */
 export function useAutoRerender(): Date;
 export function useAutoRerender(every: "second" | "ten seconds"): Date;
diff --git a/app/hooks/useBackgroundResource.ts b/app/hooks/useBackgroundResource.ts
index 4851ff769..a4fb852a0 100644
--- a/app/hooks/useBackgroundResource.ts
+++ b/app/hooks/useBackgroundResource.ts
@@ -1,19 +1,15 @@
 import * as React from "react";
 
 /**
- * Keeps an app shell resource route's JSON fresh, outside the router. A
- * `useFetcher` load that is still in flight when a navigation starts is folded
- * into that navigation and has to settle before it completes (React Router
- * reruns cancelled fetcher loads without consulting `shouldRevalidate`), so a
- * refresh that only feeds the app shell would hold up every page change it
- * happens to overlap with.
+ * Keeps an app shell resource route's JSON fresh outside the router: an in-flight `useFetcher` load is folded
+ * into a starting navigation and must settle first, so it would hold up every page change it overlaps.
  */
 export function useBackgroundResource<T>(url: string) {
 	const [data, setData] = React.useState<T>();
 	const [isLoading, setIsLoading] = React.useState(false);
 	const latestRequestRef = React.useRef(0);
 
-	// stable so effects that refresh after a mutation don't re-run every render
+	// stable so effects refreshing after a mutation don't re-run every render
 	const refresh = React.useCallback(async () => {
 		const requestId = ++latestRequestRef.current;
 		setIsLoading(true);
diff --git a/app/hooks/useCopyToClipboard.ts b/app/hooks/useCopyToClipboard.ts
index f26343307..ff437224c 100644
--- a/app/hooks/useCopyToClipboard.ts
+++ b/app/hooks/useCopyToClipboard.ts
@@ -2,11 +2,7 @@ import * as React from "react";
 
 const COPY_SUCCESS_DURATION_MS = 2000;
 
-/**
- * Copies a string to the clipboard and exposes `copySuccess`, which stays
- * `true` for a short while after a successful copy so a confirmation (e.g. a
- * checkmark) can be flashed. `reset` clears `copySuccess` immediately.
- */
+/** `copySuccess` stays `true` for a short while after a copy so a confirmation can be flashed; `reset` clears it. */
 export function useCopyToClipboard(): {
 	copyToClipboard: (value: string) => void;
 	copySuccess: boolean;
@@ -23,11 +19,7 @@ export function useCopyToClipboard(): {
 	return { copyToClipboard, copySuccess, reset };
 }
 
-/**
- * Copies a .png image to the clipboard, exposing `copySuccess` like {@link useCopyToClipboard}.
- * The image is taken as a promise rather than a blob because Safari only allows the write while
- * the click that started it is still being handled, so awaiting the image first would break it.
- */
+/** Like {@link useCopyToClipboard} for a png. Takes a promise since Safari only allows the write during the click that started it. */
 export function useCopyPngToClipboard(): {
 	copyPngToClipboard: (png: Promise<Blob>) => Promise<void>;
 	copySuccess: boolean;
diff --git a/app/hooks/useDebounce.ts b/app/hooks/useDebounce.ts
index c364d5979..b7b63478e 100644
--- a/app/hooks/useDebounce.ts
+++ b/app/hooks/useDebounce.ts
@@ -1,12 +1,8 @@
 import * as React from "react";
 
 /**
- * Runs `fn` once `ms` has elapsed without any value in `deps` changing. The
- * timer is (re)started on mount and whenever `ms` or a value in `deps` changes.
- *
- * Uses the latest-ref pattern instead of `useEffectEvent`: effect events don't
- * update past the first render inside `React.memo`/`React.forwardRef` wrapped
- * components (React 19.2), which would silently break callers.
+ * Runs `fn` once `ms` has elapsed without `deps` changing. Uses a latest-ref instead of `useEffectEvent`,
+ * which doesn't update past the first render inside `React.memo`/`forwardRef` components (React 19.2).
  */
 export function useDebounce(
 	fn: () => void,
diff --git a/app/hooks/useDragToScroll.ts b/app/hooks/useDragToScroll.ts
index 85ebe2654..1f1ee9ff1 100644
--- a/app/hooks/useDragToScroll.ts
+++ b/app/hooks/useDragToScroll.ts
@@ -7,10 +7,7 @@ const MOMENTUM_FRAME_MS = 1000 / 60;
 const VELOCITY_IDLE_TIMEOUT_MS = 100;
 const SNAP_RESTORE_SMOOTH_TIMEOUT_MS = 750;
 
-/**
- * Makes an element with overflowing content scrollable by dragging with the
- * mouse. Returns the ref to attach to the scrollable element.
- */
+/** Mouse drag-to-scroll; returns the ref to attach to the scrollable element. */
 export function useDragToScroll<
 	T extends HTMLElement,
 >(): React.RefObject<T | null> {
@@ -25,12 +22,7 @@ export function useDragToScroll<
 	return ref;
 }
 
-/**
- * Attaches mouse drag-to-scroll behavior with release momentum to an element,
- * returning a cleanup function. A grabbing cursor is shown while dragging and
- * clicks that conclude a drag are suppressed.
- * Framework-agnostic on purpose (usable as a Svelte attachment as is).
- */
+/** Drag-to-scroll with release momentum, suppressing clicks that conclude a drag. Framework-agnostic (usable as a Svelte attachment). */
 export function dragToScroll(element: HTMLElement): () => void {
 	const hasScrollSnap = getComputedStyle(element).scrollSnapType !== "none";
 	let grabbingCursorStyle: HTMLStyleElement | null = null;
@@ -54,8 +46,7 @@ export function dragToScroll(element: HTMLElement): () => void {
 		element.style.scrollBehavior = "";
 	};
 
-	// mandatory scroll snap re-snaps on every programmatic scrollLeft/scrollTop
-	// write, so it has to be off for the duration of the drag
+	// mandatory scroll snap re-snaps on every programmatic scroll write
 	const suppressScrollSnap = () => {
 		if (!hasScrollSnap || isSnapSuppressed) return;
 
diff --git a/app/hooks/useHydrated.ts b/app/hooks/useHydrated.ts
index a227498ee..f0fcaf150 100644
--- a/app/hooks/useHydrated.ts
+++ b/app/hooks/useHydrated.ts
@@ -6,23 +6,7 @@ function subscribe() {
 	return () => {};
 }
 
-/**
- * Return a boolean indicating if the JS has been hydrated already.
- * When doing Server-Side Rendering, the result will always be false.
- * When doing Client-Side Rendering, the result will always be false on the
- * first render and true from then on. Even if a new component renders it will
- * always start with true.
- *
- * Example: Disable a button that needs JS to work.
- * ```tsx
- * let hydrated = useHydrated();
- * return (
- *   <button type="button" disabled={!hydrated} onClick={doSomethingCustom}>
- *     Click me
- *   </button>
- * );
- * ```
- */
+/** False on the server and the hydration render, true from then on (a component mounting later starts with true). */
 export function useHydrated() {
 	return React.useSyncExternalStore(
 		subscribe,
diff --git a/app/hooks/usePagination.ts b/app/hooks/usePagination.ts
index 752ee0f84..a4ce7fa1a 100644
--- a/app/hooks/usePagination.ts
+++ b/app/hooks/usePagination.ts
@@ -44,8 +44,7 @@ export function usePagination<T>({
 	const thereIsNextPage = currentPage < pagesCount;
 	const thereIsPreviousPage = currentPage > 1;
 
-	// if the list changes from externally it might be that we are on a page that doesn't exist anymore
-	// setting state inside render looks weird but should be ok
+	// an external list change can leave us on a page that no longer exists
 	if (itemsToDisplay.length === 0 && currentPage > 1) {
 		setCurrentPage(1);
 	}
diff --git a/app/hooks/usePrefersReducedMotion.ts b/app/hooks/usePrefersReducedMotion.ts
index 5f183003c..cc7ce4b34 100644
--- a/app/hooks/usePrefersReducedMotion.ts
+++ b/app/hooks/usePrefersReducedMotion.ts
@@ -8,11 +8,7 @@ function subscribe(callback: () => void) {
 	return () => mediaQueryList.removeEventListener("change", callback);
 }
 
-/**
- * Returns a boolean indicating whether the user has requested reduced motion
- * via the `prefers-reduced-motion` media query. Always returns `false` during
- * server-side rendering and on the first client render.
- */
+/** `prefers-reduced-motion` media query; `false` on the server and the first client render. */
 export function usePrefersReducedMotion() {
 	return React.useSyncExternalStore(
 		subscribe,
diff --git a/app/hooks/useRecentlyReportedWeapons.ts b/app/hooks/useRecentlyReportedWeapons.ts
index bfa1c9feb..213d9e061 100644
--- a/app/hooks/useRecentlyReportedWeapons.ts
+++ b/app/hooks/useRecentlyReportedWeapons.ts
@@ -14,14 +14,7 @@ export const recentlyReportedWeaponsPersisted = PersistedState.define({
 	default: [],
 });
 
-/**
- * This hook provides access to the list of recently reported weapons,
- * which is persisted in local storage, and a function to add a new weapon
- * to the list.
- *
- * If a weapon is added that already exists in the list, it will be moved to the front of the list.
- * If the list exceeds the maximum number of reported weapons, the oldest weapon will be removed.
- */
+/** Local storage list of recently reported weapons; adding moves to the front and caps the length. */
 export function useRecentlyReportedWeapons() {
 	const [recentlyReportedWeapons, setRecentlyReportedWeapons] =
 		usePersistedState(recentlyReportedWeaponsPersisted);
diff --git a/app/hooks/useReloadOnNewDeploy.ts b/app/hooks/useReloadOnNewDeploy.ts
index e8d874f10..308e654bd 100644
--- a/app/hooks/useReloadOnNewDeploy.ts
+++ b/app/hooks/useReloadOnNewDeploy.ts
@@ -11,18 +11,14 @@ const reloadedForCommitPersisted = PersistedState.define({
 });
 
 /**
- * Reloads the page when the server starts reporting a different build than the
- * one this client's JavaScript was loaded from. Pages that stay open for hours
- * while revalidating (SendouQ looking above all) otherwise keep running old
- * code against new loader data, breaking whenever a deploy changes the shape of
- * that data.
+ * Reloads when the server reports a different build than this client's JS, since long-open revalidating
+ * pages (SendouQ looking above all) would otherwise run old code against new loader data.
  */
 export function useReloadOnNewDeploy(serverCommit: string) {
 	React.useEffect(() => {
 		if (!GIT_COMMIT || !serverCommit || serverCommit === GIT_COMMIT) return;
 
-		// the reload is expected to serve the new bundle, but should it not, the
-		// same build is never retried so the page can't end up in a reload loop
+		// the same build is never retried, so a reload not serving the new bundle can't loop
 		if (PersistedState.read(reloadedForCommitPersisted) === serverCommit) {
 			return;
 		}
diff --git a/app/hooks/useSearchParamPagination.ts b/app/hooks/useSearchParamPagination.ts
index d02b910fe..58a53bbb6 100644
--- a/app/hooks/useSearchParamPagination.ts
+++ b/app/hooks/useSearchParamPagination.ts
@@ -11,13 +11,8 @@ type PaginatedShape = { page: ParamDef<number> } & Record<
 >;
 
 /**
- * Pagination state for pages where the current page lives in the `page` search
- * param of the given search params definition and the loader takes care of
- * slicing the results.
- *
- * Returns props that can be spread to the `<Pagination />` component.
- *
- * For paginating a list that is fully available on the client, see `usePagination`.
+ * `<Pagination />` props for pages whose current page lives in the definition's `page` search param and
+ * whose loader slices the results. For a list fully on the client see `usePagination`.
  */
 export function useSearchParamPagination<Shape extends PaginatedShape>({
 	definition,
diff --git a/app/hooks/useThemeColors.ts b/app/hooks/useThemeColors.ts
index 73bdc176a..a4b612d9a 100644
--- a/app/hooks/useThemeColors.ts
+++ b/app/hooks/useThemeColors.ts
@@ -18,10 +18,8 @@ function getServerSnapshot() {
 }
 
 /**
- * Resolves CSS custom properties to their computed values (e.g. for canvas
- * rendering which can't consume CSS variables directly), re-resolving when the
- * theme class on the root element changes. All values are empty strings during
- * server-side rendering and the initial hydration render.
+ * Computed values of CSS custom properties (e.g. for canvas), re-resolved when the root theme class
+ * changes. Empty strings on the server and the hydration render.
  */
 export function useThemeColors<K extends string>(
 	cssVariables: Record<K, string>,
diff --git a/app/hooks/useUnseenFriendRequests.ts b/app/hooks/useUnseenFriendRequests.ts
index 2927ff9ab..742f359f1 100644
--- a/app/hooks/useUnseenFriendRequests.ts
+++ b/app/hooks/useUnseenFriendRequests.ts
@@ -12,14 +12,7 @@ export const seenFriendRequestsPersisted = PersistedState.define({
 	default: [],
 });
 
-/**
- * Returns the count of incoming friend requests that the user has not yet seen.
- *
- * "Seen" requests are tracked per-device in local storage (the dedicated /friends
- * page remains the authoritative view). The count updates when requests are marked
- * as seen via {@link markFriendRequestsSeen} in the same tab, or when local storage
- * changes in another tab.
- */
+/** Incoming requests not yet seen; "seen" is tracked per device in local storage via {@link markFriendRequestsSeen}. */
 export function useUnseenFriendRequests(incomingRequestIds: number[]): number {
 	const [seenIdsList] = usePersistedState(seenFriendRequestsPersisted);
 
@@ -29,12 +22,8 @@ export function useUnseenFriendRequests(incomingRequestIds: number[]): number {
 }
 
 /**
- * Records the given incoming friend request ids as seen, clearing the unseen badge.
- *
- * Ids are merged into the existing seen set rather than replacing it, so that
- * acting on a request (e.g. declining it) doesn't make an already-seen request
- * count as unseen again while other consumers still have a stale list. Only the
- * most recent ids are kept to keep the stored set from growing without bound.
+ * Merged into the seen set rather than replacing it, so acting on a request doesn't make an already-seen
+ * one unseen for consumers with a stale list. Only the most recent ids are kept.
  */
 export function markFriendRequestsSeen(ids: number[]) {
 	const merged = R.unique([
diff --git a/app/hooks/useVisualViewportHeight.ts b/app/hooks/useVisualViewportHeight.ts
index 558fb4982..a449e7c47 100644
--- a/app/hooks/useVisualViewportHeight.ts
+++ b/app/hooks/useVisualViewportHeight.ts
@@ -2,13 +2,7 @@ import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect";
 
 const CSS_VARIABLE = "--visual-viewport-height";
 
-/**
- * Keeps the `--visual-viewport-height` CSS variable in sync with the visual
- * viewport height on the document root. CSS has no native way to read the
- * visual (as opposed to layout) viewport, so elements that must stay above the
- * mobile on-screen keyboard rely on this variable to clamp their height as the
- * keyboard opens and closes.
- */
+/** Syncs `--visual-viewport-height` on the root; CSS can't read the visual viewport, which elements above the mobile keyboard need. */
 export function useVisualViewportHeight() {
 	useIsomorphicLayoutEffect(() => {
 		const viewport = window.visualViewport;
diff --git a/app/hooks/useWindowSize.ts b/app/hooks/useWindowSize.ts
index a98a4dd95..c2bd359b3 100644
--- a/app/hooks/useWindowSize.ts
+++ b/app/hooks/useWindowSize.ts
@@ -10,11 +10,7 @@ function subscribe(listener: () => void) {
 	return () => window.removeEventListener("resize", listener);
 }
 
-/**
- * Returns the current window dimensions, re-rendering on resize. Both
- * dimensions are `0` during server-side rendering and the initial hydration
- * render.
- */
+/** Window dimensions, re-rendering on resize. `0` on the server and the hydration render. */
 export function useWindowSize(): WindowSize {
 	const width = React.useSyncExternalStore(
 		subscribe,
diff --git a/app/modules/cache/index.ts b/app/modules/cache/index.ts
index 85a6a0524..1b90b63dd 100644
--- a/app/modules/cache/index.ts
+++ b/app/modules/cache/index.ts
@@ -1,8 +1,4 @@
-/**
- * A lightweight least-recently-used cache backed by a `Map`. Once `max` entries
- * are stored, inserting a new key evicts the least recently used one. Reading a
- * key via `get` marks it as most recently used.
- */
+/** LRU cache over a `Map`: past `max` entries an insert evicts the least recently used; `get` marks most recent. */
 export class LRUCache<K, V> {
 	private readonly max: number;
 	private readonly map = new Map<K, V>();
diff --git a/app/modules/csv.ts b/app/modules/csv.ts
index bddea18c0..f8bf1cd8e 100644
--- a/app/modules/csv.ts
+++ b/app/modules/csv.ts
@@ -6,32 +6,12 @@ const CHARACTERS_REQUIRING_QUOTING = [DELIMITER, QUOTE, "\n", "\r"];
 const FORMULA_PREFIX = "'";
 const FORMULA_TRIGGERS = ["=", "+", "@", "\t", "\r"];
 
-/**
- * Byte order mark to prepend when writing the CSV to a file, so that Excel
- * reads the bytes as UTF-8 and renders non-ASCII characters (e.g. Japanese or
- * accented names) correctly.
- */
+/** Prepend when writing to a file so Excel reads the bytes as UTF-8. */
 export const BOM = "\uFEFF";
 
 /**
- * Serializes a two-dimensional array of cell values into an RFC 4180 compliant
- * CSV string. Cells are quoted only when they contain a delimiter, quote or
- * line break, and any quotes inside a cell are escaped by doubling them.
- *
- * Cells whose value could be interpreted as a formula by spreadsheet software
- * (a "CSV injection") are prefixed with a single quote, which neutralizes the
- * formula while keeping the value readable. This matters because the input may
- * be user-controlled (team names, usernames, ...).
- *
- * @example
- * ```typescript
- * serialize([
- * 	["name", "note"],
- * 	["Sendou", 'say "hi"'],
- * 	["Test", "a,b"],
- * ]);
- * // name,note\r\nSendou,"say ""hi"""\r\nTest,"a,b"
- * ```
+ * RFC 4180 CSV: cells quoted only when needed, inner quotes doubled. Cells that spreadsheet software could
+ * read as a formula (CSV injection from user-controlled input) are prefixed with a single quote.
  */
 export function serialize(rows: ReadonlyArray<ReadonlyArray<string>>): string {
 	return rows.map(serializeRow).join(ROW_SEPARATOR);
@@ -58,8 +38,7 @@ function isFormulaInjectionRisk(value: string): boolean {
 	const firstCharacter = value[0];
 	if (!firstCharacter) return false;
 	if (FORMULA_TRIGGERS.includes(firstCharacter)) return true;
-	// "-" can legitimately begin a negative number, so only guard it when the
-	// value isn't numeric and could therefore be read as a formula
+	// "-" can legitimately begin a negative number
 	if (firstCharacter === "-") return !isNumeric(value);
 	return false;
 }
diff --git a/app/modules/discord-webhook.server.ts b/app/modules/discord-webhook.server.ts
index 9ca1764fe..563a23263 100644
--- a/app/modules/discord-webhook.server.ts
+++ b/app/modules/discord-webhook.server.ts
@@ -14,19 +14,12 @@ export interface WebhookUser {
 	customUrl: string | null;
 }
 
-/**
- * Posts a rich embed to the mod channel Discord webhook.
- * Fire-and-forget: meant to be called without awaiting, never throws, skipped with a log
- * line when `MOD_DISCORD_WEBHOOK_URL` is unset (e.g. in development).
- */
+/** Fire-and-forget embed to the mod channel: never throws, skipped with a log line when `MOD_DISCORD_WEBHOOK_URL` is unset. */
 export function sendModDiscordWebhook(embed: ModWebhookEmbed) {
 	sendDiscordWebhook("MOD_DISCORD_WEBHOOK_URL", embed);
 }
 
-/**
- * Posts a rich embed to the SendouQ canceled matches channel Discord webhook.
- * Fire-and-forget (see {@link sendModDiscordWebhook}).
- */
+/** Embed to the SendouQ canceled matches channel, fire-and-forget like {@link sendModDiscordWebhook}. */
 export function sendSQCancelDiscordWebhook(embed: ModWebhookEmbed) {
 	sendDiscordWebhook("SQ_CANCEL_DISCORD_WEBHOOK_URL", embed);
 }
@@ -63,10 +56,7 @@ function sendDiscordWebhook(
 		});
 }
 
-/**
- * Escapes then truncates free-text user input so it fits inside a Discord embed field
- * value without breaking the embed's markdown formatting.
- */
+/** Escapes then truncates user text to fit an embed field value without breaking its markdown. */
 export function truncateEmbedValue(text: string) {
 	const escaped = escapeMarkdown(text);
 	if (escaped.length <= EMBED_FIELD_VALUE_MAX_LENGTH) return escaped;
diff --git a/app/modules/i18n/i18next.server.ts b/app/modules/i18n/i18next.server.ts
index 7b469ffa1..3204f5cd6 100644
--- a/app/modules/i18n/i18next.server.ts
+++ b/app/modules/i18n/i18next.server.ts
@@ -47,11 +47,7 @@ interface I18nStore {
 
 const i18nAsyncLocalStorage = new AsyncLocalStorage<I18nStore>();
 
-/**
- * Detects the request locale, initializes a request-scoped i18next instance and
- * makes both available to server helpers ({@link getLocale},
- * {@link getServerTFunction}) for the duration of the request.
- */
+/** Detects the locale and sets up the request-scoped i18next instance behind {@link getLocale} and {@link getServerTFunction}. */
 export const i18nMiddleware: MiddlewareFunction<Response> = (args, next) =>
 	remixI18nextMiddleware(args, () =>
 		i18nAsyncLocalStorage.run(
@@ -68,10 +64,7 @@ export function getLocale(): string {
 	return currentStore().locale;
 }
 
-/**
- * A `TFunction` bound to the current request's locale and the given namespaces.
- * Namespaces are already available in-memory so no async loading is needed.
- */
+/** `TFunction` bound to the request's locale and the given namespaces (all in-memory, no async loading). */
 export function getServerTFunction<
 	N extends
 		| FlatNamespace
@@ -85,14 +78,9 @@ export function getServerTFunction<
 }
 
 /**
- * The request-scoped i18next instance, used to provide translations while
- * server-side rendering. Reads from the React Router context so it can be called
- * from `entry.server` where the request context is passed explicitly.
- *
- * Falls back to a shared default-language instance when the context is missing.
- * This happens when the render is an error boundary for a request whose
- * middleware chain threw before {@link i18nMiddleware} ran: without the fallback
- * the missing context would throw a second error that masks the original one.
+ * Request-scoped i18next instance for SSR, read from the router context so `entry.server` can call it.
+ * Falls back to a shared default-language instance when an error boundary renders for a request whose
+ * middleware threw before {@link i18nMiddleware} ran, so a second error doesn't mask the original.
  */
 export function getI18nInstance(
 	context: Readonly<RouterContextProvider>,
@@ -104,11 +92,7 @@ export function getI18nInstance(
 	}
 }
 
-/**
- * A `TFunction` bound to a fixed language, independent of the current request.
- * Use this when translating outside of a request (e.g. notifications) or when a
- * specific language is required regardless of the user's locale.
- */
+/** `TFunction` bound to a fixed language, for outside a request (e.g. notifications) or a required language. */
 export async function getFixedTForLanguage<
 	N extends
 		| FlatNamespace
@@ -134,9 +118,7 @@ function fallbackI18nInstance(): i18n {
 	if (!sharedFallbackInstance) {
 		const instance = createInstance();
 		instance.use(initReactI18next);
-		// initAsync: false makes init synchronous, which is safe here since
-		// resources are already in-memory and lets this be called from the sync
-		// getI18nInstance without awaiting.
+		// initAsync: false is safe with in-memory resources and lets the sync getI18nInstance call this
 		instance.init({
 			...config,
 			resources,
diff --git a/app/modules/i18n/loader.ts b/app/modules/i18n/loader.ts
index 3646caa0c..2ef82e6c0 100644
--- a/app/modules/i18n/loader.ts
+++ b/app/modules/i18n/loader.ts
@@ -36,12 +36,7 @@ declare global {
 	}
 }
 
-/**
- * Get the list of namespaces used by the application server-side so they can be
- * set on i18next init options and preloaded before hydration.
- *
- * Vendored from remix-i18next (removed in v8).
- */
+/** Namespaces used server-side, preloaded before hydration. Vendored from remix-i18next (removed in v8). */
 function getInitialNamespaces(): string[] {
 	return Object.values(window.__reactRouterRouteModules).flatMap((route) => {
 		const handle = route?.handle;
diff --git a/app/modules/i18n/locale-preload.server.ts b/app/modules/i18n/locale-preload.server.ts
index eea4a13a6..48fec5061 100644
--- a/app/modules/i18n/locale-preload.server.ts
+++ b/app/modules/i18n/locale-preload.server.ts
@@ -7,10 +7,8 @@ const localeAssetUrls = import.meta.glob<string>("../../../locales/*/*.json", {
 });
 
 /**
- * Fingerprinted asset URLs of the always-loaded translation namespaces for the
- * given locale (plus the English fallback). Rendered as `<link rel="preload">`
- * tags in the document head so the browser starts fetching them at HTML parse
- * time instead of waiting for the client entry to load and execute.
+ * Fingerprinted URLs of the always-loaded namespaces for the locale (plus English fallback), rendered as
+ * `<link rel="preload">` so fetching starts at HTML parse time rather than after the client entry runs.
  */
 export function localePreloadUrls(locale: string): string[] {
 	const languages =
diff --git a/app/modules/i18n/useChangeLanguage.ts b/app/modules/i18n/useChangeLanguage.ts
index 2bf2dad9e..086fd685d 100644
--- a/app/modules/i18n/useChangeLanguage.ts
+++ b/app/modules/i18n/useChangeLanguage.ts
@@ -4,12 +4,8 @@ import type { LanguageCode } from "~/modules/i18n/config";
 import { loadDateFnsLocale } from "~/utils/dates";
 
 /**
- * Detect when the locale returned by the root route loader changes and call
- * `i18n.changeLanguage` with the new locale so translations load automatically.
- * The date-fns locale is loaded first so the re-render triggered by the
- * language change already has it available.
- *
- * Vendored from remix-i18next (removed in v8).
+ * Calls `i18n.changeLanguage` when the root loader's locale changes, loading the date-fns locale first so
+ * the re-render already has it. Vendored from remix-i18next (removed in v8).
  */
 export function useChangeLanguage(locale: string) {
 	const { i18n } = useTranslation();
diff --git a/app/modules/in-game-lists/weapon-ids.ts b/app/modules/in-game-lists/weapon-ids.ts
index ca9781bb4..9beffb9c4 100644
--- a/app/modules/in-game-lists/weapon-ids.ts
+++ b/app/modules/in-game-lists/weapon-ids.ts
@@ -108,31 +108,14 @@ const altWeaponIdToId = new Map<MainWeaponId, MainWeaponId>([
 ]);
 
 /**
- * Folds an alt-skin weapon id to its base id, leaving non-alt ids untouched.
- *
- * Unlike {@link weaponIdToBaseWeaponId}, alt kits are preserved (e.g. Tentatek
- * Splattershot stays 41) — only cosmetic alt skins collapse to their base.
- *
- * Mirrors the `BuildWeapon.canonicalWeaponSplId` column so TypeScript callers
- * and SQL queries agree on what a weapon's canonical id is.
- *
- * @example
- * // Splattershot — base weapon, returned unchanged
- * canonicalWeaponSplId(40); // -> 40
- *
- * // Tentatek Splattershot — alt kit, returned unchanged
- * canonicalWeaponSplId(41); // -> 41
- *
- * // Hero Shot Replica — alt skin, folded to Splattershot
- * canonicalWeaponSplId(45); // -> 40
+ * Folds only cosmetic alt skins to their base (45 Hero Shot Replica → 40), keeping alt kits unlike
+ * {@link weaponIdToBaseWeaponId} (41 Tentatek stays 41). Mirrors the `BuildWeapon.canonicalWeaponSplId` column.
  */
 export function canonicalWeaponSplId(weaponSplId: MainWeaponId): MainWeaponId {
 	return altWeaponIdToId.get(weaponSplId) ?? weaponSplId;
 }
 
-/**
- * Converts a given weapon ID to an array containing the weapon ID and its alternate IDs. For example if you enter the ID 40 (Splattershot) it will return [40, 45, 47] (Splattershot, Hero Shot Replica, Order Shot Replica)
- */
+/** The weapon id and its alt skin ids, e.g. 40 (Splattershot) → [40, 45, 47] (+ Hero Shot Replica, Order Shot Replica). */
 export function weaponIdToArrayWithAlts(weaponId: MainWeaponId) {
 	const altId = weaponIdToAltId.get(weaponId);
 	if (altId !== undefined) {
@@ -150,21 +133,7 @@ export function weaponIdToArrayWithAlts(weaponId: MainWeaponId) {
 	return [weaponId];
 }
 
-/**
- * Determines the type of weapon based on its ID
- *
- * @returns "ALT_SKIN" if the weapon is an alternate skin, "BASE" if it's a base weapon, or "ALT_KIT" if it's an alternate kit
- *
- * @example
- * // Splattershot is a base weapon
- * weaponIdToType(40); // -> "BASE"
- *
- * // Tentatek Splattershot is an alternate kit
- * weaponIdToType(41); // -> "ALT_KIT"
- *
- * // Hero Shot Replica is an alternate skin
- * weaponIdToType(45); // -> "ALT_SKIN"
- */
+/** 40 Splattershot → "BASE", 41 Tentatek → "ALT_KIT", 45 Hero Shot Replica → "ALT_SKIN". */
 export const weaponIdToType = (weaponId: MainWeaponId) => {
 	if (altWeaponIdToId.has(weaponId)) return "ALT_SKIN";
 	if (weaponId === weaponIdToBaseWeaponId(weaponId)) return "BASE";
@@ -304,18 +273,6 @@ export const exampleMainWeaponIdWithSpecialWeaponId = (
 	}
 };
 
-/**
- * Calculates the base weapon ID from a main weapon ID.
- *
- * @example
- * // Returns 40 (because Splattershot is the base weapon for its kit)
- * weaponIdToBaseWeaponId(40); // -> 40
- *
- * // (41 is Tentatek Splattershot, which is an alt kit of Splattershot)
- * weaponIdToBaseWeaponId(41); // -> 40
- *
- * // (45 is Hero Shot Replica, which is an alt skin of Splattershot)
- * weaponIdToBaseWeaponId(45); // -> 40
- */
+/** Base weapon of a kit or skin: 40, 41 (Tentatek) and 45 (Hero Shot Replica) → 40. */
 export const weaponIdToBaseWeaponId = (id: MainWeaponId) =>
 	(id - (id % 10)) as MainWeaponId;
diff --git a/app/modules/patreon/updater.ts b/app/modules/patreon/updater.ts
index 58fbecdce..59605163d 100644
--- a/app/modules/patreon/updater.ts
+++ b/app/modules/patreon/updater.ts
@@ -31,7 +31,7 @@ export async function updatePatreonData(): Promise<void> {
 		noDiscordConnected.push(...parsed.noDiscordConnection);
 		noDataIds.push(...parsed.noDataIds);
 
-		// TS freaks out if we don't keep nextUrlToFetchWith string so that's why this weird thing here
+		// kept a string for TS's sake
 		nextUrlToFetchWith = patronData.links?.next ?? "";
 	}
 
diff --git a/app/modules/permissions/guards.server.ts b/app/modules/permissions/guards.server.ts
index e1bc590e1..c7d8f791f 100644
--- a/app/modules/permissions/guards.server.ts
+++ b/app/modules/permissions/guards.server.ts
@@ -2,11 +2,7 @@ import { requireUser } from "~/features/auth/core/user.server";
 import type { EntityWithPermissions, Role } from "~/modules/permissions/types";
 import { hasPermission } from "./utils";
 
-/**
- * Checks if a user has the required global role.
- *
- * @throws {Response} - Throws a 403 Forbidden response if the user does not have the required role.
- */
+/** @throws {Response} 403 if the user lacks the global role. */
 export function requireRole(role: Role) {
 	const user = requireUser();
 	if (!user.roles.includes(role)) {
@@ -14,11 +10,7 @@ export function requireRole(role: Role) {
 	}
 }
 
-/**
- * Checks if a user has the required permission to perform an action on a given entity.
- *
- * @throws {Response} - Throws a 403 Forbidden response if the user does not have the required permission.
- */
+/** @throws {Response} 403 if the user lacks the permission on the entity. */
 export function requirePermission<
 	T extends EntityWithPermissions,
 	K extends keyof T["permissions"],
diff --git a/app/modules/permissions/hooks.ts b/app/modules/permissions/hooks.ts
index 32d7a5ebb..ab0c0b991 100644
--- a/app/modules/permissions/hooks.ts
+++ b/app/modules/permissions/hooks.ts
@@ -2,11 +2,7 @@ import { useUser } from "~/features/auth/core/user";
 import type { EntityWithPermissions, Role } from "~/modules/permissions/types";
 import { hasPermission } from "./utils";
 
-/**
- * Determines whether a user has a specific global role.
- *
- * @returns A boolean indicating whether the user has the specified role. Always false if user is not logged in.
- */
+/** Whether the logged in user has the global role; false when logged out. */
 export function useHasRole(role: Role) {
 	const user = useUser();
 
@@ -15,11 +11,7 @@ export function useHasRole(role: Role) {
 	return user.roles.includes(role);
 }
 
-/**
- * Determines whether a user has a specific permission for a given entity.
- *
- * @returns A boolean indicating whether the user has the specified permission. Always false if user is not logged in.
- */
+/** Whether the logged in user has the permission on the entity; false when logged out. */
 export function useHasPermission<
 	T extends EntityWithPermissions,
 	K extends keyof T["permissions"],
diff --git a/app/modules/permissions/utils.ts b/app/modules/permissions/utils.ts
index 715744a67..fe0018a63 100644
--- a/app/modules/permissions/utils.ts
+++ b/app/modules/permissions/utils.ts
@@ -8,19 +8,14 @@ import {
 import { IS_E2E_TEST_RUN } from "~/utils/e2e";
 import type { EntityWithPermissions } from "./types";
 
-/**
- * Determines whether a user has a specific permission for a given entity.
- * Single source of truth shared by `requirePermission` and `useHasPermission`.
- *
- * @returns A boolean indicating whether the user has the specified permission. Always false if user is not logged in.
- */
+/** Shared by `requirePermission` and `useHasPermission`. False when `user` is missing. */
 export function hasPermission<
 	T extends EntityWithPermissions,
 	K extends keyof T["permissions"],
 >(obj: T, permission: K, user?: { id: number } | null) {
 	if (!user) return false;
 
-	// admin can do anything in production but not in development or e2e tests for better testing
+	// admin can do anything in production only, so dev and e2e can test permissions
 	if (
 		process.env.NODE_ENV === "production" &&
 		!IS_E2E_TEST_RUN &&
diff --git a/app/modules/persisted-state/hooks.ts b/app/modules/persisted-state/hooks.ts
index c0c9e405f..7c35b6650 100644
--- a/app/modules/persisted-state/hooks.ts
+++ b/app/modules/persisted-state/hooks.ts
@@ -7,10 +7,7 @@ import * as PersistedState from "./persisted-state";
 
 const SERVER_MAP_SNAPSHOT: Record<string, never> = {};
 
-/**
- * Typed React state backed by a persisted definition. The value stays in sync
- * across components and browser tabs; the setter accepts a value or an updater.
- */
+/** React state backed by a persisted definition, in sync across components and tabs. Setter takes a value or updater. */
 export function usePersistedState<T>(
 	definition: PersistedDefinition<T>,
 ): [T, (next: T | ((previous: T) => T)) => void] {
diff --git a/app/modules/persisted-state/persisted-state-test-utils.ts b/app/modules/persisted-state/persisted-state-test-utils.ts
index aefa88d74..e7bec0fac 100644
--- a/app/modules/persisted-state/persisted-state-test-utils.ts
+++ b/app/modules/persisted-state/persisted-state-test-utils.ts
@@ -4,11 +4,7 @@ import type {
 	PersistedMapDefinition,
 } from "./persisted-state";
 
-/**
- * Asserts `decode(encode(x))` deep-equals `x` for every given example value,
- * and that a missing value decodes to the default. Every feature definition
- * registers a test with representative and edge-case values.
- */
+/** Asserts `decode(encode(x))` deep-equals `x` for every example, and that a missing value decodes to the default. */
 export function assertRoundTrips<T>(
 	definition: PersistedDefinition<T> | PersistedMapDefinition<T>,
 	examples: NoInfer<T>[],
diff --git a/app/modules/persisted-state/persisted-state.ts b/app/modules/persisted-state/persisted-state.ts
index 6e753475c..786fd8da3 100644
--- a/app/modules/persisted-state/persisted-state.ts
+++ b/app/modules/persisted-state/persisted-state.ts
@@ -30,10 +30,8 @@ export interface PersistedMapDefinition<T> extends DefinitionBase<T> {
 }
 
 /**
- * Declares a client state persisted in web storage. One definition per stored
- * key drives reads, writes, cross-tab sync and the `usePersistedState` hook.
- * Decoding is total: the default resolves for missing or malformed values,
- * legacy plain-string values are accepted where the schema allows them.
+ * One definition per storage key drives reads, writes, cross-tab sync and `usePersistedState`. Decoding is
+ * total: missing or malformed resolves to the default, legacy plain strings are accepted where the schema allows.
  */
 export function define<S extends AnySyncSchema>(options: {
 	key: string;
@@ -49,10 +47,7 @@ export function define<S extends AnySyncSchema>(options: {
 	};
 }
 
-/**
- * Declares a keyed family of persisted values sharing a storage key prefix,
- * for maps whose entries are written independently (e.g. per chat room).
- */
+/** Keyed family sharing a storage key prefix, for entries written independently (e.g. per chat room). */
 export function defineMap<S extends AnySyncSchema>(options: {
 	keyPrefix: string;
 	storage: StorageKind;
diff --git a/app/modules/redirects/core/Redirect.ts b/app/modules/redirects/core/Redirect.ts
index 8a4077016..be9e78a73 100644
--- a/app/modules/redirects/core/Redirect.ts
+++ b/app/modules/redirects/core/Redirect.ts
@@ -1,10 +1,7 @@
 type RedirectRule = {
 	/** Path to redirect from. A trailing `/*` matches the path and anything below it. */
 	from: string;
-	/**
-	 * Path to redirect to. Ends with `/*` if `from` does, the matched suffix being appended to it.
-	 * May contain a query string, in which case the original one is merged into it.
-	 */
+	/** Ends with `/*` if `from` does (matched suffix appended). A query string here is merged with the original. */
 	to: string;
 };
 
@@ -43,11 +40,8 @@ const REDIRECTS: RedirectRule[] = [
 ];
 
 /**
- * Resolves where a location should redirect to, or null if it should be served as is.
- * The query string and the part of the path matched by a wildcard are preserved.
- *
- * @example
- * Redirect.resolve({ pathname: "/to/3325/teams/58397", search: "" }) // "/to/3192/teams/58397"
+ * Where a location redirects to, or null to serve as is. Query string and wildcard-matched path are preserved,
+ * e.g. `/to/3325/teams/58397` → `/to/3192/teams/58397`.
  */
 export function resolve(location: {
 	pathname: string;
diff --git a/app/modules/redirects/redirects-middleware.server.ts b/app/modules/redirects/redirects-middleware.server.ts
index c01f1532c..e6581cace 100644
--- a/app/modules/redirects/redirects-middleware.server.ts
+++ b/app/modules/redirects/redirects-middleware.server.ts
@@ -12,13 +12,7 @@ type MiddlewareFn = (
 	next: () => Promise<Response>,
 ) => Promise<Response>;
 
-/**
- * Redirects requests targeting a page that has moved. Runs for every kind of request
- * (documents, single fetch data requests and resource routes) so that no route needs to
- * know about the redirects.
- *
- * @see {@link Redirect.resolve}
- */
+/** Redirects moved pages for every kind of request (documents, data, resource routes), see {@link Redirect.resolve}. */
 export const redirectsMiddleware: MiddlewareFn = ({ url }, next) => {
 	const redirectTo = Redirect.resolve(url);
 	if (redirectTo) throw redirect(redirectTo);
diff --git a/app/modules/redirects/routes/$.ts b/app/modules/redirects/routes/$.ts
index f9b0dba16..232c802d3 100644
--- a/app/modules/redirects/routes/$.ts
+++ b/app/modules/redirects/routes/$.ts
@@ -9,8 +9,7 @@ export const loader = ({ request }: LoaderFunctionArgs) => {
 	throw new Response(null, { status: 404 });
 };
 
-/** Never renders (the loader always redirects or throws) but makes this a page
- * route, so the 404 shows the error page instead of a bare empty response. */
+/** Never renders (the loader always redirects or throws), but as a page route the 404 shows the error page. */
 export default function CatchAllPage() {
 	return null;
 }
diff --git a/app/modules/search-params/hooks.ts b/app/modules/search-params/hooks.ts
index f3a8c0a26..fe7440651 100644
--- a/app/modules/search-params/hooks.ts
+++ b/app/modules/search-params/hooks.ts
@@ -24,11 +24,7 @@ type SetSearchParams<Shape extends AnyShape> = (
 
 const InitialSearchContext = React.createContext<string | null>(null);
 
-/**
- * Provides the initial search string for server rendering and hydration.
- * Mounted once in the root route; the value never updates so consumers do not
- * rerender through it.
- */
+/** Initial search string for SSR and hydration. Mounted once in root; never updates so consumers don't rerender through it. */
 export function SearchParamsProvider({
 	children,
 }: {
@@ -45,13 +41,8 @@ export function SearchParamsProvider({
 }
 
 /**
- * Typed search params state for a whole definition.
- *
- * Writes are merges: params not mentioned are preserved, declared `resets`
- * are applied and values equal to their default are removed from the URL. If
- * any written param is `loader: true` the batch writes through one navigation,
- * otherwise through `history.replaceState` without triggering loaders. A write
- * known not to change loader data can force the latter with `{ loader: false }`.
+ * Writes are merges (unmentioned params preserved, `resets` applied, defaults removed). A batch with any
+ * `loader: true` param goes through one navigation, otherwise `history.replaceState`; `{ loader: false }` forces the latter.
  */
 export function useSearchParamsTyped<Shape extends AnyShape>(
 	definition: SearchParamsDefinition<Shape>,
@@ -62,10 +53,7 @@ export function useSearchParamsTyped<Shape extends AnyShape>(
 	return [values, setParams];
 }
 
-/**
- * Focused subscription to a single param of a definition: rerenders only when
- * that param's raw string value changes.
- */
+/** Rerenders only when this one param's raw string value changes. */
 export function useSearchParam<
 	Shape extends AnyShape,
 	K extends keyof Shape & string,
diff --git a/app/modules/search-params/search-params-test-utils.ts b/app/modules/search-params/search-params-test-utils.ts
index 6eaebca76..69c9e6724 100644
--- a/app/modules/search-params/search-params-test-utils.ts
+++ b/app/modules/search-params/search-params-test-utils.ts
@@ -8,12 +8,7 @@ import * as SearchParams from "./search-params";
 
 type AnyShape = Record<string, ParamDef<any>>;
 
-/**
- * Asserts `decode(encode(x))` deep-equals `x` for every given example value,
- * through both the plain and the compressed transport form, and additionally
- * through a full `href` → `parse` cycle. Every feature definition registers a
- * test with representative and edge-case values.
- */
+/** Asserts `decode(encode(x))` deep-equals `x` through plain and compressed forms and a full `href` → `parse` cycle. */
 export function assertRoundTrips<Shape extends AnyShape>(
 	definition: SearchParamsDefinition<Shape>,
 	examples: {
diff --git a/app/modules/search-params/search-params.ts b/app/modules/search-params/search-params.ts
index 41b98e27f..87fdaebc9 100644
--- a/app/modules/search-params/search-params.ts
+++ b/app/modules/search-params/search-params.ts
@@ -77,11 +77,7 @@ export interface SearchParamsDefinition<Shape extends AnyShape> {
 	shouldRevalidate: ShouldRevalidateFunction;
 }
 
-/**
- * Creates a search params definition from param declarations (see `SP.param`,
- * `SP.json` and `SP.custom`). One definition per route or feature drives
- * loader parsing, client state, href building and revalidation.
- */
+/** One definition per route/feature (from `SP.*` declarations) drives parsing, client state, hrefs and revalidation. */
 export function define<Shape extends AnyShape>(
 	shape: Shape,
 ): SearchParamsDefinition<Shape> {
@@ -157,10 +153,8 @@ export function define<Shape extends AnyShape>(
 }
 
 /**
- * Decodes one param from its raw URL values, resolving to the default when the
- * param is missing or malformed. Uses a per-param cache keyed on the raw values
- * so repeated decodes of the same string return the same reference. Params
- * declared `timeDependent` skip the cache and decode fresh every time.
+ * Decodes raw URL values, resolving to the default when missing or malformed. Cached per raw values
+ * so the same string returns the same reference; `timeDependent` params skip the cache.
  */
 export function decodeParam<T>(def: ParamDef<T>, values: string[]): T {
 	if (def.timeDependent) return def.decodeValues(values);
@@ -180,10 +174,7 @@ export function decodeParam<T>(def: ParamDef<T>, values: string[]): T {
 	return decoded;
 }
 
-/**
- * Encodes one param value to its URL values. Returns an empty array (param
- * absent) for values equal to the default.
- */
+/** Encodes to URL values; empty (param absent) for the default. */
 export function encodeParam<T>(
 	def: ParamDef<T>,
 	value: T,
@@ -195,10 +186,8 @@ export function encodeParam<T>(
 }
 
 /**
- * Applies a partial values update on top of the current search params,
- * preserving params outside the definition, applying declared `resets` and
- * omitting values equal to their defaults. A key written in the same batch is
- * never reset by another key of that batch.
+ * Merges a partial update into the current search params: outside params preserved, `resets` applied,
+ * defaults omitted. A key written in the same batch is never reset by another key of that batch.
  */
 export function applyToSearchParams<Shape extends AnyShape>(
 	definition: SearchParamsDefinition<Shape>,
@@ -239,11 +228,7 @@ export function applyToSearchParams<Shape extends AnyShape>(
 	return { next, navigationNeeded };
 }
 
-/**
- * Serializes only the definition's keys out of a search string. Used as a
- * cheap fingerprint: it changes exactly when one of the definition's params
- * changes in the URL.
- */
+/** Only the definition's keys of a search string; a fingerprint that changes exactly when one of them does. */
 export function pickRelevantSearch(keys: string[], search: string): string {
 	const searchParams = new URLSearchParams(search);
 	const picked = new URLSearchParams();
@@ -263,11 +248,7 @@ export interface ParamCodec<Value> {
 	encode: (value: Value) => string;
 }
 
-/**
- * Creates a {@link ParamCodec} whose decode result is validated against
- * `schema`. The `decode` implementation returns `undefined` (or any value the
- * schema rejects) for malformed input.
- */
+/** {@link ParamCodec} whose decode result is validated against `schema`; `decode` returns `undefined` for malformed input. */
 export function codec<TSchema extends AnySchema>(
 	schema: TSchema,
 	impl: {
@@ -284,11 +265,7 @@ export function codec<TSchema extends AnySchema>(
 	};
 }
 
-/**
- * Widens a codec to also accept `null` as its value. `null` must be the
- * param's default, so it never reaches `encode` (encoding the default omits
- * the param from the URL).
- */
+/** Widens a codec to accept `null`, which must be the default and so never reaches `encode`. */
 export function nullableCodec<Value>(
 	inner: ParamCodec<Value>,
 ): ParamCodec<Value | null> {
@@ -305,19 +282,12 @@ export function nullableCodec<Value>(
 	};
 }
 
-/**
- * Param declaration helpers. `SP.param` is the canonical declaration deriving
- * the URL encoding from the value schema; `SP.json` and `SP.custom` are the
- * explicit helpers for shapes outside the derivation table.
- */
+/** Param declarations. `SP.param` derives the encoding from the schema; `SP.json`/`SP.custom` cover the rest. */
 export const SP = {
 	/**
-	 * Declares a param whose URL encoding is derived from the valibot value
-	 * schema's type tree. Supported shapes: strings, numbers, booleans, string
-	 * and number enums/literals, same-base-type unions, arrays of those
-	 * (encoded as repeated keys) and a top-level `.nullable()` wrapper (`null`
-	 * encodes as param absent, so `default` is omitted for those). Anything else
-	 * is a `define()`-time error — use `SP.json` or `SP.custom` instead.
+	 * Encoding derived from the schema: strings, numbers, booleans, enums/literals, same-base-type unions,
+	 * arrays of those (repeated keys) and a top-level `.nullable()` (`null` = absent, no `default`).
+	 * Anything else fails at `define()` time — use `SP.json` or `SP.custom`.
 	 */
 	param<S extends AnySchema>(
 		schema: S,
@@ -399,11 +369,7 @@ export const SP = {
 		};
 	},
 
-	/**
-	 * Escape hatch: declares a param from a {@link ParamCodec} (see `codec`)
-	 * passed directly. The codec's `decode` may accept legacy formats while
-	 * `encode` always emits the canonical one.
-	 */
+	/** Escape hatch taking a {@link ParamCodec}; `decode` may accept legacy formats, `encode` emits the canonical one. */
 	custom<Value>(
 		paramCodec: ParamCodec<Value>,
 		opts: ParamOptions<Value>,
@@ -564,12 +530,7 @@ function deriveScalarBase(schema: AnySchema): ScalarBase | null {
 	return null;
 }
 
-/**
- * A pipe may only add validations, metadata and type-preserving
- * transformations (e.g. `v.trim()`) on top of its base schema. A custom
- * transform or a nested schema changes the value's type, so the URL encoding
- * cannot be derived from the base type.
- */
+/** A custom transform or nested schema changes the value's type, so the encoding can't derive from the base type. */
 function hasNonValidationPipeItems(schema: AnySchema): boolean {
 	if (!("pipe" in schema)) return false;
 
@@ -647,10 +608,7 @@ function urlEncodedLength(value: string) {
 	return new URLSearchParams([["", value]]).toString().length;
 }
 
-/**
- * Wraps a plain encoded value in the compressed transport form. Any param can
- * arrive compressed like this; used by round-trip tests and share links.
- */
+/** Compressed transport form of a plain value. Any param can arrive like this; used by round-trip tests and share links. */
 export function compressTransportValue(plain: string) {
 	return `${COMPRESSED_PREFIX}${compressToBase64(plain, { urlSafe: true })}`;
 }
diff --git a/app/modules/search-params/store.ts b/app/modules/search-params/store.ts
index 936e39fdc..1d468f6ca 100644
--- a/app/modules/search-params/store.ts
+++ b/app/modules/search-params/store.ts
@@ -3,14 +3,9 @@ const listeners = new Set<() => void>();
 let historyPatched = false;
 
 /**
- * Subscribes to changes of the current URL search string, from any write
- * channel: react-router navigations (which call `history.pushState` /
- * `history.replaceState` under the hood), our own `history.replaceState`
- * writes and back/forward navigation.
- *
- * Note that our own `history.replaceState` writes (`loader: false` params) are
- * invisible to react-router: `useLocation()` keeps returning the search string
- * of the last navigation. Read those params through this module's hooks.
+ * Fires on any search string change: react-router navigations, our own `history.replaceState` writes and
+ * back/forward. Our `replaceState` writes (`loader: false`) are invisible to `useLocation()`, so read those
+ * params through this module's hooks.
  */
 export function subscribe(listener: () => void) {
 	patchHistoryOnce();
diff --git a/app/modules/tournament-map-list-generator/balanced-map-list.ts b/app/modules/tournament-map-list-generator/balanced-map-list.ts
index 43e0fcdb4..30f56de1a 100644
--- a/app/modules/tournament-map-list-generator/balanced-map-list.ts
+++ b/app/modules/tournament-map-list-generator/balanced-map-list.ts
@@ -22,10 +22,7 @@ type MapListGenerationError =
 	| "MAPS_FOR_MODES_NOT_INCLUDED"
 	| "DUPLICATE_MAPS_IN_MAP_POOL";
 
-/**
- * Generates a map list balanced between the two teams' map pools. If generation fails
- * due to the recently played maps consideration, retries once without it.
- */
+/** Map list balanced between both teams' pools. Retries once without the recently played maps consideration if it fails. */
 export function generateBalancedMapList(
 	input: TournamentMaplistInput,
 ): Result<Array<TournamentMapListMap>, MapListGenerationError> {
@@ -55,8 +52,7 @@ function generateWithInput(
 	if (validationError) return err(validationError);
 
 	const { seededShuffle } = seededRandom(input.seed);
-	// trying the least recently played maps first lets the search find a good
-	// enough list before the recursion depth cap is hit
+	// least recently played first so a good enough list is found before the recursion depth cap
 	const stages = seededShuffle(resolveCommonStages()).sort(
 		(a, b) => recencyPenalty(a) - recencyPenalty(b),
 	);
@@ -92,8 +88,7 @@ function generateWithInput(
 						source: "TIEBREAKER" as const,
 					}));
 
-		// tiebreaker/fallback lists at the last slot get their own key range so
-		// their indices don't collide with the picked indices of the main list
+		// tiebreaker/fallback lists get their own key range so indices don't collide with the main list
 		const usedStageKeyOffset = stageList === stages ? 0 : stages.length;
 
 		for (const [i, stage] of stageList.entries()) {
@@ -114,8 +109,7 @@ function generateWithInput(
 
 	const searchExhausted = backtrack();
 
-	// a complete list found before the depth cap was hit is still valid,
-	// only its optimality is unproven
+	// a list found before the depth cap is valid, only its optimality is unproven
 	if (bestMapList.maps) return ok(bestMapList.maps);
 	if (!searchExhausted) return err("MAX_RECURSION_DEPTH_EXCEEDED");
 
@@ -163,8 +157,7 @@ function generateWithInput(
 			input.teams[0].maps.stages.length === 0 ||
 			input.teams[1].maps.stages.length === 0
 		) {
-			// let's set it up for later that if one team doesn't have stages set
-			// we can make a maplist consisting of only stages from the team that did submit
+			// if one team didn't submit, the list can consist of only the other team's stages
 			for (const stageObj of result) {
 				stageObj.score = 0;
 			}
@@ -271,9 +264,7 @@ function generateWithInput(
 		"score" | "stageId" | "mode" | "source"
 	>;
 
-	// adding rules here can achieve to things
-	// 1) adjust what kind of map list is generated
-	// 2) optimize the algorithm my eliminating subtrees from consideration
+	// rules here both shape the generated list and prune subtrees from the search
 	function stageIsOk(stage: StageValidatorInput, index: number) {
 		if (usedStages.has(index)) return false;
 		if (mapListAlreadyFull()) return false;
@@ -349,15 +340,8 @@ function generateWithInput(
 
 	// don't allow making two picks from one team in row
 	function isMakingThingsUnfair(stage: StageValidatorInput) {
-		// allow to handle edge case where both teams have 100% overlap in one mode
-		// but not others in Bo5 for example could make impossible to make map because e.g.
-		// 1) overlap
-		// 2) team 1 pick
-		// 3) team 2 pick
-		// 4) team 1 pick
-		// 5) TIEBREAKER <- system has to allow
-		// ---
-		// but later we will with score make sure that we exhaust better options too
+		// e.g. Bo5 with 100% overlap in one mode only: overlap, T1, T2, T1, TIEBREAKER must be allowed;
+		// scoring still prefers better options
 		if (stage.source === "TIEBREAKER") return false;
 
 		const score = mapList.reduce((acc, cur) => acc + cur.score, 0);
@@ -404,11 +388,10 @@ function generateWithInput(
 				),
 		);
 
-		// there was at least one possible common map
-		// to pick as tiebreaker but it (or they) got picked too early
+		// a common map for the tiebreaker existed but got picked too early
 		return (
 			commonMaps.length > 0 &&
-			// handles special case where both teams have the same maps in their pool
+			// both teams having identical pools
 			commonMaps.length !== input.teams[0].maps.stageModePairs.length &&
 			newCommonMaps.length === 0 &&
 			newMapList.length !== input.count
diff --git a/app/modules/tournament-map-list-generator/generation.test.ts b/app/modules/tournament-map-list-generator/generation.test.ts
index 9b75267eb..55a84fbc0 100644
--- a/app/modules/tournament-map-list-generator/generation.test.ts
+++ b/app/modules/tournament-map-list-generator/generation.test.ts
@@ -240,7 +240,6 @@ describe("Tournament map list generator", () => {
 		expect(mapList.length).toBe(5);
 
 		for (let i = 0; i < mapList.length - 1; i++) {
-			// map belongs to team 2 map list
 			const map = mapList[i];
 			expect(map).toBeTruthy();
 
@@ -465,7 +464,6 @@ describe("Tournament map list generator", () => {
 
 	// paddling pool 264
 	test("handles 100% overlap in one mode and none in others", () => {
-		// should not throw
 		generateMaps({
 			count: 5,
 			followModeOrder: false,
diff --git a/app/modules/tournament-map-list-generator/starter-map.ts b/app/modules/tournament-map-list-generator/starter-map.ts
index 593d55195..6028fe445 100644
--- a/app/modules/tournament-map-list-generator/starter-map.ts
+++ b/app/modules/tournament-map-list-generator/starter-map.ts
@@ -1,6 +1,4 @@
-// if one mode -> try to find common, otherwise something neither picked
-// if a tie breaker -> random tiebreaker
-// seed = always same
+// one mode: a common map, else one neither picked; tiebreaker: random; seeded
 
 import { stageIds } from "~/modules/in-game-lists/stage-ids";
 import { logger } from "~/utils/logger";
@@ -48,8 +46,7 @@ export function starterMap(args: StarterMapArgs): Array<TournamentMapListMap> {
 		];
 	}
 
-	// should be only one mode here always but just in case
-	// making it capable of handling many modes too
+	// should only ever be one mode, but handles many just in case
 	const allAvailableMaps = seededShuffle(
 		args.modesIncluded
 			.sort((a, b) => modesShort.indexOf(a) - modesShort.indexOf(b))
diff --git a/app/modules/tournament-map-list-generator/types.ts b/app/modules/tournament-map-list-generator/types.ts
index e576ea2f1..5c521f62e 100644
--- a/app/modules/tournament-map-list-generator/types.ts
+++ b/app/modules/tournament-map-list-generator/types.ts
@@ -23,10 +23,7 @@ export interface TournamentMaplistInput {
 
 export type TournamentMaplistSource = number | (typeof sourceTypes)[number];
 
-/**
- * How {@link TournamentMaplistSource} is stored in the database: one of the source types, or the
- * picking team's id in its string form. Convert with `serializeMaplistSource`/`parseMaplistSource`.
- */
+/** {@link TournamentMaplistSource} as stored: a source type or the picking team's id as a string. See `serializeMaplistSource`/`parseMaplistSource`. */
 export type DBTournamentMaplistSource =
 	| (typeof sourceTypes)[number]
 	// the team id, kept plain `string` so it survives Kysely's JSON helpers rewriting `${number}` to `number`
diff --git a/app/modules/twitch/streams.ts b/app/modules/twitch/streams.ts
index 3ab266ef9..0c793a526 100644
--- a/app/modules/twitch/streams.ts
+++ b/app/modules/twitch/streams.ts
@@ -6,77 +6,12 @@ import { logger } from "~/utils/logger";
 import { twitchFetch } from "./fetch";
 import { type RawStream, type StreamsResponse, streamsSchema } from "./schemas";
 
-// const STREAMS_MOCK = [
-//   {
-//     thumbnailUrl:
-//       "https://static-cdn.jtvnw.net/previews-ttv/live_user_777_jared-{width}x{height}.jpg",
-//     twitchUserName: "777_jared",
-//     viewerCount: 129,
-//   },
-//   {
-//     thumbnailUrl:
-//       "https://static-cdn.jtvnw.net/previews-ttv/live_user_ano_rta-{width}x{height}.jpg",
-//     twitchUserName: "ano_rta",
-//     viewerCount: 50,
-//   },
-//   {
-//     thumbnailUrl:
-//       "https://static-cdn.jtvnw.net/previews-ttv/live_user_mikashita0104-{width}x{height}.jpg",
-//     twitchUserName: "mikashita0104",
-//     viewerCount: 49,
-//   },
-//   {
-//     thumbnailUrl:
-//       "https://static-cdn.jtvnw.net/previews-ttv/live_user_veenam-{width}x{height}.jpg",
-//     twitchUserName: "veenam",
-//     viewerCount: 42,
-//   },
-//   {
-//     thumbnailUrl:
-//       "https://static-cdn.jtvnw.net/previews-ttv/live_user_minijutopia-{width}x{height}.jpg",
-//     twitchUserName: "minijutopia",
-//     viewerCount: 25,
-//   },
-//   {
-//     thumbnailUrl:
-//       "https://static-cdn.jtvnw.net/previews-ttv/live_user_liligravybread-{width}x{height}.jpg",
-//     twitchUserName: "liligravybread",
-//     viewerCount: 25,
-//   },
-//   {
-//     thumbnailUrl:
-//       "https://static-cdn.jtvnw.net/previews-ttv/live_user_ajx_live-{width}x{height}.jpg",
-//     twitchUserName: "ajx_live",
-//     viewerCount: 19,
-//   },
-//   {
-//     thumbnailUrl:
-//       "https://static-cdn.jtvnw.net/previews-ttv/live_user_yuzuki729-{width}x{height}.jpg",
-//     twitchUserName: "yuzuki729",
-//     viewerCount: 18,
-//   },
-//   {
-//     thumbnailUrl:
-//       "https://static-cdn.jtvnw.net/previews-ttv/live_user_noname_nosplat-{width}x{height}.jpg",
-//     twitchUserName: "noname_nosplat",
-//     viewerCount: 14,
-//   },
-//   {
-//     thumbnailUrl:
-//       "https://static-cdn.jtvnw.net/previews-ttv/live_user_dosankoneet-{width}x{height}.jpg",
-//     twitchUserName: "dosankoneet",
-//     viewerCount: 13,
-//   },
-// ];
-
 export async function getStreams() {
 	try {
 		const result = await cachified({
 			key: "twitch-streams",
 			cache,
-			// 2 minutes
 			ttl: 1000 * 60 * 2,
-			// 10 minutes
 			staleWhileRevalidate: 1000 * 60 * 5 * 2,
 			async getFreshValue() {
 				return (await getAllStreams())
@@ -115,7 +50,6 @@ async function getAllStreams() {
 		const { data, pagination } = await getStreamsChunk(cursor);
 
 		result.push(
-			// filter to ensure each streamer appears only once
 			...data.filter(
 				(stream) =>
 					!result.some(
diff --git a/app/root.tsx b/app/root.tsx
index 4a6344691..f9076822a 100644
--- a/app/root.tsx
+++ b/app/root.tsx
@@ -99,9 +99,8 @@ import "~/styles/utils.css";
 import "~/styles/flags.css";
 import "nprogress/nprogress.css";
 
-// Anchor the loading bar to the header so it sits between the sidebars. Set at
-// module scope (not in an effect) so the very first navigation's NProgress.start
-// already targets the header instead of briefly rendering over the sidebar.
+// anchors the loading bar to the header (between the sidebars); at module scope so
+// even the very first navigation's NProgress.start doesn't render over the sidebar
 NProgress.configure({ parent: `#${NPROGRESS_ANCHOR_ID}` });
 
 type DevFaviconColors = { fill: string; stroke: string };
@@ -296,11 +295,7 @@ function Document({
 
 const ABSOLUTE_URL_REGEX = /^[a-z][a-z\d+\-.]*:/i;
 
-/**
- * Href every React Aria link (menu items, buttons, tabs) is rendered with.
- * `useHref` resolves its argument against the current route, which would turn an
- * absolute URL such as a Twitch link into a path of our own.
- */
+/** Href for React Aria links: `useHref` would resolve an absolute URL like a Twitch link into a path of our own. */
 function useExternalAwareHref(href: string) {
 	const resolved = useHref(href);
 
@@ -499,9 +494,8 @@ function HydrationTestIndicator() {
 			data-testid="hydrated"
 			data-router-idle={routerIdle ? "true" : undefined}
 			data-router-busy={routerIdle ? undefined : busy.join(" | ")}
-			// the rendered search, trailing the browser's own by a commit: only
-			// once the toast params are gone from here have the forms keyed on
-			// the location (see SendouForm) finished remounting
+			// the rendered search trails the browser's by a commit: once the toast params are
+			// gone from here the forms keyed on the location (see SendouForm) have remounted
 			data-location-search={location.search}
 		/>
 	);
diff --git a/app/routines/computeLutiDivs.ts b/app/routines/computeLutiDivs.ts
index 324beb29a..0e86e8b1b 100644
--- a/app/routines/computeLutiDivs.ts
+++ b/app/routines/computeLutiDivs.ts
@@ -9,10 +9,8 @@ import { Routine } from "./routine.server";
 export const LUTI_NAME_PREFIX = "LUTI";
 
 /**
- * Recomputes `User.div` (the user's division in the latest finished LUTI). Looks at the most recent
- * finalized LUTI season and sets the division for every eligible participant (on a team that did
- * not drop out and played at least one match). Users not in that season keep their previous
- * division. Idempotent.
+ * Recomputes `User.div` from the latest finalized LUTI season for every eligible participant (team
+ * did not drop out, played at least one match). Others keep their previous division. Idempotent.
  */
 export const ComputeLutiDivsRoutine = new Routine({
 	name: "ComputeLutiDivs",
diff --git a/app/routines/list.server.ts b/app/routines/list.server.ts
index 057b7c167..d86004b67 100644
--- a/app/routines/list.server.ts
+++ b/app/routines/list.server.ts
@@ -27,7 +27,7 @@ import { SyncTournamentVodsRoutine } from "./syncTournamentVods";
 import { UpdatePatreonDataRoutine } from "./updatePatreonData";
 import { VacuumDatabaseRoutine } from "./vacuumDatabase";
 
-/** List of Routines that should occur hourly at XX:00 */
+/** hourly at XX:00 */
 export const everyHourAt00 = [
 	NotifySeasonStartRoutine,
 	NotifyPlusServerVotingRoutine,
@@ -37,7 +37,7 @@ export const everyHourAt00 = [
 	SyncTournamentVodsRoutine,
 ];
 
-/** List of Routines that should occur hourly at XX:30 */
+/** hourly at XX:30 */
 export const everyHourAt30 = [
 	SetOldGroupsAsInactiveRoutine,
 	UpdatePatreonDataRoutine,
@@ -47,7 +47,6 @@ export const everyHourAt30 = [
 	ResolveStaleSQMatchesRoutine,
 ];
 
-/** List of Routines that should occur daily */
 export const daily = [
 	NotifySeasonEndRoutine,
 	DeleteObsoleteMatchVodsRoutine,
@@ -64,10 +63,8 @@ export const daily = [
 	OptimizeDatabaseRoutine,
 ];
 
-/** List of Routines that should occur weekly */
 export const weekly = [VacuumDatabaseRoutine];
 
-/** List of Routines that should occur every 2 minutes */
 export const everyTwoMinutes = [
 	SyncLiveStreamsRoutine,
 	ExpireReadyChecksRoutine,
diff --git a/app/routines/notifyScheduleTeamReminder.ts b/app/routines/notifyScheduleTeamReminder.ts
index 5caf3d332..a2917f357 100644
--- a/app/routines/notifyScheduleTeamReminder.ts
+++ b/app/routines/notifyScheduleTeamReminder.ts
@@ -5,11 +5,7 @@ import { notify } from "../features/notifications/core/notify.server";
 import { logger } from "../utils/logger";
 import { Routine } from "./routine.server";
 
-/**
- * Reminds users whose teammates have reported the week that just started while
- * they have not. Runs on Mondays only, which is also what keeps it to at most
- * one reminder per user per week.
- */
+/** Reminds users whose teammates reported the week that just started while they have not. Mondays only, so at most one reminder per week. */
 export const NotifyScheduleTeamReminderRoutine = new Routine({
 	name: "NotifyScheduleTeamReminder",
 	func: async () => {
diff --git a/app/routines/syncLiveStreams.test.ts b/app/routines/syncLiveStreams.test.ts
index ad15e7a79..b9ccbde98 100644
--- a/app/routines/syncLiveStreams.test.ts
+++ b/app/routines/syncLiveStreams.test.ts
@@ -42,11 +42,7 @@ function findAllLiveStreams() {
 	return db.selectFrom("LiveStream").selectAll().execute();
 }
 
-/**
- * A tournament the sync routine considers live: its teams are in the database,
- * which is where the routine looks up their members' Twitch accounts, and the
- * tournament itself is in the running tournaments registry.
- */
+/** A tournament the routine considers live: teams in the database (for members' Twitch accounts) and in the running tournaments registry. */
 async function addRunningTournament({
 	memberUserIds = [],
 	castTwitchAccounts = [],
diff --git a/app/routines/syncTournamentVods.test.ts b/app/routines/syncTournamentVods.test.ts
index c9e01e004..9547be574 100644
--- a/app/routines/syncTournamentVods.test.ts
+++ b/app/routines/syncTournamentVods.test.ts
@@ -245,10 +245,8 @@ function twitchVideo({
 }
 
 /**
- * A played out double elimination bracket of four one-player teams, its first
- * round backdated to the times the VODs are matched against and optionally
- * streamed by a cast account. Later matches start at the current time, far from
- * any mocked VOD.
+ * Played out double elimination bracket of four one-player teams, first round backdated to the
+ * VOD times and optionally cast. Later matches start now, far from any mocked VOD.
  */
 async function seedTournamentWithMatches({
 	castedOn,
diff --git a/app/routines/vacuumDatabase.ts b/app/routines/vacuumDatabase.ts
index 72cd9f874..82847b6f6 100644
--- a/app/routines/vacuumDatabase.ts
+++ b/app/routines/vacuumDatabase.ts
@@ -7,15 +7,10 @@ import { Routine } from "./routine.server";
 const BYTES_IN_MB = 1024 * 1024;
 
 /**
- * Rewrites the database file so the space that deletes and dropped columns leave behind as
- * partially filled pages is given back to the disk. Ordinary traffic frees very little of it,
- * the freelist stays in the single digit megabytes, so what this actually collects is the
- * fragmentation left by migrations that drop a wide column or a large index.
- *
- * Readers are unaffected because WAL serves them the pre-vacuum snapshot, but writers block
- * for the whole rewrite and `busy_timeout` is 5s, which the rewrite outlasts. It is scheduled
- * for a quiet hour for that reason, and the write errors it can cause there are the reason it
- * is weekly rather than daily.
+ * Rewrites the database file to reclaim fragmentation, mostly from migrations that drop a wide
+ * column or a large index (ordinary traffic keeps the freelist in single digit MB). Readers keep
+ * the pre-vacuum WAL snapshot but writers block for the whole rewrite, longer than the 5s
+ * `busy_timeout`, hence a quiet hour and weekly rather than daily.
  */
 export const VacuumDatabaseRoutine = new Routine({
 	name: "VacuumDatabase",
diff --git a/app/styles/common.css b/app/styles/common.css
index 61e945890..135c8b4db 100644
--- a/app/styles/common.css
+++ b/app/styles/common.css
@@ -640,13 +640,10 @@
 	}
 }
 
-/* Track that NProgress renders its bar into (see NPROGRESS_ANCHOR_ID). It is a
- * child of the header positioned just below the header's 1.5px bottom border, so
- * it follows the header on scroll and in standalone (PWA) mode. It spans only the
- * header width (the area between the sidebars), and its overflow: hidden clips the
- * bar — which NProgress slides in from the left — so the bar can never extend over
- * a sidebar. Unlayered + id selector so it beats NProgress's own unlayered
- * .nprogress-custom-parent rules (and the @layer-wrapped CSS modules). */
+/* NProgress track (see NPROGRESS_ANCHOR_ID): a header child just below its 1.5px bottom border so
+ * it follows the header on scroll and in PWA mode, spanning only the area between the sidebars
+ * with overflow: hidden so the bar never slides over a sidebar. Unlayered id selector so it beats
+ * NProgress's own unlayered .nprogress-custom-parent rules. */
 #nprogress-anchor {
 	position: absolute;
 	top: calc(100% + 1.5px);
diff --git a/app/styles/vars.css b/app/styles/vars.css
index 6ff78c825..ae3b23913 100644
--- a/app/styles/vars.css
+++ b/app/styles/vars.css
@@ -1,24 +1,13 @@
 @layer reset, base, elements, components, features, utilities;
 
-/*
-⚠️⚠️⚠️
-Make sure to read styles.md before editing colors in this file,
-it contains important information about how the styles work and how to edit them properly
-⚠️⚠️⚠️
-*/
+/* ⚠️ Read styles.md before editing colors in this file */
 
 /*
-All the tokens that can be set by custom themes 
-and their default values are defined here
+Tokens settable by custom themes and their defaults. Not to be consumed directly, only as a base
+for other vars. Hue and chroma values are generated with oklch-gamut.ts, do not edit by hand.
 
-These should not be consumed directly, only used as a base for other vars!
-
-The hue and chroma values should not be edited manually, instead
-use oklch-gamut.ts to generate valid color palettes!
-
-A subtree can force a color scheme regardless of the html class with
-[data-theme="dark"|"light"] and opt out of an active custom theme with
-[data-default-theme] (e.g. image export previews)
+A subtree can force a color scheme with [data-theme="dark"|"light"] and opt out of an active
+custom theme with [data-default-theme] (e.g. image export previews)
 */
 html,
 [data-default-theme] {
@@ -54,33 +43,24 @@ html,
 
 	--_border-width: 2;
 
-	/*
-	Ommited from being overridden when viewing a page that loads a custom theme
-	to prevent accessibility issues and layout shifts
-	*/
+	/* not overridable by custom themes to prevent accessibility issues and layout shifts */
 	--_size-field: 1;
 	--_size-selector: 1;
 	--_size-spacing: 1;
 }
 
 /*
-'low' and 'high' do not indicate lightness!
-This is important because dark goes from light to dark, and light goes from dark to light
+'low' and 'high' do not indicate lightness: dark goes light to dark, light goes dark to light.
 
---color-base-x should rarely be consumed directly
-They mostly exist as a base for other vars like --color-text and --color-bg
+--color-base-x is rarely consumed directly, it is the base for vars like --color-text and --color-bg.
 
---color-text-accent and --color-text-second can be used as a background
-or highlight color that maintains a high contrast ratio in both light and dark modes
-If used as a background color, --color-text-inverse should be used as the text color
+--color-text-accent and --color-text-second keep high contrast as a background or highlight in
+both modes; pair with --color-text-inverse as the text color.
 
-Info, success, warning, and error colors:
-Preffer using --color-x-high for text
-It is recommended to use --color-x-low as the background to ensure a high contrast ratio
-You can use --color-x for things like borders and icons
+Info, success, warning, error: --color-x-high for text, --color-x-low for backgrounds,
+--color-x for borders and icons.
 
-Field icons are defined for both dark and light mode because SVGs
-cannot use currentColor inside data URLs
+Field icons are defined per mode because SVGs cannot use currentColor inside data URLs.
 
 Any changes here NEED to be reflected in oklch-gamut.ts as well
 */
@@ -194,9 +174,7 @@ html.light [data-custom-theme],
 	--field-icon-time: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='rgb(90, 90, 90)' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='12' cy='12' r='10'%3E%3C/circle%3E%3Cpolyline points='12 6 12 12 16 14'%3E%3C/polyline%3E%3C/svg%3E");
 }
 
-/*
-These are the vars you mainly want to use
-*/
+/* the vars you mainly want to use */
 html,
 /* biome-ignore lint/style/noDescendingSpecificity: [data-custom-theme] and [data-theme] re-declare theme vars for subtrees; different properties than the html.dark/light blocks so no real override */
 [data-custom-theme],
@@ -241,9 +219,7 @@ html,
 
 	--line-height: 1.5;
 
-	/*
-	Tokens used for spacings
-	*/
+	/* spacing */
 	--s-0-5: calc(var(--_size-spacing) * 0.5 * 0.25rem);
 	--s-1: calc(var(--_size-spacing) * 1 * 0.25rem);
 	--s-1-5: calc(var(--_size-spacing) * 1.5 * 0.25rem);
@@ -261,14 +237,8 @@ html,
 	--s-32: calc(var(--_size-spacing) * 32 * 0.25rem);
 
 	/*
-	Tokens used to define layout dimensions
-
-	--layout-sticky-top can be used by any element with position: sticky
-	that sticks relative to the document scroll to ensure 
-	a smooth transition between sticking and un-sticking
-
-	Elements with position: sticky that do not stick relative
-	to the document scroll do not need to use this var
+	layout dimensions; --layout-sticky-top is for position: sticky elements sticking relative
+	to the document scroll, for a smooth transition between sticking and un-sticking
 	*/
 	--layout-nav-height: 55px;
 	--layout-sidenav-width: 250px;
@@ -280,16 +250,10 @@ html,
 		env(safe-area-inset-top)
 	);
 
-	/* 
-	Boxes are elements that contain other elements, like cards, containers, and modals
-	but can also be top level elements in a visual hierarchy
-
-	Fields are interactive elements like buttons, inputs, and selects
-	but also any child of a box that is interactable or contains content
-
-	Selectors are elements like checkboxes, radio buttons, and toggles
-	but can also be any small element like bages, tags, and pills
-	that are complementary to fields
+	/*
+	Boxes contain other elements (cards, containers, modals). Fields are interactive elements
+	(buttons, inputs, selects) or any interactable/content child of a box. Selectors are small
+	elements complementary to fields (checkboxes, toggles, badges, tags, pills).
 	*/
 	--field-size-xs: calc(var(--_size-field) * 6 * 0.25rem);
 	--field-size-sm: calc(var(--_size-field) * 8 * 0.25rem);
diff --git a/app/test-setup.ts b/app/test-setup.ts
index c9d2aa2a9..8b81993cc 100644
--- a/app/test-setup.ts
+++ b/app/test-setup.ts
@@ -1,9 +1,8 @@
 import { afterEach, vi } from "vitest";
 import { isDatabaseDirty } from "~/db/write-tracker";
 
-// Wipes the database after any test that wrote to it, so no test has to remember to.
-// The flag keeps this free for the tests that never touch the database — importing
-// `~/db/reset` would open the connection for them too, hence the dynamic import.
+// wipes the database after any test that wrote to it; the dynamic import keeps
+// tests that never touch the database from opening the connection
 afterEach(async () => {
 	if (!isDatabaseDirty()) return;
 
@@ -11,8 +10,7 @@ afterEach(async () => {
 	await dbReset();
 });
 
-// mocking the AWS SDK avoids a "Cannot find module '@aws-sdk/core/dist-es/submodules/client/index'"
-// error in unit tests, can be deleted if they pass without these
+// avoids a "Cannot find module '@aws-sdk/core/dist-es/submodules/client/index'" error, delete if tests pass without
 
 vi.mock("@aws-sdk/client-s3", () => ({
 	S3: vi.fn(() => ({})),
diff --git a/app/utils/Test.ts b/app/utils/Test.ts
index 2a095ce97..c6ac12acf 100644
--- a/app/utils/Test.ts
+++ b/app/utils/Test.ts
@@ -17,11 +17,7 @@ import {
 import type { AnySchema } from "~/utils/schema";
 import { logger } from "./logger";
 
-/**
- * The user a wrapped action/loader call runs as: one of the pinned seed users,
- * or any user's id — scenario tests' users are participants and staff the test
- * itself created, not fixed ids.
- */
+/** User a wrapped action/loader runs as: a pinned seed user or any user id (e.g. one the test created). */
 export type TestUser = "admin" | "regular" | number;
 
 export function arrayContainsSameItems<T>(arr1: T[], arr2: T[]) {
@@ -30,40 +26,26 @@ export function arrayContainsSameItems<T>(arr1: T[], arr2: T[]) {
 	);
 }
 
-/**
- * Runs `fn` inside the user AsyncLocalStorage store so that repository functions
- * resolving the actor via `actorId()` / `actorIdOrNull()` see the user as the acting
- * one. Use in direct repository unit tests, which run outside a request.
- *
- * An id is all it takes: repositories read the actor solely through `actorId()`.
- */
+/** Runs `fn` with the user as the actor (`actorId()` / `actorIdOrNull()`), for repository tests outside a request. */
 export function withUserId<T>(id: number, fn: () => T): T {
 	return actAs(id, fn);
 }
 
-/**
- * Runs `fn` inside a user AsyncLocalStorage store with no acting user, mirroring an
- * anonymous visitor's request. Repository functions resolving the actor via
- * `actorIdOrNull()` then see `null`, as they would inside a real request context.
- */
+/** Runs `fn` with no acting user (`actorIdOrNull()` is `null`), like an anonymous visitor's request. */
 export function withNoUser<T>(fn: () => T): T {
 	return userAsyncLocalStorage.run({ user: undefined }, fn);
 }
 
 /**
- * Wraps an action function to provide a strongly-typed, reusable handler for executing actions
- * in unit tests as if it was a normal function. The returned function allows you to pass
- * parameters that match the schema defined by the action, and it simulates a request with
- * authentication headers based on the provided user type.
+ * Wraps an action into a typed function for unit tests: takes the schema's output as args and
+ * simulates a request authenticated as the given user.
  *
  * @example
- * import { someAction } from "../actions/some.action.server";
- *
  * const someAction = wrappedAction<typeof someActionSchema>({ action });
  */
 export function wrappedAction<T extends AnySchema>({
 	action,
-	/** Is this action submitted as json (via SendouForm) */
+	/** submitted as json (via SendouForm) */
 	isJsonSubmission = false,
 }: {
 	action: (args: ActionFunctionArgs) => any;
@@ -107,11 +89,10 @@ export function wrappedAction<T extends AnySchema>({
 
 				return response;
 			} catch (thrown) {
-				// we only log errors in vitest for failed tests so this is okay (more context)
+				// vitest only shows logs for failed tests, so this just adds context
 				logger.error("Error in wrappedAction:", thrown);
 
 				if (thrown instanceof Response) {
-					// it was a redirect
 					if (thrown.status === 302) return thrown;
 
 					throw new Error(`Response thrown with status code: ${thrown.status}`);
@@ -173,12 +154,7 @@ export function wrappedLoader<T>({
 	};
 }
 
-/**
- * Asserts that the given response errored out (with a toast message, via `errorToastIfFalsy(cond)` call)
- *
- * @param response - The HTTP response object to check.
- * @param message - Optional. The expected error toast message shown to the user.
- */
+/** Asserts the response is an error toast redirect (via `errorToastIfFalsy` etc.), optionally with the given message. */
 export function assertResponseErrored(response: Response, message?: string) {
 	if (!response) {
 		throw new Error(`Expected a Response, got: ${response}`);
diff --git a/app/utils/arrays.ts b/app/utils/arrays.ts
index a206936a7..dadcd93cf 100644
--- a/app/utils/arrays.ts
+++ b/app/utils/arrays.ts
@@ -16,12 +16,7 @@ export function nullFilledArray(size: number): null[] {
 	return new Array(size).fill(null);
 }
 
-/**
- * Calculates the average of an array of numbers. If the array is empty, returns null.
- *
- * @param values - An array of numbers to calculate the average of.
- * @returns The average of the numbers in the array, or null if the array is empty.
- */
+/** Average of the numbers, null for an empty array. */
 export function nullifyingAvg(values: number[]) {
 	if (values.length === 0) return null;
 	return values.reduce((acc, cur) => acc + cur, 0) / values.length;
@@ -78,20 +73,7 @@ export function mostPopularArrayElement<T>(arr: T[]): T | null {
 	return mostPopularElement;
 }
 
-/**
- * Safely zips two arrays together by alternating elements. If arrays have different lengths,
- * zips as much as possible, then appends remaining elements from the longer array.
- *
- * @param arr1 - The first array
- * @param arr2 - The second array
- * @returns Alternating elements from both arrays: [arr1[0], arr2[0], arr1[1], arr2[1], ...]
- *          followed by any remaining elements from the longer array
- *
- * @example
- * zipSafe([1, 2], ['a', 'b']) // [1, 'a', 2, 'b']
- * zipSafe([1, 2], ['a', 'b', 'c']) // [1, 'a', 2, 'b', 'c']
- * zipSafe([1, 2, 3], ['a', 'b']) // [1, 'a', 2, 'b', 3]
- */
+/** Alternates elements of both arrays, then appends the longer array's rest: `flatZip([1, 2, 3], ['a']) → [1, 'a', 2, 3]`. */
 export function flatZip<T, U>(arr1: T[], arr2: U[]): Array<T | U> {
 	const result: Array<T | U> = [];
 	const minLength = Math.min(arr1.length, arr2.length);
diff --git a/app/utils/compression.ts b/app/utils/compression.ts
index 09a671893..e00031083 100644
--- a/app/utils/compression.ts
+++ b/app/utils/compression.ts
@@ -1,9 +1,6 @@
 import { deflateSync, Inflate, strToU8 } from "fflate";
 
-/**
- * Compresses a string with raw deflate and encodes the result as base64.
- * With `urlSafe` the output uses the URL-safe base64 alphabet without padding.
- */
+/** Raw deflate + base64; `urlSafe` uses the URL-safe alphabet without padding. */
 export function compressToBase64(
 	value: string,
 	options?: { urlSafe?: boolean },
@@ -22,10 +19,8 @@ export function compressToBase64(
 }
 
 /**
- * Decompresses a base64 encoded (standard or URL-safe alphabet) raw deflate
- * string. Returns `null` if the input is corrupt or, when
- * `maxDecompressedBytes` is given, if it inflates past that limit (a
- * decompression bomb guard for attacker controlled input).
+ * Inverse of {@link compressToBase64} (either alphabet). `null` for corrupt input or when it
+ * inflates past `maxDecompressedBytes` (decompression bomb guard for attacker controlled input).
  */
 export function decompressFromBase64(
 	compressed: string,
diff --git a/app/utils/dates.test.ts b/app/utils/dates.test.ts
index b9b46b1b3..657554500 100644
--- a/app/utils/dates.test.ts
+++ b/app/utils/dates.test.ts
@@ -26,8 +26,7 @@ describe("getDateAtNextFullHour", () => {
 });
 
 describe("weekNumberToDate", () => {
-	// Force a timezone west of UTC so the assertion is deterministic regardless
-	// of where the test happens to run (the bug only manifests west of UTC).
+	// the bug only manifests west of UTC
 	const originalTimezone = process.env.TZ;
 	beforeAll(() => {
 		process.env.TZ = "America/Los_Angeles";
@@ -52,8 +51,7 @@ describe("weekNumberToDate", () => {
 });
 
 describe("weekNumberToDateRange", () => {
-	// Force a timezone west of UTC observing DST so the assertion is deterministic
-	// regardless of where the test happens to run.
+	// a timezone west of UTC observing DST
 	const originalTimezone = process.env.TZ;
 	beforeAll(() => {
 		process.env.TZ = "America/New_York";
@@ -65,8 +63,7 @@ describe("weekNumberToDateRange", () => {
 	const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
 
 	test("spans exactly seven days even when the week contains a DST transition", () => {
-		// US spring-forward 2025 happened on Sunday 2025-03-09, which falls inside
-		// ISO week 10 of 2025 (Mon 2025-03-03 .. Mon 2025-03-10).
+		// US spring-forward Sunday 2025-03-09 falls inside ISO week 10 (Mon 03-03 .. Mon 03-10)
 		const { startTime, endTime } = weekNumberToDateRange({
 			week: 10,
 			year: 2025,
diff --git a/app/utils/dates.ts b/app/utils/dates.ts
index 2bbf4d69b..37d184e93 100644
--- a/app/utils/dates.ts
+++ b/app/utils/dates.ts
@@ -33,11 +33,7 @@ const LOCALE_LOADERS: Record<LanguageCode, () => Promise<Locale>> = {
 
 const loadedLocales = new Map<LanguageCode, Locale>();
 
-/**
- * Loads the date-fns locale for the given language into the in-memory cache
- * used by {@link formatDistanceToNow}. Load failures are logged and result in
- * an English fallback instead of rejecting.
- */
+/** Caches the date-fns locale for {@link formatDistanceToNow}; a load failure is logged and falls back to English. */
 export async function loadDateFnsLocale(language: LanguageCode) {
 	if (loadedLocales.has(language)) return;
 
@@ -54,18 +50,14 @@ export async function loadDateFnsLocale(language: LanguageCode) {
 	}
 }
 
-/** Loads every date-fns locale into the cache (meant for the server where bundle size does not matter). */
+/** Loads every date-fns locale (server only, bundle size irrelevant). */
 export function loadAllDateFnsLocales() {
 	return Promise.all(
 		(Object.keys(LOCALE_LOADERS) as LanguageCode[]).map(loadDateFnsLocale),
 	);
 }
 
-/**
- * Formats how long ago / until the given date in the given language. The
- * language's date-fns locale must be loaded first via
- * {@link loadDateFnsLocale}; otherwise falls back to English.
- */
+/** How long ago / until the date in the given language; falls back to English unless {@link loadDateFnsLocale} ran. */
 export function formatDistanceToNow(
 	date: Parameters<typeof dateFnsFormatDistanceToNow>[0],
 	options: Omit<
@@ -95,16 +87,12 @@ export function databaseTimestampNow() {
 	return dateToDatabaseTimestamp(new Date());
 }
 
-/**
- * Converts a date represented by day, month, and year into a JavaScript Date object, noon UTC.
- */
+/** Day/month/year to a Date at noon UTC. */
 export function dayMonthYearToDate({ day, month, year }: DayMonthYear) {
 	return new Date(Date.UTC(year, month, day, 12));
 }
 
-/**
- * Converts a JavaScript Date object into a CalendarDateTime object (used by react-aria-components).
- */
+/** Date to a react-aria-components CalendarDateTime. */
 export function dateToDateValue(date: Date) {
 	return new CalendarDateTime(
 		date.getFullYear(),
@@ -116,9 +104,7 @@ export function dateToDateValue(date: Date) {
 	);
 }
 
-/**
- * Converts a JavaScript Date object into a CalendarDate object (used by react-aria-components for date-only pickers).
- */
+/** Date to a react-aria-components CalendarDate (date-only pickers). */
 export function dateToCalendarDate(date: Date) {
 	return new CalendarDate(
 		date.getFullYear(),
@@ -127,18 +113,14 @@ export function dateToCalendarDate(date: Date) {
 	);
 }
 
-/**
- * Converts a date represented by day, month, and year into a DateValue object (used by react-aria-components), noon UTC.
- */
+/** Day/month/year to a react-aria-components DateValue, noon UTC. */
 export function dayMonthYearToDateValue({ day, month, year }: DayMonthYear) {
 	const isoString = dateToYYYYMMDD(new Date(Date.UTC(year, month, day, 12)));
 
 	return parseDate(isoString);
 }
 
-/**
- * Converts a date represented by day, month, and year into a database timestamp, noon UTC.
- */
+/** Day/month/year to a database timestamp, noon UTC. */
 export function dayMonthYearToDatabaseTimestamp(args: DayMonthYear) {
 	return dateToDatabaseTimestamp(dayMonthYearToDate(args));
 }
@@ -166,10 +148,8 @@ export function weekNumberToDate({
 }
 
 /**
- * Returns the UTC date range covering an ISO week: the Monday that starts the
- * week and the Monday that starts the following week (a 7-day span). Uses UTC
- * date arithmetic so the span is exactly 7×24h regardless of the server's
- * timezone or any DST transition that falls inside the week.
+ * UTC range of an ISO week: its Monday to the next Monday. UTC arithmetic keeps the span exactly
+ * 7×24h regardless of server timezone or DST.
  */
 export function weekNumberToDateRange({
 	week,
@@ -186,13 +166,6 @@ export function weekNumberToDateRange({
 	return { startTime, endTime };
 }
 
-/**
- * Checks if a date is valid or not.
- *
- * Returns:
- * - True if date is valid
- * - False otherwise
- */
 export function isValidDate(date: Date) {
 	return !Number.isNaN(date.getTime());
 }
diff --git a/app/utils/e2e.ts b/app/utils/e2e.ts
index c0a814f57..23ac5cd88 100644
--- a/app/utils/e2e.ts
+++ b/app/utils/e2e.ts
@@ -1,9 +1,6 @@
 /**
- * Whether the app is running as part of an e2e test.
- *
- * `import.meta.env` is undefined when Playwright bundles test code, so it has to be
- * checked before accessing. There the flag comes from `process.env` instead (set by
- * playwright.config.ts), as app modules run in the test process too.
+ * `import.meta.env` is undefined when Playwright bundles test code; there the flag comes from
+ * `process.env` (set by playwright.config.ts) since app modules run in the test process too.
  */
 export const IS_E2E_TEST_RUN =
 	(typeof import.meta.env !== "undefined" &&
diff --git a/app/utils/git-commit.ts b/app/utils/git-commit.ts
index f274b1a8a..7dc1ddf60 100644
--- a/app/utils/git-commit.ts
+++ b/app/utils/git-commit.ts
@@ -1,8 +1,4 @@
 declare const __GIT_COMMIT__: string;
 
-/**
- * Commit the running bundle was built from. Inlined at build time, meaning the
- * client and the server report their own build's commit. Empty string outside
- * of deployed builds (e.g. local development).
- */
+/** Commit the bundle was built from, inlined at build time; empty outside deployed builds. */
 export const GIT_COMMIT = __GIT_COMMIT__;
diff --git a/app/utils/i18n.ts b/app/utils/i18n.ts
index a83f44e9f..0a885e1d9 100644
--- a/app/utils/i18n.ts
+++ b/app/utils/i18n.ts
@@ -42,20 +42,7 @@ export function allI18nNamespaces() {
 	return [...ALL_NAMESPACES];
 }
 
-/**
- * Returns the localized display name for a given ISO country code using the specified language. If the country code is unknown or the function fails for othe reason, returns the country code itself as a fallback.
- *
- * @example
- * ```typescript
- * function CountryNameComponent() {
- *  const { i18n } = useTranslation();
- *  const countryName = countryCodeToTranslatedName({
- *   countryCode: "FI",
- *   language: i18n.language,
- *  }); // "Suomi" in Finnish
- * }
- * ```
- */
+/** Localized display name of an ISO country code, falling back to the code itself. */
 export function countryCodeToTranslatedName({
 	countryCode,
 	language,
@@ -75,16 +62,13 @@ export function countryCodeToTranslatedName({
 			`Error getting display name for country code "${countryCode}":`,
 			e,
 		);
-		return countryCode; // fallback to the code itself if display name fails
+		return countryCode;
 	}
 }
 
 /**
- * Ordinal placement suffixes per language, keyed by the CLDR ordinal plural
- * category given by `Intl.PluralRules(language, { type: "ordinal" })`. A leading
- * `^` marks a suffix that should render as superscript. Languages without a
- * written ordinal suffix use explicit `null` – rendering no suffix is preferred
- * over borrowing the English one.
+ * Ordinal suffixes keyed by CLDR ordinal plural category. A leading `^` marks superscript.
+ * Languages without a written ordinal suffix are `null`: no suffix beats borrowing the English one.
  */
 const ORDINAL_SUFFIXES: Record<
 	LanguageCode,
@@ -122,12 +106,7 @@ function regionDisplayNames(language: string): Intl.DisplayNames {
 
 const pluralRulesCache = new Map<string, Intl.PluralRules>();
 
-/**
- * Returns the localized ordinal suffix for a placement number in the given
- * language (e.g. `"^st"` for `1` in English). A leading `^` marks a suffix the
- * caller should render as superscript. Returns an empty string for languages
- * without a written ordinal suffix.
- */
+/** Localized ordinal suffix (`"^st"` for 1 in English; leading `^` = superscript), empty when the language has none. */
 export function ordinalSuffix(placement: number, language: string): string {
 	const category = ordinalPluralRules(language).select(placement);
 
diff --git a/app/utils/id.ts b/app/utils/id.ts
index 5fcb1737a..e8016c0ed 100644
--- a/app/utils/id.ts
+++ b/app/utils/id.ts
@@ -2,9 +2,6 @@ import { nanoid } from "nanoid";
 
 export const SHORT_NANOID_LENGTH = 10;
 
-/**
- * Generates a short, unique identifier string (wraps nanoid using a smaller length than the default).
- */
 export function shortNanoid() {
 	return nanoid(SHORT_NANOID_LENGTH);
 }
diff --git a/app/utils/kysely.server.ts b/app/utils/kysely.server.ts
index 35d7a2557..a1fabeca4 100644
--- a/app/utils/kysely.server.ts
+++ b/app/utils/kysely.server.ts
@@ -22,10 +22,7 @@ import type { DB, Tables } from "~/db/tables";
 import { IS_E2E_TEST_RUN } from "./e2e";
 import { safeNumberParse } from "./number";
 
-/**
- * Base query selecting the user matching a URL identifier, which can be their user id, their Discord
- * id or their custom URL. Extend it with the columns the caller needs.
- */
+/** Base query selecting the user by URL identifier (user id, Discord id or custom URL). */
 export function userByIdentifierQuery(identifier: string) {
 	return db
 		.selectFrom("User")
@@ -86,13 +83,10 @@ type CommonUserSelectResult<O> = readonly [
 ];
 
 /**
- * Select list for the fields shared by every user representation across the app. Includes
- * `customAvatarUrl`, the full URL of the user's supporter custom avatar (resolved from
- * `User.customAvatarImgId`), or `null` when they have none. By default reads from `"User"` which
- * must be in scope at the call site; pass `alias` when the table is joined under another name
- * (`alias: "LinkedUser"`), `prefix` to prefix every output column (`prefix: "sender"` →
- * `senderId`, `senderUsername`, ...), `idAs` to rename only the id column (`idAs: "userId"`) and
- * `inTournament` to resolve `username` via {@link tournamentUsername}.
+ * Select list for the fields shared by every user representation, incl. `customAvatarUrl` (full
+ * supporter avatar URL or `null`). Reads from `"User"` unless `alias` is given; `prefix` prefixes
+ * every output column (`sender` → `senderId`, ...), `idAs` renames only the id column and
+ * `inTournament` resolves `username` via {@link tournamentUsername}.
  */
 export function commonUserSelect<const O extends CommonUserSelectOptions>(
 	eb: ExpressionBuilder<DB, any>,
@@ -118,11 +112,8 @@ export function commonUserSelect<const O extends CommonUserSelectOptions>(
 }
 
 /**
- * SQL expression resolving to the full URL of a user's supporter custom avatar (from
- * `User.customAvatarImgId`), or `null` when they have none. Alias it
- * (`.as("customAvatarUrl")`) when selecting it directly. Pass `alias` when the `User` table is
- * joined under another name. Prefer {@link commonUserSelect} / {@link commonUserJsonObject};
- * reach for this only when those don't fit (e.g. a hand-built `jsonBuildObject`).
+ * Full URL of a user's supporter custom avatar, or `null`. Alias it when selecting directly.
+ * Prefer {@link commonUserSelect} / {@link commonUserJsonObject} when they fit.
  */
 export function customAvatarUrl(
 	eb: ExpressionBuilder<DB, any>,
@@ -208,13 +199,7 @@ const USER_SUBMITTED_IMAGE_ROOT =
 		? "http://127.0.0.1:9000/sendou"
 		: "https://sendou.nyc3.cdn.digitaloceanspaces.com";
 
-/**
- * Constructs a SQL expression that returns the full URL for a tournament's logo.
- * If the tournament has a custom logo (via avatarImgId), returns that logo's URL.
- * Otherwise, returns null.
- *
- * @returns A SQL expression that concatenates the image root URL with either the custom logo URL or default logo
- */
+/** Full URL of the tournament's custom logo (via `avatarImgId`), or null when it has none. */
 export function tournamentLogoOrNull(
 	eb: ExpressionBuilder<Tables, "CalendarEvent">,
 ) {
@@ -235,13 +220,7 @@ export function tournamentLogoOrNull(
 	]);
 }
 
-/**
- * Constructs a SQL expression that returns the full URL for a tournament's logo.
- * If the tournament has a custom logo (via avatarImgId), returns that logo's URL.
- * Otherwise, falls back to the default tournament logo.
- *
- * @returns A SQL expression that concatenates the image root URL with either the custom logo URL or default logo
- */
+/** Full URL of the tournament's custom logo (via `avatarImgId`), falling back to the default logo. */
 export function tournamentLogoWithDefault(
 	eb: ExpressionBuilder<Tables, "CalendarEvent">,
 ) {
@@ -262,9 +241,8 @@ export function tournamentLogoWithDefault(
 }
 
 /**
- * Subquery resolving to the event's earliest `CalendarEventDate` start time, or `null` when it has
- * no dates. Correlates on `"CalendarEvent"."id"`. Alias it `.as("startTime")` when selecting it
- * directly. Can also be passed to `orderBy` as is.
+ * Subquery for the event's earliest `CalendarEventDate` start time (`null` without dates).
+ * Correlates on `"CalendarEvent"."id"`; alias when selecting, usable in `orderBy` as is.
  */
 export function calendarEventStartTime(
 	eb: ExpressionBuilder<Tables, "CalendarEvent">,
@@ -275,10 +253,7 @@ export function calendarEventStartTime(
 		.whereRef("CalendarEventDate.eventId", "=", "CalendarEvent.id");
 }
 
-/**
- * Subquery counting a tournament's non-placeholder teams. Correlates on `"Tournament"."id"`.
- * Alias it `.as("teamsCount")` when selecting it directly.
- */
+/** Subquery counting a tournament's non-placeholder teams. Correlates on `"Tournament"."id"`. */
 export function tournamentTeamCount(
 	eb: ExpressionBuilder<Tables, "Tournament">,
 ) {
@@ -300,12 +275,10 @@ function tournamentHasStarted(eb: ExpressionBuilder<DB, "Tournament">) {
 }
 
 /**
- * Subquery resolving to the non-placeholder teams of a tournament that are still relevant to it:
- * every registered team as long as no bracket has been started, only the checked in ones after
- * that. Mirrors how the tournament page itself resolves its teams, so keep the two in sync.
- * Correlates on `"Tournament"."id"`. Has no select of its own, so extend it with the aggregate the
- * caller needs. A team can have several check in rows, so aggregate with `.distinct()`, e.g.
- * `.select(({ fn }) => fn.count("TournamentTeam.id").distinct().as("count"))`.
+ * Non-placeholder teams still relevant to a tournament: all registered teams until a bracket has
+ * started, only checked in ones after. Mirrors the tournament page's own team resolution, keep in
+ * sync. Correlates on `"Tournament"."id"`. Has no select; a team can have several check in rows,
+ * so aggregate with `.distinct()`.
  */
 function tournamentCheckedInTeams(eb: ExpressionBuilder<DB, "Tournament">) {
 	return eb
@@ -325,10 +298,7 @@ function tournamentCheckedInTeams(eb: ExpressionBuilder<DB, "Tournament">) {
 		);
 }
 
-/**
- * Subquery counting the teams of {@link tournamentCheckedInTeams}. Correlates on
- * `"Tournament"."id"`. Alias it `.as("teamsCount")` when selecting it directly.
- */
+/** Subquery counting the teams of {@link tournamentCheckedInTeams}. Correlates on `"Tournament"."id"`. */
 export function tournamentTeamsCount(eb: ExpressionBuilder<DB, "Tournament">) {
 	return tournamentCheckedInTeams(eb).select(({ fn }) => [
 		fn.count<number>("TournamentTeam.id").distinct().as("count"),
@@ -336,10 +306,8 @@ export function tournamentTeamsCount(eb: ExpressionBuilder<DB, "Tournament">) {
 }
 
 /**
- * Expression resolving to a tournament's participant count: rostered players of the teams from
- * {@link tournamentCheckedInTeams} while the tournament is still ongoing, players who actually got
- * a result once it has been finalized. Correlates on `"Tournament"."id"`. Alias it
- * `.as("membersCount")` when selecting it directly.
+ * Tournament participant count: rostered players of {@link tournamentCheckedInTeams} while ongoing,
+ * players with a result once finalized. Correlates on `"Tournament"."id"`.
  */
 export function tournamentMembersCount(
 	eb: ExpressionBuilder<DB, "Tournament">,
@@ -374,9 +342,8 @@ export function tournamentMembersCount(
 
 /**
  * Grouped subquery picking each user's (`by: "userId"`) or team's (`by: "identifier"`) latest
- * Skill row of a season: `latestId` plus that row's `ordinal`, `matchesCount` and the `by`
- * column. Wrap it with `.selectFrom(latestSkillPerSeason(...).as("Latest"))`; extra `.where`s
- * compose before aliasing.
+ * Skill row of a season: `latestId`, `ordinal`, `matchesCount` and the `by` column.
+ * Use as `.selectFrom(latestSkillPerSeason(...).as("Latest"))`; extra `.where`s compose before aliasing.
  */
 export function latestSkillPerSeason<By extends "userId" | "identifier">({
 	season,
@@ -385,14 +352,10 @@ export function latestSkillPerSeason<By extends "userId" | "identifier">({
 	season: number;
 	by: By;
 }) {
-	// The latest row per user/team is picked via SQLite's bare column rule: with a `max()`
-	// aggregate the other selected columns come from the row that produced the max.
-	// A self-join against a `max(id)` subquery is avoided because it lets the planner
-	// pick a nested-loop plan when it misjudges the season's row count (e.g. a freshly
-	// started season whose stats are dwarfed by older seasons), which made this query
-	// take ~12s. This form is plan-stable regardless of stats: a single grouped scan of
-	// the `skill_season_user_id_leaderboard` / `skill_season_identifier_leaderboard`
-	// covering index, no temp b-tree per partition.
+	// Relies on SQLite's bare column rule: with `max()` the other columns come from the max row.
+	// A self-join against a `max(id)` subquery took ~12s when the planner misjudged a fresh
+	// season's row count; this form is plan-stable: one grouped scan of the
+	// `skill_season_{user_id,identifier}_leaderboard` covering index.
 	return db
 		.selectFrom("Skill")
 		.select(({ fn }) => [
@@ -407,9 +370,8 @@ export function latestSkillPerSeason<By extends "userId" | "identifier">({
 }
 
 /**
- * Predicate for `Skill` rows of the user that represent a played set: either a SendouQ match or
- * a ranked tournament the user has a result in. Filters out e.g. skills of tournament teams the
- * user dropped from before results. `"Skill"` must be in scope at the call site.
+ * Predicate for the user's `Skill` rows representing a played set: a SendouQ match or a ranked
+ * tournament they have a result in (excludes teams they dropped from before results).
  */
 export function skillCountsAsSeasonSet(
 	eb: ExpressionBuilder<DB, "Skill">,
@@ -427,12 +389,11 @@ export function skillCountsAsSeasonSet(
 	]);
 }
 
-/** Concats the file name (a bit misleadingly called `url` in the DB schema) with the root URL, giving the full URL for the image */
+/** Prefixes the file name (called `url` in the DB schema) with the root URL. */
 export function concatUserSubmittedImagePrefix<T extends string | null>(
 	expr: Expression<T>,
 ) {
-	// null-propagating || instead of iif(expr is not null, concat(...), null)
-	// so a correlated subquery passed as expr is evaluated only once per row
+	// null-propagating || so a correlated subquery expr is evaluated only once per row
 	return sql<T extends null ? string | null : string>`(${sql.lit(
 		`${USER_SUBMITTED_IMAGE_ROOT}/`,
 	)} || ${expr})`;
@@ -489,10 +450,8 @@ export function userProfileWeapons(eb: ExpressionBuilder<DB, any>) {
 }
 
 /**
- * The name a user is shown under inside tournaments: the name organizers have given them
- * (`User.tournamentName`) falling back to their `username`. Alias it (`.as("username")`) when
- * selecting it directly. Prefer `commonUserSelect(eb, { inTournament: true })`; reach for this
- * only when the query doesn't select the common user fields.
+ * Name shown inside tournaments: `User.tournamentName` falling back to `username`.
+ * Prefer `commonUserSelect(eb, { inTournament: true })` when selecting the common user fields.
  */
 export function tournamentUsername(alias = "User") {
 	return sql<string>`coalesce(${sql.ref(`${alias}.tournamentName`)}, ${sql.ref(
@@ -505,12 +464,10 @@ type SelectQueryBuilderExpression<O> = Parameters<
 >[0];
 
 /**
- * Drop-in replacement for kysely's sqlite `jsonArrayFrom`. Emits the same query, except
- * JSON-valued selections (per {@link jsonValuedSelection}: JSON columns, nested json helpers) get
- * `json(...)` applied at the `json_object` argument position. SQLite's JSON subtype never
- * survives a subquery boundary, so without the re-tag such values would be embedded as
- * strings; the dialect parses each result column exactly once and relies on documents
- * arriving fully nested. Always use this over the kysely one.
+ * Drop-in replacement for kysely's sqlite `jsonArrayFrom` that wraps JSON-valued selections
+ * (per {@link jsonValuedSelection}) in `json(...)`. SQLite's JSON subtype doesn't survive a
+ * subquery boundary, so without it nested documents would arrive as strings; the dialect parses
+ * each result column exactly once. Always use this over the kysely one.
  */
 export function jsonArrayFrom<O>(
 	expr: SelectQueryBuilderExpression<O>,
@@ -546,10 +503,8 @@ export function jsonBuildObject<O extends Record<string, Expression<unknown>>>(
 }
 
 /**
- * Re-tags a JSON-valued expression with SQLite's `json()` so it stays a nested document
- * (instead of an escaped string) inside {@link jsonBuildObject}/{@link jsonArrayFrom}.
- * Only needed for expressions the helpers can not recognize as JSON on their own, e.g. a
- * raw `IIF(...)` over a JSON column.
+ * Re-tags an expression with `json()` so it stays nested inside {@link jsonBuildObject}/{@link jsonArrayFrom}.
+ * Only needed when the helpers can't recognize it as JSON, e.g. a raw `IIF(...)` over a JSON column.
  */
 export function asJson<T>(expr: Expression<T>): RawBuilder<T> {
 	return sql<T>`json(${expr})`;
diff --git a/app/utils/number.ts b/app/utils/number.ts
index d7073842f..8d0754cb9 100644
--- a/app/utils/number.ts
+++ b/app/utils/number.ts
@@ -1,30 +1,11 @@
 import * as R from "remeda";
 
-/**
- * Rounds a number to a specified number of decimal places.
- *
- * @example
- * ```typescript
- * roundToNDecimalPlaces(3.14159); // returns 3.14
- * roundToNDecimalPlaces(3.14159, 3); // returns 3.142
- * roundToNDecimalPlaces(2.5, 0); // returns 3
- * ```
- */
+/** Rounds to `n` decimal places (default 2). */
 export function roundToNDecimalPlaces(num: number, n = 2) {
 	return Number((Math.round(num * 10 ** n) / 10 ** n).toFixed(n));
 }
 
-/**
- * Truncates a number to a specified number of decimal places without rounding.
- *
- * @example
- * ```typescript
- * cutToNDecimalPlaces(3.9999, 2); // returns 3.99
- * cutToNDecimalPlaces(3.12, 1); // returns 3.1
- * cutToNDecimalPlaces(100, 2); // returns 100
- * cutToNDecimalPlaces(3.0001, 2); // returns 3
- * ```
- */
+/** Truncates to `n` decimal places without rounding, dropping trailing zeros (3.0001 → 3). */
 export function cutToNDecimalPlaces(num: number, n = 2) {
 	const multiplier = 10 ** n;
 	// Round away floating point representation error (e.g. 0.29 * 100 = 28.999...) before truncating
@@ -34,41 +15,14 @@ export function cutToNDecimalPlaces(num: number, n = 2) {
 	return Number(n > 0 ? result.replace(/\.?0+$/, "") : result);
 }
 
-/**
- * Calculates the average (arithmetic mean) of an array of numbers.
- * Returns 0 if the array is empty.
- *
- * @example
- * ```typescript
- * averageArray([2, 4, 6, 8]); // returns 5
- * averageArray([-2, -4, -6, -8]); // returns -5
- * averageArray([10, -10, 20, -20]); // returns 0
- * averageArray([42]); // returns 42
- * averageArray([]); // returns 0
- * ```
- */
+/** Arithmetic mean, 0 for an empty array. */
 export function averageArray(arr: number[]) {
 	if (arr.length === 0) return 0;
 
 	return R.sum(arr) / arr.length;
 }
 
-/**
- * Safely parses a string into a number, returning `null` if the input is `null`,
- * empty, or not a valid number.
- *
- * Trims whitespace from the input before parsing. If the trimmed string is empty
- * or cannot be converted to a valid number, returns `null`.
- *
- * @example
- * ```typescript
- * safeNumberParse("42"); // returns 42
- * safeNumberParse("  3.14 "); // returns 3.14
- * safeNumberParse(""); // returns null
- * safeNumberParse("abc"); // returns null
- * safeNumberParse(null); // returns null
- * ```
- */
+/** Parses a trimmed string into a number; `null` for `null`, empty or non-numeric input. */
 export function safeNumberParse(value: string | null) {
 	if (value === null) return null;
 
@@ -79,16 +33,7 @@ export function safeNumberParse(value: string | null) {
 	return Number.isNaN(result) ? null : result;
 }
 
-/**
- * Share of games won as a percentage, or `null` when no games were played.
- * Callers decide how to round it and what to show in place of a missing rate.
- *
- * @example
- * ```typescript
- * winPercentage(3, 1); // returns 75
- * winPercentage(0, 0); // returns null
- * ```
- */
+/** Share of games won as an unrounded percentage, or `null` when no games were played. */
 export function winPercentage(wins: number, losses: number) {
 	const played = wins + losses;
 	if (played === 0) return null;
diff --git a/app/utils/random.ts b/app/utils/random.ts
index ce1167872..5ff65bd36 100644
--- a/app/utils/random.ts
+++ b/app/utils/random.ts
@@ -35,18 +35,8 @@ function mulberry32(a: number) {
 }
 
 /**
- * Creates a seeded pseudo-random number generator that produces consistent results for the same seed.
- * Uses mulberry32 algorithm with cyrb128 hash function for string-to-number conversion.
- *
- * @param seed - String seed value (e.g., "2025-1-8" for daily rotation)
- * @returns Object with random number generation methods:
- *   - `random(lo?, hi?)` - Returns random float between lo (inclusive) and hi (exclusive)
- *   - `randomInteger(lo, hi?)` - Returns random integer between lo (inclusive) and hi (exclusive)
- *   - `seededShuffle(array)` - Returns shuffled copy of array using seeded Fisher-Yates algorithm
- *
- * @example
- * const { seededShuffle } = seededRandom("2025-1-8");
- * const shuffled = seededShuffle([1, 2, 3, 4, 5]);
+ * Seeded PRNG (mulberry32 over a cyrb128 hash of `seed`, e.g. "2025-1-8" for daily rotation).
+ * `random` / `randomInteger` ranges are lo inclusive, hi exclusive.
  */
 export const seededRandom = (seed: string) => {
 	const rng = mulberry32(cyrb128(seed)[0]);
diff --git a/app/utils/remix.server.ts b/app/utils/remix.server.ts
index c7d8abbc6..bbadc47eb 100644
--- a/app/utils/remix.server.ts
+++ b/app/utils/remix.server.ts
@@ -37,12 +37,8 @@ export function badRequestIfFalsy<T>(value: T | null | undefined): T {
 }
 
 /**
- * Resolves the pagination state of a loader whose current page comes from the
- * `page` search param. `pagesCount` is at minimum 1 so empty result sets stay
- * on page 1.
- *
- * If the requested `page` exceeds `pagesCount`, throws a redirect to the last
- * available page (preserving other search params).
+ * Pagination state for a loader driven by the `page` search param. `pagesCount` is at least 1;
+ * a `page` past it throws a redirect to the last page (other search params preserved).
  */
 export function paginate({
 	url,
@@ -66,11 +62,7 @@ export function paginate({
 	return { currentPage: page, pagesCount };
 }
 
-/**
- * Parse formData of a request with the given schema. Throws HTTP 400 response if fails.
- *
- * When using SendouForm, use parseFormData from /app/form/parse.server.ts instead.
- * */
+/** Parses request payload with the schema, error toast redirect on failure. With SendouForm use `parseFormData` from `~/form/parse.server` instead. */
 export async function parseRequestPayload<T extends AnySchema>({
 	request,
 	schema,
@@ -163,11 +155,7 @@ export function errorToastIfFalsy(
 	throw errorToastRedirect(message);
 }
 
-/**
- * To be used in loader or action function. Asserts that the provided `Result` value is an `Ok` variant.
- *
- * If the value is an `Err`, shows an error toast to the user with the error message. The function will stop execution by throwing a redirect meaning it is safe to operate on the value after this function call.
- */
+/** Asserts `Result` is `Ok`; on `Err` throws a redirect showing the error as a toast. */
 export function errorToastIfErr<T, E extends string>(
 	value: Result<T, E>,
 ): asserts value is Ok<T> {
@@ -206,43 +194,27 @@ export type Breadcrumb =
 	  }
 	| { text: string; type: "TEXT"; href: string };
 
-/**
- * Our custom type for route handles - the keys are defined by us or
- * libraries that parse them.
- *
- * Can be set per route using `export const handle: SendouRouteHandle = { };`
- * Can be accessed for all currently active routes via the `useMatches()` hook.
- */
+/** Route `handle` shape; read for all active routes via `useMatches()`. */
 export type SendouRouteHandle = {
-	/** The i18n translation files used for this route, via remix-i18next */
+	/** i18n namespaces loaded for this route */
 	i18n?: Namespace;
 
-	/**
-	 * A function that returns the breadcrumb text that should be displayed in
-	 * the <Breadcrumb> component
-	 */
 	breadcrumb?: (args: {
 		match: UIMatch;
 		t: TFunction<"common", undefined>;
 	}) => Breadcrumb | Array<Breadcrumb> | undefined;
 
-	/** The name of a navItem that is active on this route. See nav-items.ts */
+	/** navItem active on this route, see nav-items.ts */
 	navItemName?: (typeof navItems)[number]["name"];
 
 	/**
-	 * When `true`, the shared `<Main>` rendered by a parent layout (e.g. the
-	 * tournament layout) fills the whole content area instead of the page
-	 * max-width, while the page content stays centered at the normal width.
-	 * Lets a descendant (e.g. the bracket) break out and grow wider than the
-	 * page when it needs to.
+	 * Parent layout's `<Main>` fills the whole content area (content stays centered at normal
+	 * width) so a descendant like the bracket can grow wider than the page.
 	 */
 	mainBreakout?: boolean;
 };
 
-/** Caches the loader response with "private" Cache-Control meaning that CDN won't cache the response.
- * To be used when the response is different for each user. This is especially useful when the response
- * is prefetched on link hover.
- */
+/** Per-user loader response cached with `private` Cache-Control (no CDN), useful for link hover prefetch. */
 export function privatelyCachedJson<T>(dataValue: T) {
 	return data(dataValue, {
 		headers: { "Cache-Control": "private, max-age=5" },
diff --git a/app/utils/remix.ts b/app/utils/remix.ts
index e473bc3d4..3858e0845 100644
--- a/app/utils/remix.ts
+++ b/app/utils/remix.ts
@@ -18,20 +18,20 @@ export function isRevalidation(args: ShouldRevalidateFunctionArgs) {
 export type SerializeFrom<T> = ReturnType<typeof useLoaderData<T>>;
 
 interface OpenGraphArgs {
-	/** Title as shown by the browser in the tab etc. Appended with "| sendou.ink"*/
+	/** Browser tab title, appended with "| sendou.ink" */
 	title: string;
-	/** Title as shown when shared on Bluesky, Discord etc. Also used in search results. If omitted, "title" is used instead. */
+	/** Title for link previews and search results, defaults to `title` */
 	ogTitle?: string;
-	/** Brief description of the page's contents used by search engines and social media sharing. If the description is over 300 characters long it is automatically truncated. */
+	/** Truncated past 300 characters */
 	description?: string;
 	location: Location;
-	/** Optionally override location pathname. */
+	/** overrides location pathname */
 	url?: string;
 	image?: OpenGraphImage;
 }
 
 interface OpenGraphImage {
-	/** Absolute URL of the image. */
+	/** absolute */
 	url: string;
 	dimensions?: {
 		width: number;
diff --git a/app/utils/request-context.server.ts b/app/utils/request-context.server.ts
index b37afecaa..4b68b73e9 100644
--- a/app/utils/request-context.server.ts
+++ b/app/utils/request-context.server.ts
@@ -3,15 +3,13 @@ import { AsyncLocalStorage } from "node:async_hooks";
 // TODO: this is only needed for our current hacky toast setup, once a proper one in place this middleware can be deleted
 
 interface RequestContext {
-	/** Normalized request URL, as provided to middleware in framework mode
-	 *  (single-fetch `.data` suffix and internal search params removed). */
+	/** Normalized (single-fetch `.data` suffix and internal search params removed) */
 	url: URL;
 }
 
 const requestContextAsyncLocalStorage = new AsyncLocalStorage<RequestContext>();
 
-/** Runs `fn` with the given request context available to server-side helpers
- *  (e.g. toast redirects) that don't otherwise receive the request. */
+/** Runs `fn` with the request context available to helpers (e.g. toast redirects) lacking the request. */
 export function runWithRequestContext<T>(
 	context: RequestContext,
 	fn: () => T,
@@ -19,8 +17,7 @@ export function runWithRequestContext<T>(
 	return requestContextAsyncLocalStorage.run(context, fn);
 }
 
-/** Normalized pathname of the current request, or `undefined` outside a request
- *  context. Used to build absolute redirects from helpers lacking the request. */
+/** Pathname of the current request, `undefined` outside a request context. */
 export function currentRequestPathname(): string | undefined {
 	return requestContextAsyncLocalStorage.getStore()?.url.pathname;
 }
diff --git a/app/utils/schema.ts b/app/utils/schema.ts
index ee51c3119..cf04176e3 100644
--- a/app/utils/schema.ts
+++ b/app/utils/schema.ts
@@ -36,10 +36,7 @@ export interface ValidationCtx {
 	addIssue: (issue: { message: string; path?: PropertyKey[] }) => void;
 }
 
-/**
- * Validation action running `fn` on the parsed value with an `addIssue`
- * taking plain key paths.
- */
+/** Validation action running `fn` on the parsed value with an `addIssue` taking plain key paths. */
 export function superRefine<TValue>(
 	fn: (value: TValue, ctx: ValidationCtx) => void,
 ) {
@@ -401,7 +398,7 @@ export const hasZalgo = (txt: string) => zalgoRe.test(encodeURIComponent(txt));
 /** Non-empty string that has the given length (max and optionally min). Prevents z͎͗ͣḁ̵̑l̉̃ͦg̐̓̒o͓̔ͥ text as well as filters out characters that have no width. */
 export const safeStringSchema = ({ min, max }: { min?: number; max: number }) =>
 	preprocess(
-		actuallyNonEmptyStringOrNull, // if this returns null, none of the checks below will run because it's not a string
+		actuallyNonEmptyStringOrNull, // null skips the string checks below
 		v.pipe(
 			v.string(),
 			v.minLength(min ?? 0),
@@ -430,9 +427,7 @@ export const safeNullableStringSchema = ({
 		),
 	);
 
-/**
- * Processes the input value and returns a non-empty string with invisible characters cleaned out or null.
- */
+/** Non-empty string with invisible characters cleaned out, or null. */
 export function actuallyNonEmptyStringOrNull(value: unknown) {
 	if (typeof value !== "string") return value;
 
diff --git a/app/utils/strings.ts b/app/utils/strings.ts
index 6632ae8b5..028f0939d 100644
--- a/app/utils/strings.ts
+++ b/app/utils/strings.ts
@@ -147,18 +147,12 @@ export function removeMarkdown(value: string) {
 			.replace(/^\s{0,3}#{1,6}\s*/gm, "")
 			// Remove * emphasis
 			.replace(/(\*+)([^\s*])(.*?[^\s*])??\1/g, "$2$3")
-			// Remove _ emphasis. Unlike *, _ emphasis gets rendered only if
-			//   1. Either there is a whitespace character before opening _ and after closing _.
-			//   2. Or _ is at the start/end of the string.
+			// Remove _ emphasis; unlike *, it only renders when surrounded by whitespace or string edges
 			.replace(/(^|\W)([_]+)(\S)(.*?\S)??\2($|\W)/g, "$1$3$4$5")
 			// Remove code blocks
 			.replace(/(`{3,})(.*?)\1/gm, "$2")
 			// Remove inline code
 			.replace(/`(.+?)`/g, "$1")
-			// // Replace two or more newlines with exactly two? Not entirely sure this belongs here...
-			// .replace(/\n{2,}/g, '\n\n')
-			// // Remove newlines in a paragraph
-			// .replace(/(\S+)\n\s*(\S+)/g, '$1 $2')
 			// Replace strike through
 			.replace(/~(.*?)~/g, "$1")
 			// Collapse runs of whitespace (e.g. from decoded &nbsp; or stripped tags)
diff --git a/app/utils/team-name.ts b/app/utils/team-name.ts
index 6428dfd61..e640a4afd 100644
--- a/app/utils/team-name.ts
+++ b/app/utils/team-name.ts
@@ -1,6 +1,6 @@
 import { ADJECTIVES, SUBTITLES_PLURALIZED } from "./team-name-data";
 
-/** Generates a random team name by combining a Splatoon 3 title adjective with a pluralized subtitle e.g. "Prestigious Heat Haters" */
+/** Splatoon 3 title adjective + pluralized subtitle, e.g. "Prestigious Heat Haters" */
 export function randomTeamName() {
 	const adjective = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
 	const subtitle =
diff --git a/app/utils/types.ts b/app/utils/types.ts
index c228e6746..2abdb4e40 100644
--- a/app/utils/types.ts
+++ b/app/utils/types.ts
@@ -1,11 +1,4 @@
-/**
- * Asserts that a code path is unreachable by accepting a value of type `never`.
- * This function is useful for exhaustive checks in switch statements or discriminated unions.
- * If called, it throws an error with a message containing the unexpected value.
- *
- * @param x - The value that should never occur (of type `never`).
- * @throws {Error} Throws an error indicating an unexpected value was encountered.
- */
+/** Exhaustiveness check for switches / discriminated unions; throws if reached. */
 export function assertUnreachable(x: never): never {
 	throw new Error(
 		`Didn't expect to get here. Unexpected value: ${JSON.stringify(x)}`,
diff --git a/app/utils/urls.ts b/app/utils/urls.ts
index a8bbebc4f..b53697048 100644
--- a/app/utils/urls.ts
+++ b/app/utils/urls.ts
@@ -34,10 +34,7 @@ export const discordAvatarUrl = ({
 		discordAvatar
 	}.webp${size === "lg" ? "?size=240" : "?size=80"}`;
 
-/**
- * Resolves the avatar image url of an user, preferring their custom avatar over
- * the Discord one. Returns undefined if the user has neither.
- */
+/** Avatar url preferring the custom avatar over the Discord one; undefined without either. */
 export const resolveAvatarUrl = ({
 	customAvatarUrl,
 	discordId,
@@ -154,10 +151,7 @@ const STATIC_ASSETS_URL = Config.staticAssetsUrl;
 
 export const BLANK_IMAGE_URL = `${STATIC_ASSETS_URL}/img/blank.gif`;
 
-/**
- * Pages that have an OG image of their own, matching their nav item name.
- * Rendered by the `/admin/og-images` page.
- */
+/** Pages with an OG image of their own (named after the nav item), rendered by `/admin/og-images`. */
 export const OG_IMAGE_PAGES = [
 	"settings",
 	"sendouq",
diff --git a/e2e/analyzer.spec.ts b/e2e/analyzer.spec.ts
index 7fd38efd4..90eb4c250 100644
--- a/e2e/analyzer.spec.ts
+++ b/e2e/analyzer.spec.ts
@@ -25,15 +25,12 @@ test.describe("Build Analyzer", () => {
 		// Luna Blaster is a light weapon so it should have lower base swim speed than Splattershot
 		await expect(swimSpeed.baseValue).not.toHaveText(swimSpeedSplattershot);
 
-		// shows comparison value when you have relevant abilities selected
 		await isNotVisible(swimSpeed.buildValueTitle);
 		await analyzer.addAbility("SSU");
 		await expect(swimSpeed.buildValueTitle).toBeVisible();
 
-		// on new build page with preselected values
 		const buildForm = await analyzer.openNewBuildPrompt();
 		await expect(buildForm.gearSelect("HEAD")).toBeVisible();
-		// Check that Luna Blaster appears in the weapon pool list (not in dropdown options)
 		await expect(buildForm.weaponPoolItem("Luna Blaster")).toBeVisible();
 		await expect(buildForm.ability("SSU")).toBeVisible();
 	});
diff --git a/e2e/builds.spec.ts b/e2e/builds.spec.ts
index c9fbf5591..2803ae83c 100644
--- a/e2e/builds.spec.ts
+++ b/e2e/builds.spec.ts
@@ -127,7 +127,7 @@ test.describe("Builds", () => {
 		await weaponBuilds.addFilter("ability");
 		await weaponBuilds.locators.comparisonSelect.selectOption("AT_MOST");
 
-		// are all builds with ISM are hidden?
+		// every build with ISM is hidden
 		await expect(weaponBuilds.ability("ISM")).toHaveCount(1);
 
 		await weaponBuilds.deleteFilter("ability");
diff --git a/e2e/calendar.spec.ts b/e2e/calendar.spec.ts
index 3c2b7c4e9..543d5478f 100644
--- a/e2e/calendar.spec.ts
+++ b/e2e/calendar.spec.ts
@@ -178,7 +178,6 @@ test.describe("Calendar", () => {
 		await expect(page).toHaveURL(calendarEventPage(eventId));
 		await expect(calendarEvent.startTime(editedDate)).toBeVisible();
 
-		// the edited name and date land on the calendar
 		const calendar = new CalendarPage(page);
 		const editedDateWeek = { day: 20, month: 0, year: 2027 };
 		await calendar.goto(editedDateWeek);
@@ -244,12 +243,10 @@ test.describe("Calendar", () => {
 		await expect(page).toHaveURL(/\/to\/\d+/);
 		const tournamentId = Number(page.url().match(/\/to\/(\d+)/)?.[1]);
 
-		// start time round-trips
 		const tournamentInfo = new TournamentInfoPage(page);
 		await tournamentInfo.goto(tournamentId);
 		await expect(tournamentInfo.startTime(startTime).first()).toBeVisible();
 
-		// the follow-up bracket shows up
 		const brackets = new TournamentBracketsPage(page);
 		await brackets.goto(tournamentId);
 		await expect(brackets.bracketTab("Underground")).toBeVisible();
diff --git a/e2e/comp-analyzer.spec.ts b/e2e/comp-analyzer.spec.ts
index 3a497ae25..11073c490 100644
--- a/e2e/comp-analyzer.spec.ts
+++ b/e2e/comp-analyzer.spec.ts
@@ -12,14 +12,13 @@ test.describe("Composition Analyzer", () => {
 
 		await compAnalyzer.selectWeapon(40);
 
-		// First slot should now have the weapon
 		await expect(compAnalyzer.selectedWeapon(0)).toBeVisible();
 		await expect(compAnalyzer.locators.emptyWeaponSlots).toHaveCount(3);
 
 		await compAnalyzer.removeWeapon(0);
 		await expect(compAnalyzer.locators.emptyWeaponSlots).toHaveCount(4);
 
-		// Select 4 weapons to test auto-collapse
+		// a full four weapons auto-collapse the grid
 		await expect(compAnalyzer.locators.categorizationToggle).toBeVisible();
 
 		await compAnalyzer.selectWeapon(40);
@@ -31,7 +30,6 @@ test.describe("Composition Analyzer", () => {
 
 		await expect(page).toHaveURL(/weapons=/);
 
-		// Weapons should still be selected after reload
 		await page.reload();
 
 		await expect(compAnalyzer.selectedWeapon(0)).toBeVisible();
@@ -52,7 +50,6 @@ test.describe("Composition Analyzer", () => {
 		await compAnalyzer.selectCategorization("special");
 		await expect(compAnalyzer.categorizationRadio("special")).toBeChecked();
 
-		// Grid should be expanded
 		await expect(compAnalyzer.locators.categorizationToggle).toBeVisible();
 
 		await compAnalyzer.toggleWeaponGrid();
@@ -61,7 +58,6 @@ test.describe("Composition Analyzer", () => {
 		await compAnalyzer.toggleWeaponGrid();
 		await expect(compAnalyzer.locators.categorizationToggle).toBeVisible();
 
-		// Switch categorization and test URL persistence
 		await compAnalyzer.selectCategorization("sub");
 		await expect(page).toHaveURL(/categorization=sub/);
 
@@ -76,18 +72,16 @@ test.describe("Composition Analyzer", () => {
 
 		const damageCombos = compAnalyzer.damageCombos;
 
-		// Both should not be visible initially
 		await expect(damageCombos.root).not.toBeVisible();
 		await expect(compAnalyzer.locators.rangeVisualization).not.toBeVisible();
 
-		// Select two weapons with range data (blaster - ID 210)
+		// 210 is a blaster, which has range data
 		await compAnalyzer.selectWeapon(40);
 		await compAnalyzer.selectWeapon(210);
 
 		await expect(damageCombos.root).toBeVisible();
 		await expect(compAnalyzer.locators.rangeVisualization).toBeVisible();
 
-		// Should be expanded by default
 		await expect(damageCombos.content).toBeVisible();
 
 		await damageCombos.toggleCollapsed();
@@ -110,13 +104,11 @@ test.describe("Composition Analyzer", () => {
 		const damageCombos = compAnalyzer.damageCombos;
 		await expect(damageCombos.root).toBeVisible();
 
-		// Part 1: Test Sub Defense slider
 		const initialDamageValues =
 			await damageCombos.damageValues.allTextContents();
 
 		await damageCombos.subDefenseSlider.fill("57");
 
-		// Damage of sub weapons should be reduced
 		const newDamageValues = await damageCombos.damageValues.allTextContents();
 		expect(initialDamageValues.join(",")).not.toEqual(
 			newDamageValues.join(","),
@@ -124,14 +116,13 @@ test.describe("Composition Analyzer", () => {
 
 		await damageCombos.subDefenseSlider.fill("0");
 
-		// Part 2: Test Ink Resistance slider
 		const initialInkTimes = await damageCombos.inkTimes.allTextContents();
 
 		await damageCombos.inkResistanceSlider.fill("57");
 
 		const newInkTimes = await damageCombos.inkTimes.allTextContents();
 
-		// If there were ink times, they should have increased or more ink combos should appear
+		// ink resistance makes ink times longer or reveals more ink combos
 		if (initialInkTimes.length > 0 || newInkTimes.length > 0) {
 			const initialTotalFrames = initialInkTimes.reduce(
 				(sum, t) => sum + (Number.parseInt(t, 10) || 0),
@@ -144,7 +135,6 @@ test.describe("Composition Analyzer", () => {
 			expect(newTotalFrames).toBeGreaterThanOrEqual(initialTotalFrames);
 		}
 
-		// Part 3: Test damage type filtering
 		const firstDamageTypeLabel = damageCombos.damageTypeLabels.first();
 		const damageTypeText = await firstDamageTypeLabel.textContent();
 
@@ -159,7 +149,6 @@ test.describe("Composition Analyzer", () => {
 			damageTypeText ?? "",
 		);
 
-		// Clicking a filtered item restores it
 		await damageCombos.filteredItems.first().click();
 		await expect(damageCombos.filteredItems).toHaveCount(filteredCount - 1);
 	});
diff --git a/e2e/global-setup.ts b/e2e/global-setup.ts
index a27d9f2de..39ed50826 100644
--- a/e2e/global-setup.ts
+++ b/e2e/global-setup.ts
@@ -55,7 +55,6 @@ async function waitForMinio(timeout = 60000): Promise<boolean> {
 }
 
 async function ensureMinioRunning(): Promise<boolean> {
-	// Check if MinIO is already running
 	if (await isMinioBucketReady()) {
 		// biome-ignore lint/suspicious/noConsole: CLI script output
 		console.log("MinIO is already running");
@@ -108,19 +107,16 @@ async function waitForServer(port: number, timeout = 120000): Promise<void> {
 				// 404 is fine - server is up, just no route at /
 				return;
 			}
-		} catch {
-			// Server not ready yet
-		}
+		} catch {}
 		await new Promise((resolve) => setTimeout(resolve, 100));
 	}
 	throw new Error(`Server on port ${port} did not start within ${timeout}ms`);
 }
 
 /**
- * The last e2e build can be reused when no build input changed since its marker
- * was written. Directory mtimes catch deletes and renames; a build made outside
- * the e2e flow (no marker, or output newer than the marker) forces a rebuild, as
- * does a marker from a different port setup. E2E_FORCE_BUILD=true overrides.
+ * Reuses the last e2e build when no build input changed since its marker. Directory mtimes
+ * catch deletes and renames; a build made outside the e2e flow (no marker, or output newer
+ * than the marker) or a marker from another port setup forces a rebuild. E2E_FORCE_BUILD=true overrides.
  */
 function isBuildFresh(): boolean {
 	if (process.env.E2E_FORCE_BUILD === "true") return false;
@@ -155,11 +151,8 @@ async function globalSetup(config: FullConfig) {
 	// biome-ignore lint/suspicious/noConsole: CLI script output
 	console.log(`\nStarting e2e test setup with ${workerCount} workers...`);
 
-	// Start MinIO if not already running
 	await ensureMinioRunning();
 
-	// Build the app once with E2E test flag so VITE_E2E_TEST_RUN is embedded
-	// Use port 6173 as the base - tests will rewrite URLs as needed
 	if (isBuildFresh()) {
 		// biome-ignore lint/suspicious/noConsole: CLI script output
 		console.log(
@@ -185,7 +178,6 @@ async function globalSetup(config: FullConfig) {
 		);
 	}
 
-	// Prepare databases and start servers for each worker
 	const serverPromises: Promise<void>[] = [];
 
 	// Kill any existing processes on our ports before starting; sweep beyond the
@@ -207,7 +199,6 @@ async function globalSetup(config: FullConfig) {
 
 		ensureMigratedDb(dbPath);
 
-		// Start server
 		// biome-ignore lint/suspicious/noConsole: CLI script output
 		console.log(`Starting server for worker ${i} on port ${port}...`);
 		// react-router-serve directly instead of `pnpm start`: ensureMigratedDb
@@ -264,11 +255,9 @@ async function globalSetup(config: FullConfig) {
 		);
 	}
 
-	// Store server processes globally for teardown before awaiting readiness so
-	// a failed startup still gets every already-spawned server cleaned up
+	// exposed to teardown before awaiting readiness so a failed startup still cleans up every spawned server
 	global.__E2E_SERVERS__ = SERVER_PROCESSES;
 
-	// Wait for all servers to be ready
 	await Promise.all(serverPromises);
 
 	// biome-ignore lint/suspicious/noConsole: CLI script output
diff --git a/e2e/global-teardown.ts b/e2e/global-teardown.ts
index 910a4925d..3e7741820 100644
--- a/e2e/global-teardown.ts
+++ b/e2e/global-teardown.ts
@@ -22,8 +22,7 @@ async function globalTeardown(_config: FullConfig) {
 			);
 
 			if (process.platform === "win32" && server.pid) {
-				// the whole process tree needs to be killed on Windows to not leave
-				// the ports occupied
+				// Windows needs the whole process tree killed or the ports stay occupied
 				try {
 					execSync(`taskkill /pid ${server.pid} /T /F`, { stdio: "pipe" });
 				} catch {
@@ -40,7 +39,7 @@ async function globalTeardown(_config: FullConfig) {
 		new Promise((resolve) => setTimeout(resolve, 2000)),
 	]);
 
-	// Stop MinIO if we started it (check for marker file)
+	// only stop MinIO if we started it
 	if (fs.existsSync(MINIO_MARKER_FILE)) {
 		// biome-ignore lint/suspicious/noConsole: CLI script output
 		console.log("Stopping MinIO...");
diff --git a/e2e/helpers/chat.ts b/e2e/helpers/chat.ts
index 6b2ad2c5f..054fbc46a 100644
--- a/e2e/helpers/chat.ts
+++ b/e2e/helpers/chat.ts
@@ -3,11 +3,7 @@ import { ADMIN_ID } from "~/features/admin/admin-constants";
 import { CHAT_ROOMS_DATA_ROUTE, chatRoomMessagesRoute } from "~/utils/urls";
 import { expect, impersonate } from "./playwright";
 
-/**
- * A second logged in browser, for the tests needing two users connected at once:
- * live delivery cannot be seen by impersonating back and forth on one page, since
- * only one of the two ever holds an event stream.
- */
+/** A second logged in browser: impersonating back and forth on one page never shows live delivery, as only one user holds the event stream. */
 export async function openSecondUser(
 	browser: Browser,
 	baseURL: string,
diff --git a/e2e/helpers/counterpick-map-pool.ts b/e2e/helpers/counterpick-map-pool.ts
index dbca8bc6a..aeffc2b58 100644
--- a/e2e/helpers/counterpick-map-pool.ts
+++ b/e2e/helpers/counterpick-map-pool.ts
@@ -21,10 +21,7 @@ export function pickedCounterpickMap(
 	return page.getByTestId(`map-pool-${mode}-${stageId}-picked`);
 }
 
-/**
- * Picks the required amount of counterpick maps for every ranked mode, skipping
- * banned ones, and returns what was picked.
- */
+/** Picks the required amount of counterpick maps for every ranked mode, skipping banned ones, and returns them. */
 export async function pickCounterpickMaps(page: Page) {
 	const picked: Array<{ mode: ModeShort; stageId: StageId }> = [];
 	let stageId = FIRST_COUNTERPICK_STAGE_ID;
diff --git a/e2e/helpers/factories.ts b/e2e/helpers/factories.ts
index 22a2f4285..17153c48d 100644
--- a/e2e/helpers/factories.ts
+++ b/e2e/helpers/factories.ts
@@ -112,9 +112,8 @@ export async function loadFactories(parallelIndex: number) {
 }
 
 /**
- * Brings the worker's database to the state every test starts from: empty except
- * for the anchor users whose ids production permission logic keys off, with the
- * server's caches flushed. Runs as an auto-use fixture, tests do not call it.
+ * Resets the worker's database to the state every test starts from: empty except for the anchor
+ * users whose ids permission logic keys off, caches flushed. An auto-use fixture, tests don't call it.
  */
 export async function resetForTest(page: Page, factories: Factories) {
 	const { dbReset } = await import("~/db/reset");
@@ -132,11 +131,7 @@ export async function resetForTest(page: Page, factories: Factories) {
 	await flushIfDirty(page, { resetDevOverrides: true });
 }
 
-/**
- * Refreshes the server's in-process caches if anything was written since the last
- * flush. Called by the helpers that make the browser talk to the server — tests do
- * not call it themselves.
- */
+/** Refreshes the server's caches if anything was written since the last flush. Called by the helpers, not tests. */
 export async function flushIfDirty(
 	page: Page,
 	{ resetDevOverrides = false } = {},
diff --git a/e2e/helpers/playwright-form.ts b/e2e/helpers/playwright-form.ts
index e1be5912d..6eb1ed019 100644
--- a/e2e/helpers/playwright-form.ts
+++ b/e2e/helpers/playwright-form.ts
@@ -24,7 +24,6 @@ function loadTranslations(): Record<string, Record<string, string>> {
 const translations = loadTranslations();
 
 function resolveTranslation(key: string): string {
-	// Handle keys like "common:forms.name" or "team:newTeam.header"
 	const [namespace, translationPath] = key.includes(":")
 		? key.split(":")
 		: ["common", key];
diff --git a/e2e/helpers/playwright.ts b/e2e/helpers/playwright.ts
index a349a1581..3a3120b16 100644
--- a/e2e/helpers/playwright.ts
+++ b/e2e/helpers/playwright.ts
@@ -226,17 +226,13 @@ export async function fillDateTimeField({
 export async function navigate({ page, url }: { page: Page; url: string }) {
 	await flushIfDirty(page);
 
-	// Rewrite absolute URLs with localhost to use the worker's baseURL
-	// This handles invite links and other URLs embedded with VITE_SITE_DOMAIN
+	// invite links and other URLs embed VITE_SITE_DOMAIN; strip it so Playwright applies the worker's baseURL
 	let targetUrl = url;
 	if (url.startsWith("http://localhost:")) {
 		const urlObj = new URL(url);
-		// Extract just the path and search params, let Playwright use the correct baseURL
 		targetUrl = urlObj.pathname + urlObj.search;
 	}
-	// domcontentloaded instead of the default load event: module scripts have
-	// executed by then, and the hydration wait below covers the rest — no need
-	// to also wait for images and other subresources
+	// domcontentloaded: module scripts have run by then and the hydration wait covers the rest
 	await page.goto(targetUrl, { waitUntil: "domcontentloaded" });
 	await expectIsHydrated(page);
 }
@@ -254,10 +250,7 @@ export function impersonate(page: Page, userId = ADMIN_ID) {
 	return retryPost(page, "impersonate", `/auth/impersonate?id=${userId}`);
 }
 
-/**
- * Makes the worker's server resolve every season as over, so tests can cover the
- * season boundary. Undone before the next test starts.
- */
+/** Makes the worker's server resolve every season as over. Undone before the next test starts. */
 export async function endSeason(page: Page) {
 	const response = await retryPost(page, "endSeason", "/end-season");
 	if (!response?.ok()) {
@@ -267,10 +260,7 @@ export async function endSeason(page: Page) {
 	}
 }
 
-/**
- * Makes the worker's server resolve Plus Server voting as active, so tests can
- * cover the voting window. Undone before the next test starts.
- */
+/** Makes the worker's server resolve Plus Server voting as active. Undone before the next test starts. */
 export async function setPlusVotingActive(page: Page, active: boolean) {
 	const response = await retryPost(
 		page,
@@ -297,11 +287,7 @@ export async function runRoutine(page: Page, name: string) {
 	}
 }
 
-/**
- * Direct (non-browser) POST that retries on transient network failures such as
- * "socket hang up", which the dev server can produce intermittently under load.
- * Only safe for idempotent endpoints.
- */
+/** Direct POST retrying transient failures ("socket hang up" under load). Only for idempotent endpoints. */
 async function retryPost(
 	page: Page,
 	name: string,
@@ -314,8 +300,7 @@ async function retryPost(
 
 	for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
 		try {
-			// maxRedirects 0: impersonate answers with a redirect to the admin
-			// page, and following it would server-render a page nobody reads —
+			// maxRedirects 0: following impersonate's redirect would render a page nobody reads;
 			// the Set-Cookie lands in the context jar either way
 			return await page.request.post(url, {
 				timeout: 7_500,
@@ -410,11 +395,7 @@ function isDataRequest(url: string) {
 	return new URL(url).pathname.endsWith(".data");
 }
 
-/**
- * Starts recording whether the router turns busy. A fast action holds the busy
- * marker for a frame or two, which a polled wait misses outright; the flag a
- * `MutationObserver` sets survives the marker flipping back.
- */
+/** Records whether the router turns busy: a fast action holds the marker for a frame or two, which a polled wait misses. */
 async function armRouterProbe(page: Page) {
 	await page.evaluate(() => {
 		window.__routerProbe?.observer.disconnect();
@@ -481,10 +462,7 @@ export function modalClickConfirmButton(page: Page) {
 	return submit(page, "confirm-button");
 }
 
-/**
- * Clicks a tournament nav tab by its testId, opening the overflow ("More") menu
- * first when the tab has collapsed into it on the current viewport.
- */
+/** Clicks a tournament nav tab by testId, via the overflow ("More") menu when it has collapsed into it. */
 export async function clickNavTab(page: Page, testId: string) {
 	const visibleTab = page.locator(`[data-testid="${testId}"]:visible`);
 	if ((await visibleTab.count()) === 0) {
@@ -497,11 +475,7 @@ export async function clickNavTab(page: Page, testId: string) {
 export const MACHINE_TIMEZONE =
 	Intl.DateTimeFormat().resolvedOptions().timeZone;
 
-/**
- * Writes the timezone cookie the browser would after hydration, so that the
- * very first document request already renders in the machine's timezone the
- * test computed its fixture times in.
- */
+/** Pre-writes the timezone cookie so the first document request already renders in the machine's timezone. */
 export function setTimezoneCookie(page: Page) {
 	return page.context().addCookies([
 		{
diff --git a/e2e/helpers/tournament.ts b/e2e/helpers/tournament.ts
index 8c057ac7a..d559ede98 100644
--- a/e2e/helpers/tournament.ts
+++ b/e2e/helpers/tournament.ts
@@ -206,10 +206,8 @@ export function startedTournamentTimes() {
 }
 
 /**
- * A tournament running an unfinished match: two checked-in teams and the bracket
- * started, which is all it takes for both teams to be "in a match". The friend and
- * their teammate play the opponent, and every user given is on the roster it is
- * named for.
+ * A tournament running an unfinished match: two checked-in teams and a started bracket, which is
+ * all it takes for both to be "in a match". The friend and their teammate play the opponent.
  */
 export async function createInProgressMatch(
 	factories: Factories,
@@ -266,11 +264,7 @@ export async function createSubSeekingTournament(
 	return { tournament };
 }
 
-/**
- * A tournament where the given user is waiting for their next match: three teams
- * in a single elimination bracket leave the top seed with a bye into the final,
- * whose other side is still being played for.
- */
+/** The user waits for their next match: three teams in single elimination give the top seed a bye into the final. */
 export async function createTournamentWithByeTeam(
 	factories: Factories,
 	{ name, waitingUserId }: { name: string; waitingUserId: number },
diff --git a/e2e/object-damage-calculator.spec.ts b/e2e/object-damage-calculator.spec.ts
index d5a469191..33cffd0c3 100644
--- a/e2e/object-damage-calculator.spec.ts
+++ b/e2e/object-damage-calculator.spec.ts
@@ -16,14 +16,12 @@ test.describe("Object Damage Calculator", () => {
 		const dmgBefore = (await dmg.textContent())!;
 		const htdBefore = (await htd.textContent())!;
 
-		// test hits to destroy calculation
 		expect(Number(htdBefore)).toBe(
 			Math.ceil(Number(hpBefore) / Number(dmgBefore)),
 		);
 
 		await calculator.selectDamageType("NORMAL_MIN");
 
-		// select did what we expect it to do
 		await expect(hp).toHaveText(hpBefore);
 		await expect(dmg).not.toHaveText(dmgBefore);
 		await expect(htd).not.toHaveText(htdBefore);
diff --git a/e2e/org.spec.ts b/e2e/org.spec.ts
index 6d2c0a039..dbe58e78b 100644
--- a/e2e/org.spec.ts
+++ b/e2e/org.spec.ts
@@ -57,12 +57,10 @@ test.describe("Tournament Organization", () => {
 
 		const organization = new OrganizationPage(page);
 
-		// 1. As a regular user, verify edit controls are not visible
 		await impersonate(page, NZAP_TEST_ID);
 		await organization.goto(org.slug);
 		await isNotVisible(organization.locators.editButton);
 
-		// 2. As admin, promote user to admin
 		await impersonate(page, ADMIN_ID);
 		await organization.goto(org.slug);
 		const organizationEdit = await organization.openEdit();
@@ -73,13 +71,11 @@ test.describe("Tournament Organization", () => {
 		await organization.goto(org.slug);
 		await organization.establish();
 
-		// 3. As the promoted user, verify edit controls are visible and page can be accessed
 		await impersonate(page, NZAP_TEST_ID);
 		await organization.goto(org.slug);
 		await organization.openEdit();
 		await expect(organizationEdit.locators.title).toBeVisible();
 
-		// 4. As the promoted user, verify they can edit tournaments
 		const tournamentPage = new TournamentPage(page);
 		await tournamentPage.goto(tournament.id);
 
@@ -109,7 +105,6 @@ test.describe("Tournament Organization", () => {
 		const organization = new OrganizationPage(page);
 		const tournamentPage = new TournamentPage(page);
 
-		// 1. As admin, ban the player from the organization
 		await impersonate(page, ADMIN_ID);
 		await organization.goto(org.slug);
 		await organization.openBannedUsers();
@@ -126,7 +121,6 @@ test.describe("Tournament Organization", () => {
 			"Test reason",
 		);
 
-		// 2. As the banned user, try to join a tournament
 		await impersonate(page, player.id);
 		await tournamentPage.goto(tournament.id);
 
@@ -137,13 +131,11 @@ test.describe("Tournament Organization", () => {
 		// "Fill roster" only appears after a successful registration
 		await expect(register.locators.fillRosterHeading).not.toBeVisible();
 
-		// 3. As admin, remove the ban
 		await impersonate(page, ADMIN_ID);
 		await organization.goto(org.slug);
 		await organization.openBannedUsers();
 		await organization.unban();
 
-		// 4. As the unbanned user, verify they can now join a tournament
 		await impersonate(page, player.id);
 		await tournamentPage.goto(tournament.id);
 		const registerAgain = await tournamentPage.register();
@@ -156,7 +148,6 @@ test.describe("Tournament Organization", () => {
 
 		await expect(teamsTab).toContainText("Teams (1)");
 
-		// 5. As admin, ban user again but with permanent ban this time
 		await impersonate(page, ADMIN_ID);
 		await organization.goto(org.slug);
 		await organization.openBannedUsers();
diff --git a/e2e/pages/auth/discord-authorize.ts b/e2e/pages/auth/discord-authorize.ts
index 631ec7ad3..5bd475e83 100644
--- a/e2e/pages/auth/discord-authorize.ts
+++ b/e2e/pages/auth/discord-authorize.ts
@@ -3,10 +3,9 @@ import { type BrowserContext, expect } from "@playwright/test";
 const AUTHORIZE_PATHNAME = "/oauth2/authorize";
 
 /**
- * Captures the Discord authorize URL from the login POST's redirect and serves a
- * stub page in its place, so the start of the login flow can be asserted without
- * discord.com being reachable. Redirects are followed inside a single request, so
- * routing discord.com directly would never fire; the capture happens on `/auth`.
+ * Captures the Discord authorize URL from the login POST's redirect and serves a stub page in
+ * its place, so the login flow can be asserted without discord.com. The capture happens on
+ * `/auth` since redirects are followed inside a single request and a discord.com route would never fire.
  */
 export class DiscordAuthorizeInterceptor {
 	private capturedUrl: URL | null = null;
diff --git a/e2e/pages/calendar/calendar-new-event-page.ts b/e2e/pages/calendar/calendar-new-event-page.ts
index d348a5d81..647ac0900 100644
--- a/e2e/pages/calendar/calendar-new-event-page.ts
+++ b/e2e/pages/calendar/calendar-new-event-page.ts
@@ -43,8 +43,7 @@ export class CalendarNewEventPage {
 		await navigate({ page: this.page, url: TOURNAMENT_NEW_PAGE });
 	}
 
-	// the `date` datetime inputs use the array item's label ("Date"), not the
-	// array's own label, so they're driven directly rather than via the form helper
+	// the `date` inputs carry the array item's label ("Date"), not the array's, so the form helper can't drive them
 	async setFirstDate(date: Date) {
 		const fill = (segment: string, value: string) =>
 			this.page
diff --git a/e2e/pages/calendar/events-page.ts b/e2e/pages/calendar/events-page.ts
index 15d831b7d..9c3736f69 100644
--- a/e2e/pages/calendar/events-page.ts
+++ b/e2e/pages/calendar/events-page.ts
@@ -42,11 +42,7 @@ export class EventsPage {
 		return this.page.getByTestId(`availability-day-edit-${dayIndex}`);
 	}
 
-	/**
-	 * Paints a range on a day track by dragging across it, `from` and `to` being
-	 * fractions of the track's width. Past 1 the drag runs beyond the hours the
-	 * track shows.
-	 */
+	/** Drags across a day track, `from` and `to` being fractions of its width (past 1 runs beyond the shown hours). */
 	async paintAvailability(dayIndex: number, from: number, to: number) {
 		const track = this.page.getByTestId(`availability-track-${dayIndex}`);
 		const box = await track.boundingBox();
diff --git a/e2e/pages/layout/chat-sidebar.ts b/e2e/pages/layout/chat-sidebar.ts
index 0c210ac0e..fa123b139 100644
--- a/e2e/pages/layout/chat-sidebar.ts
+++ b/e2e/pages/layout/chat-sidebar.ts
@@ -1,12 +1,9 @@
 import type { Locator, Page } from "@playwright/test";
 
 /**
- * The chat sidebar and the chats open inside it.
- *
- * The same component renders in three places — the desktop rail, the tablet modal
- * and the mobile panel — and never in more than one of them at a time, so the
- * accessors find their elements wherever the viewport put them instead of scoping
- * to a container.
+ * The chat sidebar and the chats open inside it. The same component renders in the desktop
+ * rail, the tablet modal or the mobile panel, never more than one at a time, so the accessors
+ * find their elements wherever the viewport put them instead of scoping to a container.
  */
 export class ChatSidebar {
 	readonly locators;
@@ -67,10 +64,7 @@ export class ChatSidebar {
 		await this.roomRow(title).click();
 	}
 
-	/**
-	 * One open chat: the only one, or the nth panel of the split view — where the
-	 * match chat comes first and the group chat below it.
-	 */
+	/** One open chat: the only one, or the nth panel of the split view (match chat first, group chat below). */
 	chat(nth = 0) {
 		return new ChatRoom(this.locators.openChats.nth(nth));
 	}
diff --git a/e2e/pages/layout/mobile-nav.ts b/e2e/pages/layout/mobile-nav.ts
index 1c62dbaed..a0d8780fd 100644
--- a/e2e/pages/layout/mobile-nav.ts
+++ b/e2e/pages/layout/mobile-nav.ts
@@ -14,10 +14,8 @@ const TAB_NAMES: Record<Panel, string> = {
 const PANELS: Panel[] = ["menu", "friends", "tourneys", "chat", "you"];
 
 /**
- * The bottom tab bar and its panels, rendered in place of the side nav on mobile.
- *
- * The panels show the same rows as the side nav does, and its accessors find them
- * the same way — scoped to the panel that is open.
+ * The bottom tab bar and its panels, rendered in place of the side nav on mobile. The panels
+ * show the same rows as the side nav, found the same way but scoped to the open panel.
  */
 export class MobileNav {
 	private readonly page: Page;
@@ -52,10 +50,7 @@ export class MobileNav {
 		await this.tab(panel).click();
 	}
 
-	/**
-	 * Switches between panels the way the tab bar does while a panel is open. Its
-	 * tabs are then covered by invisible overlays, which only a dispatched event reaches.
-	 */
+	/** Switches panels while one is open: the tabs are then under invisible overlays only a dispatched event reaches. */
 	async switchPanel(panel: Panel) {
 		await this.page
 			.locator("[class*='ghostTab']:not([class*='ghostTabBar'])")
diff --git a/e2e/pages/layout/side-nav.ts b/e2e/pages/layout/side-nav.ts
index 058b6ceee..50e2a898b 100644
--- a/e2e/pages/layout/side-nav.ts
+++ b/e2e/pages/layout/side-nav.ts
@@ -4,11 +4,9 @@ import { waitForPOSTResponse } from "../../helpers/playwright";
 type Section = "Events" | "Friends" | "Streams";
 
 /**
- * The sidebar of the site layout, a modal behind a hamburger on narrower viewports.
- *
- * Its rows are looked up inside the sidebar the viewport shows — the rail, or the
- * copy of it the modal renders — so that the same row appearing on the page behind
- * it (a tournament also shown as a front page card) is not mistaken for one.
+ * The sidebar of the site layout, a modal behind a hamburger on narrower viewports. Rows are
+ * looked up inside whichever the viewport shows so that the same row on the page behind it
+ * (a tournament also shown as a front page card) is not mistaken for one.
  */
 export class SideNav {
 	private readonly page: Page;
diff --git a/e2e/pages/sendouq/sendouq-looking-page.ts b/e2e/pages/sendouq/sendouq-looking-page.ts
index 0d4640778..7a3829415 100644
--- a/e2e/pages/sendouq/sendouq-looking-page.ts
+++ b/e2e/pages/sendouq/sendouq-looking-page.ts
@@ -49,10 +49,7 @@ export class SendouQLookingPage {
 		await modalClickConfirmButton(this.page);
 	}
 
-	/**
-	 * Presses the action another group's card offers: challenging or inviting it,
-	 * accepting what it offered, or undoing either.
-	 */
+	/** Presses the action another group's card offers: challenge, invite, accept what it offered, or undo either. */
 	async pressGroupAction() {
 		await submit(this.page, "group-card-action-button");
 	}
diff --git a/e2e/pages/sendouq/sendouq-match-page.ts b/e2e/pages/sendouq/sendouq-match-page.ts
index 6eba4b5e9..a7b4784ba 100644
--- a/e2e/pages/sendouq/sendouq-match-page.ts
+++ b/e2e/pages/sendouq/sendouq-match-page.ts
@@ -108,13 +108,9 @@ export class SendouQMatchPage {
 		await waitForPOSTResponse(this.page, async () => {
 			await this.locators.reportScoreButton.click();
 		});
-		// Wait for the action panel to remount with the new reportedCount.
-		// waitForPOSTResponse only waits for the POST itself, not the loader
-		// revalidation. MatchActionTab is keyed on reportedCount, so it (and the
-		// nested WeaponReporter) unmounts and remounts when the loader returns.
-		// Without this wait, a follow-up click can land on the about-to-unmount
-		// instance — local state set by that click (e.g. WeaponReporter's isOpen)
-		// is then thrown away on remount.
+		// waitForPOSTResponse doesn't cover the loader revalidation, which remounts
+		// MatchActionTab (keyed on reportedCount) and the nested WeaponReporter; a
+		// follow-up click landing on the about-to-unmount instance loses its local state
 		await expect(this.locators.selectedWinner).toHaveCount(0);
 	}
 
@@ -204,18 +200,14 @@ export class SendouQMatchPage {
 
 	private async selectMapWinner(winner: Side) {
 		const teamName = TEAM_NAMES[winner];
-		// Wait for the action panel to settle before clicking. waitForPOSTResponse
-		// only waits for the POST itself; the loader revalidation that swaps in the
-		// next map's component runs after, so a previous winner can still be
-		// `data-selected="true"` here. Clicking too early hits the about-to-unmount
-		// label and the selection is lost on remount.
+		// the loader revalidation swapping in the next map runs after the POST, so a
+		// previous winner can still be selected; clicking the about-to-unmount label
+		// loses the selection on remount
 		await expect(this.locators.selectedWinner).toHaveCount(0);
-		// react-aria's Radio renders a hidden input behind a span overlay; click the
-		// wrapping label so the press handler fires and updates winnerId. The press
-		// occasionally registers a press-start without a press-end (same React Aria
-		// nondeterminism as in waitForPOSTResponse), so the selection silently drops
-		// and Submit stays disabled. Re-issue the click until the radio reports
-		// selected; otherwise the Submit-click retry loop spins on a disabled button.
+		// react-aria's Radio hides its input behind a span overlay, so the label is
+		// what clicks. The press occasionally never completes (same React Aria
+		// nondeterminism as in waitForPOSTResponse), leaving Submit disabled, so the
+		// click is re-issued until the radio reports selected.
 		const label = this.page.locator(
 			`label:has(input[aria-label="${teamName}"])`,
 		);
diff --git a/e2e/pages/team/team-page.ts b/e2e/pages/team/team-page.ts
index 1998a2c71..02b107a09 100644
--- a/e2e/pages/team/team-page.ts
+++ b/e2e/pages/team/team-page.ts
@@ -80,10 +80,7 @@ export class TeamPage {
 		);
 	}
 
-	/**
-	 * Opens the leave confirmation dialog, which names the new owner if the
-	 * leaver owns the team. Requires the actions menu to be open.
-	 */
+	/** Opens the leave confirmation dialog, naming the new owner if the leaver owns the team. Requires the actions menu to be open. */
 	async startLeaving() {
 		await this.locators.leaveTeamButton.click();
 	}
diff --git a/e2e/pages/tournament/tournament-brackets-page.ts b/e2e/pages/tournament/tournament-brackets-page.ts
index 5443c60fc..904eb566b 100644
--- a/e2e/pages/tournament/tournament-brackets-page.ts
+++ b/e2e/pages/tournament/tournament-brackets-page.ts
@@ -81,11 +81,9 @@ export class TournamentBracketsPage {
 		return this.match(matchId).locator("..").getByTestId("bracket-match-timer");
 	}
 
-	/** Team names of the bracket's first round in bracket order, top to bottom; two
-	 * slots per match, both slots of a BYE match reading as an empty string.
-	 * `teamCount` is how many teams the first round holds, byes excluded. Note that a
-	 * first round of mostly byes is compacted away by the UI, in which case what is
-	 * returned is the compacted column rather than the true first round. */
+	/** Team names of the first round in bracket order, two slots per match, both slots of a BYE
+	 * reading as "". `teamCount` excludes byes. A first round of mostly byes is compacted away by
+	 * the UI, in which case the compacted column is returned instead. */
 	async firstRoundTeamNames(teamCount: number): Promise<string[]> {
 		const firstRound = this.locators.bracketsViewer
 			.locator("[data-round-id]")
@@ -234,9 +232,8 @@ class BracketMapListDialog {
 		return submit(this.page, "confirm-finalize-bracket-button");
 	}
 
-	/** Starts the bracket with a CUSTOM pick/ban flow. The flow builder UI has no
-	 * e2e-friendly handles, so the flow is written straight into the form's maps
-	 * input before submitting it. */
+	/** Starts the bracket with a CUSTOM pick/ban flow, written straight into the form's maps
+	 * input as the flow builder UI has no e2e-friendly handles. */
 	confirmWithCustomFlow(customFlow: unknown) {
 		return waitForPOSTResponse(this.page, async () => {
 			await this.page.evaluate((cfStr) => {
diff --git a/e2e/pages/tournament/tournament-match-page.ts b/e2e/pages/tournament/tournament-match-page.ts
index 6d7ce0f1e..aa1e799a4 100644
--- a/e2e/pages/tournament/tournament-match-page.ts
+++ b/e2e/pages/tournament/tournament-match-page.ts
@@ -78,10 +78,8 @@ export class TournamentMatchPage {
 	}
 
 	async openTab(tab: Tab) {
-		// When teams have more members than the minimum, the action tab is hidden
-		// until each team's active roster is locked in via the rosters tab. Auto-set
-		// any roster that's still in default-editing mode so callers can stay focused
-		// on the flow they actually care about.
+		// with more members than the minimum, the action tab is hidden until each
+		// team's active roster is locked in via the rosters tab
 		if (tab === "action") {
 			await this.ensureActiveRostersSet();
 		}
@@ -109,10 +107,8 @@ export class TournamentMatchPage {
 	}
 
 	/**
-	 * Sweeps `mapsToReport` maps in a row, all won by `winner`. By default the
-	 * last map ends the set (the typical case — full Bo3/Bo5 sweep), and the
-	 * flow goes through the confirmation screen for that map. Pass
-	 * `setEnds: false` when reporting a partial set (e.g. only 1 of a Bo3).
+	 * Sweeps `mapsToReport` maps in a row, all won by `winner`. By default the last map
+	 * ends the set and goes through its confirmation screen; pass `setEnds: false` for a partial set.
 	 */
 	async reportResult({
 		mapsToReport,
@@ -125,11 +121,9 @@ export class TournamentMatchPage {
 	}) {
 		for (let i = 0; i < mapsToReport; i++) {
 			const isFinal = setEnds && i === mapsToReport - 1;
-			// Wait for the action panel to settle before clicking. waitForPOSTResponse
-			// only waits for the POST itself; the loader revalidation that swaps in
-			// the next map's component runs after, so a previous winner can still be
-			// `data-selected="true"` here. Clicking too early hits the about-to-unmount
-			// label and the selection is lost on remount.
+			// the loader revalidation swapping in the next map runs after the POST, so a
+			// previous winner can still be selected; clicking the about-to-unmount label
+			// loses the selection on remount
 			await expect(
 				this.page.locator(
 					'[data-testid^="winner-radio-"][data-selected="true"]',
@@ -145,11 +139,7 @@ export class TournamentMatchPage {
 		}
 	}
 
-	/**
-	 * Same as `reportResult` but with the winner given by team name. Useful when
-	 * the match up was generated by the app (swiss) and the sides are not known
-	 * ahead of time.
-	 */
+	/** `reportResult` with the winner given by team name, for match ups the app generated (swiss). */
 	async reportResultForTeam({
 		teamName,
 		mapsToReport,
@@ -166,12 +156,8 @@ export class TournamentMatchPage {
 	}
 
 	/**
-	 * Selects one of the pick/ban options and submits it.
-	 *
-	 * Selecting and submitting are retried together as one unit: a re-render
-	 * landing mid-click can swallow the submit press (see waitForPOSTResponse)
-	 * and, if the panel remounted, the selection with it — so re-submitting
-	 * alone would not be enough.
+	 * Selects a pick/ban option and submits it. Both are retried as one unit: a re-render
+	 * mid-click can swallow the submit press (see waitForPOSTResponse) and, on remount, the selection.
 	 */
 	pickBan(option: "first" | "last" = "first") {
 		return waitForPOSTResponse(this.page, async () => {
@@ -191,11 +177,9 @@ export class TournamentMatchPage {
 		return this.page.getByText(`Your weapon #${mapNumber}`);
 	}
 
-	/** The weapon reporter sits collapsed behind a button unless the viewer's
-	 * preference has it open — expanding an already open one is a no-op.
-	 * Expanding persists that preference, and the action tab remounts on every
-	 * score change, so the POST is awaited to keep a remount from reading a
-	 * stale preference and collapsing the reporter again. */
+	/** Expands the weapon reporter unless the viewer's preference already has it open. Expanding
+	 * persists that preference via a POST, awaited so the action tab's remount on the next score
+	 * change doesn't read a stale preference and collapse it again. */
 	async expandWeaponReporter() {
 		await expect(this.locators.actionPanel).toBeVisible();
 		if (await this.locators.reportWeaponsButton.isVisible()) {
@@ -299,7 +283,6 @@ export class TournamentMatchPage {
 	private async ensureActiveRostersSet() {
 		const sides: RosterSide[] = ["alpha", "bravo"];
 
-		// If the action tab is already there, no rosters need setting.
 		if (
 			(await this.page.getByRole("tab", { name: TAB_LABELS.action }).count()) >
 			0
@@ -307,9 +290,8 @@ export class TournamentMatchPage {
 			return;
 		}
 
-		// Editing inputs only render on the rosters tab — switch there.
+		// editing inputs only render on the rosters tab
 		await this.page.getByRole("tab", { name: TAB_LABELS.rosters }).click();
-		// Wait for the rosters panel to be ready before probing for editing UI.
 		await expect(this.locators.rostersPanel).toBeVisible();
 
 		for (const side of sides) {
@@ -318,7 +300,7 @@ export class TournamentMatchPage {
 			);
 			if ((await submitButton.count()) === 0) continue;
 
-			// Default-editing renders all members unchecked; pick the first 4.
+			// default-editing renders every member unchecked
 			for (let i = 0; i < 4; i++) {
 				const checkbox = this.playerCheckbox(side, i);
 				if (!(await checkbox.isChecked())) await checkbox.click();
diff --git a/e2e/pages/tournament/tournament-seeds-page.ts b/e2e/pages/tournament/tournament-seeds-page.ts
index 97c35a150..d9649a584 100644
--- a/e2e/pages/tournament/tournament-seeds-page.ts
+++ b/e2e/pages/tournament/tournament-seeds-page.ts
@@ -31,8 +31,7 @@ export class TournamentSeedsPage {
 	async dragTeamDown(tournamentTeamId: number) {
 		await this.teamHandle(tournamentTeamId).hover();
 		await this.page.mouse.down();
-		// i think the drag & drop library might actually be a bit buggy
-		// so we have to do it in steps like this to allow for testing
+		// the drag & drop library only registers the drop when moved in steps
 		await this.page.mouse.move(0, DRAG_TARGET_Y, { steps: 10 });
 		await this.page.mouse.up();
 	}
diff --git a/e2e/params.spec.ts b/e2e/params.spec.ts
index 63f62d32d..423462d0e 100644
--- a/e2e/params.spec.ts
+++ b/e2e/params.spec.ts
@@ -16,8 +16,7 @@ test.describe("Weapon parameters", () => {
 		const weaponParams = await analyzer.openRawParameters("splattershot");
 		await expect(page).toHaveURL(/\/params\/splattershot/);
 
-		// Filtering: hide a weapon column. Wait for a sibling column to render after the client-side
-		// navigation before counting, otherwise the count can be taken mid-hydration.
+		// a sibling column has to render after the client-side navigation first, or the count is taken mid-hydration
 		const { weaponHeaders, showAllWeaponsButton } = weaponParams.locators;
 		await expect(weaponHeaders.nth(1)).toBeVisible();
 		const initialColumnCount = await weaponHeaders.count();
@@ -29,19 +28,16 @@ test.describe("Weapon parameters", () => {
 		await expect(weaponHeaders).toHaveCount(initialColumnCount - 1);
 		await expect(page).toHaveURL(/hidden=\d/);
 
-		// Refresh keeps the hidden selection
 		await weaponParams.reload();
 		await expect(page).toHaveURL(/hidden=\d/);
 		await expect(showAllWeaponsButton).toBeVisible();
 		await expect(weaponHeaders).toHaveCount(initialColumnCount - 1);
 
-		// Restore all weapons
 		await weaponParams.showAllWeapons();
 		await expect(showAllWeaponsButton).not.toBeVisible();
 		await expect(weaponHeaders).toHaveCount(initialColumnCount);
 		await expect(page).not.toHaveURL(/hidden=\d/);
 
-		// Comparison bar graph
 		await weaponParams.openParamComparison();
 		await expect(weaponParams.locators.comparisonDialog).toBeVisible();
 		expect(
@@ -50,8 +46,7 @@ test.describe("Weapon parameters", () => {
 		await weaponParams.closeParamComparison();
 		await expect(weaponParams.locators.comparisonDialog).not.toBeVisible();
 
-		// Collapsing a history row after expanding it. The patch-count badge is shown while the row
-		// is collapsed and hidden once expanded, so it is a reliable signal for the toggle state.
+		// the patch-count badge shows only while the row is collapsed, signalling the toggle state
 		const historyRow = weaponParams.historyRow(0);
 		await expect(historyRow.root).toBeVisible();
 		await expect(historyRow.historyBadge).toBeVisible();
@@ -83,7 +78,6 @@ test.describe("Weapon parameters", () => {
 		await weaponParams.openPatchHistoryTab();
 		await expect(page).toHaveURL(/tab=patches/);
 
-		// Refresh keeps the selected tab
 		await weaponParams.reload();
 		await expect(page).toHaveURL(/tab=patches/);
 		await expect(patchHistoryTab).toHaveAttribute("aria-selected", "true");
@@ -91,7 +85,6 @@ test.describe("Weapon parameters", () => {
 		// Either patch columns are shown or the empty state
 		await expect(weaponParams.locators.patchColumns.first()).toBeVisible();
 
-		// Toggle "Show sub & special changes" and verify it persists on refresh
 		await expect(subAndSpecialChangesSwitch).toBeChecked();
 		await weaponParams.toggleSubAndSpecialChanges();
 		await expect(page).toHaveURL(/kitExtras=false/);
diff --git a/e2e/scrims.spec.ts b/e2e/scrims.spec.ts
index 8154ae67f..e5fc0b535 100644
--- a/e2e/scrims.spec.ts
+++ b/e2e/scrims.spec.ts
@@ -359,7 +359,6 @@ test.describe("Scrims", () => {
 			isAccepted: true,
 		});
 
-		// the admin opens the Action tab — the map list form is shown immediately
 		await impersonate(page, ADMIN_ID);
 
 		const scrim = new ScrimPage(page);
@@ -368,10 +367,8 @@ test.describe("Scrims", () => {
 
 		await expect(scrim.locators.mapListForm).toBeVisible();
 
-		// the post's tournament is the default source for the author's side, so they
-		// can submit without running the tournament search. A first map is generated
-		// immediately, so the page moves on to the report UI with the map-list
-		// manager collapsed.
+		// the post's tournament is the author's default source, so no tournament search is
+		// needed; the first map is generated right away, collapsing the map-list manager
 		await scrim.submitMapList();
 
 		await expect(scrim.locators.reportScoreButton).toBeVisible();
@@ -380,8 +377,7 @@ test.describe("Scrims", () => {
 
 		await expect(scrim.mapListRow("ALPHA")).toContainText(TOURNAMENT_NAME);
 
-		// N-ZAP submits a pool-URL-based map list. They have no list yet, so the
-		// map-list manager is already expanded on mount.
+		// N-ZAP has no list yet, so the map-list manager is already expanded on mount
 		await impersonate(page, NZAP_TEST_ID);
 		await scrim.goto(post.id);
 		await scrim.openTab("action");
@@ -390,21 +386,19 @@ test.describe("Scrims", () => {
 		await expect(scrim.locators.reportScoreButton).toBeVisible();
 		await expect(scrim.mapListRow("BRAVO")).toContainText("Pool");
 
-		// map 1: ALPHA wins → next map auto-generated
+		// every reported map auto-generates the next one
 		await scrim.reportMapWinner("ALPHA");
 		await expect(scrim.locators.reportScoreButton).toBeVisible();
 
-		// map 2: BRAVO wins → next map auto-generated
 		await scrim.reportMapWinner("BRAVO");
 		await expect(scrim.locators.reportScoreButton).toBeVisible();
 
-		// map 3: ALPHA wins → undo (un-reports map 3, deletes auto-gen map 4)
+		// undo un-reports map 3 and deletes the generated map 4
 		await scrim.reportMapWinner("ALPHA");
 		await expect(scrim.locators.undoMapButton).toBeVisible();
 		await scrim.undoMap();
 		await expect(scrim.locators.reportScoreButton).toBeVisible();
 
-		// re-report map 3 as BRAVO wins → next map auto-generated
 		await scrim.reportMapWinner("BRAVO");
 
 		// replaying replaces the generated map with a copy of the previous one
@@ -412,7 +406,6 @@ test.describe("Scrims", () => {
 		await scrim.replayMap();
 		await scrim.reportMapWinner("ALPHA");
 
-		// back as the admin to change their list
 		await impersonate(page, ADMIN_ID);
 		await scrim.goto(post.id);
 		await scrim.openTab("action");
diff --git a/e2e/sendouq-match.spec.ts b/e2e/sendouq-match.spec.ts
index df59f3465..cdf0baa9d 100644
--- a/e2e/sendouq-match.spec.ts
+++ b/e2e/sendouq-match.spec.ts
@@ -46,8 +46,7 @@ test.describe("SendouQ match page", () => {
 
 		await expect(match.score(4, 1)).toBeVisible();
 
-		// Verify the reported Splattershot shows up on the result-tab timeline
-		// (the compact action-tab timeline omits per-map weapons).
+		// the compact action-tab timeline omits per-map weapons, the result tab's shows them
 		await match.goto(matchId, "result");
 		await expect(match.reportedWeaponImage("Splattershot")).toBeVisible();
 	});
diff --git a/e2e/settings.spec.ts b/e2e/settings.spec.ts
index f53b473b6..e50c930c6 100644
--- a/e2e/settings.spec.ts
+++ b/e2e/settings.spec.ts
@@ -166,7 +166,7 @@ test.describe("Match profile map preferences", () => {
 		const matchProfile = new MatchProfilePage(page);
 		await matchProfile.goto();
 
-		// Save a map pool for both SZ and TC (stage 2 is not banned in TC).
+		// stage 2 is not banned in TC
 		await matchProfile.maps.setModePreference("SZ", "Prefer");
 		await matchProfile.maps.selectModeTab("SZ");
 		await matchProfile.maps.mapButton("SZ", 1).click();
@@ -175,15 +175,13 @@ test.describe("Match profile map preferences", () => {
 		await matchProfile.maps.mapButton("TC", 2).click();
 		await matchProfile.save();
 
-		// Switch to "zones only" by avoiding every mode except SZ, then save.
 		await matchProfile.maps.setModePreference("TW", "Avoid");
 		await matchProfile.maps.setModePreference("TC", "Avoid");
 		await matchProfile.maps.setModePreference("RM", "Avoid");
 		await matchProfile.maps.setModePreference("CB", "Avoid");
 		await matchProfile.save();
 
-		// Reload so the form loads the persisted preferences. The previously saved
-		// TC pool must not resurface as an invalid "pool for an avoided mode".
+		// the previously saved TC pool must not resurface as an invalid "pool for an avoided mode"
 		await matchProfile.goto();
 
 		await matchProfile.save();
@@ -202,19 +200,16 @@ test.describe("Spoiler-free mode", () => {
 		const brackets = new TournamentBracketsPage(page);
 		await brackets.goto(tournament.id);
 
-		// bracket is censored — "Show results" button visible
 		await expect(brackets.locators.showResultsButton).toBeVisible();
 
-		// later rounds show "???" for team names
 		await expect(brackets.locators.censoredTeamNames.first()).toBeVisible();
 
 		await brackets.locators.showResultsButton.click();
 
-		// after reveal, "Hide results" button appears and "???" is gone
 		await expect(brackets.locators.hideResultsButton).toBeVisible();
 		await isNotVisible(brackets.locators.censoredTeamNames);
 
-		// navigate to results page — sessionStorage reveal carries over
+		// the sessionStorage reveal carries over to the results page
 		const results = new TournamentResultsPage(page);
 		await results.goto(tournament.id);
 		await expect(results.locators.resultTeamNames.first()).toBeVisible();
@@ -233,11 +228,9 @@ test.describe("Spoiler-free mode", () => {
 		const results = new TournamentResultsPage(page);
 		await results.goto(tournament.id);
 
-		// results are censored
 		await expect(results.locators.showResultsButton).toBeVisible();
 		await isNotVisible(results.locators.resultTeamNames);
 
-		// reveal
 		await results.locators.showResultsButton.click();
 		await expect(results.locators.resultTeamNames.first()).toBeVisible();
 	});
diff --git a/e2e/team.spec.ts b/e2e/team.spec.ts
index 162f1c064..51457b399 100644
--- a/e2e/team.spec.ts
+++ b/e2e/team.spec.ts
@@ -133,7 +133,6 @@ test.describe("Team page", () => {
 		const team = new TeamPage(page);
 		await team.goto(customUrl);
 
-		// Owner is Sendou
 		await expect(team.ownerBadge(ADMIN_ID)).toBeVisible();
 
 		const roster = await team.openManageRoster();
@@ -191,7 +190,6 @@ test.describe("Team page", () => {
 		await expect(firstRow.locators.moveUpButton).toBeDisabled();
 		await expect(lastRow.locators.moveDownButton).toBeDisabled();
 
-		// move the first member down one slot
 		await firstRow.moveDown();
 
 		await expect(firstRow.locators.username).toHaveText(secondName);
@@ -202,7 +200,6 @@ test.describe("Team page", () => {
 		await team.goto(customUrl);
 		await team.openManageRoster();
 
-		// the new order is persisted
 		await expect(firstRow.locators.username).toHaveText(secondName);
 	});
 
diff --git a/e2e/tournament-bracket-elimination.spec.ts b/e2e/tournament-bracket-elimination.spec.ts
index a5225dc5a..c5b9947b4 100644
--- a/e2e/tournament-bracket-elimination.spec.ts
+++ b/e2e/tournament-bracket-elimination.spec.ts
@@ -19,13 +19,6 @@ import { UserResultsPage } from "./pages/user/user-results-page";
 const DE_LOSERS_ROUND_ID = 3;
 
 test.describe("Tournament bracket elimination", () => {
-	// 1) Report winner of N-ZAP's first match
-	// 2) Report winner of the adjacent match by using admin powers
-	// 3) Report one match on the only losers side match available
-	// 4) Try to reopen N-ZAP's first match and fail
-	// 5) Undo score of first losers match
-	// 6) Try to reopen N-ZAP's first match and succeed
-	// 7) As N-ZAP, undo all scores and switch to different team sweeping
 	test("reports score and sees bracket update", async ({ page, factories }) => {
 		test.slow();
 		const tournament = await factories.TournamentFactory.create({
@@ -49,44 +42,44 @@ test.describe("Tournament bracket elimination", () => {
 		const brackets = new TournamentBracketsPage(page);
 		await brackets.goto(tournament.id);
 
-		// 1)
+		// report winner of N-ZAP's first match
 		let match = await brackets.openMatch(nzapsMatchId);
 		await match.openTab("action");
 		await match.reportResult({ mapsToReport: 2 });
 		await match.backToBracket();
 
-		// 2)
+		// report winner of the adjacent match using admin powers
 		match = await brackets.openMatch(adjacentMatchId);
 		await match.openTab("action");
 		await match.reportResult({ mapsToReport: 2 });
 		await match.backToBracket();
 
-		// 3)
+		// report one map of the only losers side match available
 		match = await brackets.openMatch(losersMatchId);
 		await match.openTab("action");
 		await match.reportResult({ mapsToReport: 1, setEnds: false });
 		await match.backToBracket();
 
-		// 4)
+		// N-ZAP's first match can't be reopened while the losers match depends on it
 		match = await brackets.openMatch(nzapsMatchId);
 		await match.openTab("admin");
 		await isNotVisible(match.locators.reopenMatchButton);
 		await match.backToBracket();
 
-		// 5)
+		// undo the losers match score
 		match = await brackets.openMatch(losersMatchId);
 		await match.openTab("action");
 		await match.undoLastReport();
 		await expect(match.score([0, 0])).toBeVisible();
 		await match.backToBracket();
 
-		// 6)
+		// now the reopen succeeds
 		match = await brackets.openMatch(nzapsMatchId);
 		await match.openTab("admin");
 		await match.reopen();
 		await expect(match.score([1, 0])).toBeVisible();
 
-		// 7)
+		// as N-ZAP, undo every score and let the other team sweep instead
 		await impersonate(page, NZAP_TEST_ID);
 		await brackets.goto(tournament.id);
 		match = await brackets.openMatch(nzapsMatchId);
@@ -239,7 +232,7 @@ test.describe("Tournament bracket elimination", () => {
 		// match 3 is the winners' final the winner of match 1 waits in
 		match = await brackets.openMatch(3);
 		await match.openTab("admin");
-		// Picking a chip auto-submits the cast channel; lock the match afterwards.
+		// picking a chip auto-submits the cast channel
 		await match.setCastedBy("test");
 		await match.submitCastInfo();
 		await match.backToBracket();
@@ -252,16 +245,15 @@ test.describe("Tournament bracket elimination", () => {
 		await expect(brackets.locators.castBadges.first()).toBeVisible();
 		match = await brackets.openMatch(3);
 		await match.openTab("admin");
-		// Lock state is signalled by the toggle being "Unlock" instead of "Lock"
+		// the toggle reading "Unlock" is what signals the locked state
 		await expect(match.locators.unlockButton).toBeVisible();
-		// A locked match still needs to show the pool & room pass so players can join
+		// a locked match still shows the pool & room pass so players can join
 		await expect(match.locators.poolLabel).toBeVisible();
 		await expect(match.locators.roomPass).toBeVisible();
 		await match.submitCastInfo();
 		await expect(match.locators.stageBanner).toBeVisible();
 
-		// Cast channel "test" persists across unlock; the bracket badge flips
-		// from 🔒 CAST to 🔴 LIVE once the match is unlocked and ongoing.
+		// the cast channel persists across unlock; the bracket badge flips from CAST to LIVE
 		await match.backToBracket();
 		await expect(brackets.locators.liveBadges.first()).toBeVisible();
 	});
@@ -294,7 +286,6 @@ test.describe("Tournament bracket elimination", () => {
 		await admin.resetBracket("Main bracket");
 
 		await admin.adminTab("Teams").click();
-		// check the top seed back in
 		await admin.checkTeamIn(0);
 
 		const bracketsAfterReset = await admin.nav.openBrackets();
@@ -322,7 +313,6 @@ test.describe("Tournament bracket elimination", () => {
 
 		await impersonate(page);
 
-		// 1) Report partial score on the first winners bracket match
 		const brackets = new TournamentBracketsPage(page);
 		await brackets.goto(tournament.id);
 		let match = await brackets.openMatch(ongoingMatchId);
@@ -330,26 +320,23 @@ test.describe("Tournament bracket elimination", () => {
 		await match.reportResult({ mapsToReport: 1, winner: 1, setEnds: false });
 		await match.backToBracket();
 
-		// 2) Drop the fourth team (the bravo side of the ongoing match) via admin
+		// the fourth team is the bravo side of the ongoing match
 		const admin = new TournamentAdminPage(page);
 		await admin.goto(tournament.id);
 		await admin.dropOutTeam(3);
 
-		// 3) Verify the ongoing match ended early (no longer ongoing → "Final")
+		// dropping out ended the ongoing match early
 		await match.goto({ tournamentId: tournament.id, matchId: ongoingMatchId });
 		await expect(match.locators.finalBanner).toBeVisible();
 		await match.backToBracket();
 
-		// 4) Complete the adjacent match so its loser goes to losers bracket
+		// completing the adjacent match sends its loser to the losers bracket
 		match = await brackets.openMatch(adjacentMatchId);
 		await match.openTab("action");
 		await match.reportResult({ mapsToReport: 2 });
 		await match.backToBracket();
 
-		// 5) The losers bracket match should now have teams:
-		//    - Loser of the first match (the dropped team)
-		//    - Loser of the adjacent match
-		//    It should have ended early since the dropped team is in it
+		// the losers match, now holding the dropped team, ended early as well
 		match = await brackets.openMatch(losersMatchId);
 		await expect(match.locators.finalBanner).toBeVisible();
 	});
diff --git a/e2e/tournament-bracket-multi-stage.spec.ts b/e2e/tournament-bracket-multi-stage.spec.ts
index 6fe198809..81aee92d6 100644
--- a/e2e/tournament-bracket-multi-stage.spec.ts
+++ b/e2e/tournament-bracket-multi-stage.spec.ts
@@ -417,12 +417,11 @@ test.describe("Tournament bracket multi stage", () => {
 
 		await isNotVisible(brackets.locators.preparedMapsCheckIcon);
 
-		// should reuse prepared maps from Great White
+		// reuses the maps prepared for Great White
 		await brackets.bracketTab("Hammerhead").click();
 
 		await expect(brackets.locators.preparedMapsCheckIcon).toBeVisible();
 
-		// finally, test third place match linking
 		await brackets.bracketTab("Great White").click();
 
 		const unlinkDialog = await brackets.openPrepareMapsDialog();
@@ -435,7 +434,7 @@ test.describe("Tournament bracket multi stage", () => {
 
 		const relinkDialog = await brackets.openPrepareMapsDialog();
 
-		// link button should be visible because we unlinked and made finals and third place match maps different earlier
+		// linking is offered again since the finals and third place match maps now differ
 		await expect(relinkDialog.locators.linkFinalsButton).toBeVisible();
 	});
 });
diff --git a/e2e/tournament-bracket-pick-ban.spec.ts b/e2e/tournament-bracket-pick-ban.spec.ts
index 5a6a8fae7..98279e083 100644
--- a/e2e/tournament-bracket-pick-ban.spec.ts
+++ b/e2e/tournament-bracket-pick-ban.spec.ts
@@ -131,7 +131,6 @@ test.describe("Tournament bracket pick/ban", () => {
 			],
 		};
 
-		// 1) Start bracket with CUSTOM pick/ban flow
 		await impersonate(page);
 
 		const brackets = new TournamentBracketsPage(page);
@@ -144,7 +143,7 @@ test.describe("Tournament bracket pick/ban", () => {
 
 		const match = new TournamentMatchPage(page);
 
-		// 2) PreSet: Higher seed bans 2 maps
+		// PreSet: higher seed bans 2 maps
 		await impersonate(page, higherSeedCaptainId);
 		await match.goto({ tournamentId: tournament.id, matchId });
 		await match.openTab("action");
@@ -154,7 +153,7 @@ test.describe("Tournament bracket pick/ban", () => {
 		await expect(match.locators.lastBanText).toBeVisible();
 		await match.pickBan();
 
-		// 3) PreSet: Lower seed bans 2 maps
+		// PreSet: lower seed bans 2 maps
 		await impersonate(page, lowerSeedCaptainId);
 		await match.goto({ tournamentId: tournament.id, matchId });
 		await match.openTab("action");
@@ -164,21 +163,21 @@ test.describe("Tournament bracket pick/ban", () => {
 		await expect(match.locators.lastBanText).toBeVisible();
 		await match.pickBan();
 
-		// 4) Roll auto-executed after last ban; report game 1 score
+		// the roll auto-executes after the last ban
 		await expect(match.locators.stageBanner).toBeVisible();
 		await match.openTab("action");
 
 		await match.reportResult({ mapsToReport: 1, winner: 1, setEnds: false });
 		await expect(match.score([1, 0])).toBeVisible();
 
-		// 5) PostGame: Winner (the alpha team, whose captain is still impersonated) bans 2 maps
+		// PostGame: the winner (alpha, whose captain is still impersonated) bans 2 maps
 		await expect(match.locators.banAMapText).toBeVisible();
 		await match.pickBan();
 
 		await expect(match.locators.lastBanText).toBeVisible();
 		await match.pickBan();
 
-		// PostGame: Loser (the bravo team) picks a map
+		// PostGame: the loser (bravo) picks a map
 		await impersonate(page, higherSeedCaptainId);
 		await match.goto({ tournamentId: tournament.id, matchId });
 		await match.openTab("action");
@@ -186,14 +185,14 @@ test.describe("Tournament bracket pick/ban", () => {
 		await expect(match.locators.pickAMapText).toBeVisible();
 		await match.pickBan();
 
-		// 6) Undo game 1 score — also deletes postGame pick/ban events
+		// undoing game 1 also deletes the postGame pick/ban events
 		await expect(match.locators.stageBanner).toBeVisible();
 		await match.undoLastReport();
 
 		await expect(match.score([0, 0])).toBeVisible();
 		await expect(match.locators.stageBanner).toBeVisible();
 
-		// 7) Re-report game 1 and verify postGame cycle restarts
+		// the postGame cycle restarts
 		await match.openTab("action");
 		await match.reportResult({ mapsToReport: 1, winner: 1, setEnds: false });
 		await expect(match.score([1, 0])).toBeVisible();
diff --git a/e2e/tournament-bracket-round-robin.spec.ts b/e2e/tournament-bracket-round-robin.spec.ts
index 87bf6cff0..3d7cf0d29 100644
--- a/e2e/tournament-bracket-round-robin.spec.ts
+++ b/e2e/tournament-bracket-round-robin.spec.ts
@@ -66,14 +66,12 @@ test.describe("Tournament bracket round robin", () => {
 
 		await match.openTab("admin");
 		await match.editResultButton(0).click();
-		// Swap player 3 out for player 4 on the alpha (winner) team
 		await match.editResultPlayerCheckbox("alpha", 3).click();
 		await match.editResultPlayerCheckbox("alpha", 4).click();
-		// Toggle KO so we can verify the edit went through (RR collects KO).
+		// RR collects KO, which shows the edit went through
 		await match.locators.koCheckbox.check();
 		await match.saveResult(0);
 
-		// Edit returns to read-only view, now showing the KO label
 		await expect(match.editResultButton(0)).toBeVisible();
 		await expect(match.locators.koResultText).toBeVisible();
 	});
@@ -120,9 +118,8 @@ test.describe("Tournament bracket round robin", () => {
 		});
 		await createTeams(factories, tournament.id, teamSeeds(4));
 
-		// set situation where match A is completed and its participants also completed
-		// their follow up matches B & C and then we go back and change the winner of A:
-		// the two passes play rounds 1 (matches 1 & 2) and 2 (matches 3 & 4)
+		// the two passes play rounds 1 (matches 1 & 2) and 2 (matches 3 & 4), so the
+		// winner of a match whose participants already played on gets changed
 		await factories.TournamentFactory.startBracket(tournament.id);
 		await factories.TournamentFactory.playMatches(tournament.id);
 		await factories.TournamentFactory.playMatches(tournament.id);
@@ -135,10 +132,8 @@ test.describe("Tournament bracket round robin", () => {
 		const match = await brackets.openMatch(2);
 		await match.openTab("admin");
 		await match.reopen();
-		// Wait for the reopen to be reflected before switching tabs: switching
-		// tabs is a `defaultShouldRevalidate: false` navigation that would abort
-		// the still-in-flight post-reopen loader revalidation, leaving the match
-		// stuck as "over" so the action tab never appears.
+		// switching tabs is a `defaultShouldRevalidate: false` navigation that would
+		// abort the in-flight post-reopen revalidation, leaving the match "over"
 		await isNotVisible(match.locators.reopenMatchButton);
 		await match.openTab("action");
 		await match.undoLastReport();
@@ -160,7 +155,7 @@ test.describe("Tournament bracket round robin", () => {
 		});
 		await createTeams(factories, tournament.id, teamSeeds(4));
 
-		// Complete R1 matches (1 and 2) to unlock R2 matches
+		// playing R1 (matches 1 and 2) unlocks R2
 		await factories.TournamentFactory.startBracket(tournament.id);
 		await factories.TournamentFactory.playMatches(tournament.id);
 
@@ -169,21 +164,19 @@ test.describe("Tournament bracket round robin", () => {
 		const brackets = new TournamentBracketsPage(page);
 		await brackets.goto(tournament.id);
 
-		// Match 3 is R2 - should now be unlocked since R1 is complete
-		// Start it but don't complete it
+		// match 3 is R2: start it without completing it
 		let match = await brackets.openMatch(3);
 		await match.openTab("action");
 		await match.reportResult({ mapsToReport: 1, setEnds: false });
 		await match.backToBracket();
 
-		// Reopen match 1 (R1 match) - simulating a score misreport correction
+		// reopening the R1 match simulates a score misreport correction
 		match = await brackets.openMatch(1);
 		await match.openTab("admin");
 		await match.reopen();
 		await match.backToBracket();
 
-		// Verify the R2 match that was already in progress is still playable
-		// Before the fix, this would become locked and unplayable
+		// the R2 match already in progress used to become locked and unplayable
 		match = await brackets.openMatch(3);
 		await expect(match.score([1, 0])).toBeVisible();
 		await match.openTab("action");
diff --git a/e2e/tournament-bracket-swiss.spec.ts b/e2e/tournament-bracket-swiss.spec.ts
index 9cb18fad1..4edc84068 100644
--- a/e2e/tournament-bracket-swiss.spec.ts
+++ b/e2e/tournament-bracket-swiss.spec.ts
@@ -31,7 +31,6 @@ test.describe("Tournament bracket swiss", () => {
 		await brackets.goto(tournament.id);
 		await brackets.finalize();
 
-		// report all group A round 1 scores
 		for (const matchId of [1, 2, 3, 4]) {
 			const match = await brackets.openMatch(matchId);
 			await match.openTab("action");
@@ -39,7 +38,6 @@ test.describe("Tournament bracket swiss", () => {
 			await match.backToBracket();
 		}
 
-		// test that we can change to view different group
 		await expect(brackets.locators.startRoundButton).toBeVisible();
 		await brackets.openGroup("B");
 		await isNotVisible(brackets.locators.startRoundButton);
diff --git a/e2e/tournament-bracket.spec.ts b/e2e/tournament-bracket.spec.ts
index c64c768f9..adb1d75f9 100644
--- a/e2e/tournament-bracket.spec.ts
+++ b/e2e/tournament-bracket.spec.ts
@@ -35,7 +35,7 @@ test.describe("Tournament bracket", () => {
 
 		await expect(matchPage.locators.activeRosterNeededText).toBeVisible();
 
-		// The roster tab opens in editing mode by default when active roster is missing.
+		// the roster tab opens in editing mode while the active roster is missing
 		await matchPage.openTab("rosters");
 		await matchPage.playerCheckbox("bravo", 0).click();
 		await matchPage.playerCheckbox("bravo", 1).click();
@@ -43,13 +43,11 @@ test.describe("Tournament bracket", () => {
 		await matchPage.playerCheckbox("bravo", 3).click();
 		await matchPage.saveActiveRoster("bravo");
 
-		// did it persist?
 		await matchPage.goto({ tournamentId: tournament.id, matchId: match.id });
 		await isNotVisible(matchPage.locators.activeRosterNeededText);
 
 		await matchPage.openTab("rosters");
 		await matchPage.editActiveRosterButton("bravo").click();
-		// Swap player 3 out for player 4
 		await matchPage.playerCheckbox("bravo", 3).click();
 		await matchPage.playerCheckbox("bravo", 4).click();
 		await matchPage.saveActiveRoster("bravo");
@@ -180,10 +178,9 @@ test.describe("Tournament bracket", () => {
 
 		await expect(brackets.match(matchId)).toBeVisible();
 
-		// Verify timer shows on bracket page (timer is a sibling of the match link)
 		await expect(brackets.matchTimer(matchId)).toBeVisible();
 
-		// Fast forward time past limit (30 minutes for Bo3 = 26min limit)
+		// past the 26min limit of a Bo3
 		await page.clock.fastForward("30:00");
 		await page.reload();
 
@@ -192,7 +189,6 @@ test.describe("Tournament bracket", () => {
 		await match.openTab("admin");
 		await match.endSetWithRandomWinner();
 
-		// Match is now finalized (no longer ongoing) → "Final" appears in banner
 		await expect(match.locators.finalBanner).toBeVisible();
 	});
 
diff --git a/e2e/tournament-staff.spec.ts b/e2e/tournament-staff.spec.ts
index 9899e1ec3..da1ebbe0b 100644
--- a/e2e/tournament-staff.spec.ts
+++ b/e2e/tournament-staff.spec.ts
@@ -47,7 +47,7 @@ test.describe("Tournament staff", () => {
 		const admin = new TournamentAdminPage(page);
 		await admin.goto(tournament.id);
 
-		// check that got redirected since has no access
+		// no access yet, so redirected to info
 		await page.waitForURL("**/info");
 
 		await impersonate(page, ADMIN_ID);
@@ -58,7 +58,7 @@ test.describe("Tournament staff", () => {
 		await impersonate(page, NZAP_TEST_ID);
 		await admin.goto(tournament.id);
 
-		// being an organizer grants admin page access (no longer redirected to info)
+		// an organizer gets admin page access
 		await expect(admin.adminTab("Teams")).toBeVisible();
 		// but an organizer has no perms to manage staff
 		await isNotVisible(admin.adminTab("Staff"));
diff --git a/e2e/tournament-streams.spec.ts b/e2e/tournament-streams.spec.ts
index 8f01ded06..99279b6d8 100644
--- a/e2e/tournament-streams.spec.ts
+++ b/e2e/tournament-streams.spec.ts
@@ -29,7 +29,6 @@ test.describe("Tournament streams", () => {
 		await stream.fillAccount(1, "another_cast");
 		await stream.save();
 
-		// Verify persistence by navigating away and back
 		const brackets = new TournamentBracketsPage(page);
 		await brackets.goto(tournament.id);
 		await stream.goto(tournament.id);
@@ -56,12 +55,12 @@ test.describe("Tournament streams", () => {
 		await brackets.goto(tournament.id);
 
 		const match = await brackets.openMatch(matches[0].id);
-		// Report partial score to set startedAt (match becomes "in progress")
+		// a partial score sets startedAt, making the match in progress
 		await match.openTab("action");
 		await match.reportResult({ mapsToReport: 1, setEnds: false });
 		await match.backToBracket();
 
-		// The LIVE button should be visible since a match participant is streaming
+		// a participant of an in progress match is streaming
 		await expect(brackets.locators.liveBadges.first()).toBeVisible();
 
 		await brackets.locators.liveBadges.first().click();
diff --git a/e2e/user-page.spec.ts b/e2e/user-page.spec.ts
index b2f753101..bf1126e1e 100644
--- a/e2e/user-page.spec.ts
+++ b/e2e/user-page.spec.ts
@@ -48,7 +48,6 @@ test.describe("User page", () => {
 		await expect(userPage.badgeImage("Badge 12")).toBeVisible();
 		await userPage.locators.badgePaginationButtons.nth(1).click();
 
-		// test changing the big badge
 		await userPage.badgeImage("Badge 1").click();
 		await expect(userPage.badgeImage("Badge 1")).toHaveAttribute(
 			"width",
@@ -148,20 +147,17 @@ test.describe("User page", () => {
 		const settings = new SettingsPage(page);
 		await settings.goto("theme");
 
-		// initially no custom theme
 		await expect(settings.hasCustomTheme()).resolves.toBe(false);
 
 		await settings.setBaseHue("120");
 		await settings.saveTheme();
 		await settings.reload();
 
-		// verify custom theme was applied
 		await expect(settings.hasCustomTheme()).resolves.toBe(true);
 
 		await settings.resetTheme();
 		await settings.reload();
 
-		// verify custom theme was removed
 		await expect(settings.hasCustomTheme()).resolves.toBe(false);
 	});
 
diff --git a/playwright.config.ts b/playwright.config.ts
index cae60d2b9..44a60f14c 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -10,37 +10,22 @@ const WORKER_COUNT =
 	Number(process.env.E2E_WORKERS) ||
 	Math.min(8, Math.max(4, os.cpus().length - 2));
 
-/**
- * See https://playwright.dev/docs/test-configuration.
- */
 const config: PlaywrightTestConfig = {
 	testDir: "./e2e",
-	/* Maximum time one test can run for. */
 	timeout: 30 * 1000,
 	expect: {
-		/**
-		 * Maximum time expect() should wait for the condition to be met.
-		 * For example in `await expect(locator).toHaveText();`
-		 */
 		timeout: 5000,
 	},
-	/* Run tests in files in parallel */
 	fullyParallel: true,
-	/* Fail the build on CI if you accidentally left test.only in the source code. */
 	forbidOnly: !!process.env.CI,
 	retries: 0,
-	/* Number of parallel workers */
 	workers: WORKER_COUNT,
-	/* Reporter to use. See https://playwright.dev/docs/test-reporters */
 	reporter: "list",
-	/* Global setup and teardown for managing multiple server instances */
 	globalSetup: "./e2e/global-setup.ts",
 	globalTeardown: "./e2e/global-teardown.ts",
-	/* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
 	use: {
-		/* Maximum time each action such as `click()` can take. Defaults to 0 (no limit). */
 		actionTimeout: 0,
-		/* Base URL will be set per-worker by the fixture */
+		/* overridden per-worker by the fixture */
 		baseURL: "http://localhost:6173",
 
 		// DOM snapshots are the expensive part of tracing (~17% of total test
@@ -54,7 +39,6 @@ const config: PlaywrightTestConfig = {
 		permissions: ["clipboard-read", "clipboard-write"],
 	},
 
-	/* Configure projects for major browsers */
 	projects: [
 		{
 			name: "chromium",
@@ -62,53 +46,8 @@ const config: PlaywrightTestConfig = {
 				...devices["Desktop Chrome"],
 			},
 		},
-
-		// {
-		//   name: "firefox",
-		//   use: {
-		//     ...devices["Desktop Firefox"],
-		//   },
-		// },
-
-		// {
-		//   name: "webkit",
-		//   use: {
-		//     ...devices["Desktop Safari"],
-		//   },
-		// },
-
-		/* Test against mobile viewports. */
-		// {
-		//   name: 'Mobile Chrome',
-		//   use: {
-		//     ...devices['Pixel 5'],
-		//   },
-		// },
-		// {
-		//   name: 'Mobile Safari',
-		//   use: {
-		//     ...devices['iPhone 12'],
-		//   },
-		// },
-
-		/* Test against branded browsers. */
-		// {
-		//   name: 'Microsoft Edge',
-		//   use: {
-		//     channel: 'msedge',
-		//   },
-		// },
-		// {
-		//   name: 'Google Chrome',
-		//   use: {
-		//     channel: 'chrome',
-		//   },
-		// },
 	],
 
-	/* Folder for test artifacts such as screenshots, videos, traces, etc. */
-	// outputDir: 'test-results/',
-
 	build: {
 		external: ["**/*.json"],
 	},
diff --git a/react-router.config.ts b/react-router.config.ts
index cd53bbf60..26edf6ff7 100644
--- a/react-router.config.ts
+++ b/react-router.config.ts
@@ -1,9 +1,7 @@
 import type { Config } from "@react-router/dev/config";
 
 export default {
-	// Upfront cost vs. lazy loading trade-off
-	// also lazy loading causes more load on the server
-	// this matches old Remix v2 behavior
+	// lazy discovery would add server load; matches old Remix v2 behavior
 	routeDiscovery: { mode: "initial" },
 	splitRouteModules: true,
 } satisfies Config;
diff --git a/scripts/benchmark-db/cases.ts b/scripts/benchmark-db/cases.ts
index 26dcf7e30..76cb051c7 100644
--- a/scripts/benchmark-db/cases.ts
+++ b/scripts/benchmark-db/cases.ts
@@ -60,10 +60,7 @@ export interface BenchmarkCase {
 	run: () => Promise<unknown>;
 }
 
-/**
- * Builds the full benchmark case registry from resolved fixtures. Cases whose
- * fixture resolved to null are returned in `skipped` instead.
- */
+/** Builds the benchmark case registry from resolved fixtures; cases whose fixture resolved to null go to `skipped`. */
 export function buildCases(fx: Fixtures): {
 	cases: BenchmarkCase[];
 	skipped: string[];
@@ -87,7 +84,6 @@ export function buildCases(fx: Fixtures): {
 		cases.push({ name, run: async () => run() });
 	}
 
-	// AdminRepository
 	addStatic("AdminRepository.findAllBannedUsers", () =>
 		AdminRepository.findAllBannedUsers(),
 	);
@@ -95,7 +91,6 @@ export function buildCases(fx: Fixtures): {
 		AdminRepository.findModNoteById(id),
 	);
 
-	// ExternalStreamRepository
 	addStatic("ExternalStreamRepository.findAll", () =>
 		ExternalStreamRepository.findAll(),
 	);
@@ -103,7 +98,6 @@ export function buildCases(fx: Fixtures): {
 		ExternalStreamRepository.findAllForSidebar(),
 	);
 
-	// ApiRepository
 	add("ApiRepository.findTokenByUserId", fx.apiTokenUserId, (userId) =>
 		ApiRepository.findTokenByUserId(userId, "read"),
 	);
@@ -111,7 +105,6 @@ export function buildCases(fx: Fixtures): {
 		ApiRepository.findAllApiTokens(),
 	);
 
-	// ArtRepository
 	addStatic("ArtRepository.findShowcaseArts", () =>
 		ArtRepository.findShowcaseArts(),
 	);
@@ -129,7 +122,6 @@ export function buildCases(fx: Fixtures): {
 		ArtRepository.findById(artId),
 	);
 
-	// AssociationRepository
 	add("AssociationRepository.findById", fx.heavyAssociation, (association) =>
 		AssociationRepository.findById(association.id, { withMembers: true }),
 	);
@@ -155,12 +147,10 @@ export function buildCases(fx: Fixtures): {
 		(association) => AssociationRepository.findInviteCodeById(association.id),
 	);
 
-	// LogInLinkRepository
 	add("LogInLinkRepository.findValidByCode", fx.logInLinkCode, (code) =>
 		LogInLinkRepository.findValidByCode(code),
 	);
 
-	// AvailabilityRepository
 	add(
 		"AvailabilityRepository.findAllWeeksByUserIds",
 		both(fx.manyUserIds, fx.availabilityWindow),
@@ -220,7 +210,6 @@ export function buildCases(fx: Fixtures): {
 		AvailabilityRepository.findTeamEventById(id),
 	);
 
-	// BadgeRepository
 	addStatic("BadgeRepository.findAll", () => BadgeRepository.findAll());
 	add("BadgeRepository.findById", fx.heavyBadgeId, (badgeId) =>
 		BadgeRepository.findById(badgeId),
@@ -238,7 +227,6 @@ export function buildCases(fx: Fixtures): {
 		BadgeRepository.findByAuthorUserId(userId),
 	);
 
-	// BuildRepository
 	add("BuildRepository.findAllByUserId", fx.heavyBuildUserId, (userId) =>
 		BuildRepository.findAllByUserId(userId, {
 			showPrivate: true,
@@ -269,7 +257,6 @@ export function buildCases(fx: Fixtures): {
 		}),
 	);
 
-	// CalendarRepository
 	add(
 		"CalendarRepository.findAllBetweenTwoTimestamps",
 		fx.calendarWindow,
@@ -297,7 +284,6 @@ export function buildCases(fx: Fixtures): {
 		(eventId) => CalendarRepository.findTopThreeResultsByEventIds([eventId]),
 	);
 
-	// ChatRepository
 	add("ChatRepository.findAllRoomsByIds", fx.heavyChatUsers, (chatUsers) =>
 		ChatRepository.findAllRoomsByIds(chatUsers.busiest.openRoomIds),
 	);
@@ -329,7 +315,6 @@ export function buildCases(fx: Fixtures): {
 			),
 	);
 
-	// ChatRoomResolver
 	// a tournament match room is the costliest to resolve: its owner join carries
 	// the team members and the tournament's organizer permissions on top
 	add(
@@ -341,7 +326,6 @@ export function buildCases(fx: Fixtures): {
 		ChatRoomResolver.findAllByUserId(chatUsers.busiest.id),
 	);
 
-	// FriendRepository
 	add("FriendRepository.findByUserIdWithActivity", fx.heavyFriendPair, (pair) =>
 		FriendRepository.findByUserIdWithActivity(pair.userId),
 	);
@@ -391,7 +375,6 @@ export function buildCases(fx: Fixtures): {
 		(request) => FriendRepository.findFriendRequestByIdAndReceiver(request),
 	);
 
-	// ImageRepository
 	add("ImageRepository.findById", fx.imageId, (imageId) =>
 		ImageRepository.findById(imageId),
 	);
@@ -410,7 +393,6 @@ export function buildCases(fx: Fixtures): {
 		(userId) => ImageRepository.countUnvalidatedBySubmitterUserId(userId),
 	);
 
-	// LeaderboardRepository
 	add("LeaderboardRepository.findTeamLeaderboardBySeason", fx.sq, (sq) =>
 		LeaderboardRepository.findTeamLeaderboardBySeason({
 			season: sq.season,
@@ -441,7 +423,6 @@ export function buildCases(fx: Fixtures): {
 		LeaderboardRepository.findSeasonPopularUsersWeapon(sq.season),
 	);
 
-	// LFGRepository
 	addStatic("LFGRepository.findAllPosts.anon", () =>
 		LFGRepository.findAllPosts(),
 	);
@@ -452,17 +433,14 @@ export function buildCases(fx: Fixtures): {
 		LFGRepository.findByAuthorUserId(authorId),
 	);
 
-	// LiveStreamRepository
 	addStatic("LiveStreamRepository.findXRankStreams", () =>
 		LiveStreamRepository.findXRankStreams(),
 	);
 
-	// MatchProfileRepository
 	add("MatchProfileRepository.findSettingsByUserId", fx.heavyUser, (user) =>
 		MatchProfileRepository.findSettingsByUserId(user.id),
 	);
 
-	// SkillRepository (app/features/mmr)
 	add("SkillRepository.findCurrentUserSkills", fx.skillBatch, (skillBatch) =>
 		SkillRepository.findCurrentUserSkills({
 			season: skillBatch.season,
@@ -497,7 +475,6 @@ export function buildCases(fx: Fixtures): {
 		SkillRepository.findSeasonActiveDaysByUserId(sq),
 	);
 
-	// NotificationRepository
 	add("NotificationRepository.findByUserId", fx.notification, (notification) =>
 		NotificationRepository.findByUserId(notification.userId, { limit: 50 }),
 	);
@@ -510,7 +487,6 @@ export function buildCases(fx: Fixtures): {
 		(userIds) => NotificationRepository.findAllSubscriptionsByUserIds(userIds),
 	);
 
-	// PlusSuggestionRepository
 	add(
 		"PlusSuggestionRepository.findAllByMonth",
 		fx.plusSuggestionMonthYear,
@@ -530,7 +506,6 @@ export function buildCases(fx: Fixtures): {
 		(args) => PlusSuggestionRepository.findMonthSummary(args),
 	);
 
-	// PlusVotingRepository
 	addStatic("PlusVotingRepository.findAllPlusTiersFromLatestVoting", () =>
 		PlusVotingRepository.findAllPlusTiersFromLatestVoting(),
 	);
@@ -550,7 +525,6 @@ export function buildCases(fx: Fixtures): {
 		}),
 	);
 
-	// ScannerIngestRepository
 	add(
 		"ScannerIngestRepository.gamesPlayedByUserInTournament",
 		fx.scannerIngest,
@@ -637,7 +611,6 @@ export function buildCases(fx: Fixtures): {
 			ScannerIngestRepository.gamesInTournamentMatch(tournamentMatchId),
 	);
 
-	// ScrimMapListRepository
 	add(
 		"ScrimMapListRepository.findMapListsByScrimPostId",
 		fx.heavyScrimPostId,
@@ -645,14 +618,12 @@ export function buildCases(fx: Fixtures): {
 			ScrimMapListRepository.findMapListsByScrimPostId(scrimPostId),
 	);
 
-	// ScrimMapRepository
 	add(
 		"ScrimMapRepository.findMapsByScrimPostId",
 		fx.heavyScrimPostId,
 		(scrimPostId) => ScrimMapRepository.findMapsByScrimPostId(scrimPostId),
 	);
 
-	// ScrimPostRepository
 	add(
 		"ScrimPostRepository.findAllByChatRoomIds",
 		fx.openChatRoomIdsByType?.SCRIM ?? null,
@@ -699,14 +670,12 @@ export function buildCases(fx: Fixtures): {
 			}),
 	);
 
-	// GroupMatchContinueVoteRepository
 	add(
 		"GroupMatchContinueVoteRepository.findAllByGroupIds",
 		fx.heavyGroupIds,
 		(groupIds) => GroupMatchContinueVoteRepository.findAllByGroupIds(groupIds),
 	);
 
-	// PlayerStatRepository
 	add("PlayerStatRepository.findSeasonMapWinrateByUserId", fx.sq, (sq) =>
 		PlayerStatRepository.findSeasonMapWinrateByUserId(sq),
 	);
@@ -732,7 +701,6 @@ export function buildCases(fx: Fixtures): {
 		PlayerStatRepository.findSeasonTournamentRunsByUserId(sq),
 	);
 
-	// ReportedWeaponRepository
 	add(
 		"ReportedWeaponRepository.findByMatchId",
 		fx.heavyGroupMatchId,
@@ -760,7 +728,6 @@ export function buildCases(fx: Fixtures): {
 			}),
 	);
 
-	// SQMatchRepository
 	add(
 		"SQMatchRepository.findAllByChatRoomIds",
 		fx.openChatRoomIdsByType?.SQ_MATCH ?? null,
@@ -793,12 +760,11 @@ export function buildCases(fx: Fixtures): {
 			}),
 	);
 
-	// QStreamsRepository
 	addStatic("QStreamsRepository.findAllActiveMatchPlayers", () =>
 		QStreamsRepository.findAllActiveMatchPlayers(),
 	);
 
-	// PrivateUserNoteRepository (relies on the benchmark's actor context)
+	// relies on the benchmark's actor context
 	addStatic("PrivateUserNoteRepository.findAllOwn.all", () =>
 		PrivateUserNoteRepository.findAllOwn(),
 	);
@@ -808,7 +774,6 @@ export function buildCases(fx: Fixtures): {
 		(userIds) => PrivateUserNoteRepository.findAllOwn(userIds),
 	);
 
-	// SQGroupRepository
 	add(
 		"SQGroupRepository.findAllByChatRoomIds",
 		fx.openChatRoomIdsByType?.SQ_GROUP ?? null,
@@ -858,12 +823,10 @@ export function buildCases(fx: Fixtures): {
 		SQGroupRepository.findRecentlyFinishedMatches(),
 	);
 
-	// SplatoonRotationRepository
 	addStatic("SplatoonRotationRepository.findAll", () =>
 		SplatoonRotationRepository.findAll(),
 	);
 
-	// TeamRepository
 	addStatic("TeamRepository.searchByName", () =>
 		TeamRepository.searchByName(SEARCH_QUERY),
 	);
@@ -888,7 +851,6 @@ export function buildCases(fx: Fixtures): {
 		TeamRepository.findAllByMemberUserId(team.memberUserId),
 	);
 
-	// XRankPlacementRepository
 	add("XRankPlacementRepository.isPlayerLinkedByUserId", fx.xrank, (xrank) =>
 		XRankPlacementRepository.isPlayerLinkedByUserId(xrank.userId),
 	);
@@ -919,14 +881,12 @@ export function buildCases(fx: Fixtures): {
 		XRankPlacementRepository.findPeaksByUserId(xrank.userId, "both"),
 	);
 
-	// BracketRepository
 	add(
 		"BracketRepository.findByTournamentId",
 		fx.heaviestBracketTournamentId,
 		(tournamentId) => BracketRepository.findByTournamentId(tournamentId),
 	);
 
-	// TournamentMatchVodRepository
 	add(
 		"TournamentMatchVodRepository.findVodsByTournamentId",
 		fx.heavyTournamentId,
@@ -957,7 +917,6 @@ export function buildCases(fx: Fixtures): {
 			),
 	);
 
-	// TournamentLFGRepository
 	add(
 		"TournamentLFGRepository.findLookingTeamsByTournamentId",
 		fx.lfgTournament,
@@ -977,7 +936,6 @@ export function buildCases(fx: Fixtures): {
 			TournamentLFGRepository.findAllSubsByTournamentId(lfg.tournamentId),
 	);
 
-	// TournamentMatchRepository
 	add(
 		"TournamentMatchRepository.findAllByChatRoomIds",
 		fx.openChatRoomIdsByType?.TOURNAMENT_MATCH ?? null,
@@ -1019,7 +977,6 @@ export function buildCases(fx: Fixtures): {
 			TournamentMatchRepository.findByTournamentTeamId(tournamentTeamId),
 	);
 
-	// TournamentOrganizationRepository
 	add("TournamentOrganizationRepository.findBySlug", fx.heavyOrg, (org) =>
 		TournamentOrganizationRepository.findBySlug(org.slug),
 	);
@@ -1109,7 +1066,6 @@ export function buildCases(fx: Fixtures): {
 			}),
 	);
 
-	// SavedCalendarEventRepository
 	add(
 		"SavedCalendarEventRepository.isSaved",
 		both(fx.heavyUser, fx.heavyTournamentId),
@@ -1128,7 +1084,6 @@ export function buildCases(fx: Fixtures): {
 		(user) => SavedCalendarEventRepository.findAllUpcomingByUserId(user.id),
 	);
 
-	// TournamentAuditLogRepository
 	add(
 		"TournamentAuditLogRepository.findByTournamentId",
 		fx.auditTournamentId,
@@ -1152,7 +1107,6 @@ export function buildCases(fx: Fixtures): {
 			TournamentAuditLogRepository.findTeamsByTournamentId(tournamentId),
 	);
 
-	// TournamentRepository
 	add(
 		"TournamentRepository.findOrganizerPermissionsByTournamentIds",
 		fx.recentTournamentIds,
@@ -1269,7 +1223,6 @@ export function buildCases(fx: Fixtures): {
 		TournamentRepository.findRunningTournamentIds(),
 	);
 
-	// TournamentTeamRepository
 	add(
 		"TournamentTeamRepository.findAllByChatRoomIds",
 		fx.openChatRoomIdsByType?.TOURNAMENT_TEAM ?? null,
@@ -1325,7 +1278,6 @@ export function buildCases(fx: Fixtures): {
 			}),
 	);
 
-	// TrophyRepository
 	addStatic("TrophyRepository.all", () => TrophyRepository.all());
 	add("TrophyRepository.findById", fx.trophy, (trophy) =>
 		TrophyRepository.findById(trophy.heavyTrophyId),
@@ -1340,7 +1292,6 @@ export function buildCases(fx: Fixtures): {
 		TrophyRepository.findWinsByOwner(trophy.wins),
 	);
 
-	// UserCardRepository
 	add("UserCardRepository.findAllByUserIds", fx.manyUserIds, (userIds) =>
 		UserCardRepository.findAllByUserIds({
 			userIds,
@@ -1358,7 +1309,6 @@ export function buildCases(fx: Fixtures): {
 		UserCardRepository.findVerifiedXpByUserId(user.id, null),
 	);
 
-	// UserRepository
 	add("UserRepository.findIdByIdentifier", fx.heavyUser, (user) =>
 		UserRepository.findIdByIdentifier(user.identifier),
 	);
@@ -1463,7 +1413,6 @@ export function buildCases(fx: Fixtures): {
 		UserRepository.findWeaponPoolByUserId(user.id),
 	);
 
-	// VodRepository
 	add("VodRepository.findByUserId", fx.vod, (vod) =>
 		VodRepository.findByUserId(vod.userId),
 	);
diff --git a/scripts/benchmark-db/fixtures.ts b/scripts/benchmark-db/fixtures.ts
index beb65af01..be24714f1 100644
--- a/scripts/benchmark-db/fixtures.ts
+++ b/scripts/benchmark-db/fixtures.ts
@@ -137,10 +137,8 @@ export interface Fixtures {
 }
 
 /**
- * Resolves "worst-case" benchmark arguments by sampling the heaviest rows from
- * the database (user with most tournament results, tournament with most teams
- * and so on). Fields resolve to null when the source table is empty which
- * causes the dependent benchmark cases to be skipped.
+ * Resolves worst-case benchmark arguments by sampling the heaviest rows (user with most
+ * results, tournament with most teams...). Fields resolve to null when the source table is empty, skipping their cases.
  */
 export async function resolveFixtures(): Promise<Fixtures> {
 	const heavyUser = await resolveHeavyUser();
diff --git a/scripts/check-translation-jsons.ts b/scripts/check-translation-jsons.ts
index 9582348d4..86ddc2ba3 100644
--- a/scripts/check-translation-jsons.ts
+++ b/scripts/check-translation-jsons.ts
@@ -12,10 +12,8 @@ const dontWrite = process.argv.includes(NO_WRITE_KEY);
 
 const KNOWN_SUFFIXES = ["_zero", "_one", "_two", "_few", "_many", "_other"];
 
-// `_zero` is an i18next `count === 0` override, not a CLDR plural category. It
-// may legitimately sit alongside the bare singular key that single-plural
-// languages (zh, ja, ko) use after `i18n:sync` collapses their plural forms, so
-// unlike the real plural suffixes it never counts as a with/without-suffix clash.
+// `_zero` is an i18next `count === 0` override, not a CLDR category: it legitimately sits beside the
+// bare singular key single-plural languages (zh, ja, ko) use, so it never counts as a suffix clash
 const ZERO_SUFFIX = "_zero";
 const PLURAL_SUFFIXES = KNOWN_SUFFIXES.filter((sfx) => sfx !== ZERO_SUFFIX);
 
@@ -188,7 +186,7 @@ function validateNoDuplicateKeys({
 	}
 }
 
-// get keys while respecting different plural/context key suffixes in different languages.
+// keys with their language-specific plural/context suffixes stripped
 function getKeysWithoutSuffix(
 	translations: Record<string, string>,
 	lang: string,
diff --git a/scripts/collapse-single-plural-keys.ts b/scripts/collapse-single-plural-keys.ts
index 97cb192fc..e54ca5f71 100644
--- a/scripts/collapse-single-plural-keys.ts
+++ b/scripts/collapse-single-plural-keys.ts
@@ -9,31 +9,22 @@ const __dirname = path.dirname(__filename);
 const LOCALES_PATH = path.join(__dirname, "..", "locales");
 const PRIMARY_LANGUAGE = "en";
 
-// When passed, no files are written. Instead the script exits non-zero if any
-// file would be collapsed, so CI can fail a PR that committed suffixed plural
-// keys in a single-plural language without running `pnpm run i18n:sync`.
+// writes nothing and exits non-zero if any file would be collapsed, so CI can
+// fail a PR that committed suffixed plural keys without running `pnpm run i18n:sync`
 const CHECK_KEY = "--check";
 const checkOnly = process.argv.includes(CHECK_KEY);
 
-// `_zero` is intentionally excluded: it is not a CLDR plural category but an
-// i18next special-case override for `count === 0`. `i18next-locales-sync` treats
-// e.g. `foo_zero` as a plain key (English has no `_zero` plural form), so it is
-// preserved across every language and must not be collapsed into `foo`.
+// `_zero` is excluded: an i18next `count === 0` override rather than a CLDR category, which
+// `i18next-locales-sync` treats as a plain key preserved across every language
 const COLLAPSIBLE_PLURAL_SUFFIXES = ["_one", "_two", "_few", "_many", "_other"];
 
-// The plural form whose value we keep when collapsing. `_other` is preferred
-// because it is the form i18next resolves at runtime for these languages and it
-// typically carries the `{{count}}` interpolation. The remaining forms are only
-// used as a fallback when `_other` has no translated value.
+// the form i18next resolves at runtime for these languages, typically carrying `{{count}}`;
+// the other forms are only a fallback when it has no translated value
 const PREFERRED_SUFFIX = "_other";
 
-// `i18next-locales-sync` stores plural keys for languages whose CLDR cardinal
-// rule has a single category ("other" only, e.g. zh, ja, ko) under the bare
-// singular key instead of suffixed `_one`/`_other` keys. When a translator adds
-// a value under a suffixed key for one of these languages, the sync tool can't
-// find the singular key it expects and silently drops the translation. We run
-// this before the sync to collapse those suffixed keys into the singular key,
-// preserving the (non-empty) value so it survives the sync.
+// `i18next-locales-sync` keys single-category languages (zh, ja, ko) by the bare singular key;
+// a translation a translator added under a suffixed key is silently dropped by the sync unless
+// collapsed into the singular key first, which is what this script does
 const languages = fs
 	.readdirSync(LOCALES_PATH)
 	.filter((lang) => lang !== PRIMARY_LANGUAGE && !lang.startsWith("."));
@@ -103,8 +94,7 @@ function collapsePluralKeys(content: Record<string, string>) {
 		collapsedBaseKeys.add(baseKey);
 		const isPreferred = suffix === PREFERRED_SUFFIX;
 
-		// prefer the `_other` value (it carries {{count}}); otherwise keep the
-		// first non-empty value found across the remaining plural forms
+		// `_other` wins; otherwise the first non-empty value of the remaining forms
 		const shouldReplace =
 			!(baseKey in collapsed) ||
 			(!collapsed[baseKey] && !!value) ||
diff --git a/scripts/create-analyzer-json.ts b/scripts/create-analyzer-json.ts
index 70457613b..daad64186 100644
--- a/scripts/create-analyzer-json.ts
+++ b/scripts/create-analyzer-json.ts
@@ -695,20 +695,16 @@ function parametersToSubWeaponResult(
 	};
 }
 
-// Thrown targeting specials (Booyah Bomb, Super Chump, Triple Inkstrike, Ultra Stamp) are
-// player-aimed and have no throw-distance param in the game data, so their throw (fly) range is
-// approximated with a constant. Kept as named per-special constants so each can be tuned later;
-// for now they all reuse Booyah Bomb's value.
+// Thrown targeting specials (Booyah Bomb, Super Chump, Triple Inkstrike, Ultra Stamp) are player-aimed
+// with no throw-distance param, so their fly range is a per-special constant, all Booyah Bomb's value for now.
 const BOOYAH_BOMB_FLY_DISTANCE = 27;
 const SUPER_CHUMP_FLY_DISTANCE = 30;
 const TRIPLE_INKSTRIKE_FLY_DISTANCE = 28;
 const ULTRA_STAMP_FLY_DISTANCE = 24;
 
-// Range circle data for the map planner. Projectile / thrown specials store the distance the shot
-// travels plus its blast; a few store a single effect radius. Specials whose reach is global
-// (Tenta Missiles, Killer Wail), placed or utility (Big Bubbler, Tacticooler, Ink Storm, Ink Vac),
-// or otherwise has no meaningful circle (Kraken Royale, Splattercolor Screen) are left out.
-// See app/features/comp-analyzer/core/special-weapon-range.ts.
+// Range circles for the map planner (see app/features/comp-analyzer/core/special-weapon-range.ts):
+// travel distance plus blast, or a single effect radius. Global (Tenta Missiles, Killer Wail), placed/utility
+// (Big Bubbler, Tacticooler, Ink Storm, Ink Vac) and circle-less (Kraken Royale, Splattercolor Screen) specials are left out.
 function specialWeaponRangeParams(
 	specialWeapon: SpecialWeapon,
 	rawParams: any,
@@ -785,8 +781,7 @@ function specialWeaponRangeParams(
 	}
 }
 
-// some specials lack damage values in the params
-// so they are instead hardcoded here as a workaround
+// some specials lack damage values in the params, so they are hardcoded here
 function parametersToSpecialWeaponResult(params: any) {
 	const result: any = {};
 
diff --git a/scripts/create-object-dmg-json.ts b/scripts/create-object-dmg-json.ts
index 6ff5cc3e1..ab92b17a2 100644
--- a/scripts/create-object-dmg-json.ts
+++ b/scripts/create-object-dmg-json.ts
@@ -114,9 +114,8 @@ const specialIdsForRow = (rowKey: string) =>
 	);
 
 /**
- * Resolves the per-target damage rate of every damage rate info row in a single config dump.
- * Only the PvP-relevant receivers are kept and the synthetic launched/Recycled Brella canopy
- * targets are derived the same way the live object damage calculator expects them.
+ * Per-target damage rates of every damage rate info row in one config dump, PvP-relevant receivers
+ * only, with the synthetic launched/Recycled Brella canopy targets derived as the calculator expects.
  */
 const damageRatesByRow = (
 	config: DamageRateConfig,
@@ -190,9 +189,8 @@ function versionDirToDisplay(version: string): string {
 }
 
 /**
- * Builds the per-row, per-target damage rate history across every versioned config dump and
- * writes it for the params page to surface in its patch history. Only PvP-relevant rows and
- * only targets whose rate actually changed at some point are kept, so the output stays small.
+ * Writes the per-row, per-target damage rate history across every versioned dump for the params
+ * page's patch history. Only PvP-relevant rows and targets whose rate ever changed are kept.
  */
 function writeDamageRateHistory() {
 	const versionDirs = fs
diff --git a/scripts/ensure-test-db.ts b/scripts/ensure-test-db.ts
index 9a1850035..c409d76c4 100644
--- a/scripts/ensure-test-db.ts
+++ b/scripts/ensure-test-db.ts
@@ -15,23 +15,17 @@ const TEST_DB_PATH = path.join(ROOT_DIR, "db-test.sqlite3");
 export function setup() {
 	ensureMigratedDb(TEST_DB_PATH);
 
-	// Test workers only ever read this file, to copy its schema into their own
-	// in-memory database. Taking it out of WAL drops the -wal/-shm sidecars, so
-	// those concurrent opens need no write access and cannot contend.
+	// test workers only read this file to copy its schema; out of WAL there are no
+	// -wal/-shm sidecars, so their concurrent opens need no write access
 	const db = new DatabaseSync(TEST_DB_PATH);
 	db.exec("PRAGMA journal_mode = DELETE");
 	db.close();
 }
 
 /**
- * Ensures the SQLite file at `dbPath` has every migration applied: creates it
- * if missing, applies pending migrations, and rebuilds it from scratch if an
- * already applied migration no longer exists on disk or its contents changed
- * since it was applied.
- *
- * Rebuilding on changed contents matters because a branch edits the migration
- * it added rather than stacking a new one, so the file name kysely tracks stays
- * the same while the schema it produces does not.
+ * Creates `dbPath` if missing, applies pending migrations, and rebuilds it from scratch if an
+ * applied migration disappeared or changed contents: a branch edits the migration it added
+ * rather than stacking a new one, so the file name kysely tracks stays the same while the schema does not.
  */
 export function ensureMigratedDb(dbPath: string) {
 	const resolvedPath = path.resolve(ROOT_DIR, dbPath);
diff --git a/scripts/generate-changelog-image.ts b/scripts/generate-changelog-image.ts
index db828f377..2ecdd5e65 100644
--- a/scripts/generate-changelog-image.ts
+++ b/scripts/generate-changelog-image.ts
@@ -120,10 +120,7 @@ async function main() {
 	}
 }
 
-/**
- * The screenshotted page is whatever dev server holds the port, which can be another
- * checkout of the repo whose entries are not the ones being shipped.
- */
+/** The dev server holding the port can be another checkout whose entries are not the ones being shipped. */
 async function assertSameCheckout(page: Page) {
 	const marker = page.locator("[data-changelog-head]");
 	const pageHead =
diff --git a/scripts/generate-og-images.ts b/scripts/generate-og-images.ts
index 4952f5b74..5206cbdca 100644
--- a/scripts/generate-og-images.ts
+++ b/scripts/generate-og-images.ts
@@ -37,8 +37,7 @@ async function main() {
 	});
 
 	await page.goto(OG_IMAGES_PAGE_URL, { waitUntil: "networkidle" });
-	// the page previews the canvases scaled down and inside the site layout, the
-	// one being captured is blown up to full size and lifted on top of everything
+	// the page previews the canvases scaled down; the captured one is blown up to full size on top of everything
 	await page.addStyleTag({
 		content: `
 			* { --og-scale: 1 !important }
diff --git a/scripts/org-monthly-active-players.ts b/scripts/org-monthly-active-players.ts
index 22b03ba77..373b20dd3 100644
--- a/scripts/org-monthly-active-players.ts
+++ b/scripts/org-monthly-active-players.ts
@@ -1,7 +1,5 @@
-// calculates org stats for the last 6 finished months
-// used to decide which orgs are considered "established"
-// you need at least 150 average monthly active players to be considered established
-// if you drop below 100 you lose it
+// org stats for the last 6 finished months, deciding which orgs are "established":
+// 150 average monthly active players to gain it, dropping below 100 loses it
 
 import { db } from "~/db/sql";
 import { logger } from "~/utils/logger";
diff --git a/scripts/refresh-prod-db.ts b/scripts/refresh-prod-db.ts
index c6f8bb6e6..48f477ec4 100644
--- a/scripts/refresh-prod-db.ts
+++ b/scripts/refresh-prod-db.ts
@@ -18,22 +18,18 @@ function main() {
 		process.exit(1);
 	}
 
-	// delete db-prod.sqlite3-shm file if exists
 	if (fs.existsSync(dbProdShmPath)) {
 		fs.unlinkSync(dbProdShmPath);
 	}
 
-	// delete db-prod.sqlite3-wal file if exists
 	if (fs.existsSync(dbProdWalPath)) {
 		fs.unlinkSync(dbProdWalPath);
 	}
 
-	// delete db-prod.sqlite3 if exists
 	if (fs.existsSync(dbProdPath)) {
 		fs.unlinkSync(dbProdPath);
 	}
 
-	// copy db-copy.sqlite3 to db-prod.sqlite3
 	fs.copyFileSync(dbCopyPath, dbProdPath);
 }
 
diff --git a/scripts/scanner/bootstrap-atlas-from-fixture.ts b/scripts/scanner/bootstrap-atlas-from-fixture.ts
index ee2ea4aef..884f65834 100644
--- a/scripts/scanner/bootstrap-atlas-from-fixture.ts
+++ b/scripts/scanner/bootstrap-atlas-from-fixture.ts
@@ -1,15 +1,14 @@
 /** biome-ignore-all lint/suspicious/noConsole: CLI script output */
 /**
- * Bootstrap glyph atlases from the labeled reference fixtures: slices glyph
- * templates straight out of the reference frames, since the same scoreboard
- * captured through different pipelines (OBS virtual camera 720p, game
- * capture 1080p) yields subtly different pixels — every source contributes
- * its own crop per character and recognition takes the best-scoring one.
- * build-glyph-atlas.ts then fills in the rest of the charset from the
- * fonts, preserving these fixture-tagged glyphs.
+ * Bootstraps glyph atlases from labeled reference fixtures: slices templates
+ * straight out of the frames, since the same scoreboard captured through
+ * different pipelines (OBS virtual camera 720p, game capture 1080p) yields
+ * subtly different pixels — every source contributes its own crop per char and
+ * recognition takes the best-scoring one. build-glyph-atlas.ts then fills the
+ * rest of the charset from the fonts, preserving these fixture-tagged glyphs.
  *
  * Usage: pnpm scanner:bootstrap-atlas
- * Writes SCANNER_ASSETS_DIR/glyphs/scoreboard-{names,paint-digits,stat-digits}.{png,json}
+ * Writes SCANNER_ASSETS_DIR/glyphs/*.{png,json}
  */
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -61,9 +60,8 @@ interface Source {
 	stats: string[][];
 	teamScores: string[];
 	/**
-	 * Split hints are absolute x positions where merged segments must be cut
-	 * (keyed by row index) — e.g. the "Te" in Teddy renders as one segment,
-	 * with the exact boundary shifting a couple of pixels between sources.
+	 * absolute x positions where merged segments must be cut, keyed by row —
+	 * e.g. "Te" in Teddy renders as one segment, boundary shifting a few px per source
 	 */
 	nameSplitHints: Record<number, number[]>;
 	/** omit to skip header harvest for this source */
@@ -94,10 +92,9 @@ const REFERENCE = {
 		["05", "02", "04"],
 	],
 	/**
-	 * Team totals render with an outline on the colored team box, so they get
-	 * their own atlas rather than reusing paint digits. This fixture only
-	 * contributes '5' and '0' — later fixtures extend the set (harvest keeps
-	 * the first instance per char, so rerunning with more fixtures is additive).
+	 * Team totals render outlined on the colored team box, so they get their own
+	 * atlas. This fixture only contributes '5' and '0'; harvest keeps the first
+	 * instance per char, so rerunning with more fixtures is additive.
 	 */
 	teamScores: ["500", "0"],
 	header: {
@@ -154,11 +151,10 @@ const SOURCES: Source[] = [
 		nameSplitHints: {},
 	},
 	{
-		// This capture renders names slightly smaller than the reference: its
-		// 'T' (9x15) loses to the taller reference crops, and its baseline dots
-		// are pure homoglyphs the font templates can't split — '.' renders 4px,
-		// '・' 5px, so exact crops separate them via the ink-coverage penalty.
-		// Only the dot/T rows are labeled; the rest add nothing new.
+		// Renders names slightly smaller than the reference: its 'T' (9x15) loses
+		// to the taller reference crops, and its baseline dots are homoglyphs the
+		// font templates can't split ('.' 4px, '・' 5px; exact crops separate them
+		// via the ink-coverage penalty). Only the dot/T rows are labeled.
 		frame: "scoreboard/robot/frame.png",
 		names: ["R.O.B.O.T", "", "", "", "", "Rαι×ι..・", "", ""],
 		paints: ["", "", "", "", "", "", "", ""],
@@ -239,10 +235,9 @@ async function loadGreen(framePath: string): Promise<Mat> {
 }
 
 /**
- * Death splash-tag name band, prepared the way the detector reads it
- * (see src/core/detectors/death/index.ts): crop the tilted tag, rotate it
- * level, crop the name band, then map each pixel to its max-channel
- * distance from the median banner color, normalized to 0-255.
+ * Death splash-tag name band, prepared the way death/index.ts reads it: crop
+ * the tilted tag, rotate it level, crop the name band, then map each pixel to
+ * its max-channel distance from the median banner color, normalized to 0-255.
  */
 async function loadTagBand(framePath: string): Promise<Mat> {
 	const srcMat = toMat(await readImage(join(FIXTURES_DIR, framePath)));
@@ -321,11 +316,9 @@ async function loadTagBand(framePath: string): Promise<Mat> {
 }
 
 /**
- * Zero out ink components touching the band border, exactly as the
- * detector does before parsing (see clearBorderBlobs in death/index.ts):
- * banner art and title-line slivers enter at the band edges, and without
- * this they join the column runs (mismatching the label) or push a crop's
- * tight box past the band edge.
+ * Zeroes ink components touching the band border, as the detector does before
+ * parsing (clearBorderBlobs in death/index.ts): banner art and title-line
+ * slivers at the edges would join the column runs or push a tight box past it.
  */
 function clearBorderBlobs(band: Mat, threshold: number): void {
 	const bin = new cv.Mat();
@@ -384,9 +377,8 @@ function columnRuns(
 		}
 	}
 	if (start >= 0) runs.push({ x0: start, x1: roi.x + roi.w });
-	// Merge hints bridge runs that belong to one glyph (multi-stroke kana
-	// like パ segments as two strokes): a hint x inside the gap between two
-	// consecutive runs joins them into a single crop.
+	// Merge hints bridge runs belonging to one glyph (multi-stroke kana like パ
+	// segment as two strokes): a hint x inside the gap joins the two runs.
 	for (const hint of mergeHints) {
 		const i = runs.findIndex(
 			(r, idx) =>
@@ -460,10 +452,9 @@ function cropGlyph(
 }
 
 /**
- * Slice a labeled text ROI into per-char crops. A Map collector keeps the
+ * Slices a labeled text ROI into per-char crops. A Map collector keeps the
  * first instance per char (digits render identically everywhere); an array
- * collector keeps every instance — letters land on different subpixel
- * phases, so each occurrence is a distinct, equally-authoritative exemplar.
+ * collector keeps every instance (letters land on different subpixel phases).
  */
 function harvest(
 	roi: Roi,
@@ -621,8 +612,7 @@ for (const source of SOURCES) {
 }
 
 // Replay-browser fixtures: the code line renders in FOT-RowdyStd, which no
-// live-scoreboard atlas covers. Letters land on different subpixel phases,
-// so keep every occurrence (array collector), like names.
+// live-scoreboard atlas covers. Every occurrence kept (array), like names.
 const REPLAY_SOURCES: { frame: string; code: string }[] = [
 	{
 		frame:
@@ -639,10 +629,9 @@ const REPLAY_SOURCES: { frame: string; code: string }[] = [
 			"scoreboard-battle-log-replay/private-battle-crableg-capital/frame.png",
 		code: "R1V4-PAHW-GGM2-PD9S",
 	},
-	// Heavily compressed stream captures: font-rendered templates lose to
-	// fixture crops of lookalikes on these (E beat a real F by 0.1+), so the
-	// chars they cover (8 B F J N T U 5 among them) need crops at this
-	// fidelity. brinewater-1411/marlin stay out as generalization checks.
+	// Heavily compressed stream captures: font-rendered templates lose to fixture
+	// crops of lookalikes here (E beat a real F by 0.1+), so the chars they cover
+	// need crops at this fidelity. brinewater-1411/marlin stay out as generalization checks.
 	{
 		frame:
 			"scoreboard-battle-log-replay/x-battle-rainmaker-brinewater-1404/frame.png",
@@ -671,9 +660,8 @@ for (const source of REPLAY_SOURCES) {
 }
 
 // Death splash-tag names (BlitzBold + Rowdy kana at ~46px). The atlas is
-// nominal 42 with the detector upscaling to 46 at load (see the builder
-// comment in scripts/scanner/build-glyph-atlas.ts), so native-size crops shrink to
-// 42 here and come back to native after the load-time upscale.
+// nominal 42 with the detector upscaling to 46 at load (see build-glyph-atlas.ts),
+// so native-size crops shrink to 42 here.
 const TAG_BIN_THRESHOLD = 160; // TAG_NAME_BIN_THRESHOLD in death/index.ts
 const TAG_ATLAS_HEIGHT = 42;
 const DEATH_TAG_SOURCES: {
@@ -725,10 +713,9 @@ for (const source of DEATH_TAG_SOURCES) {
 	}
 }
 
-// JA death-message lines (condensed Kurokane/Rowdy blend at ~40px; the
-// atlas is native-size, matched unscaled by the detector's JA read path).
-// ROIs are fixture-specific tight boxes around each line so scene ink
-// outside the burst stays out of the runs.
+// JA death-message lines (condensed Kurokane/Rowdy blend at ~40px; native-size
+// atlas, matched unscaled by the JA read path). ROIs are fixture-specific tight
+// boxes around each line so scene ink outside the burst stays out of the runs.
 const DEATH_JA_BIN_THRESHOLD = 190; // SPLAT_TEXT_BIN_THRESHOLD in death/rois.ts
 const DEATH_JA_SOURCES: {
 	frame: string;
diff --git a/scripts/scanner/build-glyph-atlas.ts b/scripts/scanner/build-glyph-atlas.ts
index af9c7882e..1db909ef5 100644
--- a/scripts/scanner/build-glyph-atlas.ts
+++ b/scripts/scanner/build-glyph-atlas.ts
@@ -1,19 +1,15 @@
 /** biome-ignore-all lint/suspicious/noConsole: CLI script output */
 /**
- * Build glyph atlases by rendering the Splatoon fonts at the exact
- * scoreboard render sizes, calibrated against the reference fixture:
+ * Builds glyph atlases by rendering the Splatoon fonts at the exact scoreboard
+ * render sizes, calibrated against the reference fixture:
  *
  *   paint digits  BlitzMain 34px  (tight '0' height ~29px at 1080p)
  *   stat digits   BlitzMain 20px  (~17px)
- *   team digits   BlitzBold 36px  (~28px — team totals use the bold face,
- *                                  which is why they can't reuse paint glyphs)
- *   names         BlitzMain 20px  (cap height ~17px), full charset:
- *                 ASCII + Latin-1 + kana + common symbols (~330 glyphs)
+ *   team digits   BlitzBold 36px  (~28px — bold face, so paint glyphs can't be reused)
+ *   names         BlitzMain 20px  (cap height ~17px), ASCII + Latin-1 + kana + symbols
  *
  * The fonts ship with the game and are not committed — drop them into
- * assets/fonts/ (see README). Fixture-crop bootstrapping
- * (scripts/scanner/bootstrap-atlas-from-fixture.ts) remains as a cross-check and as
- * the fallback when the fonts are unavailable.
+ * assets/fonts/ (see README); bootstrap-atlas-from-fixture.ts is the fallback.
  *
  * Usage: pnpm scanner:build-glyph-atlas
  * Writes SCANNER_ASSETS_DIR/glyphs/scoreboard-*.{png,json}
@@ -39,11 +35,9 @@ import { readImage, writePng } from "../../app/features/scanner/node/image-io";
 import { readFontCoverage } from "./otf-cmap";
 
 /**
- * Atlases are hybrids: glyphs harvested from labeled fixtures
- * (scripts/scanner/bootstrap-atlas-from-fixture.ts, tagged source:"fixture") are exact
- * in-game pixels and are preserved across rebuilds; font-rendered glyphs
- * fill in the rest of the charset. Recognition takes the best-scoring glyph,
- * so fixture crops dominate wherever they exist.
+ * Atlases are hybrids: fixture-harvested glyphs (bootstrap-atlas-from-fixture.ts,
+ * source:"fixture") are exact in-game pixels preserved across rebuilds;
+ * font-rendered glyphs fill the rest of the charset and lose ties to them.
  */
 
 const FONTS_DIR = new URL("../../assets/fonts", import.meta.url).pathname;
@@ -59,11 +53,9 @@ const FONT_FILES = {
 } as const;
 
 /**
- * Which codepoints each font actually maps: canvas silently substitutes a
- * system font for the rest (the Blitz cuts have no kanji/hangul/hanzi), so
- * charsets are filtered through this before rendering — the CJK languages'
- * ideographs drop out of the localized charsets instead of baking
- * wrong-font glyphs into the atlases.
+ * Which codepoints each font maps: canvas silently substitutes a system font
+ * for the rest (the Blitz cuts have no kanji/hangul/hanzi), so charsets are
+ * filtered through this so no wrong-font glyphs get baked into the atlases.
  */
 const fontCoverage: Record<string, (codepoint: number) => boolean> = {};
 
@@ -100,35 +92,31 @@ function nameCharset(): string[] {
 }
 
 /**
- * Greek letters players stylize scoreboard names with, added per attested
- * fixture need only ("Rιppιng_H"): most of the block are homoglyphs of latin
- * or kana at capture fidelity (η~n, ε~c, Γ~か strokes...) and displace
- * correct matches on ranking noise, so it is not included wholesale — and
- * even a few extra narrow glyphs shift an atlas's median width enough to
- * change wide-segment splitting, so it stays out of the death-tag charset
- * until a death fixture attests it.
+ * Greek letters players stylize names with, added per attested fixture only
+ * ("Rιppιng_H"): most of the block are homoglyphs of latin/kana at capture
+ * fidelity (η~n, ε~c) and displace correct matches on ranking noise. Even a
+ * few narrow glyphs shift an atlas's median width enough to change
+ * wide-segment splitting, so it stays out of the death-tag charset until attested.
  */
 const NAME_GREEK = "ια"; // ι: "Rιppιng_H", α: "◇Dαrz™" (special-symbols fixture)
 
 /**
  * The rest of the in-game name editor's symbol pickers (sendou.ink's
- * IN_GAME_NAME_CHARACTER_CATEGORIES: "symbols" + "cjk-symbols"), minus what
- * nameCharset() already carries via ASCII/Latin-1/kana and minus chars the
- * Blitz cmap doesn't map (ˊˋ𝑓⁀⚪⚫◻◼⍑ — canvas would render a system-font
- * substitute; nameSymbols() re-checks at build time). "•" stays out too:
- * BlitzMain's own bullet is a 4px dot, the on-screen full-size circle comes
- * from "●" via RENDER_ALIASES. The tilde is the fullwidth "～" (U+FF5E) only
- * — the wave dash "〜" (U+301C) is a pixel-identical homoglyph that would
- * duel it on ranking noise, and FF5E is the form the fixture labels attest.
- * Like NAME_GREEK, scoreboard-names only (not death-tag) until attested.
+ * IN_GAME_NAME_CHARACTER_CATEGORIES "symbols" + "cjk-symbols"), minus what
+ * nameCharset() already carries and chars the Blitz cmap doesn't map
+ * (ˊˋ𝑓⁀⚪⚫◻◼⍑; nameSymbols() re-checks at build time). "•" stays out: BlitzMain's
+ * bullet is a 4px dot, the on-screen circle comes from "●" via RENDER_ALIASES.
+ * Only the fullwidth "～" (U+FF5E), the form fixture labels attest — the wave
+ * dash "〜" (U+301C) is a pixel-identical homoglyph that would duel it.
+ * Scoreboard-names only (not death-tag) until attested, like NAME_GREEK.
  */
 const NAME_SYMBOLS =
 	"′‘’‚‛…″“”„←→↑↓⇒⇔˜€∞√∀⊂⊃∴∵∂№♭♀♂◎◇◆△▲▽▼†※™" + "『』【】〈〉《》〔〕々〆〇〃～";
 
 /**
- * Render the key char's glyph but emit it as the value char: in-game names
- * show "•" as the full-size filled circle (BlitzMain's own "•" is a 4px dot
- * that never appears on screen), and fixture labels write it as "•".
+ * Render the key char but emit it as the value: in-game names show "•" as a
+ * full-size filled circle (BlitzMain's own "•" is a 4px dot never seen on
+ * screen) and fixture labels write it as "•".
  */
 const RENDER_ALIASES: Record<string, string> = { "●": "•" };
 
@@ -163,9 +151,8 @@ async function readFixtureGlyphs(name: string): Promise<GlyphBitmap[]> {
 }
 
 /**
- * Render one glyph and tight-crop it via the alpha channel. xScale < 1
- * condenses the glyph horizontally (the JA death message renders its font
- * squeezed to ~3/4 width in-game).
+ * Renders one glyph and tight-crops it via the alpha channel. xScale < 1
+ * condenses horizontally (the JA death message renders squeezed to ~3/4 width).
  */
 function renderGlyph(
 	family: string,
@@ -331,15 +318,12 @@ await build("scoreboard-names", 17, [
 	},
 ]);
 /**
- * Localized closed-set charsets (all 14 game languages; the canonical
- * English strings are included by construction), restricted to the Latin
- * scripts (< U+0250) the fixtures attest: like the Greek block in the name
- * charset, wholesale Cyrillic/kana/ideograph glyphs displace Latin matches
- * on ranking noise (adding them regressed the English fixtures), so the
- * non-Latin languages' entries stay in the closed sets — ready to snap —
- * but their glyphs wait for fixtures to tune against. Chars the font
- * doesn't map are dropped too: canvas would silently render a system-font
- * substitute into the atlas.
+ * Localized closed-set charsets (all 14 game languages), restricted to the
+ * Latin scripts (< U+0250) the fixtures attest: wholesale Cyrillic/kana/
+ * ideograph glyphs displace Latin matches on ranking noise (adding them
+ * regressed the English fixtures), so non-Latin entries stay in the closed
+ * sets but their glyphs wait for fixtures. Chars the font doesn't map are
+ * dropped too (canvas would render a system-font substitute).
  */
 function localizedChars(texts: readonly string[], family: string): string[] {
 	const covers = fontCoverage[family]!;
@@ -391,12 +375,10 @@ await build("scoreboard-replay-result", 30, [
 		chars: localizedChars(resultTexts, "Rowdy"),
 	},
 ]);
-// map-start intro splash: the big mode title on the center splat is
-// BlitzBold (~76px tight caps at 1080p; a px sweep against the fixture reads
-// best at 99-101), the stage name bottom-right is BlitzMain (~40px tight;
-// 46-48px render). The constant "MODE" label ("Kampfart", ...) is BlitzMain
-// too and is read with the stage atlas rescaled to its ~48px height, so its
-// chars ride along.
+// map-start intro splash: the mode title on the center splat is BlitzBold
+// (~76px tight caps at 1080p; a px sweep reads best at 99-101), the stage name
+// bottom-right is BlitzMain (~40px tight; 46-48px render). The constant "MODE"
+// label is BlitzMain too, read with the stage atlas rescaled to ~48px.
 await build("map-start-mode", 76, [
 	{
 		family: "BlitzBold",
@@ -411,11 +393,9 @@ await build("map-start-stage", 40, [
 		chars: localizedChars([...stageTexts, ...ALL_MODE_LABELS], "BlitzMain"),
 	},
 ]);
-// death screen: the localized "Splatted by <weapon>!" burst message (tight
-// caps ~28px; the face reads between the two Blitz cuts at capture
-// fidelity, so carry both and let recognition take the max) and the
-// splash-tag name, which is BlitzBold for latin but the angular Rowdy face
-// for kana
+// death screen: the localized "Splatted by <weapon>!" burst (tight caps ~28px;
+// the face reads between the two Blitz cuts at capture fidelity, so carry both)
+// and the splash-tag name: BlitzBold for latin, the angular Rowdy face for kana
 const deathWeaponTexts = [
 	...ALL_WEAPON_ENTRIES.map((e) => e.name),
 	...Object.values(LOCALIZED_WEAPON_NAMES).flatMap((names) =>
@@ -439,15 +419,12 @@ await build("death-weapon", 34, [
 		chars: localizedChars(deathWeaponTexts, "BlitzBold"),
 	},
 ]);
-// JA death message, a separate atlas read only by the JA line ROIs: mixing
-// kana into the Latin set would shift its median width (breaking wide-
-// segment splitting) and displace Latin matches on ranking noise. The
-// in-game JP face renders horizontally condensed and sits between the two
-// FOT cuts at capture fidelity — ス/ク read as Kurokane, で as Rowdy — so
-// carry both, at the (px, xScale) pairs that peaked in an NCC sweep against
-// the classic-squiffer-jp fixture. Latin/digit chars inside JP weapon names
-// (LACT-450, .52ガロン) ride along in both faces. Attested-fixture rule as
-// everywhere: KO/ZH names stay in the closed sets without an atlas.
+// JA death message, a separate atlas read only by the JA line ROIs: mixing kana
+// into the Latin set would shift its median width (breaking wide-segment
+// splitting) and displace Latin matches. The in-game JP face renders condensed
+// and sits between the two FOT cuts (ス/ク read as Kurokane, で as Rowdy), so
+// carry both at the (px, xScale) pairs that peaked in an NCC sweep against the
+// classic-squiffer-jp fixture. KO/ZH names stay in the closed sets without an atlas.
 const deathJaTexts = [
 	...(LOCALIZED_WEAPON_NAMES.JPja ?? []).map((n) => n.text),
 	...DEATH_MESSAGE_TEMPLATES.filter((t) =>
diff --git a/scripts/scanner/build-localized-entries.ts b/scripts/scanner/build-localized-entries.ts
index c3b26a72e..d0f6ab5fb 100644
--- a/scripts/scanner/build-localized-entries.ts
+++ b/scripts/scanner/build-localized-entries.ts
@@ -1,25 +1,19 @@
 /** biome-ignore-all lint/suspicious/noConsole: CLI script output */
 /**
- * Generate the localized closed sets from the splat3 repo's language dumps
- * (https://github.com/Leanny/splat3, data/language/<Lang>_full.json), so
- * ingestion works no matter which language the player runs the game in.
- * Detectors OCR whatever is on screen, snap it against every language's
- * entries, and always emit the sendou.ink id (canonical English text
- * exists only inside the snap tables).
+ * Generates the localized closed sets from the splat3 repo's language dumps
+ * (https://github.com/Leanny/splat3, data/language/<Lang>_full.json) so
+ * ingestion works in any game language: detectors OCR what is on screen, snap
+ * it against every language's entries, and emit the sendou.ink id.
  *
  * Sources per language:
- *   CommonMsg/VS/VSRuleName          modes (+ the _2L two-line intro-splash
- *                                    wrap variants, e.g. "Muschel-\nchaos")
+ *   CommonMsg/VS/VSRuleName          modes (+ _2L two-line intro-splash wraps, "Muschel-\nchaos")
  *   CommonMsg/VS/VSStageName         stages (keyed via the USen values)
  *   CommonMsg/MatchMode              lobby tags (XMatch / Private)
  *   LayoutMsg/Lobby_MenuMode_00      the intro splash's "MODE" label
  *   LayoutMsg/Mng_Result_00          replay-browser VICTORY / DEFEAT tags
- *   LayoutMsg/VS_Beaten_00 (999)     the death-burst message; the weapon
- *                                    placeholder sits on line 1 or 2
- *                                    depending on language, so this becomes
- *                                    a per-language template
- *   CommonMsg/Weapon/WeaponName_*    weapon names, mapped to the canonical
- *                                    entries via their USen value
+ *   LayoutMsg/VS_Beaten_00 (999)     death-burst message; the weapon placeholder sits on
+ *                                    line 1 or 2 by language, so it becomes a per-language template
+ *   CommonMsg/Weapon/WeaponName_*    weapon names, mapped to canonical entries via USen
  *
  * Usage: pnpm scanner:build-localized-entries [path-to-splat3]
  * Writes app/features/scanner/core/localized-entries.ts
@@ -119,8 +113,6 @@ if (!languages.includes(CANONICAL_LANG)) {
 const dumps = new Map<string, LangDump>(languages.map((l) => [l, loadLang(l)]));
 const usen = dumps.get(CANONICAL_LANG)!;
 
-// ---- validate the canonical sets against USen ------------------------------
-
 for (const [key, mode] of Object.entries(RULE_KEYS)) {
 	const value = clean(usen["CommonMsg/VS/VSRuleName"]![key]!);
 	const expected = misc[`MODE_LONG_${mode}`]!;
@@ -152,8 +144,6 @@ for (const [name, stageId] of stageIdByEnglishName) {
 	}
 }
 
-// ---- per-language closed sets ----------------------------------------------
-
 interface LocalizedLobby {
 	text: string;
 	lobby: ScannerLobby;
@@ -233,8 +223,6 @@ for (const category of ["lobbies", "modes", "modeWraps", "stages"] as const) {
 	}
 }
 
-// ---- death message templates -----------------------------------------------
-
 const PLACEHOLDER = /\[group=[^\]]*\]/;
 /** stands in for the weapon placeholder while splitting the message */
 const SENTINEL = "\u0000";
@@ -282,8 +270,6 @@ for (const lang of languages) {
 		});
 }
 
-// ---- localized weapon names --------------------------------------------------
-
 const WEAPON_MSGS = [
 	"CommonMsg/Weapon/WeaponName_Main",
 	"CommonMsg/Weapon/WeaponName_Sub",
@@ -328,8 +314,6 @@ for (const lang of languages) {
 	if (entries.length > 0) localizedWeaponNames[lang] = entries;
 }
 
-// ---- emit --------------------------------------------------------------------
-
 const banner = (extra: string) =>
 	`/**
  * GENERATED by scripts/scanner/build-localized-entries.ts from the splat3 repo's
diff --git a/scripts/scanner/build-planner-signatures.ts b/scripts/scanner/build-planner-signatures.ts
index 217274bf3..f239bb30b 100644
--- a/scripts/scanner/build-planner-signatures.ts
+++ b/scripts/scanner/build-planner-signatures.ts
@@ -1,16 +1,13 @@
 /** biome-ignore-all lint/suspicious/noConsole: CLI script output */
 /**
- * Build the planner signature atlas from the assets repo's planner renders.
- *
- * The sendou-ink/assets checkout's assets/planner-maps/ holds the full
- * planner PNGs (~340MB), named "<stageId>-<MODE>-<TYPE>.png" (MODE in
- * CB/RM/SZ/TC/TW; TYPE in OVER/MINI/ITEMS). This tool reduces each
- * PLANNER_TYPE render to the ink-invariant structural signature
- * (app/features/scanner/core/detectors/minimap/stage.ts) and packs all of them,
- * quantized to uint8, into a single grayscale atlas PNG plus a manifest
- * (keys "<stageId>-<MODE>") — a few hundred KB the minimap detector loads
- * to identify the stage. Output goes to the assets checkout
- * (SCANNER_ASSETS_DIR/planner); shipping a regen means pushing the assets repo.
+ * Builds the planner signature atlas from the assets repo's planner renders:
+ * assets/planner-maps/ in the sendou-ink/assets checkout holds the full PNGs
+ * (~340MB) named "<stageId>-<MODE>-<TYPE>.png" (MODE in CB/RM/SZ/TC/TW; TYPE
+ * in OVER/MINI/ITEMS). Each PLANNER_TYPE render is reduced to the
+ * ink-invariant structural signature (core/detectors/minimap/stage.ts) and
+ * packed, quantized to uint8, into one grayscale atlas PNG plus a manifest
+ * (keys "<stageId>-<MODE>"). Output goes to SCANNER_ASSETS_DIR/planner;
+ * shipping a regen means pushing the assets repo.
  *
  *   pnpm scanner:build-planner-signatures
  */
diff --git a/scripts/scanner/otf-cmap.ts b/scripts/scanner/otf-cmap.ts
index 606c45382..ad9522ff2 100644
--- a/scripts/scanner/otf-cmap.ts
+++ b/scripts/scanner/otf-cmap.ts
@@ -1,13 +1,10 @@
 /** biome-ignore-all lint/suspicious/noConsole: CLI script output */
 /**
- * Minimal OpenType cmap reader: which codepoints does a font actually map?
- *
+ * Minimal OpenType cmap reader: which codepoints a font actually maps.
  * @napi-rs/canvas silently falls back to a system font for characters the
- * requested family lacks (the Blitz cuts carry Latin/Greek/Cyrillic/kana
- * but no kanji, hangul or hanzi), which would bake wrong-font glyphs into
- * the atlases. The builder filters every charset through this before
- * rendering. Supports the two subtable formats the game fonts use:
- * format 4 (BMP segments) and format 12 (grouped full-range).
+ * family lacks (the Blitz cuts have no kanji, hangul or hanzi), which would
+ * bake wrong-font glyphs into the atlases. Supports format 4 (BMP segments)
+ * and format 12 (grouped full-range), the two the game fonts use.
  */
 import { readFileSync } from "node:fs";
 
diff --git a/scripts/scanner/replay-frames.ts b/scripts/scanner/replay-frames.ts
index db0338cc4..d4495f32d 100644
--- a/scripts/scanner/replay-frames.ts
+++ b/scripts/scanner/replay-frames.ts
@@ -1,9 +1,8 @@
 /** biome-ignore-all lint/suspicious/noConsole: CLI script output */
 /**
- * CLI harness: replay a directory of extracted VoD frames through the full
- * detector registry driven by a DetectorScheduler, mirroring the analyzer
- * worker's chunk scan — to reproduce scheduling-dependent misses offline.
- * This is the tool for "the browser scan missed an event that a fixture
+ * CLI harness: replays a directory of extracted VoD frames through the full
+ * detector registry driven by a DetectorScheduler, mirroring the worker's
+ * chunk scan — the tool for "the browser scan missed an event that a fixture
  * parses fine": extract the surrounding footage with
  *   ffmpeg -ss <startT> -i vod.mkv -t 30 -vf fps=6 frames/f%04d.png
  * then replay it and watch which checks the scheduler ran and what they saw.
diff --git a/scripts/scanner/report.ts b/scripts/scanner/report.ts
index 066c5fe49..f77d55e90 100644
--- a/scripts/scanner/report.ts
+++ b/scripts/scanner/report.ts
@@ -1,11 +1,8 @@
 /** biome-ignore-all lint/suspicious/noConsole: CLI script output */
 /**
- * Accuracy report across all fixtures — separate from pass/fail testing.
- * Runs each detector over its own fixture directory and prints aggregate
- * per-field accuracy plus character error rate (CER) for names, the metric
- * that drives glyph atlas expansion.
- *
- * Usage: pnpm scanner:report
+ * Accuracy report across all fixtures, separate from pass/fail testing:
+ * aggregate per-field accuracy plus character error rate (CER) for names,
+ * the metric that drives glyph atlas expansion. Usage: pnpm scanner:report
  */
 import { loadOpenCV } from "../../app/features/scanner/core/cv";
 import {
diff --git a/scripts/scanner/scan-vod.ts b/scripts/scanner/scan-vod.ts
index 905010607..b387c645c 100644
--- a/scripts/scanner/scan-vod.ts
+++ b/scripts/scanner/scan-vod.ts
@@ -1,18 +1,15 @@
 /** biome-ignore-all lint/suspicious/noConsole: CLI script output */
 /**
- * CLI equivalent of the VoD tab: scan a video file with the full detector
- * registry and write the same events CSV the tab's Export menu downloads.
- * ffmpeg decodes the video to raw RGBA frames piped through the
- * DetectorScheduler + detectors, and every parse event goes through a
- * TimelineBuilder with the tab's default merge/confidence options — so the
- * CSV matches a browser scan of the same footage (minus the calm-stretch
- * keyframe skimming, which only affects speed, not results).
+ * CLI equivalent of the VoD tab: scans a video with the full detector registry
+ * and writes the same events CSV the tab's Export menu downloads. ffmpeg
+ * decodes to raw RGBA frames piped through the DetectorScheduler + detectors
+ * and a TimelineBuilder with the tab's default options, so the CSV matches a
+ * browser scan (minus keyframe skimming, which only affects speed).
  *
  * Requires ffmpeg (and ffprobe for the progress percentage) on PATH.
  *
  * Usage: pnpm scanner:scan-vod <video> [--fps 8] [--start T] [--duration S] [--out file.csv] [--telemetry]
- * --telemetry prints the VoD tab's ?telemetry=true scan counters after the
- * run (per-detector gate/parse time, scheduling savings).
+ * --telemetry prints the VoD tab's ?telemetry=true scan counters after the run.
  */
 import { spawn } from "node:child_process";
 import { writeFileSync } from "node:fs";
diff --git a/scripts/scanner/status-audit.ts b/scripts/scanner/status-audit.ts
index 174767036..0cdd7af2f 100644
--- a/scripts/scanner/status-audit.ts
+++ b/scripts/scanner/status-audit.ts
@@ -1,20 +1,16 @@
 /** biome-ignore-all lint/suspicious/noConsole: CLI script output */
 /**
- * Audit death/special detection against scoreboard truth, from an events CSV
- * downloaded from the scanner UI (Live/VoD tab → Download CSV). The CSV rows
- * are parsed back into DetectedEvents, run through the real match builder,
- * and rendered into the same status spans the timeline would draw — then
- * each player's span counts are diffed against the scoreboard's D/S numbers,
- * which are near-always correct. A special span ending in a death (or held
- * at the final whistle) is a legit non-use and does not count toward S.
+ * Audits death/special detection against scoreboard truth, from an events CSV
+ * downloaded from the scanner UI. Rows are parsed back into DetectedEvents,
+ * run through the real match builder and rendered into the timeline's status
+ * spans; each player's span counts are diffed against the scoreboard's D/S
+ * numbers. A special span ending in a death (or held at the final whistle) is
+ * a legit non-use and does not count toward S.
  *
  * The CSV is lossy (no ink colors, only top-1 strip-weapon candidates), so
- * cast-footage side orientation and slot→row assignment can degrade to
- * their fallbacks; the output flags when a mismatch looks like a
- * slot-mapping artifact rather than a detection error.
- *
- * Output is structured for triage: every discrepancy lists the exact
- * read timestamps most likely to yield a new failing fixture.
+ * cast-footage side orientation and slot→row assignment can degrade to their
+ * fallbacks; the output flags mismatches that look like slot-mapping artifacts.
+ * Every discrepancy lists the read timestamps most likely to yield a fixture.
  *
  * Usage: pnpm scanner:status-audit <events.csv> [--all]
  */
@@ -182,9 +178,6 @@ for (const [index, builtMatch] of built.entries()) {
 printCandidates();
 printGuidance();
 
-// ---------------------------------------------------------------------------
-// CSV → DetectedEvent reconstruction
-
 function parseCsv(text: string): string[][] {
 	const result: string[][] = [];
 	let row: string[] = [];
@@ -451,9 +444,6 @@ function parseScoreboardRow(row: string[]): ScoreboardData & {
 	};
 }
 
-// ---------------------------------------------------------------------------
-// Analysis
-
 interface FixtureCandidate {
 	score: number;
 	t: number;
@@ -471,10 +461,9 @@ interface StatusSpan extends TimeWindow {
 	/** sample timestamps that read the flag true inside the span */
 	confirmingReads: number[];
 	/**
-	 * widest the true state could really have held: from the last false read
-	 * before the span to the false read that closed it (the builder's
-	 * flank-to-flank measure); the rendered span bounds where a flank is
-	 * unobserved (series edge or gap-split)
+	 * widest the true state could have held: from the last false read before the
+	 * span to the false read that closed it (the builder's flank-to-flank measure);
+	 * the rendered span bounds where a flank is unobserved
 	 */
 	maxPossibleSeconds: number;
 }
@@ -587,9 +576,6 @@ function readsInWindow(
 		.map((event) => Math.round(event.t * 100) / 100);
 }
 
-// ---------------------------------------------------------------------------
-// Output
-
 function ts(t: number): string {
 	return `t=${Math.round(t * 10) / 10} (${formatTime(t)})`;
 }
diff --git a/scripts/scanner/vite-node.config.ts b/scripts/scanner/vite-node.config.ts
index c795a609a..4b15bcb5b 100644
--- a/scripts/scanner/vite-node.config.ts
+++ b/scripts/scanner/vite-node.config.ts
@@ -1,9 +1,8 @@
 /**
- * Config for running the scanner scripts with vite-node. Deliberately minimal:
- * the root vite.config.ts pre-bundles @techstark/opencv-js for the browser
- * worker, and vite-node would resolve that browser prebundle (which
- * crashes on __dirname in Node). Without the include, vite-node
- * externalizes the dep to a plain require of the (patched) CJS bundle.
+ * vite-node config for the scanner scripts. The root vite.config.ts
+ * pre-bundles @techstark/opencv-js for the browser worker, and vite-node would
+ * resolve that prebundle (which crashes on __dirname in Node); without the
+ * include it externalizes the dep to a plain require of the patched CJS bundle.
  */
 import { defineConfig } from "vite";
 
diff --git a/scripts/setup.ts b/scripts/setup.ts
index d4896c12d..63e044526 100644
--- a/scripts/setup.ts
+++ b/scripts/setup.ts
@@ -5,12 +5,10 @@ import { seedImages } from "./seed-images";
 async function main() {
 	const dbEmpty = !(await db.selectFrom("User").selectAll().executeTakeFirst());
 
-	// Run migration and seed if db.sqlite3 doesn't exist
 	if (dbEmpty) {
 		logger.info("🌱 Seeding database...");
 		try {
-			// Dynamically imported so we skip transforming the large
-			// seed import graph if the database is already seeded
+			// dynamic so the large seed import graph is not transformed when already seeded
 			const { seed } = await import("~/db/seed");
 			await seed();
 			logger.info("Database seeded successfully");
@@ -23,7 +21,6 @@ async function main() {
 		}
 	}
 
-	// Seed images to Minio
 	logger.info("🖼️  Seeding images to Minio...");
 	try {
 		await seedImages();
diff --git a/scripts/splat3-types.ts b/scripts/splat3-types.ts
index 877491c8b..a4521b9c5 100644
--- a/scripts/splat3-types.ts
+++ b/scripts/splat3-types.ts
@@ -1,12 +1,7 @@
 /**
- * Hand-maintained types for the [Leanny/splat3](https://github.com/Leanny/splat3) game data dump.
- *
- * The dump itself is not checked in (see `.gitignore`), so these types are declared here rather
- * than inferred from the JSON files. That keeps `pnpm run typecheck:scripts` passing whether or
- * not the dump is currently sitting in `scripts/dicts/splat3`.
- *
- * Only the fields the scripts actually read are declared for the deeply nested parameter dumps.
- * When a monthly update changes the dump's shape, update these types alongside the scripts.
+ * Hand-maintained types for the [Leanny/splat3](https://github.com/Leanny/splat3) game data dump,
+ * declared rather than inferred so `pnpm run typecheck:scripts` passes without the gitignored dump in
+ * `scripts/dicts/splat3`. Only the fields the scripts read are declared; update alongside the scripts.
  */
 
 /** `data/language/<Lang>.json` — message category -> message key -> localized (URI encoded) text. */
diff --git a/scripts/swap-users.ts b/scripts/swap-users.ts
index 8b178cd10..e5d62b780 100644
--- a/scripts/swap-users.ts
+++ b/scripts/swap-users.ts
@@ -10,7 +10,6 @@ invariant(discordId !== discordId2, "discord ids must be different");
 
 const tempDiscordId = "temp-discord-id";
 
-// swap user discordIds
 await db.transaction().execute(async (trx) => {
 	const swap = (from: string, to: string) =>
 		trx
diff --git a/scripts/sync-homemade-badges.ts b/scripts/sync-homemade-badges.ts
index ef46be01b..c2a9c8baf 100644
--- a/scripts/sync-homemade-badges.ts
+++ b/scripts/sync-homemade-badges.ts
@@ -16,7 +16,6 @@ async function main() {
 	let deleted = 0;
 	let updated = 0;
 
-	// update existing
 	for (const existingBadge of await homemadeBadgesInDb()) {
 		const badge = homemadeBadges[existingBadge.code];
 
@@ -51,7 +50,6 @@ async function main() {
 
 	let added = 0;
 
-	// add new
 	for (const [fileName, badge] of Object.entries(homemadeBadges)) {
 		const existing = homemadeAfterUpdates.find(
 			(existingBadge) => fileName === existingBadge.code,
diff --git a/vite.config.ts b/vite.config.ts
index a1abedd41..210d71e17 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -16,11 +16,9 @@ export default defineConfig((config) => {
 		},
 		plugins: [
 			{
-				// Vite dev serves everything with no-cache, so the browser revalidates
-				// the woff2 on every font re-resolution — any <head> mutation (e.g. an
-				// intent-prefetch link mounting) then flashes fallback fonts across the
-				// whole page while the 304 round-trips. Fonts effectively never change,
-				// so dev caches them hard, matching how the production build serves them.
+				// Vite dev serves everything with no-cache, so any <head> mutation (e.g. a prefetch
+				// link mounting) revalidates the woff2 and flashes fallback fonts while the 304
+				// round-trips. Fonts never change, so dev caches them hard like the production build.
 				name: "cache-fonts-in-dev",
 				apply: "serve",
 				configureServer(server) {
@@ -36,14 +34,10 @@ export default defineConfig((config) => {
 				},
 			},
 			{
-				// Wraps CSS modules in a @layer so utility classes always win and, more
-				// generally, so that the more specific of two modules styling the same
-				// element wins no matter what order Vite happens to emit the chunks in:
-				// `elements` (headless library wrappers) < `components` (shared
-				// components) < `features` (feature code and composed component groups).
-				// The layer order declaration is prepended to each module because in Vite
-				// dev mode, module <style> tags are injected before global stylesheets —
-				// without it the implicit first layer would get lowest priority.
+				// Wraps CSS modules in a @layer so utilities always win and the higher of two modules
+				// styling the same element wins regardless of chunk order: `elements` < `components`
+				// < `features`. The layer order is prepended to each module because in Vite dev module
+				// <style> tags are injected before global stylesheets.
 				name: "css-modules-layer",
 				enforce: "pre",
 				transform(code, id) {
@@ -62,8 +56,7 @@ export default defineConfig((config) => {
 				},
 			},
 			reactRouter(),
-			// React Compiler is skipped in dev where its per-module transform cost
-			// outweighs its value.
+			// React Compiler is skipped in dev, its transform cost outweighs its value there
 			...(isBuild
 				? [
 						babel({
@@ -99,9 +92,7 @@ export default defineConfig((config) => {
 			tsconfigPaths: true,
 		},
 		optimizeDeps: {
-			// Dependencies which are only imported by specific route modules.
-			// Pre-bundling them at startup avoids mid-session re-optimization
-			// and full page reloads on first navigations.
+			// route-specific deps pre-bundled at startup to avoid mid-session re-optimization and full page reloads
 			include: [
 				"@date-fns/tz",
 				"@techstark/opencv-js",
diff --git a/vitest.scanner.config.ts b/vitest.scanner.config.ts
index bbc550a8a..9b69ccfdc 100644
--- a/vitest.scanner.config.ts
+++ b/vitest.scanner.config.ts
@@ -1,12 +1,9 @@
 import { configDefaults, defineConfig } from "vitest/config";
 
-// Scanner golden-file suite: Node-side (OpenCV.js WASM + @napi-rs/canvas image
-// IO), sweeping every fixture under app/features/scanner/tests/fixtures. Kept
-// out of the unit project so `--project unit` stays fast, and out of CI
-// (`test:unit:browser`) because the game icons come from a sibling
-// sendou-ink/assets checkout the runner does not have — run it locally with
-// `pnpm test:scanner`. The fixture-free logic tests live in
-// app/features/scanner/tests/logic and run in the unit project instead.
+// Scanner golden-file suite (OpenCV.js WASM + @napi-rs/canvas) over app/features/scanner/tests/fixtures.
+// Out of the unit project to keep it fast and out of CI because the game icons come from a
+// sibling sendou-ink/assets checkout; run locally with `pnpm test:scanner`. The fixture-free
+// logic tests in app/features/scanner/tests/logic run in the unit project.
 export default defineConfig({
 	test: {
 		name: "scanner",
diff --git a/vitest.unit.config.ts b/vitest.unit.config.ts
index 75a5e0ba7..71adee35d 100644
--- a/vitest.unit.config.ts
+++ b/vitest.unit.config.ts
@@ -8,14 +8,11 @@ export default defineConfig({
 			...configDefaults.exclude,
 			"e2e/**",
 			"**/*.browser.test.{ts,tsx}",
-			// the scanner golden-file suites have their own heavy project
-			// (vitest.scanner.config.ts); tests/logic/ stays here because it is
-			// pure logic over synthetic events and needs no image fixtures
+			// golden-file suites live in vitest.scanner.config.ts; tests/logic/ needs no fixtures so stays here
 			"app/features/scanner/tests/*.test.{ts,tsx}",
 		],
 		setupFiles: ["./app/test-setup.ts"],
-		// the scanner-ingest scenario suite exercises the real ingest action,
-		// whose gate reads Config.scannerEnabled from this variable
+		// the scanner-ingest scenario suite's real ingest action is gated on Config.scannerEnabled
 		env: {
 			VITE_SCANNER_ENABLED: "true",
 		},