From 7d08c59a7138a761aea224268f6826be2ef0ba9b Mon Sep 17 00:00:00 2001
From: InnerDesires <vlad.tertyshny@gmail.com>
Date: Thu, 6 Aug 2026 18:52:35 +0300
Subject: [PATCH] chore: prune non-critical comments across src

Comment lines in src/ drop from 785 to 333 (-58%) across 112 files. The bar
for keeping a comment: a reader would be confused, or likely break something,
without it.

Removed:
- JSX section markers ({/* Top bar */}, {/* stats */}, {/* certificates */})
- Step/narration comments that restate the next statement
- JSDoc that only repeats the symbol name, including the /** Locale-aware base
  path ... */ prop doc duplicated across four components
- Payload/Next template boilerplate: the 27-line ImageMedia loader essay,
  @param blocks on deepMerge/getMediaUrl/formatAuthors, defaultPopulate notes,
  the shadcn preamble in ui.ts, and a stale note in Media.ts claiming uploads
  land in public/media (they go to Vercel Blob)
- ~10 near-identical "session-free so it stays in the ISR cache" headers; kept
  one authoritative copy on getCatalogData.ts plus the two documenting a
  specific trap (generateStaticParams, useSearchParams)
- Commented-out code in VideoMedia. That left a useEffect registering an empty
  'suspend' listener, so the dead effect and its useEffect import went too --
  the only non-comment change in the diff, and provably inert.

