docs: cut the comments that were not earning their place

I wrote 731 comment lines on this branch against 4,530 lines of code — 14%,
where the rest of the repo runs at 1.8%. CLAUDE.md asks for code that reads
like its surroundings, and this did not.

Removed by genre rather than by taste:

- restating the code, e.g. "JS getUTCDay() numbering: Sunday = 0" above the
  map that literally shows it, and a docblock on startOfWeek explaining that
  it returns the start of the week;
- narrating history — "this used to rebuild the whole map", "left the bar
  recording forever" — which the commit message and git blame already carry;
- saying the same thing in several places: the "cannot record is not a
  denied microphone" reason appeared three times in one file, and the
  "aborting stops a per-minute metered call" reason across three files. Each
  now lives once, where the behaviour it explains lives;
- defending decisions nobody would question, like why toLatinDigits is its
  own module;
- over-explaining defensive branches, three separate comments to distinguish
  null from missing-kind from unrecognised-kind.

What stays is what the code cannot say: the patient-right convention in
toFdi, whose failure mode is a valid code for the wrong tooth; the
"this"-vs-"next" week anchoring; StrictMode re-arming mountedRef; Safari
accepting no mimeType hint; and the invariants whose violation already cost
a bug — the body parser's middleware ordering and the dispatch panel's
auto-fill rules.

Comments only. The diff contains no non-comment line.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

backend/src/common/body-parsers.ts

@@ -17,23 +17,18 @@ export const VOICE_BODY_LIMIT = '10mb';
  * of audio, so that one route needs a larger limit while every other endpoint keeps the
  * default — a large body should not become acceptable everywhere.
  *
- * Deliberately a single middleware that *chooses* a parser, rather than a path-mounted
- * parser stacked in front of a default one. That arrangement relied on Express's
- * mount-path stripping plus body-parser skipping an already-parsed request, and it
- * silently stopped applying when the surrounding middleware order shifted — at which point
- * the endpoint rejected every real recording with a 500. One explicit branch has no such
- * coupling, and is covered by body-parsers.spec.ts.
+ * Deliberately one middleware that *chooses* a parser, not a path-mounted parser stacked in
+ * front of a default one: that arrangement depended on Express's mount-path stripping and on
+ * body-parser skipping an already-parsed request, and silently stopped applying whenever the
+ * middleware order shifted. One explicit branch has no such coupling.
  */
 /**
- * Express routes case-insensitively and ignores a trailing slash unless configured
- * otherwise, so `/API/Voice/Extract/` reaches the same controller. Matching only the
- * canonical spelling would hand those requests the 100 kb parser and 413 every real
- * recording — a failure that looks like a broken microphone, not a routing detail.
+ * Express routes case-insensitively and ignores exactly one trailing slash, so
+ * `/API/Voice/Extract/` reaches the same controller and must get the same limit — otherwise
+ * it 413s every real recording, which reads as a broken microphone rather than a route.
+ * Two slashes never route, so they must not buy a 10 MB buffer either.
  */
 function isVoiceExtractPath(path: string): boolean {
-  // Exactly one trailing slash, because that is exactly what Express ignores. Stripping
-  // every trailing slash would hand the 10 MB parser to `/api/voice/extract//`, which
-  // buffers the body and then 404s — memory spent on a request that never routes.
   return path.toLowerCase().replace(/\/$/, '') === VOICE_EXTRACT_PATH;
 }
 

backend/src/common/digits.ts

