From c859099cc8651ef48b4e266e4575ce822f8e9436 Mon Sep 17 00:00:00 2001
From: Ewan Croft <git@ewancroft.uk>
Date: Thu, 25 Jun 2026 15:58:57 +0100
Subject: [PATCH] docs: add explanatory comments throughout codebase

---
 src/hooks.server.js                            |  8 ++++++++
 src/lib/components/BaseModal.svelte            | 18 +++++++++++++-----
 src/lib/components/CommentSection.svelte       |  6 ++++++
 src/lib/components/EmptyState.svelte           |  5 +++++
 src/lib/components/ErrorDisplay.svelte         |  6 ++++++
 src/lib/components/Footer.svelte               |  6 ++++++
 src/lib/components/Header.svelte               |  6 ++++++
 src/lib/components/LoadingSkeleton.svelte      |  6 ++++++
 src/lib/components/Now.svelte                  |  5 +++++
 src/lib/components/SabbatBackground.svelte     | 10 +++++++++-
 src/lib/components/ShareButtons.svelte         |  5 +++++
 src/lib/components/TableOfContents.svelte      |  7 +++++++
 src/lib/components/VerificationBadge.svelte    | 17 ++++++-----------
 src/lib/components/layout/WolfToggle.svelte    |  4 ++++
 .../components/leaflet/LeafletBskyPost.svelte  |  7 ++++---
 .../components/leaflet/LeafletButton.svelte    |  4 ++--
 src/lib/components/leaflet/LeafletEmbed.svelte |  5 +++--
 .../leaflet/LeafletWebsiteCard.svelte          |  5 +++--
 src/lib/components/ostara-eggs/eggStores.ts    |  9 +++++++++
 src/lib/config.ts                              |  5 +++++
 src/lib/providers/markdown.ts                  |  9 +++++++++
 src/lib/server/theme.ts                        | 11 +++++++++++
 src/lib/services/atproto/did.ts                | 15 +++++++++++++--
 src/lib/services/atproto/fetch.ts              | 18 ++++++++++++++++++
 src/lib/stores/wolfMode.ts                     | 18 +++++++++++++++++-
 src/lib/utils/avatar.ts                        |  7 ++++++-
 src/lib/utils/cache.ts                         | 13 ++++++++++++-
 src/lib/utils/promise.ts                       |  8 +++++++-
 src/lib/utils/sabbats.ts                       | 12 ++++++++++++
 src/lib/utils/slugify.ts                       |  5 +++++
 src/routes/+page.server.ts                     |  8 ++++++++
 src/routes/.well-known/atproto-did/+server.ts  |  8 ++++++++
 .../site.standard.publication/+server.ts       |  9 +++++++++
 src/routes/about/+page.server.ts               | 10 ++++++++++
 src/routes/blog/+page.server.ts                |  8 ++++++++
 src/routes/projects/+page.server.ts            |  4 ++++
 src/routes/projects/[slug]/+page.server.ts     |  3 +++
 src/routes/subscriptions/+page.server.ts       |  6 ++++++
 src/routes/webhook/+server.ts                  |  8 ++++++++
 src/routes/webhook/github/+server.ts           |  8 ++++++++
 40 files changed, 300 insertions(+), 32 deletions(-)

diff --git a/src/hooks.server.js b/src/hooks.server.js
index 32a3e51..6e6987a 100644
--- a/src/hooks.server.js
+++ b/src/hooks.server.js
@@ -1,3 +1,11 @@
+/**
+ * Server-side hooks.
+ *
+ * The sole hook injects the dynamic Sabbat-driven theme CSS into every page
+ * via transformPageChunk, so the seasonal colour palette is present before
+ * any client JavaScript runs.
+ */
+
 import { getDynamicThemeCSS } from "$lib/server/theme";
 
 /** @type {import('@sveltejs/kit').Handle} */
diff --git a/src/lib/components/BaseModal.svelte b/src/lib/components/BaseModal.svelte
index 49b5bb9..afa88e4 100644
--- a/src/lib/components/BaseModal.svelte
+++ b/src/lib/components/BaseModal.svelte
@@ -1,15 +1,23 @@
 <script lang="ts">
+  /**
+   * BaseModal — generic portal-based dialog.
+   *
+   * Accepts a `children` snippet for body content and an optional
+   * `footer` snippet for action buttons. Renders into document.body
+   * via a Svelte use:portal action to avoid z-index and overflow
+   * issues from deep DOM nesting.
+   */
   import { X } from '@lucide/svelte';
   import type { Snippet } from 'svelte';
   import { onMount } from 'svelte';
 