Kept: security invariants (collection access rationale, role-escalation
warning, FK delete ordering), framework workarounds (Payload's empty-array
minRows loophole, the cyrillicSlugify NULL-vs-'' unique-constraint fix,
better-auth's #fragment rejection, plugin-search per-locale writes), magic
number provenance (certificate PDF coordinates, rate-limit thresholds), CSS
tricks (StepsList minmax(0,1fr), the -50% ticker keyframe), and all functional
directives (eslint-disable, @ts-expect-error, @ts-nocheck, empty-catch markers).

About 20 surviving multi-line headers were shortened to their load-bearing
sentence rather than deleted outright.

tsc --noEmit and eslint are clean on all changed files. Prettier's failing-file
set is unchanged from HEAD (40 files were already failing).
---
 src/Header/Nav/index.tsx                      |  1 -
 src/HomeCalendar/config.ts                    |  2 --
 src/actions/commentsAndLikes.ts               |  2 --
 src/actions/xp.ts                             |  2 --
 .../[locale]/courses/[slug]/loading.tsx       |  1 -
 .../[locale]/courses/[slug]/page.tsx          |  3 --
 .../courses/[slug]/steps/[stepIndex]/page.tsx |  5 ----
 .../(frontend)/[locale]/courses/actions.ts    | 14 ++-------
 .../[locale]/courses/category/[slug]/page.tsx |  4 ---
 src/app/(frontend)/[locale]/courses/page.tsx  |  2 --
 .../(frontend)/[locale]/leaderboard/page.tsx  |  2 --
 src/app/(frontend)/[locale]/login/page.tsx    |  1 -
 src/app/(frontend)/[locale]/page.tsx          |  5 ++--
 .../[locale]/posts/[slug]/loading.tsx         |  1 -
 .../(frontend)/[locale]/posts/[slug]/page.tsx |  2 --
 src/app/(frontend)/[locale]/profile/page.tsx  |  7 -----
 src/app/(frontend)/[locale]/register/page.tsx |  1 -
 .../(frontend)/[locale]/users/[id]/page.tsx   |  6 ----
 src/app/(frontend)/next/preview/route.ts      |  2 --
 src/app/api/auth/verify-registration/route.ts |  4 ---
 src/app/api/courses/[id]/completions/route.ts |  6 ++--
 src/app/api/dev-login/route.ts                | 14 ---------
 src/blocks/Form/Component.tsx                 |  1 -
 src/collections/Courses.ts                    |  1 -
 src/collections/Media.ts                      |  1 -
 src/collections/Pages/hooks/revalidatePage.ts |  1 -
 src/collections/Pages/index.ts                |  5 ----
 .../Posts/hooks/populateAuthors.ts            |  2 --
 src/collections/Posts/hooks/revalidatePost.ts |  1 -
 src/collections/Posts/index.ts                |  8 -----
 src/collections/XpEvents.ts                   | 10 ++-----
 src/components/AccountSettings/AvatarForm.tsx | 19 ++++--------
 .../AccountSettings/ConnectedProviders.tsx    |  1 -
 src/components/AdminBar/index.tsx             |  5 ----
 src/components/Auth/ForgotPasswordForm.tsx    |  3 --
 src/components/Auth/PasswordInput.tsx         |  2 --
 src/components/Auth/RegisterForm.tsx          |  5 ----
 src/components/BeforeDashboard/index.tsx      |  1 -
 src/components/Card/index.tsx                 |  2 --
 src/components/CollectionArchive/index.tsx    |  1 -
 .../CommentsAndLikes/CommentItem.tsx          |  1 -
 .../CommentsAndLikes/CommentsSection.tsx      |  2 --
 .../CommentsAndLikes/InteractionClient.tsx    |  6 ----
 .../CommentsAndLikes/InteractionSection.tsx   |  6 ----
 .../CommentsAndLikes/LikeButton.tsx           |  2 --
 src/components/Courses/CategoryCarousels.tsx  |  6 ----
 src/components/Courses/CategoryFilter.tsx     |  3 --
 src/components/Courses/CompleteStepButton.tsx |  4 ---
 src/components/Courses/CompletedByTicker.tsx  |  5 ----
 src/components/Courses/CourseCard.tsx         |  2 --
 src/components/Courses/CourseCatalog.tsx      |  2 --
 src/components/Courses/CourseGrid.tsx         |  4 ---
 src/components/Courses/CourseUserState.tsx    |  7 -----
 src/components/Courses/FileEmbed.tsx          |  1 -
 src/components/Courses/LoginPromptDialog.tsx  |  4 ---
 src/components/Courses/QuizAttemptHistory.tsx |  1 -
 src/components/Courses/StepsList.tsx          |  1 -
 src/components/Courses/useMyCourseStatuses.ts |  5 ----
 src/components/Home/CoursesServer.tsx         |  1 -
 src/components/Home/FadeIn.tsx                |  8 ++---
 src/components/Home/Hero.tsx                  |  3 --
 src/components/Home/News.tsx                  |  1 -
 src/components/Home/Stats.tsx                 |  5 ----
 src/components/Home/content.ts                |  3 --
 src/components/Home/index.tsx                 |  1 -
 src/components/Link/index.tsx                 | 11 ++-----
 src/components/Logo/Brand.tsx                 |  4 ---
 src/components/Logo/Logo.tsx                  |  1 -
 src/components/Media/ImageMedia/index.tsx     | 30 -------------------
 src/components/Media/VideoMedia/index.tsx     | 13 +-------
 src/components/Media/types.ts                 | 12 ++++----
 src/components/PayloadRedirects/index.tsx     |  1 -
 .../Profile/ProfileLatestComments.tsx         |  6 ----
 src/components/RichText/WithArchive.tsx       |  9 ++----
 src/components/RichText/index.tsx             |  1 -
 src/components/ShareButtons.tsx               |  1 -
 src/components/UserMenu/index.tsx             |  6 ----
 src/components/YouTubeEmbed.tsx               |  4 ---
 .../admin/InviteUserButton/index.tsx          |  5 ----
 src/components/admin/graphics/Icon.tsx        |  1 -
 src/components/admin/graphics/Logo.tsx        |  7 ++---
 src/components/brand/index.tsx                | 11 -------
 src/endpoints/seed/home-static.ts             |  1 -
 src/environment.d.ts                          |  2 --
 src/hooks/rateLimitCreate.ts                  | 11 ++-----
 src/hooks/revalidateCourse.ts                 | 11 ++-----
 src/hooks/syncCourseCompletions.ts            |  9 ++----
 src/lib/auth/dev-credentials.ts               |  9 ++----
 src/lib/auth/options.ts                       |  1 -
 src/lib/auth/pre-verified.ts                  |  5 ++--
 src/lib/auth/seed-dev-admin.ts                | 14 ++-------
 src/lib/courses/getCatalogData.ts             |  9 ++----
 src/lib/email/admin-invite.ts                 |  1 -
 src/lib/rate-limit.ts                         | 22 +++++---------
 src/payload.config.ts                         | 22 ++------------
 src/plugins/ukrainianAdmin.ts                 | 13 ++------
 src/search/localeSync.ts                      |  1 -
 src/utilities/contentCounts.ts                | 14 ++-------
 src/utilities/courseCompletion.ts             |  9 ++----
 src/utilities/deepMerge.ts                    | 10 -------
 src/utilities/formatAuthors.ts                | 11 -------
 src/utilities/formatDateTime.ts               |  1 -
 src/utilities/generatePreviewPath.ts          |  2 --
 src/utilities/getDocument.ts                  |  3 --
 src/utilities/getMediaUrl.ts                  |  8 -----
 src/utilities/getRedirects.ts                 |  5 ----
 src/utilities/leaderboard.ts                  | 13 ++------
 src/utilities/myXpCache.ts                    |  6 ----
 src/utilities/plural.ts                       |  7 ++---
 src/utilities/safeRedirect.ts                 |  6 ++--
 src/utilities/ui.ts                           |  6 ----
 src/utilities/xp.ts                           | 14 ++-------
 112 files changed, 75 insertions(+), 534 deletions(-)

diff --git a/src/Header/Nav/index.tsx b/src/Header/Nav/index.tsx
index 1352914..1435f9c 100644
--- a/src/Header/Nav/index.tsx
+++ b/src/Header/Nav/index.tsx
@@ -78,7 +78,6 @@ export const HeaderNav: React.FC<{ data: HeaderType; locale: SiteLocale }> = ({
   return (
     <div ref={rootRef} className="contents">
       <nav className="flex items-center gap-0.5" aria-label={t.projectName}>
-        {/* mobile: a single hamburger holds nav, search, account, and language */}
         <button
           type="button"
           onClick={toggleMobile}
diff --git a/src/HomeCalendar/config.ts b/src/HomeCalendar/config.ts
index 352d8eb..74f38d1 100644
--- a/src/HomeCalendar/config.ts
+++ b/src/HomeCalendar/config.ts
@@ -3,8 +3,6 @@ import type { GlobalConfig } from 'payload'
 import { getHomeContent } from '@/components/Home/content'
 import { revalidateHomeCalendar } from './hooks/revalidateHomeCalendar'
 
-// Admin form defaults mirror the hardcoded landing content (content.ts), so the
-// first save starts from what the site already shows.
 const defaults = (locale: unknown) => getHomeContent(locale === 'en' ? 'en' : 'uk').calendar
 
 export const HomeCalendar: GlobalConfig = {
diff --git a/src/actions/commentsAndLikes.ts b/src/actions/commentsAndLikes.ts
index 516a050..15f56b2 100644
--- a/src/actions/commentsAndLikes.ts
+++ b/src/actions/commentsAndLikes.ts
@@ -5,7 +5,6 @@ import configPromise from '@payload-config'
 import { revalidateTag } from 'next/cache'
 import { getSession } from '@/lib/auth/getSession'
 
-/** True when a Local API write was rejected by a rate-limit hook (429). */
 const isRateLimited = (err: unknown): boolean => err instanceof APIError && err.status === 429
 
 type TargetCollection = 'posts' | 'courses'
@@ -249,7 +248,6 @@ export type LikeInfo = {
   count: number
 }
 
-/** Invalidate the cached grouped counts (src/utilities/contentCounts.ts) after a write. */
 function revalidateCounts(kind: 'likes' | 'comments', targetCollection: LikeTargetCollection) {
   if (targetCollection === 'posts' || targetCollection === 'courses') {
     revalidateTag(`${kind}-counts-${targetCollection}`)
diff --git a/src/actions/xp.ts b/src/actions/xp.ts
index 65f9d9d..5ef7112 100644
--- a/src/actions/xp.ts
+++ b/src/actions/xp.ts
@@ -10,11 +10,9 @@ export type MyXp = {
   level: number
   intoLevel: number
   span: number
-  /** Avatar URL from the users doc — the better-auth session payload omits `image`. */
   image: string | null
 }
 
-/** Total XP and level for the signed-in user (30 XP/step, 100 XP/passed quiz). */
 export async function getMyXp(): Promise<MyXp | null> {
   const session = await getSession().catch(() => null)
   if (!session?.user) return null
diff --git a/src/app/(frontend)/[locale]/courses/[slug]/loading.tsx b/src/app/(frontend)/[locale]/courses/[slug]/loading.tsx
index 3abe217..8fd3216 100644
--- a/src/app/(frontend)/[locale]/courses/[slug]/loading.tsx
+++ b/src/app/(frontend)/[locale]/courses/[slug]/loading.tsx
@@ -1,4 +1,3 @@
-// Instant skeleton shown while a course overview renders — mirrors its layout.
 export default function Loading() {
   return (
     <div className="animate-pulse pb-16">
diff --git a/src/app/(frontend)/[locale]/courses/[slug]/page.tsx b/src/app/(frontend)/[locale]/courses/[slug]/page.tsx
index 73ae777..1a5f41a 100644
--- a/src/app/(frontend)/[locale]/courses/[slug]/page.tsx
+++ b/src/app/(frontend)/[locale]/courses/[slug]/page.tsx
@@ -19,9 +19,6 @@ import { RewardPill } from '@/components/brand'
 import { courseXp } from '@/utilities/xp'
 import { plural } from '@/utilities/plural'
 
-// Per-user state (enrollment, progress) is fetched client-side via
-// CourseUserStateProvider, so the page itself is the same for everyone and
-// can be served from the ISR cache. Enrollment mutations revalidate it by path.
 export const revalidate = 300
 
 export async function generateStaticParams() {
diff --git a/src/app/(frontend)/[locale]/courses/[slug]/steps/[stepIndex]/page.tsx b/src/app/(frontend)/[locale]/courses/[slug]/steps/[stepIndex]/page.tsx
index cfc811b..7847f46 100644
--- a/src/app/(frontend)/[locale]/courses/[slug]/steps/[stepIndex]/page.tsx
+++ b/src/app/(frontend)/[locale]/courses/[slug]/steps/[stepIndex]/page.tsx
@@ -99,7 +99,6 @@ export default async function StepViewerPage({ params: paramsPromise }: Args) {
   return (
     <div className="pt-10 pb-16">
       <div className="container max-w-7xl">
-        {/* Top bar */}
         <div className="flex items-center justify-between gap-4 mb-4 flex-wrap">
           <Link
             href={`${prefix}/courses/${slug}`}
@@ -124,7 +123,6 @@ export default async function StepViewerPage({ params: paramsPromise }: Args) {
           step body and the steps sidebar both start on row 2 — their tops line up.
         */}
         <div className="grid grid-cols-1 gap-x-8 lg:grid-cols-[minmax(0,1fr)_18rem] xl:grid-cols-[minmax(0,1fr)_20rem]">
-          {/* Title + meta — spans only the content column */}
           <div className="min-w-0 lg:col-start-1 lg:row-start-1">
             <h1 className="heading-display mb-2.5 text-[clamp(24px,3vw,34px)]">{stepTitle}</h1>
 
@@ -142,7 +140,6 @@ export default async function StepViewerPage({ params: paramsPromise }: Args) {
             </div>
           </div>
 
-          {/* Main content */}
           <div className="min-w-0 lg:col-start-1 lg:row-start-2">
             <div className="mb-8">
               {step.blockType === 'richTextStep' && step.content && (
@@ -178,7 +175,6 @@ export default async function StepViewerPage({ params: paramsPromise }: Args) {
               )}
             </div>
 
-            {/* Navigation footer */}
             {isLastStep && quizEnabled && !quizReady && (
               <p className="mb-3 flex items-center justify-end gap-1.5 text-[11.5px] font-semibold uppercase tracking-[0.08em] text-steel">
                 <Lock className="h-3.5 w-3.5 flex-none" />
@@ -218,7 +214,6 @@ export default async function StepViewerPage({ params: paramsPromise }: Args) {
             </div>
           </div>
 
-          {/* Sidebar steps list — visible on desktop */}
           <aside className="mt-8 w-full min-w-0 lg:col-start-2 lg:row-start-2 lg:mt-0">
             <div className="rounded-2xl border border-line bg-card p-4 lg:sticky lg:top-24">
               <h3 className="mb-3.5 px-1 font-display text-xs font-semibold uppercase tracking-[0.2em] text-fog">
diff --git a/src/app/(frontend)/[locale]/courses/actions.ts b/src/app/(frontend)/[locale]/courses/actions.ts
index bde1d04..41669c0 100644
--- a/src/app/(frontend)/[locale]/courses/actions.ts
+++ b/src/app/(frontend)/[locale]/courses/actions.ts
@@ -10,10 +10,8 @@ import { getStepIds, isCourseComplete } from '@/utilities/courseCompletion'
 import type { Course, Enrollment, QuizAttempt } from '@/payload-types'
 import type { Payload } from 'payload'
 
-/**
- * Timestamped XP log for period leaderboards; total XP stays derived from
- * enrollments, so a failed log write must not fail the mutation that earned it.
- */
+// Total XP stays derived from enrollments, so a failed log write must not fail the
+// mutation that earned it.
 async function logXpEvent(
   payload: Payload,
   data: { user: number; course: number; kind: 'step' | 'quiz'; amount: number },
@@ -26,14 +24,12 @@ async function logXpEvent(
   }
 }
 
-/** Bust cached course pages (both locales) after an enrollment mutation. */
 function revalidateCoursePages(slug: string) {
   for (const prefix of ['', '/en']) {
     revalidatePath(`${prefix}/courses/${slug}`)
     revalidatePath(`${prefix}/courses/${slug}/steps/[stepIndex]`, 'page')
     revalidatePath(`${prefix}/courses/${slug}/quiz`)
   }
-  // Cached aggregate counters (src/utilities/contentCounts.ts)
   revalidateTag('course-enrollment-stats')
 }
 
@@ -42,10 +38,6 @@ export type MyCourseStatuses = {
   inProgress: number[]
 }
 
-/**
- * Course ids the signed-in user has completed / started. Fetched client-side
- * so the catalog page itself can stay statically cached for everyone.
- */
 export async function getMyCourseStatuses(): Promise<MyCourseStatuses> {
   const session = await getSession().catch(() => null)
   if (!session?.user) return { completed: [], inProgress: [] }
@@ -225,8 +217,6 @@ export async function getEnrollment(
       ],
     },
     limit: 1,
-    // Consumed client-side (CourseUserState) — ids are enough, don't populate
-    // the full user/course docs into the response.
     depth: 0,
   })
 
diff --git a/src/app/(frontend)/[locale]/courses/category/[slug]/page.tsx b/src/app/(frontend)/[locale]/courses/category/[slug]/page.tsx
index 39ba76e..ae6e122 100644
--- a/src/app/(frontend)/[locale]/courses/category/[slug]/page.tsx
+++ b/src/app/(frontend)/[locale]/courses/category/[slug]/page.tsx
@@ -13,8 +13,6 @@ import { getCatalogData } from '@/lib/courses/getCatalogData'
 import { plural } from '@/utilities/plural'
 import type { Media as MediaType } from '@/payload-types'
 
-// Session-free on the server (viewer progress loads client-side in CourseGrid),
-// so category pages serve from the ISR cache like the main catalog.
 export const revalidate = 300
 
 export async function generateStaticParams() {
@@ -77,8 +75,6 @@ export default async function CourseCategoryPage({ params: paramsPromise }: Args
             style={{ backgroundImage: `url(${imageUrl})` }}
           />
         )}
-        {/* Lighter at the top than the course hero so the category cover
-            actually reads through; still settles into solid void for the grid. */}
         <div
           className="absolute inset-0"
           style={{
diff --git a/src/app/(frontend)/[locale]/courses/page.tsx b/src/app/(frontend)/[locale]/courses/page.tsx
index 7ce60c7..b65dfd3 100644
--- a/src/app/(frontend)/[locale]/courses/page.tsx
+++ b/src/app/(frontend)/[locale]/courses/page.tsx
@@ -9,8 +9,6 @@ import { CategoryCarousels } from '@/components/Courses/CategoryCarousels'
 import { PageHead } from '@/components/brand'
 import { getCatalogData } from '@/lib/courses/getCatalogData'
 
-// The catalog is the same for everyone — per-user progress badges are fetched
-// client-side (useMyCourseStatuses), so this page can be served from the ISR cache.
 export const revalidate = 300
 
 export function generateStaticParams() {
diff --git a/src/app/(frontend)/[locale]/leaderboard/page.tsx b/src/app/(frontend)/[locale]/leaderboard/page.tsx
index a2669d7..1950879 100644
--- a/src/app/(frontend)/[locale]/leaderboard/page.tsx
+++ b/src/app/(frontend)/[locale]/leaderboard/page.tsx
@@ -10,8 +10,6 @@ import {
   getCachedPeriodLeaderboard,
 } from '@/utilities/leaderboard'
 
-// The leaderboard is the same for everyone, so it can be served from the ISR
-// cache; XP-awarding mutations revalidate the `xp-leaderboard` tag.
 export const revalidate = 300
 
 export function generateStaticParams() {
diff --git a/src/app/(frontend)/[locale]/login/page.tsx b/src/app/(frontend)/[locale]/login/page.tsx
index 83765f5..921d36d 100644
--- a/src/app/(frontend)/[locale]/login/page.tsx
+++ b/src/app/(frontend)/[locale]/login/page.tsx
@@ -15,7 +15,6 @@ export default async function LoginPage({ params, searchParams }: Args) {
   const { locale } = await params
   const { redirect: redirectParam, reset } = await searchParams
   const home = locale === defaultLocale ? '/' : `/${locale}`
-  // sanitized return path; undefined keeps each form's own default
   const redirectTo = redirectParam ? safeRedirectPath(redirectParam, home) : undefined
 
   const session = await getSession()
diff --git a/src/app/(frontend)/[locale]/page.tsx b/src/app/(frontend)/[locale]/page.tsx
index 426248a..82cd137 100644
--- a/src/app/(frontend)/[locale]/page.tsx
+++ b/src/app/(frontend)/[locale]/page.tsx
@@ -10,9 +10,8 @@ import { NewsSectionServer, NewsSectionSkeleton } from '@/components/Home/NewsSe
 import { CoursesGridServer, CoursesGridSkeleton } from '@/components/Home/CoursesServer'
 import { CategoryCarousels } from '@/components/Courses/CategoryCarousels'
 
-// Home has no per-request personalization on the server — safe to serve from ISR cache.
-// generateStaticParams is required for that: without it, a dynamic-segment route
-// is rendered per request and `revalidate` has no effect.
+// generateStaticParams is required for `revalidate` to take effect: without it a
+// dynamic-segment route is rendered per request.
 export const revalidate = 300
 
 export function generateStaticParams() {
diff --git a/src/app/(frontend)/[locale]/posts/[slug]/loading.tsx b/src/app/(frontend)/[locale]/posts/[slug]/loading.tsx
index 74dee01..d991091 100644
--- a/src/app/(frontend)/[locale]/posts/[slug]/loading.tsx
+++ b/src/app/(frontend)/[locale]/posts/[slug]/loading.tsx
@@ -1,4 +1,3 @@
-// Instant skeleton shown while an article renders — mirrors the PostHero layout.
 export default function Loading() {
   return (
     <article className="animate-pulse pb-16">
diff --git a/src/app/(frontend)/[locale]/posts/[slug]/page.tsx b/src/app/(frontend)/[locale]/posts/[slug]/page.tsx
index 683a4a4..b66744c 100644
--- a/src/app/(frontend)/[locale]/posts/[slug]/page.tsx
+++ b/src/app/(frontend)/[locale]/posts/[slug]/page.tsx
@@ -21,8 +21,6 @@ import { ShareButtons } from '@/components/ShareButtons'
 import { getServerSideURL } from '@/utilities/getURL'
 import { getFrontendMessages } from '@/utilities/i18n'
 
-// Refresh periodically so the baked-in like/comment counts don't go stale;
-// content edits still revalidate immediately via the collection hook.
 export const revalidate = 600
 
 export async function generateStaticParams() {
diff --git a/src/app/(frontend)/[locale]/profile/page.tsx b/src/app/(frontend)/[locale]/profile/page.tsx
index afe8c03..ec6af19 100644
--- a/src/app/(frontend)/[locale]/profile/page.tsx
+++ b/src/app/(frontend)/[locale]/profile/page.tsx
@@ -77,7 +77,6 @@ export default async function ProfilePage({ params }: Args) {
     }),
   ])
 
-  // XP scoreboard: 30 XP per completed step, 100 XP per passed final quiz.
   let stepsDone = 0
   let quizzesPassed = 0
   for (const enrollment of enrollments.docs) {
@@ -113,7 +112,6 @@ export default async function ProfilePage({ params }: Args) {
   return (
     <div className="container max-w-2xl py-16">
       <div className="mb-8 flex flex-col items-center gap-4">
-        {/* avatar with XP level ring */}
         <div
           className="h-24 w-24 rounded-full p-[4px]"
           style={{
@@ -186,7 +184,6 @@ export default async function ProfilePage({ params }: Args) {
         </div>
       </div>
 
-      {/* XP progress to next level */}
       <div className="rounded-2xl border border-line-2 bg-[linear-gradient(150deg,rgb(4_40_113/0.5),var(--navy))] p-6">
         <div className="mb-2 flex items-center justify-between text-[11px] font-bold uppercase tracking-[0.1em] text-fog">
           <span>{t.profileToNextLevel}</span>
@@ -219,7 +216,6 @@ export default async function ProfilePage({ params }: Args) {
         </div>
       </div>
 
-      {/* courses in progress */}
       <h2 className={sectionHeading}>{t.profileMyCourses}</h2>
       {inProgress.length === 0 && completed.length === 0 ? (
         <div className="rounded-2xl border border-line bg-card p-8 text-center">
@@ -277,7 +273,6 @@ export default async function ProfilePage({ params }: Args) {
         </div>
       )}
 
-      {/* certificates */}
       {completed.length > 0 && (
         <>
           <h2 className={sectionHeading}>{t.profileCertificates}</h2>
@@ -323,7 +318,6 @@ export default async function ProfilePage({ params }: Args) {
         </>
       )}
 
-      {/* recent quiz attempts */}
       {recentAttempts.docs.length > 0 && (
         <>
           <h2 className={sectionHeading}>{t.profileRecentQuizzes}</h2>
@@ -370,7 +364,6 @@ export default async function ProfilePage({ params }: Args) {
         </>
       )}
 
-      {/* account info */}
       <div className="mt-10 space-y-5 rounded-2xl border border-line bg-card p-6">
         <div className="flex items-center gap-3">
           <Mail className="h-5 w-5 shrink-0 text-orange" />
diff --git a/src/app/(frontend)/[locale]/register/page.tsx b/src/app/(frontend)/[locale]/register/page.tsx
index 8dec18d..5ec9591 100644
--- a/src/app/(frontend)/[locale]/register/page.tsx
+++ b/src/app/(frontend)/[locale]/register/page.tsx
@@ -16,7 +16,6 @@ export default async function RegisterPage({ params, searchParams }: Args) {
   const { redirect: redirectParam } = await searchParams
 
   const home = locale === defaultLocale ? '/' : `/${locale}`
-  // sanitized return path; undefined keeps each form's own default
   const redirectTo = redirectParam ? safeRedirectPath(redirectParam, home) : undefined
 
   const session = await getSession()
diff --git a/src/app/(frontend)/[locale]/users/[id]/page.tsx b/src/app/(frontend)/[locale]/users/[id]/page.tsx
index b8264c4..8b17c68 100644
--- a/src/app/(frontend)/[locale]/users/[id]/page.tsx
+++ b/src/app/(frontend)/[locale]/users/[id]/page.tsx
@@ -76,7 +76,6 @@ export default async function PublicProfilePage({ params }: Args) {
     depth: 1,
   })
 
-  // Same XP math as the private profile page.
   let stepsDone = 0
   let quizzesPassed = 0
   for (const enrollment of enrollments.docs) {
@@ -102,7 +101,6 @@ export default async function PublicProfilePage({ params }: Args) {
   return (
     <div className="container max-w-2xl py-16">
       <div className="mb-8 flex flex-col items-center gap-4">
-        {/* avatar with XP level ring */}
         <div
           className="h-24 w-24 rounded-full p-[4px]"
           style={{
@@ -158,7 +156,6 @@ export default async function PublicProfilePage({ params }: Args) {
         )}
       </div>
 
-      {/* stats */}
       <div className="rounded-2xl border border-line-2 bg-[linear-gradient(150deg,rgb(4_40_113/0.5),var(--navy))] p-6">
         <div className="grid grid-cols-3 gap-3 text-center">
           <div>
@@ -182,7 +179,6 @@ export default async function PublicProfilePage({ params }: Args) {
         </div>
       </div>
 
-      {/* completed courses — no scores, no certificate downloads */}
       {completed.length > 0 && (
         <>
           <h2 className="heading-display mb-4 mt-10 text-xl tracking-[0.06em]">
@@ -218,14 +214,12 @@ export default async function PublicProfilePage({ params }: Args) {
         </>
       )}
 
-      {/* latest comments — streamed after first paint so they never block the page */}
       {user.hideProfileComments !== true && (
         <Suspense fallback={<ProfileLatestCommentsSkeleton />}>
           <ProfileLatestComments userId={user.id} locale={locale} />
         </Suspense>
       )}
 
-      {/* joined date */}
       {joinedDate && (
         <div className="mt-10 flex items-center gap-3 rounded-2xl border border-line bg-card p-6">
           <Calendar className="h-5 w-5 shrink-0 text-orange" />
diff --git a/src/app/(frontend)/next/preview/route.ts b/src/app/(frontend)/next/preview/route.ts
index ce2fb55..6d6b55f 100644
--- a/src/app/(frontend)/next/preview/route.ts
+++ b/src/app/(frontend)/next/preview/route.ts
@@ -48,8 +48,6 @@ export async function GET(req: NextRequest): Promise<Response> {
     return new Response('You are not allowed to preview this page', { status: 403 })
   }
 
-  // You can add additional checks here to see if the user is allowed to preview this page
-
   draft.enable()
 
   redirect(path)
diff --git a/src/app/api/auth/verify-registration/route.ts b/src/app/api/auth/verify-registration/route.ts
index c255e8b..764c19a 100644
--- a/src/app/api/auth/verify-registration/route.ts
+++ b/src/app/api/auth/verify-registration/route.ts
@@ -56,7 +56,6 @@ async function handleSendOtp(request: Request, body: { email?: string }) {
     body: { email, type: 'email-verification' },
   })
 
-  // Send the OTP email via Resend (skipped when API key is not configured, e.g. in CI/tests)
   if (process.env.RESEND_API_KEY) {
     const resend = new Resend(process.env.RESEND_API_KEY)
     await resend.emails.send({
@@ -94,7 +93,6 @@ async function handleVerifyOtp(request: Request, body: { email?: string; otp?: s
 
   const identifier = `email-verification-otp-${email}`
 
-  // Find the verification record
   const records = await payload.find({
     collection: 'verifications',
     where: { identifier: { equals: identifier } },
@@ -123,7 +121,6 @@ async function handleVerifyOtp(request: Request, body: { email?: string; otp?: s
   }
 
   if (storedOtp !== otp) {
-    // Increment attempt counter
     await payload.update({
       collection: 'verifications',
       id: record.id,
@@ -132,7 +129,6 @@ async function handleVerifyOtp(request: Request, body: { email?: string; otp?: s
     return NextResponse.json({ error: 'Invalid OTP' }, { status: 400 })
   }
 
-  // OTP valid — mark email as pre-verified and clean up
   markPreVerified(email)
   await payload.delete({ collection: 'verifications', id: record.id })
 
diff --git a/src/app/api/courses/[id]/completions/route.ts b/src/app/api/courses/[id]/completions/route.ts
index 0be1058..9e41f43 100644
--- a/src/app/api/courses/[id]/completions/route.ts
+++ b/src/app/api/courses/[id]/completions/route.ts
@@ -1,9 +1,7 @@
 import { getCachedCourseCompletions } from '@/utilities/leaderboard'
 
-/**
- * Public projection of who completed a course (name/avatar only), consumed by
- * the course-page ticker. Enrollment docs themselves stay admin-or-own.
- */
+// Public projection of who completed a course (name/avatar only) — enrollment docs
+// themselves stay admin-or-own.
 export async function GET(
   _req: Request,
   { params }: { params: Promise<{ id: string }> },
diff --git a/src/app/api/dev-login/route.ts b/src/app/api/dev-login/route.ts
index 6847724..31a3f16 100644
--- a/src/app/api/dev-login/route.ts
+++ b/src/app/api/dev-login/route.ts
@@ -3,19 +3,6 @@ import { getPayload } from '@/lib/payload'
 import { DEV_ADMIN } from '@/lib/auth/dev-credentials'
 import { seedDevAdmin } from '@/lib/auth/seed-dev-admin'
 
-/**
- * Dev-only auto-login: signs in as the dev admin and sets the Better Auth
- * session cookies, then redirects. One request logs a browser in —
- * `open http://localhost:3000/api/dev-login`.
- *
- * Self-healing: when sign-in fails (fresh/wiped database without the account),
- * it runs the dev-admin seed and retries — so the first login on any dev
- * branch works without a manual seeding step. The account normally pre-exists
- * via the seeded dev parent Neon branch, making the fast path seed-free.
- *
- * Never available on Vercel. Local production builds (pnpm dev:prod) must
- * opt in with ALLOW_DEV_LOGIN=1. See docs/dev-admin-login.md.
- */
 function devLoginEnabled(): boolean {
   if (process.env.VERCEL) return false
   return process.env.NODE_ENV !== 'production' || process.env.ALLOW_DEV_LOGIN === '1'
@@ -38,7 +25,6 @@ export async function GET(request: Request) {
   let authResponse = await signIn(payload)
 
   if (!authResponse.ok) {
-    // Account missing (or stale password) — seed it, then retry once.
     payload.logger.info('dev-login: sign-in failed, running dev-admin seed')
     try {
       pendingSeed ??= seedDevAdmin(payload).finally(() => {
diff --git a/src/blocks/Form/Component.tsx b/src/blocks/Form/Component.tsx
index 1e50ecd..3729ffd 100644
--- a/src/blocks/Form/Component.tsx
+++ b/src/blocks/Form/Component.tsx
@@ -60,7 +60,6 @@ export const FormBlock: React.FC<
           value,
         }))
 
-        // delay loading indicator by 1s
         loadingTimerID = setTimeout(() => {
           setIsLoading(true)
         }, 1000)
diff --git a/src/collections/Courses.ts b/src/collections/Courses.ts
index 3819d75..5f1ed4c 100644
--- a/src/collections/Courses.ts
+++ b/src/collections/Courses.ts
@@ -7,7 +7,6 @@ import { cyrillicSlugify } from '../utilities/cyrillicSlugify'
 import { syncCourseCompletions } from '../hooks/syncCourseCompletions'
 import { revalidateCourse, revalidateCourseDelete } from '../hooks/revalidateCourse'
 
-// Орієнтовна тривалість кроку — показується учням у списках кроків («Відео · 8 хв»).
 const stepDurationField: Field = {
   name: 'duration',
   type: 'number',
diff --git a/src/collections/Media.ts b/src/collections/Media.ts
index 67130a7..5301972 100644
--- a/src/collections/Media.ts
+++ b/src/collections/Media.ts
@@ -45,7 +45,6 @@ export const Media: CollectionConfig = {
     },
   ],
   upload: {
-    // Upload to the public/media directory in Next.js making them publicly accessible even outside of Payload
     staticDir: path.resolve(dirname, '../../public/media'),
     adminThumbnail: 'thumbnail',
     focalPoint: true,
diff --git a/src/collections/Pages/hooks/revalidatePage.ts b/src/collections/Pages/hooks/revalidatePage.ts
index 2a19809..b0aee9e 100644
--- a/src/collections/Pages/hooks/revalidatePage.ts
+++ b/src/collections/Pages/hooks/revalidatePage.ts
@@ -19,7 +19,6 @@ export const revalidatePage: CollectionAfterChangeHook<Page> = ({
       revalidateTag('pages-sitemap')
     }
 
-    // If the page was previously published, we need to revalidate the old path
     if (previousDoc?._status === 'published' && doc._status !== 'published') {
       const oldPath = previousDoc.slug === 'home' ? '/' : `/${previousDoc.slug}`
 
diff --git a/src/collections/Pages/index.ts b/src/collections/Pages/index.ts
index 6cc65a5..36d6657 100644
--- a/src/collections/Pages/index.ts
+++ b/src/collections/Pages/index.ts
@@ -31,9 +31,6 @@ export const Pages: CollectionConfig<'pages'> = {
     read: authenticatedOrPublished,
     update: admin,
   },
-  // This config controls what's populated by default when a page is referenced
-  // https://payloadcms.com/docs/queries/select#defaultpopulate-collection-config-property
-  // Type safe if the collection slug generic is passed to `CollectionConfig` - `CollectionConfig<'pages'>
   defaultPopulate: {
     title: true,
     slug: true,
@@ -109,10 +106,8 @@ export const Pages: CollectionConfig<'pages'> = {
               overrides: { label: 'Мета-опис' },
             }),
             PreviewField({
-              // if the `generateUrl` function is configured
               hasGenerateFn: true,
 
-              // field paths to match the target field for data
               titlePath: 'meta.title',
               descriptionPath: 'meta.description',
             }),
diff --git a/src/collections/Posts/hooks/populateAuthors.ts b/src/collections/Posts/hooks/populateAuthors.ts
index 746ebfd..17e139d 100644
--- a/src/collections/Posts/hooks/populateAuthors.ts
+++ b/src/collections/Posts/hooks/populateAuthors.ts
@@ -2,8 +2,6 @@ import type { CollectionAfterReadHook } from 'payload'
 
 // The `user` collection has access control locked so that users are not publicly accessible
 // This means that we need to populate the authors manually here to protect user privacy
-// GraphQL will not return mutated user data that differs from the underlying schema
-// So we use an alternative `populatedAuthors` field to populate the user data, hidden from the admin UI
 export const populateAuthors: CollectionAfterReadHook = async ({ doc, req, req: { payload } }) => {
   if (doc?.authors && doc?.authors?.length > 0) {
     const authorIds: number[] = doc.authors.map((author: { id: number } | number) =>
diff --git a/src/collections/Posts/hooks/revalidatePost.ts b/src/collections/Posts/hooks/revalidatePost.ts
index ff43752..ccff28c 100644
--- a/src/collections/Posts/hooks/revalidatePost.ts
+++ b/src/collections/Posts/hooks/revalidatePost.ts
@@ -19,7 +19,6 @@ export const revalidatePost: CollectionAfterChangeHook<Post> = ({
       revalidateTag('posts-sitemap')
     }
 
-    // If the post was previously published, we need to revalidate the old path
     if (previousDoc._status === 'published' && doc._status !== 'published') {
       const oldPath = `/posts/${previousDoc.slug}`
 
diff --git a/src/collections/Posts/index.ts b/src/collections/Posts/index.ts
index d87cafb..a41644b 100644
--- a/src/collections/Posts/index.ts
+++ b/src/collections/Posts/index.ts
@@ -39,9 +39,6 @@ export const Posts: CollectionConfig<'posts'> = {
     read: authenticatedOrPublished,
     update: admin,
   },
-  // This config controls what's populated by default when a post is referenced
-  // https://payloadcms.com/docs/queries/select#defaultpopulate-collection-config-property
-  // Type safe if the collection slug generic is passed to `CollectionConfig` - `CollectionConfig<'posts'>
   defaultPopulate: {
     title: true,
     slug: true,
@@ -165,10 +162,8 @@ export const Posts: CollectionConfig<'posts'> = {
               overrides: { label: 'Мета-опис' },
             }),
             PreviewField({
-              // if the `generateUrl` function is configured
               hasGenerateFn: true,
 
-              // field paths to match the target field for data
               titlePath: 'meta.title',
               descriptionPath: 'meta.description',
             }),
@@ -207,9 +202,6 @@ export const Posts: CollectionConfig<'posts'> = {
       hasMany: true,
       relationTo: 'users',
     },
-    // This field is only used to populate the user data via the `populateAuthors` hook
-    // This is because the `user` collection has access control locked to protect user privacy
-    // GraphQL will also not return mutated user data that differs from the underlying schema
     {
       name: 'populatedAuthors',
       type: 'array',
diff --git a/src/collections/XpEvents.ts b/src/collections/XpEvents.ts
index 3e2a363..b717367 100644
--- a/src/collections/XpEvents.ts
+++ b/src/collections/XpEvents.ts
@@ -2,13 +2,9 @@ import type { CollectionConfig } from 'payload'
 
 import { admin } from '../access/admin'
 
-/**
- * Append-only log of XP awards (step completed, final quiz passed).
- *
- * Total XP stays derived from enrollments (see src/utilities/xp.ts); this log
- * exists so period leaderboards («XP за день/тиждень/місяць») can be computed —
- * enrollments store which steps are done but not when.
- */
+// Append-only log of XP awards. Total XP stays derived from enrollments (src/utilities/xp.ts);
+// this log exists only so period leaderboards can be computed — enrollments store which
+// steps are done but not when.
 export const XpEvents: CollectionConfig = {
   slug: 'xp-events',
   labels: { singular: 'Подія XP', plural: 'Події XP' },
diff --git a/src/components/AccountSettings/AvatarForm.tsx b/src/components/AccountSettings/AvatarForm.tsx
index b402656..1fdd0cf 100644
--- a/src/components/AccountSettings/AvatarForm.tsx
+++ b/src/components/AccountSettings/AvatarForm.tsx
@@ -31,13 +31,10 @@ const fileType = (file: File): string =>
   file.type || EXTENSION_TYPES[file.name.split('.').pop()?.toLowerCase() ?? ''] || ''
 
 /**
- * Re-encodes the picked image to a modest JPEG before it ever reaches the
- * server action. A phone photo is routinely 2–5 MB, which blows past the
- * server action body limit and fails as an opaque rejection — this keeps the
- * upload at a couple hundred KB and normalises the type on the way.
- *
- * Returns the untouched file when re-encoding is not worth it or not possible;
- * the caller still validates size, so a passthrough is always safe.
+ * A phone photo is routinely 2–5 MB, which blows past the server action body limit and
+ * fails as an opaque rejection, so re-encode to a modest JPEG first. Returns the
+ * untouched file when that is not worth it or not possible — the caller still validates
+ * size, so a passthrough is always safe.
  */
 async function shrinkForUpload(file: File): Promise<File> {
   const type = fileType(file)
@@ -74,10 +71,8 @@ async function shrinkForUpload(file: File): Promise<File> {
   }
 }
 
-/** The server action updates the user in the DB, but two caches still hold the
- *  old snapshot: the session cookie cache (5 min) and the header's myXp cache,
- *  whose payload carries `image`. Clear both so the header avatar changes with
- *  the rest of the page instead of lagging behind it by up to 5 minutes. */
+// Two caches still hold the old snapshot after the server action writes: the session
+// cookie cache (5 min) and the header's myXp cache, whose payload carries `image`.
 const refreshAndReload = async () => {
   clearMyXpCache()
   await authClient.getSession({ query: { disableCookieCache: true } })
@@ -143,8 +138,6 @@ export const AvatarForm: React.FC<{
             : t.settingsErrorGeneric,
       )
     } catch {
-      // A rejected server action (body too large, network drop, cold start
-      // timeout) used to leave the button stuck on "saving" with no message.
       setError(t.settingsErrorGeneric)
     }
     setBusy(false)
diff --git a/src/components/AccountSettings/ConnectedProviders.tsx b/src/components/AccountSettings/ConnectedProviders.tsx
index 92cc4c3..4885de6 100644
--- a/src/components/AccountSettings/ConnectedProviders.tsx
+++ b/src/components/AccountSettings/ConnectedProviders.tsx
@@ -60,7 +60,6 @@ export const ConnectedProviders: React.FC<{
       setError(t.settingsErrorGeneric)
       setBusy(false)
     }
-    // On success the browser redirects to Google.
   }
 
   const handleDisconnectGoogle = async () => {
diff --git a/src/components/AdminBar/index.tsx b/src/components/AdminBar/index.tsx
index 46aeaa1..7f6b7ac 100644
--- a/src/components/AdminBar/index.tsx
+++ b/src/components/AdminBar/index.tsx
@@ -14,7 +14,6 @@ import './index.scss'
 
 const baseClass = 'admin-bar'
 
-/** Collections an admin touches daily; `create` adds a quick «+» link. */
 const quickLinks = [
   { create: true, icon: GraduationCap, label: 'Курси', slug: 'courses' },
   { create: true, icon: Newspaper, label: 'Публікації', slug: 'posts' },
@@ -33,10 +32,6 @@ type MeUser = {
   role?: ('admin' | 'learner')[] | null
 }
 
-/**
- * Slim bar shown above the site header to logged-in admins only: quick links
- * into the CMS (courses, posts, pages, users) plus create shortcuts.
- */
 export const AdminBar: React.FC<AdminBarProps> = ({ adminBarProps }) => {
   const preview = adminBarProps?.preview ?? false
   const [isAdmin, setIsAdmin] = useState(false)
diff --git a/src/components/Auth/ForgotPasswordForm.tsx b/src/components/Auth/ForgotPasswordForm.tsx
index a7f5e9c..942164c 100644
--- a/src/components/Auth/ForgotPasswordForm.tsx
+++ b/src/components/Auth/ForgotPasswordForm.tsx
@@ -26,7 +26,6 @@ export const ForgotPasswordForm: React.FC<{
 
   const loginHref = `/${locale === 'uk' ? '' : locale + '/'}login`
 
-  // Resend cooldown timer
   useEffect(() => {
     if (resendCooldown <= 0) return
     const timer = setTimeout(() => setResendCooldown((c) => c - 1), 1000)
@@ -88,7 +87,6 @@ export const ForgotPasswordForm: React.FC<{
     router.refresh()
   }
 
-  // Step 2: OTP + new password
   if (step === 'reset') {
     return (
       <div className="mx-auto w-full max-w-md">
@@ -159,7 +157,6 @@ export const ForgotPasswordForm: React.FC<{
     )
   }
 
-  // Step 1: Email entry
   return (
     <div className="mx-auto w-full max-w-md">
       <h1 className="heading-display mb-2 text-center text-3xl">{t.forgotTitle}</h1>
diff --git a/src/components/Auth/PasswordInput.tsx b/src/components/Auth/PasswordInput.tsx
index 23af3ed..aa8699b 100644
--- a/src/components/Auth/PasswordInput.tsx
+++ b/src/components/Auth/PasswordInput.tsx
@@ -4,12 +4,10 @@ import React, { useState } from 'react'
 import { Eye, EyeOff } from 'lucide-react'
 
 type Props = Omit<React.ComponentProps<'input'>, 'type'> & {
-  /** aria-labels for the toggle button */
   showLabel: string
   hideLabel: string
 }
 
-/** Password field with a show/hide toggle. Keeps the same id/name/autofill contract as a plain input. */
 export const PasswordInput: React.FC<Props> = ({ showLabel, hideLabel, className, ...props }) => {
   const [visible, setVisible] = useState(false)
 
diff --git a/src/components/Auth/RegisterForm.tsx b/src/components/Auth/RegisterForm.tsx
index 56d90a3..23dc38d 100644
--- a/src/components/Auth/RegisterForm.tsx
+++ b/src/components/Auth/RegisterForm.tsx
@@ -31,7 +31,6 @@ export const RegisterForm: React.FC<{
   // fragment (e.g. #comments) only rides on the client-side navigation below.
   const serverCallbackURL = callbackURL.split('#')[0] || '/'
 
-  // Resend cooldown timer
   useEffect(() => {
     if (resendCooldown <= 0) return
     const timer = setTimeout(() => setResendCooldown((c) => c - 1), 1000)
@@ -94,7 +93,6 @@ export const RegisterForm: React.FC<{
         return
       }
 
-      // OTP verified — create the account
       setStep('creating')
       const { error: signUpError } = await authClient.signUp.email({
         name,
@@ -142,7 +140,6 @@ export const RegisterForm: React.FC<{
     ? `/${locale === 'uk' ? '' : locale + '/'}login?redirect=${encodeURIComponent(redirectTo)}`
     : `/${locale === 'uk' ? '' : locale + '/'}login`
 
-  // Step 3: Creating account (loading screen)
   if (step === 'creating') {
     return (
       <div className="mx-auto w-full max-w-md text-center">
@@ -151,7 +148,6 @@ export const RegisterForm: React.FC<{
     )
   }
 
-  // Step 2: OTP verification
   if (step === 'otp') {
     return (
       <div className="mx-auto w-full max-w-md">
@@ -206,7 +202,6 @@ export const RegisterForm: React.FC<{
     )
   }
 
-  // Step 1: Credentials form
   return (
     <div className="mx-auto w-full max-w-md">
       <h1 className="heading-display mb-2 text-center text-3xl">{t.registerTitle}</h1>
diff --git a/src/components/BeforeDashboard/index.tsx b/src/components/BeforeDashboard/index.tsx
index 4f768d5..99c03b9 100644
--- a/src/components/BeforeDashboard/index.tsx
+++ b/src/components/BeforeDashboard/index.tsx
@@ -5,7 +5,6 @@ import './index.scss'
 
 const baseClass = 'before-dashboard'
 
-/** Quick links into the collections admins touch daily, plus live counts. */
 const quickStats = [
   { slug: 'courses', label: 'Курси' },
   { slug: 'users', label: 'Користувачі' },
diff --git a/src/components/Card/index.tsx b/src/components/Card/index.tsx
index b1d9a1e..6153d87 100644
--- a/src/components/Card/index.tsx
+++ b/src/components/Card/index.tsx
@@ -18,11 +18,9 @@ export type CardRelationTo = 'posts' | 'courses' | 'course-categories' | 'pages'
 export type CardPostData = Pick<Post, 'id' | 'slug' | 'categories' | 'meta' | 'title'> & {
   collectionType?: string | null
   publishedAt?: string | null
-  /** Id of the underlying document (search results only) — used for category deep links. */
   docId?: number | null
 }
 
-// Fallback covers extracted from the approved design prototype.
 const FALLBACK_COVERS = [
   '/illustrations/post-shift-recap.svg',
   '/illustrations/post-enrollment.svg',
diff --git a/src/components/CollectionArchive/index.tsx b/src/components/CollectionArchive/index.tsx
index 84bd677..be19f1a 100644
--- a/src/components/CollectionArchive/index.tsx
+++ b/src/components/CollectionArchive/index.tsx
@@ -9,7 +9,6 @@ export type Props = {
   posts: CardPostData[]
   likesCountMap?: Record<number, number>
   commentsCountMap?: Record<number, number>
-  /** Optional label per collection type, shown as a chip on each card (used on search results). */
   typeLabels?: Partial<Record<CardRelationTo, string>>
 }
 
diff --git a/src/components/CommentsAndLikes/CommentItem.tsx b/src/components/CommentsAndLikes/CommentItem.tsx
index 2d30c75..0ae7d32 100644
--- a/src/components/CommentsAndLikes/CommentItem.tsx
+++ b/src/components/CommentsAndLikes/CommentItem.tsx
@@ -30,7 +30,6 @@ interface CommentItemProps {
   onDelete: (commentId: number) => Promise<boolean>
   depth?: number
   loginUrl?: string
-  /** Locale-aware base path for public profiles, e.g. "/users" or "/en/users". */
   userProfileBase?: string
 }
 
diff --git a/src/components/CommentsAndLikes/CommentsSection.tsx b/src/components/CommentsAndLikes/CommentsSection.tsx
index 3ac8c6f..1eeb3a2 100644
--- a/src/components/CommentsAndLikes/CommentsSection.tsx
+++ b/src/components/CommentsAndLikes/CommentsSection.tsx
@@ -34,11 +34,9 @@ interface CommentsSectionProps {
   isAuthenticated: boolean
   currentUserId: number | null
   isAdmin: boolean
-  /** When false, loading the comment list is deferred (e.g. until scrolled into view). */
   active?: boolean
   labels: Labels
   loginUrl: string
-  /** Locale-aware base path for public profiles, e.g. "/users" or "/en/users". */
   userProfileBase: string
 }
 
diff --git a/src/components/CommentsAndLikes/InteractionClient.tsx b/src/components/CommentsAndLikes/InteractionClient.tsx
index 27ff21b..4a08a82 100644
--- a/src/components/CommentsAndLikes/InteractionClient.tsx
+++ b/src/components/CommentsAndLikes/InteractionClient.tsx
@@ -25,7 +25,6 @@ interface InteractionClientProps {
   targetCollection: 'posts' | 'courses'
   targetId: number
   loginUrl: string
-  /** Locale-aware base path for public profiles, e.g. "/users" or "/en/users". */
   userProfileBase: string
   labels: Labels
 }
@@ -37,8 +36,6 @@ export function InteractionClient({
   userProfileBase,
   labels,
 }: InteractionClientProps) {
-  // Auth state comes from the client session so the embedding page can stay
-  // statically cached for guests and members alike.
   const { data: session } = useSession()
   const user = session?.user
   const isAuthenticated = Boolean(user)
@@ -47,8 +44,6 @@ export function InteractionClient({
     user && 'role' in user && (user as { role?: string[] }).role?.includes('admin'),
   )
 
-  // Comments/likes only load once the section is near the viewport — page
-  // views that never scroll down here don't pay for the data requests.
   const rootRef = useRef<HTMLDivElement>(null)
   const [active, setActive] = useState(false)
   useEffect(() => {
@@ -65,7 +60,6 @@ export function InteractionClient({
   }, [active])
 
   return (
-    // #comments — post-login redirects land here so the user resumes the action in place
     <div id="comments" ref={rootRef} className="scroll-mt-24">
       <div className="flex items-center gap-4 pt-4 pb-4 pl-2">
         <LikeButton
diff --git a/src/components/CommentsAndLikes/InteractionSection.tsx b/src/components/CommentsAndLikes/InteractionSection.tsx
index 5b8dada..188befe 100644
--- a/src/components/CommentsAndLikes/InteractionSection.tsx
+++ b/src/components/CommentsAndLikes/InteractionSection.tsx
@@ -8,15 +8,9 @@ interface InteractionSectionProps {
   targetCollection: 'posts' | 'courses'
   targetId: number
   locale: SiteLocale
-  /** Path of the page hosting this section — guests return here (at #comments) after login. */
   redirectPath?: string
 }
 
-/**
- * Likes + comments block. Deliberately session-free on the server: auth state
- * is derived client-side (useSession) and data loads lazily once the section
- * scrolls into view, so pages embedding it can be statically cached.
- */
 export function InteractionSection({
   targetCollection,
   targetId,
diff --git a/src/components/CommentsAndLikes/LikeButton.tsx b/src/components/CommentsAndLikes/LikeButton.tsx
index 173d18c..93d6a29 100644
--- a/src/components/CommentsAndLikes/LikeButton.tsx
+++ b/src/components/CommentsAndLikes/LikeButton.tsx
@@ -9,12 +9,10 @@ interface LikeButtonProps {
   targetCollection: LikeTargetCollection
   targetId: number
   isAuthenticated: boolean
-  /** When false, the like-state request is deferred (e.g. until scrolled into view). */
   active?: boolean
   initialLiked?: boolean
   initialCount?: number
   size?: 'sm' | 'md'
-  /** Guests are sent here (login with a redirect back) instead of a dead disabled button. */
   loginUrl?: string
   loginPromptLabel?: string
 }
diff --git a/src/components/Courses/CategoryCarousels.tsx b/src/components/Courses/CategoryCarousels.tsx
index 083dab4..ef7415e 100644
--- a/src/components/Courses/CategoryCarousels.tsx
+++ b/src/components/Courses/CategoryCarousels.tsx
@@ -17,12 +17,6 @@ type CategoryGroup = {
   courses: CourseCardData[]
 }
 
-/**
- * A handful of randomly picked course categories, each rendered as a
- * horizontally scrollable strip of course cards linking to the category page.
- * Session-free on purpose so it stays safe inside ISR-cached pages (home);
- * the random pick re-rolls on each render / cache regeneration.
- */
 export async function CategoryCarousels({
   locale,
   count = 3,
diff --git a/src/components/Courses/CategoryFilter.tsx b/src/components/Courses/CategoryFilter.tsx
index 8a80967..002bb63 100644
--- a/src/components/Courses/CategoryFilter.tsx
+++ b/src/components/Courses/CategoryFilter.tsx
@@ -15,7 +15,6 @@ type Props = {
   allLabel: string
 }
 
-/** Chip style for horizontal filter rows (course categories, leaderboard periods). */
 export const filterPill = (active: boolean) =>
   cn(
     'shrink-0 whitespace-nowrap rounded-full border px-3 py-1.5 font-display text-[11px] font-semibold uppercase tracking-[0.06em] transition-colors md:px-4 md:py-2 md:text-xs md:tracking-[0.1em]',
@@ -27,8 +26,6 @@ export const filterPill = (active: boolean) =>
 export const CategoryFilter: React.FC<Props> = ({ categories, selectedCategory, onSelect, allLabel }) => {
   const activeRef = useRef<HTMLButtonElement>(null)
 
-  // When a filtered view is deep-linked, bring the active chip into view
-  // inside the mobile scroll row.
   useEffect(() => {
     activeRef.current?.scrollIntoView({ block: 'nearest', inline: 'center' })
   }, [])
diff --git a/src/components/Courses/CompleteStepButton.tsx b/src/components/Courses/CompleteStepButton.tsx
index bae237c..e19454f 100644
--- a/src/components/Courses/CompleteStepButton.tsx
+++ b/src/components/Courses/CompleteStepButton.tsx
@@ -12,7 +12,6 @@ type Props = {
   stepBlockId: string
   courseId: number
   courseSlug: string
-  /** Ordered block ids of all course steps — used to find the first incomplete step. */
   stepIds: string[]
   completedSteps: string[]
   isLastStep: boolean
@@ -77,8 +76,6 @@ export const CompleteStepButton: React.FC<Props> = ({
         return
       }
 
-      // The quiz only opens once every step is done — otherwise continue with
-      // the first step that still needs finishing.
       const firstIncomplete = isCourseCompleted
         ? -1
         : stepIds.findIndex((id) => !latestCompleted.includes(id))
@@ -88,7 +85,6 @@ export const CompleteStepButton: React.FC<Props> = ({
     })
   }
 
-  // Promise the quiz only when this press actually opens it.
   const label = !isLastStep
     ? nextLabel
     : quizEnabled
diff --git a/src/components/Courses/CompletedByTicker.tsx b/src/components/Courses/CompletedByTicker.tsx
index 94603e4..5e4d27f 100644
--- a/src/components/Courses/CompletedByTicker.tsx
+++ b/src/components/Courses/CompletedByTicker.tsx
@@ -7,13 +7,8 @@ import type { CourseCompletion } from '@/utilities/leaderboard'
 
 const REFRESH_MS = 60_000
 
-/** Constant scroll speed so short and long lists feel the same. */
 const SPEED_PX_PER_S = 35
 
-/**
- * Live «completed by» running line for the course hero. Fetched client-side
- * (and refreshed on an interval) so the page itself stays statically cached.
- */
 export const CompletedByTicker: React.FC<{
   courseId: number
   localePrefix: string
diff --git a/src/components/Courses/CourseCard.tsx b/src/components/Courses/CourseCard.tsx
index 6952073..f20e63e 100644
--- a/src/components/Courses/CourseCard.tsx
+++ b/src/components/Courses/CourseCard.tsx
@@ -33,7 +33,6 @@ type Props = {
   className?: string
 }
 
-// Fallback covers extracted from the approved design prototype.
 const FALLBACK_COVERS = [
   '/illustrations/course-leadership.svg',
   '/illustrations/course-first-aid.svg',
@@ -104,7 +103,6 @@ export const CourseCard: React.FC<Props> = ({
           {description && (
             <p className="line-clamp-2 text-[12.5px] leading-relaxed text-fog">{description}</p>
           )}
-          {/* single line always: lower-priority chips hide as the card narrows */}
           <div className="@container mt-auto flex flex-nowrap items-center gap-3.5 overflow-hidden whitespace-nowrap border-t border-line pt-3 text-[11.5px] font-semibold text-fog">
             <span className="num flex flex-none items-center gap-1.5">
               <Rows3 className="h-3.5 w-3.5 flex-none" />
diff --git a/src/components/Courses/CourseCatalog.tsx b/src/components/Courses/CourseCatalog.tsx
index d5994a0..1ef411c 100644
--- a/src/components/Courses/CourseCatalog.tsx
+++ b/src/components/Courses/CourseCatalog.tsx
@@ -25,8 +25,6 @@ export const CourseCatalog: React.FC<Props> = ({ courses, categories, courseStat
   const router = useRouter()
   const pathname = usePathname()
 
-  // Per-user progress badges load after hydration so the page itself can be
-  // served from the shared ISR cache. Guests never trigger the request.
   const myStatuses = useMyCourseStatuses()
 
   // The active filter lives in ?category= so filtered views can be shared,
diff --git a/src/components/Courses/CourseGrid.tsx b/src/components/Courses/CourseGrid.tsx
index 816fb0a..f7bfef8 100644
--- a/src/components/Courses/CourseGrid.tsx
+++ b/src/components/Courses/CourseGrid.tsx
@@ -12,10 +12,6 @@ type Props = {
   className?: string
 }
 
-/**
- * Plain course-card grid with client-side per-user progress badges, for
- * ISR-cached pages that don't need the catalog's category filter.
- */
 export const CourseGrid: React.FC<Props> = ({ courses, courseStats, locale, className }) => {
   const myStatuses = useMyCourseStatuses()
 
diff --git a/src/components/Courses/CourseUserState.tsx b/src/components/Courses/CourseUserState.tsx
index 017c569..cf0a36b 100644
--- a/src/components/Courses/CourseUserState.tsx
+++ b/src/components/Courses/CourseUserState.tsx
@@ -5,14 +5,7 @@ import { useSession } from '@/lib/auth/client'
 import { getEnrollment } from '@/app/(frontend)/[locale]/courses/actions'
 import type { Enrollment } from '@/payload-types'
 
-/**
- * Per-user course state, fetched once per course page after hydration.
- * Keeping this client-side lets the course overview page render from the
- * shared ISR cache; guests never trigger the enrollment request.
- */
-
 type CourseUserState = {
-  /** true until the session (and enrollment, when logged in) is resolved */
   loading: boolean
   isLoggedIn: boolean
   enrollment: Enrollment | null
diff --git a/src/components/Courses/FileEmbed.tsx b/src/components/Courses/FileEmbed.tsx
index f38e869..8cf29ef 100644
--- a/src/components/Courses/FileEmbed.tsx
+++ b/src/components/Courses/FileEmbed.tsx
@@ -61,7 +61,6 @@ export const FileEmbed: React.FC<Props> = ({
         </div>
       )}
 
-      {/* Download bar */}
       <div className="flex items-center gap-4 flex-wrap sm:flex-nowrap px-1">
         <div className="flex-shrink-0 w-9 h-9 rounded-lg bg-primary/10 flex items-center justify-center">
           {pdf ? (
diff --git a/src/components/Courses/LoginPromptDialog.tsx b/src/components/Courses/LoginPromptDialog.tsx
index 1c46ae2..9fc2310 100644
--- a/src/components/Courses/LoginPromptDialog.tsx
+++ b/src/components/Courses/LoginPromptDialog.tsx
@@ -17,10 +17,6 @@ type Props = {
   }
 }
 
-/**
- * Modal shown to guests who tap a course step: explains that steps require an
- * account and links to /login with a redirect back to the course page.
- */
 export function LoginPromptDialog({ open, onClose, loginHref, labels }: Props) {
   const loginLinkRef = useRef<HTMLAnchorElement>(null)
 
diff --git a/src/components/Courses/QuizAttemptHistory.tsx b/src/components/Courses/QuizAttemptHistory.tsx
index 8b95aae..4dcf4aa 100644
--- a/src/components/Courses/QuizAttemptHistory.tsx
+++ b/src/components/Courses/QuizAttemptHistory.tsx
@@ -19,7 +19,6 @@ type Props = {
   attempts: QuizAttempt[]
   labels: Labels
   locale?: SiteLocale
-  /** When set, passed attempts get a certificate download link. */
   certificateHref?: string
 }
 
diff --git a/src/components/Courses/StepsList.tsx b/src/components/Courses/StepsList.tsx
index 8d7f54b..a79692e 100644
--- a/src/components/Courses/StepsList.tsx
+++ b/src/components/Courses/StepsList.tsx
@@ -31,7 +31,6 @@ type Props = {
   completedSteps: string[]
   activeStepIndex?: number
   linked?: boolean
-  /** When set (and not linked), step rows become buttons — used to prompt guests to log in */
   onStepClick?: (index: number) => void
   completedLabel: string
   stepsLabel: string
diff --git a/src/components/Courses/useMyCourseStatuses.ts b/src/components/Courses/useMyCourseStatuses.ts
index fcaf3d8..2b0d865 100644
--- a/src/components/Courses/useMyCourseStatuses.ts
+++ b/src/components/Courses/useMyCourseStatuses.ts
@@ -6,11 +6,6 @@ import { getMyCourseStatuses, type MyCourseStatuses } from '@/app/(frontend)/[lo
 
 const NO_STATUSES: MyCourseStatuses = { completed: [], inProgress: [] }
 
-/**
- * The signed-in user's completed / in-progress course ids, fetched after
- * hydration so pages rendering course cards can stay in the shared ISR cache.
- * Guests never trigger the request.
- */
 export function useMyCourseStatuses(): MyCourseStatuses {
   const { data: session } = useSession()
   const [statuses, setStatuses] = useState<MyCourseStatuses>(NO_STATUSES)
diff --git a/src/components/Home/CoursesServer.tsx b/src/components/Home/CoursesServer.tsx
index 4309e74..e43d09d 100644
--- a/src/components/Home/CoursesServer.tsx
+++ b/src/components/Home/CoursesServer.tsx
@@ -7,7 +7,6 @@ type Props = {
   locale: SiteLocale
 }
 
-/** Latest three published courses for the home page strip. */
 export async function CoursesGridServer({ locale }: Props) {
   const payload = await getPayload({ config: configPromise })
   const { docs } = await payload.find({
diff --git a/src/components/Home/FadeIn.tsx b/src/components/Home/FadeIn.tsx
index 6d29e43..2d842f9 100644
--- a/src/components/Home/FadeIn.tsx
+++ b/src/components/Home/FadeIn.tsx
@@ -10,11 +10,8 @@ type Props = {
   style?: CSSProperties
 }
 
-/**
- * Progressive-enhancement reveal: content is visible by default (SSR, no-JS,
- * reduced-motion). Only elements mounted below the fold are hidden and then
- * faded in when scrolled into view.
- */
+// Content stays visible by default (SSR, no-JS, reduced-motion); only elements mounted
+// below the fold are hidden and then faded in.
 export function FadeIn({ children, className, delay = 0, style }: Props) {
   const ref = useRef<HTMLDivElement>(null)
 
@@ -24,7 +21,6 @@ export function FadeIn({ children, className, delay = 0, style }: Props) {
 
     if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return
 
-    // Already on screen — leave it visible, no entrance animation.
     if (el.getBoundingClientRect().top < window.innerHeight) return
 
     el.classList.add('fade-pending')
diff --git a/src/components/Home/Hero.tsx b/src/components/Home/Hero.tsx
index e49be40..96c1b2a 100644
--- a/src/components/Home/Hero.tsx
+++ b/src/components/Home/Hero.tsx
@@ -34,7 +34,6 @@ export function HeroSection({
 
   return (
     <section className="relative overflow-hidden pb-24 pt-20 md:pb-28 md:pt-24">
-      {/* brand-blue glow + orange ember */}
       <div
         className="absolute inset-0"
         style={{
@@ -43,7 +42,6 @@ export function HeroSection({
         }}
         aria-hidden="true"
       />
-      {/* landing echo: orange diagonal sliver on the right edge */}
       <div
         className="pointer-events-none absolute inset-y-0 right-0 hidden w-[38%] md:block"
         style={{
@@ -103,7 +101,6 @@ export function HeroSection({
           </FadeIn>
         </div>
 
-        {/* stats scoreboard */}
         <div className="grid gap-3.5">
           {stats.map((stat, i) => (
             <FadeIn key={stat.label} delay={300 + i * 120}>
diff --git a/src/components/Home/News.tsx b/src/components/Home/News.tsx
index 553ede8..02ff2b4 100644
--- a/src/components/Home/News.tsx
+++ b/src/components/Home/News.tsx
@@ -28,7 +28,6 @@ type Props = {
   locale: string
 }
 
-// Fallback covers extracted from the approved design prototype.
 export const POST_FALLBACK_COVERS = [
   '/illustrations/post-shift-recap.svg',
   '/illustrations/post-enrollment.svg',
diff --git a/src/components/Home/Stats.tsx b/src/components/Home/Stats.tsx
index d49b940..00eb47b 100644
--- a/src/components/Home/Stats.tsx
+++ b/src/components/Home/Stats.tsx
@@ -7,11 +7,6 @@ import { useRef, useEffect, useState } from 'react'
 const formatNumber = (n: number): string =>
   n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ' ')
 
-/**
- * Count-up number. The real value is server-rendered so it is always correct
- * even without JS; the 0→value count-up runs only as a client enhancement
- * when the number scrolls into view.
- */
 export function StatCounter({ value, suffix }: { value: number; suffix?: string }) {
   const ref = useRef<HTMLSpanElement>(null)
   const [display, setDisplay] = useState(() => formatNumber(value))
diff --git a/src/components/Home/content.ts b/src/components/Home/content.ts
index e9e95b6..6b5380b 100644
--- a/src/components/Home/content.ts
+++ b/src/components/Home/content.ts
@@ -326,9 +326,6 @@ export const getHomeContent = (locale: SiteLocale) => content[locale]
 
 export type CalendarContent = HomeContent['calendar']
 
-// Overlays the `home-calendar` Payload global on the hardcoded content above:
-// per-field fallback for the section texts, and the hardcoded schedule when the
-// global has no events yet (never saved / cleared).
 export const resolveCalendarContent = (
   locale: SiteLocale,
   global: HomeCalendar | null | undefined,
diff --git a/src/components/Home/index.tsx b/src/components/Home/index.tsx
index 4dfea36..9b7d1c8 100644
--- a/src/components/Home/index.tsx
+++ b/src/components/Home/index.tsx
@@ -28,7 +28,6 @@ export function HomePage({ locale, calendar, newsSlot, coursesSlot }: Props) {
       </CoursesSection>
       <AboutSection {...c.about} />
 
-      {/* warm diagonal band: news + shifts calendar */}
       <div id="news" className="band on-paper mt-14 scroll-mt-24">
         <div className="container">
           {newsSlot}
diff --git a/src/components/Link/index.tsx b/src/components/Link/index.tsx
index 1447d55..44cd6fc 100644
--- a/src/components/Link/index.tsx
+++ b/src/components/Link/index.tsx
@@ -23,13 +23,9 @@ type CMSLinkType = {
   url?: string | null
 }
 
-/**
- * CMS-managed links store locale-less internal paths (/posts, /page-slug), so
- * keep the viewer's locale by prefixing internal hrefs with /en on /en pages.
- * External URLs, anchors and already-prefixed hrefs pass through untouched.
- * (During prerender the default locale renders under the internal /uk/* path,
- * which is not `/en`, so those pages correctly get unprefixed hrefs.)
- */
+// CMS links store locale-less internal paths (/posts, /page-slug), so prefix them with
+// /en on /en pages. During prerender the default locale renders under the internal /uk/*
+// path, which is not `/en`, so those pages correctly get unprefixed hrefs.
 const localizeHref = (href: string, pathname: string): string => {
   const isEnglish = pathname === '/en' || pathname.startsWith('/en/')
   if (!isEnglish) return href
@@ -67,7 +63,6 @@ export const CMSLink: React.FC<CMSLinkType> = (props) => {
   const size = appearance === 'link' ? 'clear' : sizeFromProps
   const newTabProps = newTab ? { rel: 'noopener noreferrer', target: '_blank' } : {}
 
-  /* Ensure we don't break any styles set by richText */
   if (appearance === 'inline') {
     return (
       <Link className={cn(className)} href={href} {...newTabProps}>
diff --git a/src/components/Logo/Brand.tsx b/src/components/Logo/Brand.tsx
index d4304a3..c154282 100644
--- a/src/components/Logo/Brand.tsx
+++ b/src/components/Logo/Brand.tsx
@@ -6,10 +6,6 @@ import { Logo } from './Logo'
 import { getFrontendMessages } from '@/utilities/i18n'
 import { cn } from '@/utilities/ui'
 
-/**
- * Brand lockup: official emblem + two-tone display wordmark with the
- * "Платформа" sub-label. Used in the header and footer.
- */
 export const Brand: React.FC<{
   locale: SiteLocale
   size?: 'md' | 'lg'
diff --git a/src/components/Logo/Logo.tsx b/src/components/Logo/Logo.tsx
index 1cb7050..a3d3001 100644
--- a/src/components/Logo/Logo.tsx
+++ b/src/components/Logo/Logo.tsx
@@ -8,7 +8,6 @@ interface Props {
   priority?: 'auto' | 'high' | 'low'
 }
 
-/** Official Iron Squad emblem (circular badge). Roughly square — size via height. */
 export const Logo = (props: Props) => {
   const { alt, className, loading = 'eager', priority = 'high' } = props
 
diff --git a/src/components/Media/ImageMedia/index.tsx b/src/components/Media/ImageMedia/index.tsx
index e13e31a..59bdafb 100644
--- a/src/components/Media/ImageMedia/index.tsx
+++ b/src/components/Media/ImageMedia/index.tsx
@@ -13,38 +13,9 @@ import { getMediaUrl } from '@/utilities/getMediaUrl'
 
 const { breakpoints } = cssVariables
 
-// A base64 encoded image to use as a placeholder while the image is loading
 const placeholderBlur =
   'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAAXNSR0IArs4c6QAABchJREFUWEdtlwtTG0kMhHtGM7N+AAdcDsjj///EBLzenbtuadbLJaZUTlHB+tRqSesETB3IABqQG1KbUFqDlQorBSmboqeEBcC1d8zrCixXYGZcgMsFmH8B+AngHdurAmXKOE8nHOoBrU6opcGswPi5KSP9CcBaQ9kACJH/ALAA1xm4zMD8AczvQCcAQeJVAZsy7nYApTSUzwCHUKACeUJi9TsFci7AHmDtuHYqQIC9AgQYKnSwNAig4NyOOwXq/xU47gDYggarjIpsRSEA3Fqw7AGkwgW4fgALAdiC2btKgNZwbgdMbEFpqFR2UyCR8xwAhf8bUHIGk1ckMyB5C1YkeWAdAPQBAeiD6wVYPoD1HUgXwFagZAGc6oSpTmilopoD5GzISQD3odcNIFca0BUQQM5YA2DpHV0AYURBDIAL0C+ugC0C4GedSsVUmwC8/4w8TPiwU6AClJ5RWL1PgQNkrABWdKB3YF3cBwRY5lsI4ApkKpCQi+FIgFJU/TDgDuAxAAwonJuKpGD1rkCXCR1ALyrAUSSEQAhwBdYZ6DPAgSUA2c1wKIZmRcHxMzMYR9DH8NlbkAwwApSAcABwBwTAbb6owAr0AFiZPILVEyCtMmK2jCkTwFDNUNj7nJETQx744gCUmgkZVGJUHyakEZE4W91jtGFA9KsD8Z3JFYDlhGYZLWcllwJMnplcPy+csFAgAAaIDOgeuAGoB96GLZg4kmtfMjnr6ig5oSoySsoy3ya/FMivXZWxwr0KIf9nACbfqcBEgmBSAtAlIT83R+70IWpyACamIjf5E1Iqb9ECVmnoI/FvAIRk8s2J0Y5IquQDgB+5wpScw5AUTC75VTmTs+72NUzoCvQIaAXv5Q8PDAZKLD+MxLv3RFE7KlsQChgBIlKiCv5ByaZv3gJZNm8AnVMhAN+EjrtTYQMICJpu6/0aiQnhClANlz+Bw0cIWa8ev0sBrtrhAyaXEnrfGfATQJiRKih5vKeOHNXXPFrgyamAADh0Q4F2/sESojomDS9o9k0b0H83xjB8qL+JNoTjN+enjpaBpingRh4e8MSugudM030A8FeqMI6PFIgNyPehkpZWGFEAARIQdH5LcAAqIACHkAJqg4OoBccHAuz76wr4BbzFOEa8iBuAZB8AtJHLP2VgMgJw/EIBowo7HxCAH3V6dAXEE/vZ5aZIA8BP8RKhm7Cp8BnAMnAQADdgQDA520AVIpScP+enHz0Gwp25h4i2dPg5FkDXrbsdJikQwXuWgaM5gEMk1AgH4DKKFjDf3bMD+FjEeIxLlRKYnBk2BbquvSDCAQ4gwZiMAAmH4gBTyRtEsYxi7gP6QSrc//39BrDNqG8rtYTmC4BV1SfMhOhaumFCT87zy4pPhQBZEK1kQVRjJBBi7AOlePgyAPYjwlvtagx9e/dnQraAyS894TIkkAIEYMKEc8k4EqJ68lZ5jjNqcQC2QteQOf7659umwBgPybNtK4dg9WvnMyFwXYGP7uEO1lwJgAnPNeMYMVXbIIYKFioI4PGFt+BWPVfmWJdjW2lTUnLGCswECAgaUy86iwA1464ajo0QhgMBFGyBoZahANsMpMfXr1JA1SN29m5lqgXj+UPV85uRA7yv/KYUO4Tk7Hc1AZwbIRzg0AyNj2UlAMwfSLSMnl7fdAbcxHuA27YaAMvaQ4GOjwX4RTUGAG8Ge14N963g1AynqUiFqRX9noasxT4b8entNRQYyamk/3tYcHsO7R3XJRRYOn4tw4iUnwBM5gDnySGOreAwAGo8F9IDHEcq8Pz2Kg/oXCpuIL6tOPD8LsDn0ABYQoGFRowlsAEUPPDrGAGowAbgKsgDMmE8mDy/vXQ9IAwI7u4wta+gAdAdgB64Ah9SgD4IgGKhwACoAjgNgFDhtxY8f33ZTMjqdTAiHMBPrn8ZWkEfzFdX4Oc1AHg3+ADbvN8PU8WdFKg4Tt6CQy2+D4YHaMT/JP4XzbAq98cPDIUAAAAASUVORK5CYII='
 
-/**
- * ImageMedia
- *
- * This component passes a **relative** `src` (e.g. `/media/...`) to Next.js Image.
- * The `getMediaUrl` utility constructs the full URL by prepending the base URL from env vars
- * (NEXT_PUBLIC_SERVER_URL). Next.js then optimizes this using `remotePatterns` configured
- * in next.config.js — no custom `loader` needed.
- *
- * Flow:
- *   1. Resource URL from Payload: `/media/image-123.jpg`
- *   2. getMediaUrl() adds base URL: `https://yourdomain.com/media/image-123.jpg`
- *   3. Next.js Image optimizes via remotePatterns: `/_next/image?url=...&w=1200&q=75`
- *
- * If your storage/plugin returns **external CDN URLs** (e.g. `https://cdn.example.com/...`),
- * choose ONE of the following:
- *   A) Allow the remote host in next.config.js:
- *      images: { remotePatterns: [{ protocol: 'https', hostname: 'cdn.example.com' }] }
- *   B) Provide a **custom loader** for CDN-specific transforms:
- *      const imageLoader: ImageLoader = ({ src, width, quality }) =>
- *        `https://cdn.example.com${src}?w=${width}&q=${quality ?? 75}`
- *      <Image loader={imageLoader} src="/media/hero.jpg" width={1200} height={600} alt="" />
- *   C) Skip optimization:
- *      <Image unoptimized src="https://cdn.example.com/hero.jpg" width={1200} height={600} alt="" />
- *
- * TL;DR: Template uses relative URLs + getMediaUrl() to construct full URLs, then relies on
- * remotePatterns for optimization. Only add `loader` if using external CDNs with custom transforms.
- */
-
 export const ImageMedia: React.FC<MediaProps> = (props) => {
   const {
     alt: altFromProps,
@@ -77,7 +48,6 @@ export const ImageMedia: React.FC<MediaProps> = (props) => {
 
   const loading = loadingFromProps || (!priority ? 'lazy' : undefined)
 
-  // NOTE: this is used by the browser to determine which image to download at different screen sizes.
   // Match the viewport width — next/image already accounts for devicePixelRatio,
   // so doubling here would double every transformation and payload.
   const sizes = sizeFromProps
diff --git a/src/components/Media/VideoMedia/index.tsx b/src/components/Media/VideoMedia/index.tsx
index ccff66e..21b00fe 100644
--- a/src/components/Media/VideoMedia/index.tsx
+++ b/src/components/Media/VideoMedia/index.tsx
@@ -1,7 +1,7 @@
 'use client'
 
 import { cn } from '@/utilities/ui'
-import React, { useEffect, useRef } from 'react'
+import React, { useRef } from 'react'
 
 import type { Props as MediaProps } from '../types'
 
@@ -11,17 +11,6 @@ export const VideoMedia: React.FC<MediaProps> = (props) => {
   const { onClick, resource, videoClassName } = props
 
   const videoRef = useRef<HTMLVideoElement>(null)
-  // const [showFallback] = useState<boolean>()
-
-  useEffect(() => {
-    const { current: video } = videoRef
-    if (video) {
-      video.addEventListener('suspend', () => {
-        // setShowFallback(true);
-        // console.warn('Video was suspended, rendering fallback image.')
-      })
-    }
-  }, [])
 
   if (resource && typeof resource === 'object') {
     const { filename } = resource
diff --git a/src/components/Media/types.ts b/src/components/Media/types.ts
index 3bbbf22..5807967 100644
--- a/src/components/Media/types.ts
+++ b/src/components/Media/types.ts
@@ -6,17 +6,17 @@ import type { Media as MediaType } from '@/payload-types'
 export interface Props {
   alt?: string
   className?: string
-  fill?: boolean // for NextImage only
+  fill?: boolean
   htmlElement?: ElementType | null
   pictureClassName?: string
   imgClassName?: string
   onClick?: () => void
   onLoad?: () => void
-  loading?: 'lazy' | 'eager' // for NextImage only
-  priority?: boolean // for NextImage only
+  loading?: 'lazy' | 'eager'
+  priority?: boolean
   ref?: Ref<HTMLImageElement | HTMLVideoElement | null>
-  resource?: MediaType | string | number | null // for Payload media
-  size?: string // for NextImage only
-  src?: StaticImageData // for static media
+  resource?: MediaType | string | number | null
+  size?: string
+  src?: StaticImageData
   videoClassName?: string
 }
diff --git a/src/components/PayloadRedirects/index.tsx b/src/components/PayloadRedirects/index.tsx
index d239771..dbd286c 100644
--- a/src/components/PayloadRedirects/index.tsx
+++ b/src/components/PayloadRedirects/index.tsx
@@ -10,7 +10,6 @@ interface Props {
   url: string
 }
 
-/* This component helps us with SSR based dynamic redirects */
 export const PayloadRedirects: React.FC<Props> = async ({ disableNotFound, url }) => {
   const redirects = await getCachedRedirects()()
 
diff --git a/src/components/Profile/ProfileLatestComments.tsx b/src/components/Profile/ProfileLatestComments.tsx
index 056d81d..e83491a 100644
--- a/src/components/Profile/ProfileLatestComments.tsx
+++ b/src/components/Profile/ProfileLatestComments.tsx
@@ -8,8 +8,6 @@ import { defaultLocale, type SiteLocale } from '@/utilities/locales'
 import { formatDateTime } from '@/utilities/formatDateTime'
 import { plural } from '@/utilities/plural'
 
-// One window of recent comments is enough for the profile teaser; per-page
-// "and N more" counts are computed within it rather than with extra queries.
 const COMMENTS_WINDOW = 30
 const MAX_PAGES = 5
 
@@ -18,9 +16,6 @@ type Props = {
   locale: SiteLocale
 }
 
-// Streams in behind <Suspense> on the public profile page: everything runs in
-// the same serverless invocation (no extra API routes / function calls), and
-// every query selects only the columns the UI renders.
 export async function ProfileLatestComments({ userId, locale }: Props) {
   const payload = await getPayload()
   const t = getFrontendMessages(locale)
@@ -125,7 +120,6 @@ export async function ProfileLatestComments({ userId, locale }: Props) {
     })
   }
 
-  // Drop comments whose target was deleted or unpublished.
   const items = topGroups.flatMap((group) => {
     const target = targets.get(`${group.latest.targetCollection}:${group.latest.targetId}`)
     return target ? [{ group, target }] : []
diff --git a/src/components/RichText/WithArchive.tsx b/src/components/RichText/WithArchive.tsx
index 1bfc284..71e873a 100644
--- a/src/components/RichText/WithArchive.tsx
+++ b/src/components/RichText/WithArchive.tsx
@@ -12,13 +12,8 @@ type Props = {
   locale?: SiteLocale
 } & Omit<React.ComponentProps<typeof RichText>, 'converters'>
 
-/**
- * Server-only variant of RichText that can also render the Archive block
- * (card grids of posts / courses / course categories) embedded in post
- * content. Kept out of the shared RichText component because the Archive
- * renderer pulls in the Payload Local API, which must never end up in a
- * client bundle (RichText is imported by client components).
- */
+// Server-only: the Archive renderer pulls in the Payload Local API, which must never end
+// up in a client bundle, so it stays out of the shared RichText component.
 export default function RichTextWithArchive({ locale, ...rest }: Props) {
   const converters: JSXConvertersFunction<
     NodeTypes | SerializedBlockNode<ArchiveBlockProps>
diff --git a/src/components/RichText/index.tsx b/src/components/RichText/index.tsx
index 85c3e4b..83d44e4 100644
--- a/src/components/RichText/index.tsx
+++ b/src/components/RichText/index.tsx
@@ -59,7 +59,6 @@ type Props = {
   data: DefaultTypedEditorState
   enableGutter?: boolean
   enableProse?: boolean
-  /** Override the JSX converters, e.g. to add server-only block renderers. */
   converters?: JSXConvertersFunction<NodeTypes>
 } & React.HTMLAttributes<HTMLDivElement>
 
diff --git a/src/components/ShareButtons.tsx b/src/components/ShareButtons.tsx
index 9684e06..6662762 100644
--- a/src/components/ShareButtons.tsx
+++ b/src/components/ShareButtons.tsx
@@ -57,7 +57,6 @@ const networks = (
   },
 ]
 
-/** Share row for articles: social intents + copy link (+ native share when available). */
 export const ShareButtons: React.FC<Props> = ({ url, title, label, copyLabel, copiedLabel }) => {
   const [copied, setCopied] = useState(false)
   const [canNativeShare, setCanNativeShare] = useState(false)
diff --git a/src/components/UserMenu/index.tsx b/src/components/UserMenu/index.tsx
index 268cdbb..818bc7f 100644
--- a/src/components/UserMenu/index.tsx
+++ b/src/components/UserMenu/index.tsx
@@ -71,7 +71,6 @@ export const UserMenu: React.FC<UserMenuProps> = ({ locale, open: controlledOpen
   const isEn = locale === 'en'
   const profilePath = isEn ? '/en/profile' : '/profile'
   const pathname = usePathname()
-  // send the visitor back to where they were after signing in
   const loginPath = `${isEn ? '/en' : ''}/login?redirect=${encodeURIComponent(pathname)}`
 
   useEffect(() => {
@@ -119,7 +118,6 @@ export const UserMenu: React.FC<UserMenuProps> = ({ locale, open: controlledOpen
         onClick={() => setOpen((v) => !v)}
         className="flex h-9 w-9 flex-none rounded-full p-[2.5px] transition-shadow hover:shadow-[0_0_16px_rgb(249_140_31/0.35)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         style={{
-          // ring mirrors real progress to the next level (same math as /profile)
           background: `conic-gradient(from -90deg, var(--orange) 0 ${
             xp ? Math.round((xp.intoLevel / xp.span) * 100) : 0
           }%, var(--blue-line) 0 100%)`,
@@ -189,10 +187,6 @@ export const UserMenu: React.FC<UserMenuProps> = ({ locale, open: controlledOpen
 const mobileRowClass =
   'flex w-full items-center gap-2.5 rounded-lg px-4 py-3 text-sm font-medium text-fog no-underline transition-colors hover:bg-navy hover:text-cloud hover:no-underline'
 
-/**
- * Inline user section for the mobile hamburger panel — same functionality as
- * the avatar dropdown (profile, settings, sign out / sign in).
- */
 export const UserMenuMobileSection: React.FC<{
   locale: SiteLocale
   onNavigate?: () => void
diff --git a/src/components/YouTubeEmbed.tsx b/src/components/YouTubeEmbed.tsx
index 5da5d89..6444b0f 100644
--- a/src/components/YouTubeEmbed.tsx
+++ b/src/components/YouTubeEmbed.tsx
@@ -22,10 +22,6 @@ function extractYouTubeId(url: string): string | null {
   return null
 }
 
-/**
- * Click-to-load facade: renders only the YouTube thumbnail until the user
- * presses play, so pages don't pay the full YT iframe cost up front.
- */
 export const YouTubeEmbed: React.FC<Props> = ({ url, title = 'YouTube video' }) => {
   const [activated, setActivated] = useState(false)
   const videoId = extractYouTubeId(url)
diff --git a/src/components/admin/InviteUserButton/index.tsx b/src/components/admin/InviteUserButton/index.tsx
index efae723..907e1dc 100644
--- a/src/components/admin/InviteUserButton/index.tsx
+++ b/src/components/admin/InviteUserButton/index.tsx
@@ -24,10 +24,6 @@ const roleLabels: Record<string, string> = {
 
 type SelectOption = { label: string; value: string }
 
-/**
- * Ukrainian replacement for payload-auth's hardcoded-English AdminInviteButton.
- * Reuses the plugin's server endpoints; only the UI strings differ.
- */
 export function InviteUserButton({ roles }: { roles: OptionObject[] }) {
   const [role, setRole] = useState<SelectOption | undefined>(undefined)
   const [email, setEmail] = useState('')
@@ -43,7 +39,6 @@ export function InviteUserButton({ roles }: { roles: OptionObject[] }) {
     },
   } = useConfig()
 
-  // Only render the invite button in the users list view.
   const pathname = usePathname()
   if (pathname !== `${adminRoute}/collections/${userSlug}`) return null
 
diff --git a/src/components/admin/graphics/Icon.tsx b/src/components/admin/graphics/Icon.tsx
index 7557067..d7744d1 100644
--- a/src/components/admin/graphics/Icon.tsx
+++ b/src/components/admin/graphics/Icon.tsx
@@ -1,6 +1,5 @@
 import React from 'react'
 
-/** Iron Squad emblem used as the small admin nav icon (replaces the Payload mark). */
 const Icon: React.FC = () => {
   return <img alt="Залізна Зміна" src="/logo-iron-squad.svg" style={{ height: 26, width: 'auto' }} />
 }
diff --git a/src/components/admin/graphics/Logo.tsx b/src/components/admin/graphics/Logo.tsx
index f9d26b4..84e3596 100644
--- a/src/components/admin/graphics/Logo.tsx
+++ b/src/components/admin/graphics/Logo.tsx
@@ -1,10 +1,7 @@
 import React from 'react'
 
-/**
- * Iron Squad brand lockup for the admin panel (login screen and loading views).
- * Inline styles only — admin pages don't load the frontend Tailwind bundle,
- * and `--theme-text` keeps the wordmark legible in both admin themes.
- */
+// Inline styles only — admin pages don't load the frontend Tailwind bundle, and
+// `--theme-text` keeps the wordmark legible in both admin themes.
 const Logo: React.FC = () => {
   return (
     <div
diff --git a/src/components/brand/index.tsx b/src/components/brand/index.tsx
index 0f9c571..1a6574a 100644
--- a/src/components/brand/index.tsx
+++ b/src/components/brand/index.tsx
@@ -2,27 +2,23 @@ import React from 'react'
 import { Zap } from 'lucide-react'
 import { cn } from '@/utilities/ui'
 
-/** Railway-track motif shown under section headings. */
 export const Rails: React.FC<{ className?: string }> = ({ className }) => (
   <div className={cn('rails', className)} aria-hidden="true">
     <i />
   </div>
 )
 
-/** Orange overline label above a section heading. */
 export const Eyebrow: React.FC<{ children: React.ReactNode; className?: string }> = ({
   children,
   className,
 }) => <span className={cn('eyebrow', className)}>{children}</span>
 
-/** Scoreboard XP chip: ⚡ +NNN XP */
 export const XpChip: React.FC<{ xp: number; className?: string }> = ({ xp, className }) => (
   <span className={cn('xp-chip num', className)}>
     <Zap fill="currentColor" strokeWidth={0} aria-hidden="true" />+{xp} XP
   </span>
 )
 
-/** Reward pill shown on course/quiz heroes: ⚡ label · +NNN XP */
 export const RewardPill: React.FC<{ children: React.ReactNode; className?: string }> = ({
   children,
   className,
@@ -33,9 +29,6 @@ export const RewardPill: React.FC<{ children: React.ReactNode; className?: strin
   </span>
 )
 
-/**
- * Standard page header: eyebrow + big display h1 + rails + optional sub line.
- */
 export const PageHead: React.FC<{
   eyebrow?: React.ReactNode
   title: React.ReactNode
@@ -54,10 +47,6 @@ export const PageHead: React.FC<{
   </div>
 )
 
-/**
- * Standard section header: eyebrow + display heading + rails, with an
- * optional action slot on the right.
- */
 export const SectionHead: React.FC<{
   eyebrow?: React.ReactNode
   title: React.ReactNode
diff --git a/src/endpoints/seed/home-static.ts b/src/endpoints/seed/home-static.ts
index 114dfca..5b14757 100644
--- a/src/endpoints/seed/home-static.ts
+++ b/src/endpoints/seed/home-static.ts
@@ -1,6 +1,5 @@
 import type { RequiredDataFromCollectionSlug } from 'payload'
 
-// Used for pre-seeded content so that the homepage is not empty
 export const homeStatic: RequiredDataFromCollectionSlug<'pages'> = {
   slug: 'home',
   _status: 'published',
diff --git a/src/environment.d.ts b/src/environment.d.ts
index ef50f4f..61010b9 100644
--- a/src/environment.d.ts
+++ b/src/environment.d.ts
@@ -10,6 +10,4 @@ declare global {
   }
 }
 
-// If this file has no import/export statements (i.e. is a script)
-// convert it into a module by adding an empty export statement.
 export {}
diff --git a/src/hooks/rateLimitCreate.ts b/src/hooks/rateLimitCreate.ts
index 317a4bd..bc4aff7 100644
--- a/src/hooks/rateLimitCreate.ts
+++ b/src/hooks/rateLimitCreate.ts
@@ -2,14 +2,9 @@ import { APIError, type CollectionBeforeValidateHook } from 'payload'
 
 import { checkRateLimit } from '@/lib/rate-limit'
 
-/**
- * Per-user create throttle for user-generated content. Lives on the collection
- * so both write paths — REST API (req.user) and server actions (Local API,
- * user id passed in data) — go through one choke point.
- *
- * Admin-panel operations are exempt; system writes without a user id in either
- * place (seeds, hooks) pass through untouched.
- */
+// Lives on the collection so both write paths — REST (req.user) and server actions
+// (Local API, user id in data) — go through one choke point. Admin operations and system
+// writes without a user id (seeds, hooks) pass through.
 export const rateLimitCreate = ({
   prefix,
   userField = 'user',
diff --git a/src/hooks/revalidateCourse.ts b/src/hooks/revalidateCourse.ts
index 8e65b69..b5655da 100644
--- a/src/hooks/revalidateCourse.ts
+++ b/src/hooks/revalidateCourse.ts
@@ -6,14 +6,9 @@ import type { Course } from '@/payload-types'
 
 const LOCALE_PREFIXES = ['', '/en']
 
-/**
- * Every ISR-cached surface a course appears on. Its own page plus the lists that
- * embed it — all on a 300s window, so without this an edit sits invisible for
- * up to five minutes. Step and quiz pages render per request and need no bust.
- *
- * Scheduled publishes run outside a request, where revalidatePath throws; a
- * missed bust just falls back to the time window, so it must not fail the save.
- */
+// Busts every ISR-cached surface a course appears on (step and quiz pages render per
+// request and need none). Scheduled publishes run outside a request, where
+// revalidatePath throws; a missed bust falls back to the time window, so never fail the save.
 function revalidateCoursePaths(payload: Payload, slug: string) {
   try {
     for (const prefix of LOCALE_PREFIXES) {
diff --git a/src/hooks/syncCourseCompletions.ts b/src/hooks/syncCourseCompletions.ts
index 15769a7..9de0827 100644
--- a/src/hooks/syncCourseCompletions.ts
+++ b/src/hooks/syncCourseCompletions.ts
@@ -6,12 +6,9 @@ import { getStepIds, isCourseComplete } from '@/utilities/courseCompletion'
 const completionSignature = (course: Course) =>
   `${course.quiz?.enabled === true}|${getStepIds(course).join(',')}`
 
-/**
- * Dropping the quiz or a step lowers the bar for finishing a course, which would
- * otherwise strand enrollments that already meet the new requirements at
- * `in_progress`. Promote those; never demote, so certificates already earned
- * survive a later edit.
- */
+// Dropping the quiz or a step lowers the bar for finishing a course, so promote
+// enrollments that now qualify. Never demote — certificates already earned survive a
+// later edit.
 export const syncCourseCompletions: CollectionAfterChangeHook<Course> = async ({
   doc,
   previousDoc,
diff --git a/src/lib/auth/dev-credentials.ts b/src/lib/auth/dev-credentials.ts
index bcbc8aa..58f2f46 100644
--- a/src/lib/auth/dev-credentials.ts
+++ b/src/lib/auth/dev-credentials.ts
@@ -1,10 +1,5 @@
-/**
- * Fixed credentials for the seeded dev-admin account (dev/test databases only).
- *
- * Shared between `scripts/seed-dev-admin.ts` (creates the account) and
- * `GET /api/dev-login` (signs in with it) so the two can never drift apart.
- * Both entry points are disabled in production. See docs/dev-admin-login.md.
- */
+// Dev/test databases only — shared by the seed script and /api/dev-login so the two can
+// never drift apart. Both entry points are disabled in production.
 export const DEV_ADMIN = {
   email: 'dev-admin@example.com',
   password: 'dev-admin-password',
diff --git a/src/lib/auth/options.ts b/src/lib/auth/options.ts
index 25eacc3..cfb09cc 100644
--- a/src/lib/auth/options.ts
+++ b/src/lib/auth/options.ts
@@ -73,7 +73,6 @@ export const betterAuthOptions = {
     // (hidden, admin-only); the same table backs src/lib/rate-limit.ts.
     storage: 'database',
     customRules: {
-      // Credential brute force / signup flooding (per IP).
       '/sign-in/email': { window: 60, max: 10 },
       '/sign-up/email': { window: 60, max: 5 },
       // Every OTP request sends a Resend email — strictest limits.
diff --git a/src/lib/auth/pre-verified.ts b/src/lib/auth/pre-verified.ts
index 7764e75..e1c2c37 100644
--- a/src/lib/auth/pre-verified.ts
+++ b/src/lib/auth/pre-verified.ts
@@ -1,6 +1,5 @@
-/** In-memory store of emails that passed OTP verification during registration.
- *  Uses globalThis to survive HMR reloads in dev mode.
- *  Set by the verify-registration API route, checked by databaseHooks in auth options. */
+// Emails that passed OTP verification during registration. On globalThis so it survives
+// HMR reloads in dev.
 const globalStore = globalThis as unknown as {
   __preVerifiedEmails?: Map<string, number>
 }
diff --git a/src/lib/auth/seed-dev-admin.ts b/src/lib/auth/seed-dev-admin.ts
index 09cf5f7..4afd314 100644
--- a/src/lib/auth/seed-dev-admin.ts
+++ b/src/lib/auth/seed-dev-admin.ts
@@ -4,12 +4,8 @@ import type { ConstructedBetterAuthPluginOptions } from './options'
 import { markPreVerified } from './pre-verified'
 import { DEV_ADMIN } from './dev-credentials'
 
-/**
- * Core of the dev-admin seed, shared by `scripts/seed-dev-admin.ts` (explicit
- * reset via `pnpm seed:dev-admin`) and `GET /api/dev-login` (lazy auto-seed
- * when the account is missing). Dev/test databases only — both callers are
- * disabled in production. See docs/dev-admin-login.md.
- */
+// Dev/test databases only — shared by `pnpm seed:dev-admin` and /api/dev-login's lazy
+// auto-seed. Both callers are disabled in production. See docs/dev-admin-login.md.
 export type PayloadAuth = Awaited<
   ReturnType<typeof getPayloadAuth<ConstructedBetterAuthPluginOptions>>
 >
@@ -57,7 +53,6 @@ async function findAdmin(payload: PayloadAuth): Promise<User | undefined> {
   return docs[0]
 }
 
-/** Remove every document the dev admin owns so reruns start from a clean slate. */
 async function resetAdminActivity(payload: PayloadAuth, userId: number): Promise<void> {
   await payload.delete({ collection: 'enrollments', where: { user: { equals: userId } } })
   await payload.delete({ collection: 'quiz-attempts', where: { user: { equals: userId } } })
@@ -163,7 +158,6 @@ async function createDemoCourse(payload: PayloadAuth, index: number): Promise<Co
   })) as Course
 }
 
-/** Published courses with steps, oldest first; demo courses fill any shortfall. */
 async function ensureCourses(payload: PayloadAuth): Promise<Course[]> {
   const { docs } = await payload.find({
     collection: 'courses',
@@ -298,10 +292,6 @@ async function seedComments(
   return created
 }
 
-/**
- * Full seed: ensure the account with fixed credentials, reset its activity,
- * recreate enrollments (one completed, one in progress), quiz attempt, comments.
- */
 export async function seedDevAdmin(payload: PayloadAuth): Promise<SeedDevAdminSummary> {
   const admin = await ensureAdminUser(payload)
   const courses = await ensureCourses(payload)
diff --git a/src/lib/courses/getCatalogData.ts b/src/lib/courses/getCatalogData.ts
index 090b038..3180028 100644
--- a/src/lib/courses/getCatalogData.ts
+++ b/src/lib/courses/getCatalogData.ts
@@ -12,13 +12,8 @@ export type CatalogData = {
   courseStats: Record<number, CourseStats>
 }
 
-/**
- * Published courses (optionally narrowed by `where`) together with per-course
- * aggregate stats. Deliberately session-free — the viewer's own progress is
- * fetched client-side (useMyCourseStatuses) — so pages built on this stay in
- * the shared ISR cache. Counters come from the cached grouped queries in
- * src/utilities/contentCounts.ts, not per-request table scans.
- */
+// Deliberately session-free — the viewer's own progress is fetched client-side
+// (useMyCourseStatuses) — so pages built on this stay in the shared ISR cache.
 export async function getCatalogData({
   payload,
   locale,
diff --git a/src/lib/email/admin-invite.ts b/src/lib/email/admin-invite.ts
index 7bc35d9..3fa7ffc 100644
--- a/src/lib/email/admin-invite.ts
+++ b/src/lib/email/admin-invite.ts
@@ -1,4 +1,3 @@
-/** Ukrainian admin-invite email, matching the OTP email's house style. */
 export function buildInviteEmailHtml(url: string): string {
   return `<!DOCTYPE html>
 <html lang="uk">
diff --git a/src/lib/rate-limit.ts b/src/lib/rate-limit.ts
index 36a6532..911723f 100644
--- a/src/lib/rate-limit.ts
+++ b/src/lib/rate-limit.ts
@@ -2,14 +2,10 @@ import { sql } from '@payloadcms/db-postgres'
 import type { BasePayload } from 'payload'
 
 /**
- * Fixed-window rate limiter shared across serverless instances, backed by the
- * Better Auth `rate_limit` table (created for `rateLimit.storage: 'database'`
- * in src/lib/auth/options.ts — Better Auth uses it for /api/auth/*, this
- * helper for everything else; key prefixes keep the two disjoint).
- *
- * One atomic upsert both counts the request and resets expired windows, so
- * concurrent lambdas can't double-count or clobber each other. `last_request`
- * stores the window start (epoch ms).
+ * Fixed-window limiter backed by the Better Auth `rate_limit` table — Better Auth uses it
+ * for /api/auth/*, this helper for everything else; key prefixes keep the two disjoint.
+ * One atomic upsert both counts the request and resets expired windows, so concurrent
+ * lambdas can't double-count. `last_request` stores the window start (epoch ms).
  */
 
 export type RateLimitResult =
@@ -17,12 +13,10 @@ export type RateLimitResult =
   | { ok: false; retryAfter: number }
 
 /**
- * Single policy switch for BOTH limiters (Better Auth reads it in
- * src/lib/auth/options.ts). Production-on by default; RATE_LIMIT=true opts a
- * dev session in, RATE_LIMIT=false opts out even of a production build — E2E
- * runs `next start` (NODE_ENV=production) from one runner IP and would
- * otherwise trip the limits it has no business testing.
- * Read at call time so tests can toggle it per process.
+ * Single policy switch for BOTH limiters (Better Auth reads it too). Production-on by
+ * default; RATE_LIMIT=true opts a dev session in, RATE_LIMIT=false opts out even of a
+ * production build — E2E runs `next start` from one runner IP. Read at call time so tests
+ * can toggle it per process.
  */
 export function isRateLimitEnabled(): boolean {
   if (process.env.RATE_LIMIT === 'false') return false
diff --git a/src/payload.config.ts b/src/payload.config.ts
index 301d640..7c4e4f6 100644
--- a/src/payload.config.ts
+++ b/src/payload.config.ts
@@ -29,18 +29,12 @@ import { getServerSideURL } from './utilities/getURL'
 const filename = fileURLToPath(import.meta.url)
 const dirname = path.dirname(filename)
 
-/**
- * `pg-connection-string` currently treats sslmode `prefer`/`require`/`verify-ca`
- * as aliases for `verify-full`, but warns that this changes in pg v9. Make the
- * current (stronger) behavior explicit so we keep full verification and silence
- * the deprecation warning. Neon serves a publicly-trusted cert, so verify-full works.
- */
+// `pg-connection-string` treats sslmode `prefer`/`require`/`verify-ca` as aliases for
+// `verify-full` today but warns that pg v9 changes this; make it explicit. Neon serves a
+// publicly-trusted cert, so verify-full works.
 const normalizeDatabaseURL = (url: string): string =>
   url.replace(/([?&]sslmode=)(prefer|require|verify-ca)\b/i, '$1verify-full')
 
-// Every Neon branch has its own endpoint host, so logging the host answers
-// "which database am I actually connected to?" at a glance (multiple env
-// files and per-session branches make this easy to get wrong silently).
 try {
   const dbHost = new URL(process.env.DATABASE_URL || '').hostname
   console.log(`[payload] DATABASE_URL host: ${dbHost}`)
@@ -100,7 +94,6 @@ export default buildConfig({
       ],
     },
   },
-  // This config helps us configure global or default features that the other editors can inherit
   editor: defaultLexical,
   db: postgresAdapter({
     pool: {
@@ -136,10 +129,7 @@ export default buildConfig({
     translations: {
       uk: {
         general: {
-          // «Створення нового {{label}}» clashes with feminine/plural labels
-          // (e.g. «нового Форма») — a case-neutral wording avoids that.
           creatingNewLabel: 'Створення: {{label}}',
-          // Core uk translation says «Налаштування Payload» — strip the vendor name.
           payloadSettings: 'Налаштування панелі',
         },
         // The redirects plugin ships no uk translations, and with fallbackLanguage=uk
@@ -164,8 +154,6 @@ export default buildConfig({
     fallback: true,
   },
   plugins,
-  // Same Resend account Better Auth uses for OTP emails (src/lib/auth/options.ts).
-  // Without the key (CI), Payload falls back to logging emails to console.
   email: process.env.RESEND_API_KEY
     ? resendAdapter({
         defaultFromAddress: process.env.EMAIL_FROM || 'onboarding@resend.dev',
@@ -181,15 +169,11 @@ export default buildConfig({
   jobs: {
     access: {
       run: ({ req }: { req: PayloadRequest }): boolean => {
-        // Allow logged in users to execute this endpoint (default)
         if (req.user) return true
 
         const secret = process.env.CRON_SECRET
         if (!secret) return false
 
-        // If there is no logged in user, then check
-        // for the Vercel Cron secret to be present as an
-        // Authorization header:
         const authHeader = req.headers.get('authorization')
         return authHeader === `Bearer ${secret}`
       },
diff --git a/src/plugins/ukrainianAdmin.ts b/src/plugins/ukrainianAdmin.ts
index 8cda21e..556ea7e 100644
--- a/src/plugins/ukrainianAdmin.ts
+++ b/src/plugins/ukrainianAdmin.ts
@@ -1,13 +1,9 @@
 import type { Block, CollectionConfig, Field, Plugin } from 'payload'
 
 /**
- * Ukrainian labels for collections generated by third-party plugins
- * (payload-auth, form-builder, search, MCP) that expose no translation API —
- * their labels/descriptions are hardcoded English strings. This plugin runs
- * last and rewrites those strings in the sanitized config.
- *
- * Only fields explicitly listed in the map are touched; everything else is
- * left as the plugin produced it.
+ * Third-party plugins (payload-auth, form-builder, search, MCP) hardcode English
+ * labels and expose no translation API, so this plugin runs last and rewrites the
+ * listed strings in the sanitized config. Unlisted fields are left untouched.
  */
 
 type FieldMap = Record<
@@ -253,7 +249,6 @@ const collectionMap: Record<string, CollectionMap> = {
   },
 }
 
-/** English tab labels inside plugin-generated collections. */
 const tabLabelMap: Record<string, string> = {
   Prompts: 'Промпти',
   Resources: 'Ресурси',
@@ -328,8 +323,6 @@ export const ukrainianAdmin: Plugin = (config) => {
     const map = collectionMap[collection.slug]
     if (map) applyCollectionMap(collection, map)
 
-    // The payload-auth invite button is hardcoded English — swap in our
-    // Ukrainian version (it reuses the same server endpoints).
     if (collection.slug === 'users') {
       const description = collection.admin?.components?.Description
       if (
diff --git a/src/search/localeSync.ts b/src/search/localeSync.ts
index 3dffad3..dc0423e 100644
--- a/src/search/localeSync.ts
+++ b/src/search/localeSync.ts
@@ -1,6 +1,5 @@
 import type { CollectionAfterChangeHook, CollectionSlug, Plugin, TypedLocale } from 'payload'
 
-/** Collections indexed by the search plugin — single source for both the plugin config and the locale backfill. */
 export const searchIndexedCollections: CollectionSlug[] = [
   'posts',
   'courses',
diff --git a/src/utilities/contentCounts.ts b/src/utilities/contentCounts.ts
index 1e7729c..6fa1f8d 100644
--- a/src/utilities/contentCounts.ts
+++ b/src/utilities/contentCounts.ts
@@ -3,15 +3,8 @@ import { sql } from '@payloadcms/db-postgres'
 import { unstable_cache } from 'next/cache'
 import { getPayload } from 'payload'
 
-/**
- * Site-wide aggregate counters (likes, comments, enrollments) computed with
- * grouped SQL instead of fetching rows and counting in JS. Each aggregate is
- * one GROUP BY over a small table and is shared across requests via
- * unstable_cache, so per-request cost is a cache read, not a table scan.
- *
- * Counts here are display-only and may lag by up to the revalidate window;
- * live per-user state (liked/not liked) is fetched client-side.
- */
+// Counts here are display-only and may lag by up to the revalidate window; live
+// per-user state (liked/not liked) is fetched client-side.
 
 type SqlQuery = ReturnType<typeof sql>
 type CountsByTarget = Record<number, number>
@@ -88,13 +81,10 @@ const enrollmentStatsCache = unstable_cache(
   { revalidate: 60, tags: ['course-enrollment-stats'] },
 )
 
-/** Likes per document for a whole collection, cached across requests. */
 export const getCachedLikesCounts = (targetCollection: 'posts' | 'courses') =>
   likesCountsCache(targetCollection)()
 
-/** Comments per document for a whole collection, cached across requests. */
 export const getCachedCommentsCounts = (targetCollection: 'posts' | 'courses') =>
   commentsCountsCache(targetCollection)()
 
-/** Enrolled/completed totals per course, cached across requests. */
 export const getCachedEnrollmentStats = () => enrollmentStatsCache()
diff --git a/src/utilities/courseCompletion.ts b/src/utilities/courseCompletion.ts
index 77937ff..65cb3a2 100644
--- a/src/utilities/courseCompletion.ts
+++ b/src/utilities/courseCompletion.ts
@@ -2,15 +2,12 @@ import type { Course } from '@/payload-types'
 
 type CourseShape = Pick<Course, 'steps' | 'quiz'>
 
-/** Block ids of the course's current steps — the source of truth for progress. */
 export const getStepIds = (course: Pick<Course, 'steps'>): string[] =>
   (course.steps ?? []).map((step) => step.id).filter((id): id is string => Boolean(id))
 
-/**
- * A course counts as finished only when every current step is done and, when a
- * quiz is enabled, it has been passed. Compare against step ids rather than
- * counts so stale ids of deleted steps can't complete a course early.
- */
+// Finished means every current step is done and, when a quiz is enabled, it has been
+// passed. Compare step ids rather than counts so stale ids of deleted steps can't complete
+// a course early.
 export function isCourseComplete({
   course,
   completedSteps,
diff --git a/src/utilities/deepMerge.ts b/src/utilities/deepMerge.ts
index 62cc18d..db29ed8 100644
--- a/src/utilities/deepMerge.ts
+++ b/src/utilities/deepMerge.ts
@@ -1,20 +1,10 @@
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-nocheck
 
-/**
- * Simple object check.
- * @param item
- * @returns {boolean}
- */
 export function isObject(item: unknown): item is object {
   return typeof item === 'object' && !Array.isArray(item)
 }
 
-/**
- * Deep merge two objects.
- * @param target
- * @param ...sources
- */
 export default function deepMerge<T, R>(target: T, source: R): T {
   const output = { ...target }
   if (isObject(target) && isObject(source)) {
diff --git a/src/utilities/formatAuthors.ts b/src/utilities/formatAuthors.ts
index d1e36c5..3d71b11 100644
--- a/src/utilities/formatAuthors.ts
+++ b/src/utilities/formatAuthors.ts
@@ -1,19 +1,8 @@
 import { Post } from '@/payload-types'
 
-/**
- * Formats an array of populatedAuthors from Posts into a prettified string.
- * @param authors - The populatedAuthors array from a Post.
- * @returns A prettified string of authors.
- * @example
- *
- * [Author1, Author2] becomes 'Author1 and Author2'
- * [Author1, Author2, Author3] becomes 'Author1, Author2, and Author3'
- *
- */
 export const formatAuthors = (
   authors: NonNullable<NonNullable<Post['populatedAuthors']>[number]>[],
 ) => {
-  // Ensure we don't have any authors without a name
   const authorNames = authors.map((author) => author.name).filter(Boolean)
 
   if (authorNames.length === 0) return ''
diff --git a/src/utilities/formatDateTime.ts b/src/utilities/formatDateTime.ts
index 1674804..0b1763e 100644
--- a/src/utilities/formatDateTime.ts
+++ b/src/utilities/formatDateTime.ts
@@ -5,7 +5,6 @@ const formatters: Record<SiteLocale, Intl.DateTimeFormat> = {
   en: new Intl.DateTimeFormat('en-GB', { day: 'numeric', month: 'short', year: 'numeric' }),
 }
 
-/** «28 чер 2026» (uk) / "28 Jun 2026" (en). */
 export const formatDateTime = (timestamp: string, locale: SiteLocale = 'uk'): string => {
   const date = timestamp ? new Date(timestamp) : new Date()
   return formatters[locale].format(date)
diff --git a/src/utilities/generatePreviewPath.ts b/src/utilities/generatePreviewPath.ts
index e6e1130..35006bc 100644
--- a/src/utilities/generatePreviewPath.ts
+++ b/src/utilities/generatePreviewPath.ts
@@ -12,12 +12,10 @@ type Props = {
 }
 
 export const generatePreviewPath = ({ collection, slug }: Props) => {
-  // Allow empty strings, e.g. for the homepage
   if (slug === undefined || slug === null) {
     return null
   }
 
-  // Encode to support slugs with special characters
   const encodedSlug = encodeURIComponent(slug)
 
   const encodedParams = new URLSearchParams({
diff --git a/src/utilities/getDocument.ts b/src/utilities/getDocument.ts
index d58069f..23ba288 100644
--- a/src/utilities/getDocument.ts
+++ b/src/utilities/getDocument.ts
@@ -25,9 +25,6 @@ async function getDocument(collection: Collection, slug: string, depth = 0) {
   return page.docs[0]
 }
 
-/**
- * Returns a unstable_cache function mapped with the cache tag for the slug
- */
 export const getCachedDocument = (collection: Collection, slug: string) =>
   unstable_cache(async () => getDocument(collection, slug), [collection, slug], {
     tags: [`${collection}_${slug}`],
diff --git a/src/utilities/getMediaUrl.ts b/src/utilities/getMediaUrl.ts
index f50af91..9a3e0dd 100644
--- a/src/utilities/getMediaUrl.ts
+++ b/src/utilities/getMediaUrl.ts
@@ -1,11 +1,5 @@
 import { getClientSideURL } from '@/utilities/getURL'
 
-/**
- * Processes media resource URL to ensure proper formatting
- * @param url The original URL from the resource
- * @param cacheTag Optional cache tag to append to the URL
- * @returns Properly formatted URL with cache tag if provided
- */
 export const getMediaUrl = (url: string | null | undefined, cacheTag?: string | null): string => {
   if (!url) return ''
 
@@ -13,12 +7,10 @@ export const getMediaUrl = (url: string | null | undefined, cacheTag?: string |
     cacheTag = encodeURIComponent(cacheTag)
   }
 
-  // Check if URL already has http/https protocol
   if (url.startsWith('http://') || url.startsWith('https://')) {
     return cacheTag ? `${url}?${cacheTag}` : url
   }
 
-  // Otherwise prepend client-side URL
   const baseUrl = getClientSideURL()
   return cacheTag ? `${baseUrl}${url}?${cacheTag}` : `${baseUrl}${url}`
 }
diff --git a/src/utilities/getRedirects.ts b/src/utilities/getRedirects.ts
index 8eac7f2..cbd3cec 100644
--- a/src/utilities/getRedirects.ts
+++ b/src/utilities/getRedirects.ts
@@ -15,11 +15,6 @@ export async function getRedirects(depth = 1) {
   return redirects
 }
 
-/**
- * Returns a unstable_cache function mapped with the cache tag for 'redirects'.
- *
- * Cache all redirects together to avoid multiple fetches.
- */
 export const getCachedRedirects = () =>
   unstable_cache(async () => getRedirects(), ['redirects'], {
     tags: ['redirects'],
diff --git a/src/utilities/leaderboard.ts b/src/utilities/leaderboard.ts
index e401484..3d9de11 100644
--- a/src/utilities/leaderboard.ts
+++ b/src/utilities/leaderboard.ts
@@ -4,13 +4,8 @@ import { unstable_cache } from 'next/cache'
 import { runRows } from '@/utilities/contentCounts'
 import { STEP_XP, QUIZ_XP } from '@/utilities/xp'
 
-/**
- * Leaderboard aggregates, computed with grouped SQL like the counters in
- * contentCounts.ts. All-time XP is derived from enrollments (the source of
- * truth for XP); period XP comes from the timestamped xp_events log, which
- * only spans since the log was introduced. XP-awarding mutations revalidate
- * the `xp-leaderboard` tag, so the revalidate window is just a backstop.
- */
+// All-time XP is derived from enrollments (the source of truth for XP); period XP comes
+// from the xp_events log, which only spans since the log was introduced.
 
 export type LeaderboardEntry = {
   userId: number
@@ -82,10 +77,8 @@ const periodLeaderboardCache = (period: LeaderboardPeriod) =>
     { revalidate: 300, tags: ['xp-leaderboard'] },
   )
 
-/** Top users by derived total XP, cached across requests. */
 export const getCachedAllTimeLeaderboard = () => allTimeLeaderboardCache()
 
-/** Top users by XP logged within the rolling period, cached across requests. */
 export const getCachedPeriodLeaderboard = (period: LeaderboardPeriod) =>
   periodLeaderboardCache(period)()
 
@@ -120,10 +113,8 @@ const courseCompletionsCache = (courseId: number) =>
       }))
     },
     [`course-completions-${courseId}`],
-    // Enrollment mutations already revalidate this tag (courses/actions.ts).
     { revalidate: 60, tags: ['course-enrollment-stats'] },
   )
 
-/** Latest users who completed a course (for the course-page ticker). */
 export const getCachedCourseCompletions = (courseId: number) =>
   courseCompletionsCache(courseId)()
diff --git a/src/utilities/myXpCache.ts b/src/utilities/myXpCache.ts
index c810988..1635fa7 100644
--- a/src/utilities/myXpCache.ts
+++ b/src/utilities/myXpCache.ts
@@ -1,11 +1,5 @@
 import type { MyXp } from '@/actions/xp'
 
-/**
- * Session-scoped cache for the header XP pill so it doesn't cost a server
- * round trip on every full page load. Mutations that award XP (step
- * completion, quiz pass) clear it explicitly.
- */
-
 const KEY = 'myXp:v1'
 const TTL_MS = 5 * 60 * 1000
 
diff --git a/src/utilities/plural.ts b/src/utilities/plural.ts
index b617e09..6f7d34c 100644
--- a/src/utilities/plural.ts
+++ b/src/utilities/plural.ts
@@ -1,10 +1,7 @@
 import type { SiteLocale } from '@/utilities/locales'
 
-/**
- * Pick the correct plural form for a count.
- * `forms` is pipe-separated: uk expects «one|few|many» («крок|кроки|кроків»),
- * en expects "one|other" ("step|steps").
- */
+// `forms` is pipe-separated: uk expects «one|few|many» («крок|кроки|кроків»), en expects
+// "one|other" ("step|steps").
 export const plural = (locale: SiteLocale, count: number, forms: string): string => {
   const parts = forms.split('|')
   if (locale === 'uk') {
diff --git a/src/utilities/safeRedirect.ts b/src/utilities/safeRedirect.ts
index 5de2e28..0b72921 100644
--- a/src/utilities/safeRedirect.ts
+++ b/src/utilities/safeRedirect.ts
@@ -1,7 +1,5 @@
-/**
- * Only allow same-site relative paths for post-auth redirects — anything else
- * (absolute URLs, protocol-relative //host, backslash tricks) falls back.
- */
+// Only same-site relative paths are allowed — absolute URLs, protocol-relative //host and
+// backslash tricks all fall back.
 export const safeRedirectPath = (
   value: string | null | undefined,
   fallback: string,
diff --git a/src/utilities/ui.ts b/src/utilities/ui.ts
index fc08f6e..d32b0fe 100644
--- a/src/utilities/ui.ts
+++ b/src/utilities/ui.ts
@@ -1,9 +1,3 @@
-/**
- * Utility functions for UI components automatically added by ShadCN and used in a few of our frontend components and blocks.
- *
- * Other functions may be exported from here in the future or by installing other shadcn components.
- */
-
 import { type ClassValue, clsx } from 'clsx'
 import { twMerge } from 'tailwind-merge'
 
diff --git a/src/utilities/xp.ts b/src/utilities/xp.ts
index 5b29a80..aa74b6b 100644
--- a/src/utilities/xp.ts
+++ b/src/utilities/xp.ts
@@ -1,22 +1,13 @@
-/**
- * XP («досвід») conventions for the Iron Energy design.
- *
- * XP is derived from real progress data rather than stored:
- *  - every completed course step is worth STEP_XP
- *  - a passed final quiz is worth QUIZ_XP
- *  - a course's total reward = steps × STEP_XP (+ QUIZ_XP when it has a quiz)
- */
+// XP is derived from progress data rather than stored: STEP_XP per completed step,
+// QUIZ_XP for a passed final quiz.
 export const STEP_XP = 30
 export const QUIZ_XP = 100
 
-/** Total XP a course awards. */
 export const courseXp = (stepsCount: number, hasQuiz: boolean): number =>
   stepsCount * STEP_XP + (hasQuiz ? QUIZ_XP : 0)
 
-/** XP needed to go from `level` to `level + 1`. */
 const levelSpan = (level: number): number => 300 + (level - 1) * 100
 
-/** Level for a given XP total: 1 → 2 needs 300 XP, each next level +100 XP more. */
 export const levelForXp = (xp: number): { level: number; intoLevel: number; span: number } => {
   let level = 1
   let rest = Math.max(0, xp)
@@ -27,5 +18,4 @@ export const levelForXp = (xp: number): { level: number; intoLevel: number; span
   return { level, intoLevel: rest, span: levelSpan(level) }
 }
 
-/** Format like «1 240 XP» (thin non-breaking spaces per uk convention). */
 export const formatXp = (xp: number): string => `${xp.toLocaleString('uk-UA')} XP`