@@ -1,19 +1,11 @@
-/**
- * Persian (Extended Arabic-Indic, U+06F0–U+06F9) zero, and Arabic-Indic (U+0660–U+0669)
- * zero. ASR output can carry either block, sometimes mixed with ASCII in one transcript.
- */
 const PERSIAN_ZERO = 0x06f0;
 const ARABIC_INDIC_ZERO = 0x0660;
 
 /**
  * Normalise Persian and Arabic-Indic digits to ASCII. Non-digits pass through.
  *
- * Deliberately wider than the frontend original, which only handles the Persian block:
- * this parses model/ASR output rather than keystrokes, so both blocks must be accepted
- * or a spoken date or tooth number silently degrades to "unresolved".
- *
- * Lives on its own rather than inside jalali.ts because tooth codes need it too, and a
- * tooth module reaching into the calendar module would read as an accident.
+ * Both blocks, not just the Persian one the frontend handles: ASR output can carry either,
+ * sometimes mixed with ASCII in a single transcript.
  */
 export function toLatinDigits(value: string): string {
   return value.replace(/[۰-۹٠-٩]/g, (ch) => {

backend/src/common/fdi.ts

@@ -14,10 +14,9 @@ export type Arch = 'upper' | 'lower';
 export type PatientSide = 'patient_right' | 'patient_left';
 
 /**
- * Upper arch in chart order: patient's RIGHT (18) → midline → patient's LEFT (28).
- * That is the drawn left-to-right layout, which is the mirror of the patient's own sides.
- * Do not read a tooth position off this array by index — use `toFdi()`, which owns the
- * side convention.
+ * Upper arch in chart order: patient's RIGHT (18) → midline → patient's LEFT (28) — the drawn
+ * layout, which mirrors the patient's own sides. Never read a position off this array by
+ * index; use `toFdi()`, which owns the side convention.
  */
 export const FDI_UPPER_ARCH_ORDER = [
   '18',
@@ -68,12 +67,9 @@ export function isFdiTooth(value: unknown): value is string {
 }
 
 /**
- * Clean up a tooth code the extraction model echoed back, before it is matched.
- *
- * The model is transcribing Persian speech, so it can hand back "۲۶" in Persian digits or
- * "2 6" from a digit-by-digit dictation. Neither matches an FDI code literally, and a
- * near-miss here does not fail loudly — the tooth quietly turns into "not understood".
- * Returns '' for anything that is not a string.
+ * Clean up a tooth code the model echoed back. It is reading Persian speech, so it can hand
+ * back "۲۶" or "2 6" from digit-by-digit dictation; neither matches literally, and the
+ * near-miss does not fail loudly — the tooth just turns into "not understood".
  */
 export function normalizeFdiCode(value: unknown): string {
   if (typeof value !== 'string') return '';
@@ -114,9 +110,8 @@ export function teethBetweenInclusive(a: string, b: string): string[] | null {
 /**
  * Arch + patient side + position (1 = central incisor … 8 = third molar) → FDI code.
  *
- * This function is the single place the patient-right convention lives. Getting it
- * backwards mirrors every quadrant and produces a valid-looking code for the wrong tooth,
- * which no schema check can catch — hence the exhaustive test coverage.
+ * The single place the patient-right convention lives. Getting it backwards mirrors every
+ * quadrant into a valid-looking code for the wrong tooth, which no schema check can catch.
  */
 export function toFdi(
   arch: Arch,
@@ -135,8 +130,8 @@ export function toFdi(
 }
 
 /**
- * Sort teeth along the arch, not lexically — a bridge reads 16-15-14, and 11 sits beside
- * 21 across the midline. Teeth from another arch (or unknown) sort to the end, stably.
+ * Along the arch, not lexically — a bridge reads 16-15-14, and 11 sits beside 21 across the
+ * midline. Teeth from another arch sort to the end, stably.
  */
 export function sortInArchOrder(teeth: readonly string[]): string[] {
   if (teeth.length === 0) return [];

backend/src/common/jalali.ts

@@ -1,10 +1,8 @@
 /**
- * Jalali (Persian) calendar arithmetic.
- *
- * Ported from `frontend/src/lib/i18n/persianCalendar.ts` (itself from jalaali-js, MIT).
- * The backend needs this because voice extraction resolves spoken Jalali dates into ISO
- * dates server-side, where the resolvers are unit-tested — the frontend has no test
- * runner. Keep the two copies in step; the underlying calendar does not change.
+ * Jalali (Persian) calendar arithmetic, ported from
+ * `frontend/src/lib/i18n/persianCalendar.ts` (itself jalaali-js, MIT). The backend needs it
+ * because voice resolves spoken Jalali dates server-side, where the resolvers are tested.
+ * Keep the two copies in step; the underlying calendar does not change.
  */
 
 const BREAKS = [
@@ -144,11 +142,8 @@ export function isJalaliLeapYear(jy: number): boolean {
 }
 
 /**
- * Days in a Jalali month, or 0 when the year or month is not real.
- *
- * Zero rather than a throw: every export here is reachable from model-supplied values, so
- * the whole module degrades instead of raising. Zero also makes `isValidJalaliDate`'s
- * `jd <= jalaliDaysInMonth(...)` naturally false.
+ * Days in a Jalali month, or 0 when the year or month is not real. Zero rather than a throw:
+ * every export here is reachable from model-supplied values, so the module degrades.
  */
 export function jalaliDaysInMonth(jy: number, jm: number): number {
   if (!isSupportedJalaliYear(jy)) return 0;
@@ -170,10 +165,8 @@ export function isValidJalaliDate(jy: number, jm: number, jd: number): boolean {
 }
 
 /**
- * Jalali triple → `YYYY-MM-DD`, or null when the date is not real.
- *
- * Returns null rather than throwing: callers resolve model-supplied values, which may be
- * nonsense, and an invalid date must degrade to "unresolved" rather than a 500.
+ * Jalali triple → `YYYY-MM-DD`, or null when the date is not real. Null rather than a throw,
+ * for the same reason: callers resolve model-supplied values, which may be nonsense.
  */
 export function jalaliToIsoDate(
   jy: number,

backend/src/common/zoned-civil-time.ts

@@ -55,15 +55,12 @@ export function civilDateJsWeekday(isoDate: string): number {
 }
 
 /**
- * Today's civil date (`YYYY-MM-DD`) in an IANA zone.
- *
- * Lets the server derive "today" from a client-supplied time zone instead of trusting a
- * client-supplied date, which matters for relative deadlines like "by Thursday".
+ * Today's civil date (`YYYY-MM-DD`) in an IANA zone, so the server derives "today" from a
+ * client-supplied *zone* rather than trusting a client-supplied date.
  */
 export function civilDateInZone(date: Date, timeZone: string): string {
-  // Intl throws RangeError on an unknown zone, before any fallback below could help, and
-  // this receives a client-supplied string. Callers validate first; this is the backstop
-  // so a bad zone degrades to a date that is at most a day out rather than a 500.
+  // Intl throws RangeError on an unknown zone and this takes a client-supplied string;
+  // callers validate first, this is the backstop.
   const zone = isValidIanaTimeZone(timeZone) ? timeZone : 'UTC';
   const parts = new Intl.DateTimeFormat('en-CA', {
     timeZone: zone,