-  let { 
-    title, 
-    open, 
-    onClose, 
+  let {
+    title,
+    open,
+    onClose,
     children,
     footer
-  }: { 
+  }: {
     title: string, 
     open: boolean, 
     onClose: () => void, 
diff --git a/src/lib/components/CommentSection.svelte b/src/lib/components/CommentSection.svelte
index 1198a62..4e47f39 100644
--- a/src/lib/components/CommentSection.svelte
+++ b/src/lib/components/CommentSection.svelte
@@ -1,4 +1,10 @@
 <script lang="ts">
+    /**
+     * CommentSection — Leaflet comment feed for blog posts.
+     * Displays a list of comments from the AT Protocol network
+     * (fetched via Constellation backlinks). Supports display
+     * name, handle, and relative dating.
+     */
     import { MessageCircle } from '@lucide/svelte';
     import EmptyState from '$lib/components/EmptyState.svelte';
     import type { LeafletComment } from '$lib/services/atproto/fetch';
diff --git a/src/lib/components/EmptyState.svelte b/src/lib/components/EmptyState.svelte
index 2e73b7a..ba19df0 100644
--- a/src/lib/components/EmptyState.svelte
+++ b/src/lib/components/EmptyState.svelte
@@ -1,4 +1,9 @@
 <script lang="ts">
+  /**
+   * EmptyState — universal placeholder for empty data states.
+   * Shows an icon (optional), title, and description.
+   * Used across home, blog, projects, subscriptions, and comments.
+   */
   import { AlertCircle } from '@lucide/svelte';
 
   interface Props {
diff --git a/src/lib/components/ErrorDisplay.svelte b/src/lib/components/ErrorDisplay.svelte
index 4682c85..fab6e61 100644
--- a/src/lib/components/ErrorDisplay.svelte
+++ b/src/lib/components/ErrorDisplay.svelte
@@ -1,4 +1,10 @@
 <script lang="ts">
+  /**
+   * ErrorDisplay — standalone error page component.
+   * Used by route error boundaries and within pages that need
+   * to surface API failures with a status code, title, and
+   * optional technical details panel.
+   */
   import { AlertCircle } from '@lucide/svelte';
 
   interface Props {
diff --git a/src/lib/components/Footer.svelte b/src/lib/components/Footer.svelte
index 8212279..717bb4d 100644
--- a/src/lib/components/Footer.svelte
+++ b/src/lib/components/Footer.svelte
@@ -1,4 +1,10 @@
 <script lang="ts">
+  /**
+   * Footer — site-wide footer.
+   * Shows the current Sabbat name with an info modal trigger,
+   * social links (Bluesky, Eurosky), the wolf mode toggle,
+   * copyright, and quick links to contact/design/meta pages.
+   */
   import { onMount } from 'svelte';
   import { Info } from '@lucide/svelte';
   import { WolfToggle } from '$lib/components/layout';
diff --git a/src/lib/components/Header.svelte b/src/lib/components/Header.svelte
index a9f3ed7..e7684c9 100644
--- a/src/lib/components/Header.svelte
+++ b/src/lib/components/Header.svelte
@@ -1,4 +1,10 @@
 <script lang="ts">
+    /**
+     * Header — site navigation bar.
+     * Includes the brand logo (Triskele icon + name), nav links,
+     * a mobile hamburger menu, and the Mōnandæg moon-day indicator.
+     * DEV environment gets a visible development chip.
+     */
     import { SITE, NAV_LINKS } from '$lib/config';
     import { page } from '$app/state';
     import { X, Menu } from '@lucide/svelte';
diff --git a/src/lib/components/LoadingSkeleton.svelte b/src/lib/components/LoadingSkeleton.svelte
index d6ac2b1..ab4de92 100644
--- a/src/lib/components/LoadingSkeleton.svelte
+++ b/src/lib/components/LoadingSkeleton.svelte
@@ -1,4 +1,10 @@
 <script lang="ts">
+  /**
+   * LoadingSkeleton — shimmer placeholder for async content.
+   * Renders `count` animated skeleton bars that appear while
+   * data is being fetched. Matches the site's surface color
+   * tokens so the transition to real content is seamless.
+   */
   interface Props {
     count?: number;
   }
diff --git a/src/lib/components/Now.svelte b/src/lib/components/Now.svelte
index 8a1d1ed..5ef3ba9 100644
--- a/src/lib/components/Now.svelte
+++ b/src/lib/components/Now.svelte
@@ -1,4 +1,9 @@
 <script lang="ts">
+  /**
+   * Now — displays the author's current Kibun status.
+   * Shows emoji + text + date in a subtle card. When no status
+   * is set, collapses silently.
+   */
   import type { KibunStatusData } from '$lib/services/atproto/types';
 
   let { kibunStatus }: { kibunStatus: KibunStatusData | null } = $props();
diff --git a/src/lib/components/SabbatBackground.svelte b/src/lib/components/SabbatBackground.svelte
index b8531cc..99853a3 100644
--- a/src/lib/components/SabbatBackground.svelte
+++ b/src/lib/components/SabbatBackground.svelte
@@ -1,6 +1,14 @@
 <script lang="ts">
+  /**
+   * SabbatBackground — fading seasonal icons behind the page.
+   *
+   * Renders two large Sabbat symbols (waning previous, waxing next)
+   * at fixed positions. Opacity and scale lerp with the seasonal
+   * progress, creating a slow visual transition that matches the
+   * dynamic colour scheme.
+   */
   import { onMount } from 'svelte';
-  
+
   import Imbolc from '$lib/components/icons/sabbats/Imbolc.svelte';
   import Ostara from '$lib/components/icons/sabbats/Ostara.svelte';
   import Beltane from '$lib/components/icons/sabbats/Beltane.svelte';
diff --git a/src/lib/components/ShareButtons.svelte b/src/lib/components/ShareButtons.svelte
index 17d704b..b022a93 100644
--- a/src/lib/components/ShareButtons.svelte
+++ b/src/lib/components/ShareButtons.svelte
@@ -1,4 +1,9 @@
 <script lang="ts">
+  /**
+   * ShareButtons — share bar for blog posts.
+   * Bluesky intent link, clipboard copy, structured email template.
+   * Bluesky is the primary channel; email covers the rest.
+   */
   import { Link2, Mail } from '@lucide/svelte';
   import Bluesky from '$lib/components/icons/Bluesky.svelte';
 
diff --git a/src/lib/components/TableOfContents.svelte b/src/lib/components/TableOfContents.svelte
index eecdfe2..ec67e98 100644
--- a/src/lib/components/TableOfContents.svelte
+++ b/src/lib/components/TableOfContents.svelte
@@ -1,4 +1,11 @@
 <script lang="ts">
+    /**
+     * TableOfContents — generates a linked outline from headings.
+     *
+     * Queries the given `container` for headings matching `selector`,
+     * slug-ifies each heading id (disambiguating duplicates), and
+     * renders a navigable list. SSR-safe: shows a skeleton before mount.
+     */
     import { onMount } from 'svelte';
 
     let { container, selector = 'h2, h3, h4' }: { container: string; selector?: string } = $props();
diff --git a/src/lib/components/VerificationBadge.svelte b/src/lib/components/VerificationBadge.svelte
index 3a99d6c..eb1d2df 100644
--- a/src/lib/components/VerificationBadge.svelte
+++ b/src/lib/components/VerificationBadge.svelte
@@ -1,18 +1,13 @@
 <script lang="ts">
   /**
-   * VerificationBadge.svelte
+   * VerificationBadge — clickable seal with modal explanation.
    *
-   * Clickable "seal" badge — opens a small modal explaining what the
-   * mark means and who/what backs it, mirroring the structure/styling
-   * of SabbatModal.svelte (dialog + modal-content + modal-header).
+   * Renders as an inline SVG badge inside a heading (h1) that opens
+   * a BaseModal listing verifiers. The modal's font must be explicitly
+   * reset because it inherits the parent h1's oversized styling.
    *
-   * Note: this component renders inside an <h1>, so the modal needs an
-   * explicit font reset — otherwise its text inherits the page-title's
-   * huge, bold styling via normal CSS cascade.
-   *
-   * Edit `verifiedBy` / the body copy below to point at whatever you
-   * want this to actually claim (DID, PDS, a specific attestation, etc).
-   */
+   * Verifiers are fetched server-side from Constellation backlinks
+   * pointing at this DID (app.bsky.graph.verification).
   import { X } from '@lucide/svelte';
   import BaseModal from './BaseModal.svelte';
   import VerifierCard from './VerifierCard.svelte';
diff --git a/src/lib/components/layout/WolfToggle.svelte b/src/lib/components/layout/WolfToggle.svelte
index b40bb6f..afbe295 100644
--- a/src/lib/components/layout/WolfToggle.svelte
+++ b/src/lib/components/layout/WolfToggle.svelte
@@ -1,4 +1,8 @@
 <script lang="ts">
+	/**
+	 * WolfToggle — footer toggle for the wolf-mode Easter egg.
+	 * Reads the wolfMode store and displays "awoo" or "normal".
+	 */
 	import { wolfMode } from '$lib/stores/wolfMode';
 </script>
 
diff --git a/src/lib/components/leaflet/LeafletBskyPost.svelte b/src/lib/components/leaflet/LeafletBskyPost.svelte
index 1f035e9..e7542a8 100644
--- a/src/lib/components/leaflet/LeafletBskyPost.svelte
+++ b/src/lib/components/leaflet/LeafletBskyPost.svelte
@@ -1,9 +1,10 @@
 <script lang="ts">
   /**
-   * Render a Leaflet Bluesky post embed block.
-   * Uses the Bluesky embed URL for a lightweight embed.
+   * LeafletBskyPost — rendered Bluesky post embed from a Leaflet document.
+   * Converts the at:// URI into a bsky.app profile/post URL and links
+   * to it. Uses the configured clientHost to support custom PDS
+   * front-ends.
    */
-
   let { postRef, clientHost }: {
     postRef: { uri: string; cid: string };
     clientHost?: string;
diff --git a/src/lib/components/leaflet/LeafletButton.svelte b/src/lib/components/leaflet/LeafletButton.svelte
index bb4d164..47e55ed 100644
--- a/src/lib/components/leaflet/LeafletButton.svelte
+++ b/src/lib/components/leaflet/LeafletButton.svelte
@@ -1,8 +1,8 @@
 <script lang="ts">
   /**
-   * Render a Leaflet button block.
+   * LeafletButton — rendered button block from a Leaflet document.
+   * Opens the linked URL in a new tab with rel=noopener.
    */
-
   let { text, url }: { text: string; url: string } = $props();
 </script>
 
diff --git a/src/lib/components/leaflet/LeafletEmbed.svelte b/src/lib/components/leaflet/LeafletEmbed.svelte
index ba643e1..808e874 100644
--- a/src/lib/components/leaflet/LeafletEmbed.svelte
+++ b/src/lib/components/leaflet/LeafletEmbed.svelte
@@ -1,8 +1,9 @@
 <script lang="ts">
   /**
-   * Render a Leaflet iframe/embed block.
+   * LeafletEmbed — rendered iframe embed from a Leaflet document.
+   * Supports explicit height or an aspect-ratio based sizing with
+   * a 16:9 fallback for unmeasured embeds.
    */
-
   let { url, height, aspectRatio }: {
     url: string;
     height?: number;
diff --git a/src/lib/components/leaflet/LeafletWebsiteCard.svelte b/src/lib/components/leaflet/LeafletWebsiteCard.svelte
index 72444bd..ffd88b3 100644
--- a/src/lib/components/leaflet/LeafletWebsiteCard.svelte
+++ b/src/lib/components/leaflet/LeafletWebsiteCard.svelte
@@ -1,8 +1,9 @@
 <script lang="ts">
   /**
-   * Render a Leaflet website card block (link preview).
+   * LeafletWebsiteCard — rendered link preview from a Leaflet document.
+   * Shows a thumbnail, title, description, and the hostname extracted
+   * from the destination URL.
    */
-
   import { ExternalLink } from "@lucide/svelte";
 
   let { src, title, description, previewImageSrc }: {
diff --git a/src/lib/components/ostara-eggs/eggStores.ts b/src/lib/components/ostara-eggs/eggStores.ts
index 123becc..cbc902b 100644
--- a/src/lib/components/ostara-eggs/eggStores.ts
+++ b/src/lib/components/ostara-eggs/eggStores.ts
@@ -1,3 +1,8 @@
+/**
+ * Shared state for Easter eggs.
+ * Currently manages the "three clicks" triskele toast.
+ */
+
 import { writable } from "svelte/store";
 
 // ── Easter egg #3: three clicks on the triskele ──────────────────
@@ -5,6 +10,10 @@ let _threeTimer: ReturnType<typeof setTimeout> | null = null;
 
 export const threeVisible = writable(false);
 
+/**
+ * Show the "Three again." toast for 3 seconds.
+ * Calling while visible resets the timer.
+ */
 export function triggerThree() {
   if (_threeTimer) clearTimeout(_threeTimer);
   threeVisible.set(true);
diff --git a/src/lib/config.ts b/src/lib/config.ts
index 7a739c7..0b57cd6 100644
--- a/src/lib/config.ts
+++ b/src/lib/config.ts
@@ -1,3 +1,8 @@
+/**
+ * Site-wide constants and configuration.
+ * Single source of truth for nav structure and metadata defaults.
+ */
+
 import { PUBLIC_SITE_TITLE, PUBLIC_SITE_DESCRIPTION } from "$env/static/public";
 
 export const SITE = {
diff --git a/src/lib/providers/markdown.ts b/src/lib/providers/markdown.ts
index 415be70..b170f0c 100644
--- a/src/lib/providers/markdown.ts
+++ b/src/lib/providers/markdown.ts
@@ -1,3 +1,12 @@
+/**
+ * Client-side markdown renderer.
+ *
+ * Used in the browser for Live Markdown preview rather than the
+ * server-side remark pipeline. Converts raw text to sanitised HTML
+ * using marked + DOMPurify. Falls back to unsanitised output during
+ * SSR (hydration catches up).
+ */
+
 import { marked } from "marked";
 import DOMPurify from "dompurify";
 
diff --git a/src/lib/server/theme.ts b/src/lib/server/theme.ts
index 65360fc..8dde2d4 100644
--- a/src/lib/server/theme.ts
+++ b/src/lib/server/theme.ts
@@ -1,3 +1,14 @@
+/**
+ * Seasonal colour theme engine.
+ *
+ * The entire site's colour palette is derived from the current Sabbat
+ * position on the Wheel of the Year. This module interpolates between
+ * Sabbat hue rotations using OKLCH colour space via chroma-js.
+ *
+ * The generated CSS is injected server-side in the SvelteKit handle hook
+ * so the theme is present before any client JS runs.
+ */
+
 import chroma from "chroma-js";
 import { type Sabbat, sabbats, getCurrentSabbat } from "$lib/utils/sabbats";
 
diff --git a/src/lib/services/atproto/did.ts b/src/lib/services/atproto/did.ts
index 2788b0e..bdf09ee 100644
--- a/src/lib/services/atproto/did.ts
+++ b/src/lib/services/atproto/did.ts
@@ -1,5 +1,11 @@
-// In-process DID cache — avoids duplicate resolutions within a single request
-// and benefits warm Vercel function instances.
+/**
+ * DID resolution with in-process cache.
+ *
+ * Resolves did:plc and did:web DIDs to their DID documents,
+ * caching results for 1 hour to avoid redundant network calls
+ * within the same Vercel function instance.
+ */
+
 const DID_CACHE = new Map<string, { doc: any; ts: number }>();
 const DID_CACHE_TTL_MS = 1000 * 60 * 60; // 1 hour
 
@@ -15,6 +21,11 @@ function fetchWithAbort(
   );
 }
 
+/**
+ * Resolve a DID to its DID document.
+ * Supports did:plc (PLC directory) and did:web (/.well-known/did.json).
+ * Uses AbortController with an 8-second timeout.
+ */
 export async function resolveDid(
   did: string,
   fetchFn: typeof fetch = fetch,
diff --git a/src/lib/services/atproto/fetch.ts b/src/lib/services/atproto/fetch.ts
index 9b1f91f..333409d 100644
--- a/src/lib/services/atproto/fetch.ts
+++ b/src/lib/services/atproto/fetch.ts
@@ -1,3 +1,15 @@
+/**
+ * AT Protocol data fetching layer.
+ *
+ * Thin wrappers around @ewanc26/atproto library calls plus heavier
+ * fetch functions for subscriptions, comments, and recommendations
+ * that stitch together DID resolution, PDS queries, and Constellation
+ * backlinks.
+ *
+ * All fetch functions accept an optional `fetch` override so SvelteKit's
+ * server-side request context (cookies, caching) is respected.
+ */
+
 import { PUBLIC_ATPROTO_DID } from "$env/static/public";
 import { mapWithConcurrency } from "$lib/utils/promise";
 import {
@@ -12,6 +24,8 @@ import { resolveDid } from "./did";
 import { getPDSAgent } from "./agents";
 import { getCache, setCache } from "$lib/utils/cache";
 
+// ── Simple wrappers (delegate to @ewanc26/atproto) ──────
+
 const CACHE_TTL_MS = 1000 * 60 * 5; // 5 minutes
 
 export async function fetchKibunStatus(fetchFn?: typeof fetch) {
@@ -38,6 +52,8 @@ export async function fetchSiteInfo(fetchFn?: typeof fetch) {
   return _fetchSiteInfo(PUBLIC_ATPROTO_DID, fetchFn);
 }
 
+// ── Subscriptions & Recommendations ────────────────────
+
 export interface SubscriptionPublication {
   uri: string;
   name: string;
@@ -217,6 +233,8 @@ export async function fetchRecommendations(
   return data;
 }
 
+// ── Comments ──────────────────────────────────────────
+
 export interface LeafletComment {
   uri: string;
   plaintext: string;
diff --git a/src/lib/stores/wolfMode.ts b/src/lib/stores/wolfMode.ts
index 570aa90..910e52b 100644
--- a/src/lib/stores/wolfMode.ts
+++ b/src/lib/stores/wolfMode.ts
@@ -1,3 +1,14 @@
+/**
+ * wolfMode — replaces visible text with canine onomatopoeia.
+ *
+ * An Easter egg: every word on the page becomes "awoo" / "yip" / "grr" etc.
+ * Numbers, punctuation, abbreviations, and navigation elements are preserved
+ * so the page remains functional.
+ *
+ * The same word always maps to the same sound within a session for
+ * a consistent reading experience.
+ */
+
 import { browser } from "$app/environment";
 import { writable } from "svelte/store";
 
@@ -25,7 +36,8 @@ const wolfSounds = [
   "huff",
 ];
 
-// Store original text content
+// ── State: original text + word→sound mapping ──────────────
+
 let originalTexts = new Map<Node, string>();
 let wordCounter = 0;
 let wordToSoundMap = new Map<string, string>();
@@ -182,6 +194,8 @@ function walkTextNodes(node: Node, callback: (textNode: Text) => void) {
   }
 }
 
+// ── Transform & Revert ────────────────────────────────────
+
 function enableWolfMode() {
   originalTexts.clear();
   wordToSoundMap.clear();
@@ -213,6 +227,8 @@ function disableWolfMode() {
   wordCounter = 0;
 }
 
+// ── Public API ────────────────────────────────────────────
+
 const wolfStore = writable(false);
 
 export const wolfMode = {
diff --git a/src/lib/utils/avatar.ts b/src/lib/utils/avatar.ts
index f758e75..2220fe2 100644
--- a/src/lib/utils/avatar.ts
+++ b/src/lib/utils/avatar.ts
@@ -1,5 +1,10 @@
 /**
- * Generates a deterministic 8x8 blocky SVG avatar based on a seed (DID).
+ * Deterministic identicon from any string seed.
+ *
+ * Generates a symmetrical 8x8 block grid coloured by a hash of the
+ * input — useful for DIDs and handles that have no profile image set.
+ * Mirrors the left half across the vertical axis for the classic
+ * identicon look.
  */
 export function getPlaceholderAvatar(seed: string): string {
   // Simple deterministic hash function
diff --git a/src/lib/utils/cache.ts b/src/lib/utils/cache.ts
index fc1c72f..a51240e 100644
--- a/src/lib/utils/cache.ts
+++ b/src/lib/utils/cache.ts
@@ -1,6 +1,14 @@
-// src/lib/utils/cache.ts
+/**
+ * In-memory TTL cache for API responses.
+ * Keeps warm Vercel function instances responsive without
+ * external cache infrastructure. Data lives per-instance only.
+ */
+
 const cache = new Map<string, { data: any; expiry: number }>();
 
+/**
+ * Retrieve a cached value, or null if expired or absent.
+ */
 export function getCache<T>(key: string): T | null {
   const entry = cache.get(key);
   if (!entry) return null;
@@ -11,6 +19,9 @@ export function getCache<T>(key: string): T | null {
   return entry.data as T;
 }
 
+/**
+ * Store a value in cache with a TTL in milliseconds.
+ */
 export function setCache<T>(key: string, data: T, ttlMs: number) {
   cache.set(key, { data, expiry: Date.now() + ttlMs });
 }
diff --git a/src/lib/utils/promise.ts b/src/lib/utils/promise.ts
index 40b507e..660d396 100644
--- a/src/lib/utils/promise.ts
+++ b/src/lib/utils/promise.ts
@@ -1,4 +1,10 @@
-// src/lib/utils/promise.ts
+/**
+ * Map an async function over an array with a concurrency cap.
+ * Uses a fixed-size worker pool instead of Promise.all on every slice,
+ * which is fairer for mixed-latency tasks and avoids thundering
+ * the downstream service.
+ */
+
 export async function mapWithConcurrency<T, R>(
   items: T[],
   fn: (item: T) => Promise<R>,
diff --git a/src/lib/utils/sabbats.ts b/src/lib/utils/sabbats.ts
index 7b3976a..626a185 100644
--- a/src/lib/utils/sabbats.ts
+++ b/src/lib/utils/sabbats.ts
@@ -1,3 +1,11 @@
+/**
+ * sabbats.ts — The Wheel of the Year.
+ *
+ * Defines the eight Neopagan Sabbats with dates, descriptions,
+ * colour palettes, and hue rotations for the dynamic seasonal theme.
+ * All visual transitions across the site are anchored to these dates.
+ */
+
 export interface Sabbat {
   name: string;
   month: number;
@@ -83,6 +91,10 @@ export const sabbats: Sabbat[] = [
   },
 ];
 
+/**
+ * Return the Sabbat whose date range contains `now`.
+ * Used by the site chrome to display the current seasonal icon.
+ */
 export function getCurrentSabbat(now: Date = new Date()): Sabbat {
   const year = now.getFullYear();
   const getSabbatDate = (s: Sabbat, y: number) =>
diff --git a/src/lib/utils/slugify.ts b/src/lib/utils/slugify.ts
index ac8a2d5..01f29d1 100644
--- a/src/lib/utils/slugify.ts
+++ b/src/lib/utils/slugify.ts
@@ -1,3 +1,8 @@
+/**
+ * Convert a title to a URL-friendly slug.
+ * Lowercases, replaces non-alphanumeric runs with hyphens,
+ * strips leading/trailing hyphens. Matches Leaflet's slug logic.
+ */
 export function normalizeSlug(title: string): string {
   return title
     .toLowerCase()
diff --git a/src/routes/+page.server.ts b/src/routes/+page.server.ts
index 00bd672..69dae40 100644
--- a/src/routes/+page.server.ts
+++ b/src/routes/+page.server.ts
@@ -1,3 +1,11 @@
+/**
+ * Homepage server load.
+ *
+ * Fetches the AT Protocol profile and any cross-account verifications
+ * (Bluesky social verification records pointing at this DID).
+ * Cache is short (~1 min) so the profile reflects recent changes.
+ */
+
 import type { PageServerLoad } from "./$types";
 import type { Config } from "@sveltejs/adapter-vercel";
 import { fetchProfile } from "@ewanc26/atproto";
diff --git a/src/routes/.well-known/atproto-did/+server.ts b/src/routes/.well-known/atproto-did/+server.ts
index 8b29f38..4cc7996 100644
--- a/src/routes/.well-known/atproto-did/+server.ts
+++ b/src/routes/.well-known/atproto-did/+server.ts
@@ -1,3 +1,11 @@
+/**
+ * GET /.well-known/atproto-did
+ *
+ * AT Protocol DID discovery endpoint (did:plc → domain binding).
+ * Returns the site owner's DID as plain text so Bluesky and other
+ * AT Protocol services can verify domain ownership.
+ */
+
 import type { RequestHandler } from "./$types";
 import { PUBLIC_ATPROTO_DID } from "$env/static/public";
 
diff --git a/src/routes/.well-known/site.standard.publication/+server.ts b/src/routes/.well-known/site.standard.publication/+server.ts
index ae821aa..bbd0f4b 100644
--- a/src/routes/.well-known/site.standard.publication/+server.ts
+++ b/src/routes/.well-known/site.standard.publication/+server.ts
@@ -1,3 +1,12 @@
+/**
+ * GET /.well-known/site.standard.publication
+ *
+ * Standard.site publication discovery endpoint.
+ * Returns the AT Protocol URI for the blog publication record,
+ * enabling Standard.site ecosystem tools to link back to the
+ * canonical publication source.
+ */
+
 import type { RequestHandler } from "./$types";
 import {
   PUBLIC_ATPROTO_DID,
diff --git a/src/routes/about/+page.server.ts b/src/routes/about/+page.server.ts
index 8dd9db1..5072514 100644
--- a/src/routes/about/+page.server.ts
+++ b/src/routes/about/+page.server.ts
@@ -1,3 +1,13 @@
+/**
+ * About page server load.
+ *
+ * Fetches all profile data (AT Protocol profile, SIFA skills/education/
+ * languages/external accounts/projects) concurrently with per-call error
+ * fallbacks so a single upstream failure doesn't blank the page.
+ * The SIFA data uses SvelteKit streaming (lazy promise) to unblock
+ * the initial shell render.
+ */
+
 import type { PageServerLoad } from "./$types";
 import type { Config } from "@sveltejs/adapter-vercel";
 import {
diff --git a/src/routes/blog/+page.server.ts b/src/routes/blog/+page.server.ts
index 6afa567..cb48aff 100644
--- a/src/routes/blog/+page.server.ts
+++ b/src/routes/blog/+page.server.ts
@@ -1,3 +1,11 @@
+/**
+ * Blog index server load.
+ *
+ * Groups posts by year → month and returns an initial page for client-side
+ * pagination. Uses a flat slice for the first load so the initial render
+ * is fast regardless of the total post count.
+ */
+
 import type { PageServerLoad } from "./$types";
 import type { Config } from "@sveltejs/adapter-vercel";
 import { fetchBlogPosts, fetchPublications } from "@ewanc26/atproto";
diff --git a/src/routes/projects/+page.server.ts b/src/routes/projects/+page.server.ts
index 7150b07..bf72462 100644
--- a/src/routes/projects/+page.server.ts
+++ b/src/routes/projects/+page.server.ts
@@ -1,3 +1,7 @@
+/**
+ * Redirect /projects to the external docs site.
+ * Projects are managed via SIFA and rendered on docs.ewancroft.uk.
+ */
 import { redirect } from "@sveltejs/kit";
 
 export const load = () => redirect(301, "https://docs.ewancroft.uk");
diff --git a/src/routes/projects/[slug]/+page.server.ts b/src/routes/projects/[slug]/+page.server.ts
index 7150b07..98f9aa8 100644
--- a/src/routes/projects/[slug]/+page.server.ts
+++ b/src/routes/projects/[slug]/+page.server.ts
@@ -1,3 +1,6 @@
+/**
+ * Redirect individual project slugs to the external docs site.
+ */
 import { redirect } from "@sveltejs/kit";
 
 export const load = () => redirect(301, "https://docs.ewancroft.uk");
diff --git a/src/routes/subscriptions/+page.server.ts b/src/routes/subscriptions/+page.server.ts
index 67115f7..56bb6b9 100644
--- a/src/routes/subscriptions/+page.server.ts
+++ b/src/routes/subscriptions/+page.server.ts
@@ -1,5 +1,11 @@
 import type { PageServerLoad } from "./$types";
 
+/**
+ * Subscriptions page — all data is fetched client-side via the
+ * /api/subscriptions and /api/recommendations endpoints to keep
+ * the initial server response lightweight. These API routes handle
+ * their own caching and DID resolution.
+ */
 export const load: PageServerLoad = async () => {
   return {};
 };
diff --git a/src/routes/webhook/+server.ts b/src/routes/webhook/+server.ts
index 620fa02..6099efc 100644
--- a/src/routes/webhook/+server.ts
+++ b/src/routes/webhook/+server.ts
@@ -1,3 +1,11 @@
+/**
+ * POST /webhook — Ko-fi webhook receiver.
+ *
+ * Parses Ko-fi donation/subscription events and persists them to
+ * the AT Protocol PDS using @ewanc26/supporters. Private donations
+ * are silently accepted (200) but not recorded.
+ */
+
 import { json } from "@sveltejs/kit";
 import { env } from "$env/dynamic/private";
 import { parseWebhook, WebhookError, appendEvent } from "@ewanc26/supporters";
diff --git a/src/routes/webhook/github/+server.ts b/src/routes/webhook/github/+server.ts
index bca74b0..25c5e62 100644
--- a/src/routes/webhook/github/+server.ts
+++ b/src/routes/webhook/github/+server.ts
@@ -1,3 +1,11 @@
+/**
+ * POST /webhook/github — GitHub Sponsors webhook receiver.
+ *
+ * Handles sponsorship lifecycle events (created, cancelled, tier changes).
+ * Respects sponsor privacy and skips pending/transitional states that
+ * should not produce records.
+ */
+
 import { json } from "@sveltejs/kit";
 import { env } from "$env/dynamic/private";
 import {
-- 
2.51.2