From ff53c7048bf510d18c32125f5d3a31056df0913c Mon Sep 17 00:00:00 2001
From: eti <eti@eti.tf>
Date: Tue, 1 Sep 2026 23:12:06 +0200
Subject: [PATCH] web: sweep the comments

Signed-off-by: eti <eti@eti.tf>
---
 web/src/app.css                               | 19 -----
 web/src/lib/api/collaborator.ts               |  2 -
 web/src/lib/api/fileHistory.ts                |  5 --
 web/src/lib/api/repo.ts                       |  3 -
 web/src/lib/api/repoIndex.ts                  |  1 -
 web/src/lib/auth.svelte.ts                    |  2 +
 .../comment/CommentCard.stories.svelte        |  4 -
 web/src/lib/components/icons/Bluesky.svelte   |  3 -
 .../icons/UserRoundArrowForward.svelte        |  4 +-
 .../moderation/ReportDialog.stories.svelte    |  3 -
 .../components/moderation/ReportDialog.svelte |  5 --
 .../moderation/ReportItems.stories.svelte     |  6 --
 .../components/moderation/reporting.svelte.ts |  1 -
 .../notifications/NotificationBell.svelte     |  7 --
 .../NotificationItem.stories.svelte           |  1 -
 .../notifications/NotificationItem.svelte     |  2 -
 .../notifications/NotificationList.svelte     |  2 -
 .../notifications/NotificationToolbar.svelte  |  1 -
 .../components/notifications/notification.ts  |  3 -
 web/src/lib/components/notifications/types.ts |  4 -
 .../profile/VouchButton.stories.svelte        |  6 --
 .../lib/components/profile/VouchButton.svelte |  1 -
 web/src/lib/components/repo/BlobHeader.svelte |  2 +-
 web/src/lib/components/repo/CommitList.svelte |  3 -
 .../repo/CommitLogView.stories.svelte         |  2 -
 .../components/repo/CommitRow.stories.svelte  |  2 -
 web/src/lib/components/repo/CommitRow.svelte  |  3 -
 web/src/lib/components/repo/EmptyRepo.svelte  |  5 --
 .../repo/FileHistoryView.stories.svelte       |  2 -
 .../lib/components/repo/RefSelector.svelte    |  2 -
 .../repo/RepoIndexView.stories.svelte         |  1 -
 .../components/repo/StarButton.stories.svelte |  4 -
 web/src/lib/components/repo/StarButton.svelte |  2 -
 .../repo/SubscribeButton.stories.svelte       |  7 --
 .../components/repo/SubscribeButton.svelte    |  1 -
 .../repo/pipelines/Elapsed.stories.svelte     |  5 --
 .../components/repo/pipelines/Elapsed.svelte  |  3 -
 .../repo/pipelines/PipelineCardContent.svelte |  4 -
 .../repo/pipelines/PipelineEmptyState.svelte  |  2 -
 .../pipelines/PipelineList.stories.svelte     |  2 -
 .../repo/pipelines/PipelineList.svelte        |  1 -
 .../pipelines/PipelineSearch.stories.svelte   |  1 -
 .../repo/pipelines/PipelineSearch.svelte      |  3 -
 .../repo/pipelines/PipelineStatusIcon.svelte  |  3 -
 .../repo/pipelines/PipelineSymbol.svelte      |  7 +-
 .../repo/pipelines/PipelineToolbar.svelte     |  4 -
 .../PipelineWorkflows.stories.svelte          |  3 -
 .../repo/pipelines/PipelineWorkflows.svelte   | 13 ---
 .../pipelines/StepStatusIcon.stories.svelte   |  2 -
 .../repo/pipelines/StepStatusIcon.svelte      |  4 -
 .../pipelines/WorkflowLogs.stories.svelte     | 23 -----
 .../repo/pipelines/WorkflowLogs.svelte        | 44 ----------
 .../pipelines/WorkflowSidebar.stories.svelte  |  3 -
 .../repo/pipelines/WorkflowSidebar.svelte     | 11 ---
 .../pipelines/WorkflowSteps.stories.svelte    | 17 ----
 .../repo/pipelines/WorkflowSteps.svelte       | 13 ---
 .../pipelines/WorkflowView.stories.svelte     | 13 ---
 .../repo/pipelines/WorkflowView.svelte        |  2 -
 web/src/lib/components/repo/pipelines/logs.ts |  4 -
 .../lib/components/repo/pipelines/pipeline.ts | 11 ---
 .../repo/pulls/PullApproveCi.svelte           | 17 ----
 .../lib/components/repo/pulls/PullDiff.svelte |  3 +-
 .../repo/tickets/Ticket.stories.svelte        |  2 -
 web/src/lib/components/repo/types.ts          |  6 --
 .../lib/components/settings/DocsButton.svelte |  2 -
 .../lib/components/settings/DrillDown.svelte  |  3 -
 .../components/settings/FormActions.svelte    |  2 -
 .../lib/components/settings/FormRow.svelte    |  4 -
 .../components/settings/SettingsBlock.svelte  |  4 -
 .../components/settings/SettingsEmpty.svelte  |  2 -
 .../components/settings/SettingsEntry.svelte  |  3 -
 .../components/settings/SettingsList.svelte   |  5 --
 .../settings/SettingsNav.stories.svelte       |  4 -
 .../components/settings/SettingsNav.svelte    |  4 -
 .../settings/SettingsPanel.stories.svelte     |  2 -
 .../components/settings/SettingsPanel.svelte  |  3 -
 .../components/settings/SettingsRow.svelte    | 10 ---
 .../settings/SettingsSection.svelte           |  2 -
 .../settings/SettingsToolbar.svelte           |  1 -
 .../components/settings/ThemePicker.svelte    |  2 -
 .../components/settings/ThemePreview.svelte   | 12 ---
 .../settings/tabs/ProfileTab.svelte           |  3 -
 web/src/lib/components/ui/Avatar.svelte       |  6 --
 web/src/lib/components/ui/Button.svelte       | 11 +--
 web/src/lib/components/ui/ButtonGroup.svelte  |  7 --
 web/src/lib/components/ui/ColorBall.svelte    |  2 -
 web/src/lib/components/ui/Combobox.svelte     | 11 ---
 web/src/lib/components/ui/CopyButton.svelte   |  3 -
 web/src/lib/components/ui/Dropdown.svelte     |  5 --
 web/src/lib/components/ui/Field.svelte        |  2 -
 web/src/lib/components/ui/Input.svelte        | 15 ----
 web/src/lib/components/ui/Link.svelte         |  2 -
 .../lib/components/ui/MarkdownEditor.svelte   |  2 -
 web/src/lib/components/ui/Modal.svelte        |  9 +-
 web/src/lib/components/ui/MoreMenu.svelte     |  8 --
 web/src/lib/components/ui/MorphIcon.svelte    |  4 -
 web/src/lib/components/ui/Select.svelte       | 12 ---
 web/src/lib/components/ui/ShimmerText.svelte  |  9 --
 web/src/lib/components/ui/Tabs.svelte         |  8 --
 web/src/lib/components/ui/TagInput.svelte     | 85 +------------------
 web/src/lib/components/ui/Textarea.svelte     | 10 +--
 web/src/lib/components/ui/Tooltip.svelte      | 22 +----
 web/src/lib/components/ui/User.svelte         |  3 -
 web/src/lib/components/ui/inputField.ts       | 11 ---
 web/src/lib/components/ui/selectField.ts      |  8 --
 .../lib/components/welcome/FinishStep.svelte  |  3 -
 .../lib/components/welcome/SocialStep.svelte  |  1 -
 .../lib/components/welcome/StepHeader.svelte  |  1 -
 web/src/lib/components/welcome/Steps.svelte   |  5 --
 .../lib/components/welcome/WelcomeCard.svelte |  6 --
 web/src/lib/components/welcome/steps.ts       |  1 -
 web/src/lib/format.ts                         |  2 -
 web/src/lib/motion/spring.ts                  | 18 ++--
 web/src/lib/optimistic.svelte.ts              |  1 -
 web/src/lib/popoverExit.ts                    |  2 -
 web/src/routes/+layout.svelte                 |  1 -
 .../[repo]/history/[ref]/[...path]/+page.ts   |  5 --
 .../[[range]]/PullViewPage.stories.svelte     | 39 ---------
 .../[version]/[[range]]/PullViewPage.svelte   | 17 ++--
 .../[repo]/settings/hooks/new/+page.svelte    |  2 +-
 .../[repo]/settings/sites/+page.svelte        |  2 +-
 web/src/routes/favicon.svg/+server.ts         |  2 -
 web/src/routes/notifications/+page.svelte     |  5 --
 web/src/routes/settings/+layout.svelte        |  1 -
 .../settings/profile/handle/+page.svelte      |  2 -
 web/src/routes/welcome/+page.svelte           |  2 -
 126 files changed, 27 insertions(+), 761 deletions(-)

diff --git a/web/src/app.css b/web/src/app.css
index 898558b6e..306d16cd9 100644
--- a/web/src/app.css
+++ b/web/src/app.css
@@ -3,8 +3,6 @@
 @import "./pierre.css";
 @import "./logs.css";
 
-/* dark follows the system unless an ancestor pins the theme, so Storybook (and
-   later the theme setting) can force either mode with data-theme on <html> */
 @custom-variant dark {
 	@media (prefers-color-scheme: dark) {
 		&:where(:not([data-theme="light"], [data-theme="light"] *)) {
@@ -24,13 +22,6 @@
 
 	--font-sans--font-feature-settings: "kern" 1, "liga" 1, "cv05" 1, "tnum" 1;
 
-	/* =========================================================================
-	   Semantic color tokens — synced from Figma "Design System" › semantic colors
-	   Names mirror the Figma variables verbatim (`/` → `-`). Light-mode values
-	   here; dark-mode overrides live in the dark variant block below.
-	   ========================================================================= */
-
-	/* --- background --- */
 	--color-background-default: #ffffff;
 	--color-background-subtle: #f9fafb;
 	--color-background-inset: #f3f4f6;
@@ -61,7 +52,6 @@
 	--color-background-navigation-frame: #f9fafb;
 	--color-background-navigation-item: #ffffff;
 
-	/* --- foreground --- */
 	--color-foreground-default: #111827;
 	--color-foreground-muted: #4b5563;
 	--color-foreground-subtle: #6b7280;
@@ -94,7 +84,6 @@
 	--color-foreground-link-info: #4f46e5;
 	--color-foreground-link-info-hover: #6366f1;
 
-	/* --- border --- */
 	--color-border-default: #e5e7eb;
 	--color-border-subtle: #f3f4f6;
 	--color-border-strong: #d1d5db;
@@ -107,21 +96,18 @@
 	--color-border-danger-subtle: #fecaca;
 	--color-border-navigation-item-active: #e5e7eb;
 
-	/* --- shadow (inner depth, eg.: for the button component) --- */
 	--color-shadow-inner-strong: #d1d5db;
 	--color-shadow-inner-strong-hover: #d1d5db;
 	--color-shadow-inner-subtle: #e5e7eb;
 	--color-shadow-ambient-strong: var(--color-alpha-dark-10);
 	--color-shadow-ambient-subtle: var(--color-alpha-dark-5);
 
-	/* --- shadow --- */
 	--shadow-small: 0 2px 4px var(--color-shadow-ambient-strong);
 	--shadow-regular:
 		0 4px 12px var(--color-shadow-ambient-subtle), 0 2px 4px var(--color-shadow-ambient-subtle);
 	--shadow-large:
 		0 6px 16px var(--color-shadow-ambient-subtle), 0 4px 6px var(--color-shadow-ambient-subtle);
 
-	/* --- alpha --- */
 	--color-alpha-light-5: color-mix(in srgb, var(--color-background-default) 5%, transparent);
 	--color-alpha-light-10: color-mix(in srgb, var(--color-background-default) 10%, transparent);
 	--color-alpha-light-15: color-mix(in srgb, var(--color-background-default) 15%, transparent);
@@ -181,7 +167,6 @@
 	--color-ansi-bright-cyan: #04a5e5;
 	--color-ansi-bright-white: #bcc0cc;
 
-	/* --- animations --- */
 	--animate-spin-step: spin-step 2.5s infinite;
 
 	@keyframes spin-step {
@@ -445,7 +430,6 @@
 
 	:root {
 		@variant dark {
-			/* --- background (Dark) --- */
 			--color-background-default: #1f2937;
 			--color-background-subtle: #374151;
 			--color-background-inset: #374151;
@@ -473,7 +457,6 @@
 			--color-background-navigation-frame: #1f2937;
 			--color-background-navigation-item: #374151;
 
-			/* --- foreground (Dark) --- */
 			--color-foreground-default: #f3f4f6;
 			--color-foreground-muted: #9ca3af;
 			--color-foreground-subtle: #6b7280;
@@ -505,7 +488,6 @@
 			--color-foreground-link-info: #6366f1;
 			--color-foreground-link-info-hover: #818cf8;
 
-			/* --- border (Dark) --- */
 			--color-border-default: #374151;
 			--color-border-subtle: #2d3643;
 			--color-border-strong: #6b7280;
@@ -517,7 +499,6 @@
 			--color-border-danger: #991b1b;
 			--color-border-navigation-item-active: #4b5563;
 
-			/* --- shadow (Dark) --- */
 			--color-shadow-inner-strong: #030712;
 			--color-shadow-inner-strong-hover: #1f2937;
 			--color-shadow-inner-subtle: #111827;
diff --git a/web/src/lib/api/collaborator.ts b/web/src/lib/api/collaborator.ts
index 0b30bb04e..c3fb713dd 100644
--- a/web/src/lib/api/collaborator.ts
+++ b/web/src/lib/api/collaborator.ts
@@ -2,8 +2,6 @@ import type { Did } from "@atcute/lexicons/syntax";
 import type { BobbinContext } from "./client";
 import { items } from "./pagination";
 
-// the appview guards every write on a repo with `repo:push`, which the owner always
-// holds and everyone else earns through a collaborator record
 export const resolvePushAccess = async (
 	ctx: BobbinContext,
 	repo: { ownerDid: string; repoDid?: string },
diff --git a/web/src/lib/api/fileHistory.ts b/web/src/lib/api/fileHistory.ts
index dc312a939..7f64df1aa 100644
--- a/web/src/lib/api/fileHistory.ts
+++ b/web/src/lib/api/fileHistory.ts
@@ -67,7 +67,6 @@ const seedOf = (key: string): number => {
 	return hash >>> 0;
 };
 
-// mulberry32, so one path always invents the same history
 const random = (seed: number) => {
 	let state = seed;
 	return () => {
@@ -80,10 +79,6 @@ const random = (seed: number) => {
 
 const DAY_MS = 86_400_000;
 
-/**
- * an invented history for one path: deterministic in `${repo}:${path}`, newest
- * first, spread over enough months to group and often long enough to paginate
- */
 export const mockFileHistory = (
 	repo: string,
 	path: string,
diff --git a/web/src/lib/api/repo.ts b/web/src/lib/api/repo.ts
index 8f882be07..3e4520156 100644
--- a/web/src/lib/api/repo.ts
+++ b/web/src/lib/api/repo.ts
@@ -151,10 +151,7 @@ export interface CommitSummary {
 	body: string;
 	authorName: string;
 	authorEmail: string;
-	// a commit made through tangled signs with the author's did instead of an
-	// email, so unlike a git name that author is an account we can link to
 	authorDid?: string;
-	// filled in by the loader, since resolving the did takes a round trip
 	authorHandle?: string;
 	when: string;
 	changeId?: string;
diff --git a/web/src/lib/api/repoIndex.ts b/web/src/lib/api/repoIndex.ts
index 3fd79073f..646d3822c 100644
--- a/web/src/lib/api/repoIndex.ts
+++ b/web/src/lib/api/repoIndex.ts
@@ -123,7 +123,6 @@ export interface RepoIndexOptions {
 	requireRef?: boolean;
 }
 
-// a did-signed commit points at a real account, so trade the git author name
 // for the handle and the row reads like the rest of the site. a plain git
 // email that belongs to a verified signup resolves to that same did first, so
 // those rows get the identical treatment.
diff --git a/web/src/lib/auth.svelte.ts b/web/src/lib/auth.svelte.ts
index 2b6cda536..8a7e520e9 100644
--- a/web/src/lib/auth.svelte.ts
+++ b/web/src/lib/auth.svelte.ts
@@ -173,6 +173,7 @@ const resolveProfile = async (
 	} catch {
 		// try local resolver next.
 	}
+	} catch {}
 
 	try {
 		const identity = await identityResolver.resolve(identifier as ActorIdentifier);
@@ -326,6 +327,7 @@ export const createAuth = (
 				} catch {
 					// fall through to the inline error
 				}
+				} catch {}
 			}
 			throw new Error(`${handle}'s session expired. Sign in again to act as them.`, {
 				cause
diff --git a/web/src/lib/components/comment/CommentCard.stories.svelte b/web/src/lib/components/comment/CommentCard.stories.svelte
index 3fadebeae..376d9d818 100644
--- a/web/src/lib/components/comment/CommentCard.stories.svelte
+++ b/web/src/lib/components/comment/CommentCard.stories.svelte
@@ -61,7 +61,6 @@
 	}}
 />
 
-<!-- logged in to several accounts: the reply box carries an account picker -->
 <Story
 	name="Replying with several accounts"
 	parameters={{ auth: { accounts: 2 } }}
@@ -77,8 +76,6 @@
 	}}
 />
 
-<!-- someone else's reply, with a moderation service configured: the actions row offers a
-	report menu instead of edit/delete -->
 <Story
 	name="Reporting a reply"
 	parameters={{
@@ -100,7 +97,6 @@
 	}}
 />
 
-<!-- an edit keeps the record's author, so no picker even with several accounts -->
 <Story
 	name="Editing with several accounts"
 	args={{ thread: myThread }}
diff --git a/web/src/lib/components/icons/Bluesky.svelte b/web/src/lib/components/icons/Bluesky.svelte
index 72be9924c..38304406d 100644
--- a/web/src/lib/components/icons/Bluesky.svelte
+++ b/web/src/lib/components/icons/Bluesky.svelte
@@ -1,7 +1,4 @@
 <script lang="ts">
-	// lucide carries no Bluesky mark, so this is the vector the appview already
-	// ships at appview/pages/static/icons/bluesky.svg — kept identical so both
-	// front ends draw the same butterfly.
 	import type { SVGAttributes } from "svelte/elements";
 
 	let { class: className = "size-4", ...rest }: SVGAttributes<SVGSVGElement> = $props();
diff --git a/web/src/lib/components/icons/UserRoundArrowForward.svelte b/web/src/lib/components/icons/UserRoundArrowForward.svelte
index 8ba3d47b7..77462c12d 100644
--- a/web/src/lib/components/icons/UserRoundArrowForward.svelte
+++ b/web/src/lib/components/icons/UserRoundArrowForward.svelte
@@ -1,7 +1,5 @@
 <script lang="ts">
-	// lucide has no assign mark, so this is the vector the appview already ships at
-	// icons/user-round-arrow-forward.svg — kept identical so both front ends draw
-	// the same glyph.
+	// lucide has no assign mark
 	import type { SVGAttributes } from "svelte/elements";
 
 	let { class: className = "size-4", ...rest }: SVGAttributes<SVGSVGElement> = $props();
diff --git a/web/src/lib/components/moderation/ReportDialog.stories.svelte b/web/src/lib/components/moderation/ReportDialog.stories.svelte
index 8697e1a37..a1915da11 100644
--- a/web/src/lib/components/moderation/ReportDialog.stories.svelte
+++ b/web/src/lib/components/moderation/ReportDialog.stories.svelte
@@ -11,14 +11,12 @@
 
 	const spam = "tools.ozone.report.defs#reasonMisleadingSpam";
 
-	// the reason field is a Combobox: a trigger button over a listbox popover
 	const pickReason = async () => {
 		await userEvent.click(screen.getByLabelText(/reason/i));
 		await userEvent.click(await screen.findByRole("option", { name: "Spam" }));
 	};
 	const details = "Posting the same link on every issue.";
 
-	// what the labeler answers with once it accepted the report
 	const reportAccepted = () =>
 		Response.json({
 			id: 4127,
@@ -47,7 +45,6 @@
 	});
 </script>
 
-<!-- Modal portals the dialog onto <body>, so the queries are document-wide, not canvas-scoped -->
 <Story name="Record" />
 
 <Story
diff --git a/web/src/lib/components/moderation/ReportDialog.svelte b/web/src/lib/components/moderation/ReportDialog.svelte
index 154268f16..ac6b2d2a0 100644
--- a/web/src/lib/components/moderation/ReportDialog.svelte
+++ b/web/src/lib/components/moderation/ReportDialog.svelte
@@ -42,16 +42,11 @@
 		sent = false;
 	};
 
-	// a new target starts a fresh form, but a dismissed one keeps its draft: clicking
-	// outside is easy to do by accident, and it should not eat what you typed
 	$effect(() => {
 		void subject;
 		clear();
 	});
 
-	// clearing on close would swap the form back in behind the panel while it is
-	// still fading out, so a sent report keeps its confirmation and resets on the
-	// way back in
 	let showing = false;
 	$effect(() => {
 		if (open && !showing && sent) clear();
diff --git a/web/src/lib/components/moderation/ReportItems.stories.svelte b/web/src/lib/components/moderation/ReportItems.stories.svelte
index 4c9b1014f..2804ff650 100644
--- a/web/src/lib/components/moderation/ReportItems.stories.svelte
+++ b/web/src/lib/components/moderation/ReportItems.stories.svelte
@@ -20,7 +20,6 @@
 	});
 </script>
 
-<!-- the items only make sense inside a menu, so every story wears one -->
 {#snippet template(args: ComponentProps<typeof ReportItems>)}
 	<MoreMenu label="More actions for @bob.pds.tngl.boltless.dev">
 		<ReportItems {...args} />
@@ -29,7 +28,6 @@
 
 <Story name="Default" {template} />
 
-<!-- one popover opening another: the dialog has to survive the click that picked the item -->
 <Story
 	name="Opens the dialog"
 	{template}
@@ -37,7 +35,6 @@
 		const canvas = within(canvasElement);
 		await userEvent.click(canvas.getByRole("button", { name: /more actions/i }));
 		await userEvent.click(canvas.getByRole("menuitem", { name: /report comment/i }));
-		// Modal portals the dialog onto <body>, out of the story canvas
 		const dialog = await waitFor(() => {
 			const el = screen.getByRole("dialog", { hidden: true });
 			expect(el).toBeVisible();
@@ -48,7 +45,6 @@
 	}}
 />
 
-<!-- the noun names the reported thing, on the menu item and in the dialog title -->
 <Story name="Reply" {template} args={{ subjectNoun: "reply" }} />
 
 <Story
@@ -69,7 +65,6 @@
 	}}
 />
 
-<!-- no labelerDid prop: the moderation service comes from the site config -->
 <Story
 	name="Labeler from site config"
 	{template}
@@ -81,7 +76,6 @@
 	}}
 />
 
-<!-- without a record ref only the account can be reported, like on a profile -->
 <Story name="Account only" {template} args={{ subjectUri: undefined, subjectCid: undefined }} />
 
 <Story name="Own comment" {template} args={{ authorDid: "did:plc:alice" }} />
diff --git a/web/src/lib/components/moderation/reporting.svelte.ts b/web/src/lib/components/moderation/reporting.svelte.ts
index 6cb2479e3..f961baa51 100644
--- a/web/src/lib/components/moderation/reporting.svelte.ts
+++ b/web/src/lib/components/moderation/reporting.svelte.ts
@@ -6,7 +6,6 @@ export interface Reporting {
 	canReport(authorDid: string): boolean;
 }
 
-/** Call at component init: reads the auth context. */
 export const createReporting = (labelerDid?: () => string | undefined): Reporting => {
 	const auth = getAuth();
 	const labeler = $derived(
diff --git a/web/src/lib/components/notifications/NotificationBell.svelte b/web/src/lib/components/notifications/NotificationBell.svelte
index de85e787c..10a65f140 100644
--- a/web/src/lib/components/notifications/NotificationBell.svelte
+++ b/web/src/lib/components/notifications/NotificationBell.svelte
@@ -30,7 +30,6 @@
 
 	const auth = getAuth();
 
-	// the appview preview serves five rows and sends the rest to the full page
 	const PREVIEW_LIMIT = 5;
 
 	let readFilter = $state<ReadFilter>("unread");
@@ -66,13 +65,9 @@
 		notifications.map((n) => (n.uri in overrides ? { ...n, read: overrides[n.uri] } : n))
 	);
 
-	// the badge counts everything unread, not the rows this filter shows
 	const unreadCount = $derived(totalUnread);
 	const badge = $derived(unreadCount > 99 ? "99+" : String(unreadCount));
 
-	// the unread tab filters on the data as it loaded, never on the local read
-	// state, so toggling a row restyles it in place instead of dropping it out of
-	// the list under the cursor.
 	const unreadOnLoad = $derived(new Set(notifications.filter((n) => !n.read).map((n) => n.uri)));
 
 	const filtered = $derived(
@@ -107,7 +102,6 @@
 		await markAllNotificationsRead(deliberi).catch(() => {});
 	};
 
-	// the popover survives a client-side navigation unless something closes it
 	const dismiss = (event: MouseEvent & { currentTarget: HTMLAnchorElement }) => {
 		const popover = event.currentTarget.closest("[popover]");
 		if (popover instanceof HTMLElement) popover.hidePopover();
@@ -133,7 +127,6 @@
 	{/if}
 {/snippet}
 
-<!-- the popover needs the room a phone does not have, so mobile goes to the page -->
 <div class="relative flex md:hidden">
 	<Button
 		variant="ghost"
diff --git a/web/src/lib/components/notifications/NotificationItem.stories.svelte b/web/src/lib/components/notifications/NotificationItem.stories.svelte
index aba405774..8b0f488ab 100644
--- a/web/src/lib/components/notifications/NotificationItem.stories.svelte
+++ b/web/src/lib/components/notifications/NotificationItem.stories.svelte
@@ -21,7 +21,6 @@
 
 	const read = (n: NotificationSummary): NotificationSummary => ({ ...n, read: true });
 
-	// a row is a subgrid of NotificationList's columns, so it needs that grid around it
 	const frame =
 		"grid grid-cols-[auto_1fr_auto] gap-x-4 divide-y divide-border-default overflow-hidden rounded-sm border border-border-default";
 
diff --git a/web/src/lib/components/notifications/NotificationItem.svelte b/web/src/lib/components/notifications/NotificationItem.svelte
index 35188519d..97befedfc 100644
--- a/web/src/lib/components/notifications/NotificationItem.svelte
+++ b/web/src/lib/components/notifications/NotificationItem.svelte
@@ -65,8 +65,6 @@
 
 	const toggle = () => onToggleRead?.(notification.uri, !notification.read);
 
-	// client-side navigation leaves a popover open, so a row inside the topbar
-	// dropdown has to dismiss it on the way out
 	const open = (event: MouseEvent & { currentTarget: HTMLAnchorElement }) => {
 		onToggleRead?.(notification.uri, true);
 		const popover = event.currentTarget.closest("[popover]");
diff --git a/web/src/lib/components/notifications/NotificationList.svelte b/web/src/lib/components/notifications/NotificationList.svelte
index 8d03ff2df..757faaa19 100644
--- a/web/src/lib/components/notifications/NotificationList.svelte
+++ b/web/src/lib/components/notifications/NotificationList.svelte
@@ -12,8 +12,6 @@
 		title?: string;
 		unreadCount?: number;
 		readFilter?: ReadFilter;
-		// the dropdown draws its own frame around the list, and a five-row preview
-		// is too short for the date headings to earn their space
 		border?: boolean;
 		grouped?: boolean;
 		onToggleRead?: (uri: string, read: boolean) => void;
diff --git a/web/src/lib/components/notifications/NotificationToolbar.svelte b/web/src/lib/components/notifications/NotificationToolbar.svelte
index 982d624a0..473fc40cf 100644
--- a/web/src/lib/components/notifications/NotificationToolbar.svelte
+++ b/web/src/lib/components/notifications/NotificationToolbar.svelte
@@ -15,7 +15,6 @@
 		categoryFilter?: CategoryFilter;
 		hasNotifications?: boolean;
 		preferences?: boolean;
-		// the page navigates between filters, the dropdown swaps them in place
 		onReadFilter?: (filter: ReadFilter) => void;
 		onCategoryFilter?: (filter: CategoryFilter) => void;
 		onMarkAllRead?: () => void;
diff --git a/web/src/lib/components/notifications/notification.ts b/web/src/lib/components/notifications/notification.ts
index f32c14b75..2ee90b031 100644
--- a/web/src/lib/components/notifications/notification.ts
+++ b/web/src/lib/components/notifications/notification.ts
@@ -126,7 +126,6 @@ export const notificationPhrase = (notification: NotificationSummary): string =>
 	return PHRASES[notification.type];
 };
 
-// the subject of the phrase, which the appview prints as owner/name after it
 export const notificationTarget = (notification: NotificationSummary): string =>
 	notification.knot?.domain ??
 	(notification.repo ? `${notification.repo.ownerHandle}/${notification.repo.name}` : "");
@@ -144,8 +143,6 @@ export const notificationHref = (notification: NotificationSummary): string => {
 	return `${base}/${subject.kind === "issue" ? "issues" : "pulls"}/${subject.uri}`;
 };
 
-// today, the six days before it, then everything older, same buckets the go page
-// builds in GroupNotificationsByDate
 export const groupNotificationsByDate = (
 	notifications: NotificationSummary[],
 	now: Date = new Date()
diff --git a/web/src/lib/components/notifications/types.ts b/web/src/lib/components/notifications/types.ts
index ca497ff46..d081ca25c 100644
--- a/web/src/lib/components/notifications/types.ts
+++ b/web/src/lib/components/notifications/types.ts
@@ -7,10 +7,6 @@ export type DidRkey = Did & { readonly [didRkey]: true };
 export const parseDidRkey = (did: string | undefined): DidRkey | undefined =>
 	did !== undefined && isDid(did) && isRecordKey(did) ? (did as DidRkey) : undefined;
 
-// mirrors org.tangled.temp.notification.listNotifications#notification, plus the
-// repo and issue/pull details the appview page renders. the xrpc method only
-// hands back at-uris for those, so a real loader has to hydrate them from bobbin
-// before it can build this shape.
 export type NotificationType =
 	| "repo_starred"
 	| "followed"
diff --git a/web/src/lib/components/profile/VouchButton.stories.svelte b/web/src/lib/components/profile/VouchButton.stories.svelte
index 56a590a91..31e20e9de 100644
--- a/web/src/lib/components/profile/VouchButton.stories.svelte
+++ b/web/src/lib/components/profile/VouchButton.stories.svelte
@@ -9,10 +9,7 @@
 	// spinner swap can be asserted
 	const hang = () => new Promise<Response>(() => {});
 
-	// opens the modal, selects the "Vouch" choice (so save hits putVouch rather
 	// than the instant no-op of clearing an absent vouch), and clicks Save; returns
-	// the save button for further asserts. Modal portals onto <body>, so everything
-	// inside the panel is queried document-wide, not canvas-scoped.
 	const openAndSave = async (canvas: PlayContext["canvas"]) => {
 		const trigger = await canvas.findByRole("button", { name: "Vouch" });
 		await userEvent.click(trigger);
@@ -65,7 +62,6 @@
 	});
 </script>
 
-<!-- signed in, no existing vouch: neutral trigger, modal opens on "None" -->
 <Story name="Undecided" parameters={{ auth: true }}>
 	{#snippet template(args)}
 		<div class="w-64">
@@ -74,7 +70,6 @@
 	{/snippet}
 </Story>
 
-<!-- viewer has vouched: success trigger, modal preselects "Vouch" + reason -->
 <Story name="Vouched" parameters={{ auth: true }}>
 	{#snippet template(args)}
 		<div class="w-64">
@@ -90,7 +85,6 @@
 	{/snippet}
 </Story>
 
-<!-- viewer has denounced: danger trigger, modal preselects "Denounce" -->
 <Story name="Denounced" parameters={{ auth: true }}>
 	{#snippet template(args)}
 		<div class="w-64">
diff --git a/web/src/lib/components/profile/VouchButton.svelte b/web/src/lib/components/profile/VouchButton.svelte
index 81fc9099f..4559ce9db 100644
--- a/web/src/lib/components/profile/VouchButton.svelte
+++ b/web/src/lib/components/profile/VouchButton.svelte
@@ -19,7 +19,6 @@
 		profileDid: string;
 		profileLabel?: string;
 		initialVouch?: DirectVouch | null;
-		// indirect vouches from the viewer's network, shown inside the modal
 		networkVouches?: NetworkVouch[];
 		bordered?: boolean;
 		insetShadow?: boolean;
diff --git a/web/src/lib/components/repo/BlobHeader.svelte b/web/src/lib/components/repo/BlobHeader.svelte
index 9fe0a4b3d..319038f4e 100644
--- a/web/src/lib/components/repo/BlobHeader.svelte
+++ b/web/src/lib/components/repo/BlobHeader.svelte
@@ -82,7 +82,7 @@
 	<div class="flex flex-col gap-4 whitespace-nowrap md:flex-row md:items-center md:gap-2">
 		<div class="flex items-center gap-4 max-md:justify-between md:flex-row-reverse md:px-2">
 			{#if language && languageColor}
-				<div class="flex w-fit items-center px-1 md:px-0 gap-2 typography-paragraph-small">
+				<div class="flex w-fit items-center gap-2 px-1 typography-paragraph-small md:px-0">
 					<ColorBall color={languageColor} />
 					{language}
 				</div>
diff --git a/web/src/lib/components/repo/CommitList.svelte b/web/src/lib/components/repo/CommitList.svelte
index 69e8f1ad1..b197a50ae 100644
--- a/web/src/lib/components/repo/CommitList.svelte
+++ b/web/src/lib/components/repo/CommitList.svelte
@@ -65,9 +65,6 @@
 				>
 					{commit.shortHash}
 				</a>
-				<!-- an author we resolved to an account gets their handle and a link to
-				it. a plain email address resolves to nobody, so the git name stays and
-				the chip mails them instead, same as the commit log does -->
 				{#if commit.authorHandle}
 					<User did={commit.authorDid} handle={commit.authorHandle} size="small" link />
 				{:else if commit.authorName && commit.authorEmail && !commit.authorDid}
diff --git a/web/src/lib/components/repo/CommitLogView.stories.svelte b/web/src/lib/components/repo/CommitLogView.stories.svelte
index 9ff60bb33..0ebb7a344 100644
--- a/web/src/lib/components/repo/CommitLogView.stories.svelte
+++ b/web/src/lib/components/repo/CommitLogView.stories.svelte
@@ -20,7 +20,6 @@
 	type PlayContext = Pick<StoryContext<Record<string, unknown>>, "canvas">;
 
 	const firstPage = async ({ canvas }: PlayContext) => {
-		// Pagination spends its arrows with aria-disabled, never the attribute
 		await expect(canvas.getByRole("button", { name: "Previous page" })).toHaveAttribute(
 			"aria-disabled",
 			"true"
@@ -34,7 +33,6 @@
 		await userEvent.click(next);
 		await expect(onPageChange).toHaveBeenCalledWith(2);
 
-		// desktop and mobile rows each render the sha cluster
 		await expect(canvas.getAllByTitle("Copy SHA")).toHaveLength(commits.length * 2);
 		await expect(canvas.getAllByTitle("Browse repository at this commit")).toHaveLength(
 			commits.length * 2
diff --git a/web/src/lib/components/repo/CommitRow.stories.svelte b/web/src/lib/components/repo/CommitRow.stories.svelte
index ebbd4575f..4f6764336 100644
--- a/web/src/lib/components/repo/CommitRow.stories.svelte
+++ b/web/src/lib/components/repo/CommitRow.stories.svelte
@@ -18,7 +18,6 @@
 	type PlayContext = Pick<StoryContext<Record<string, unknown>>, "canvas">;
 
 	const cells = async ({ canvas }: PlayContext) => {
-		// desktop and mobile rows each render the sha cluster
 		await expect(canvas.getAllByTitle("Copy SHA")).toHaveLength(2);
 		const chip = canvas.getAllByRole("link", { name: commit.shortHash })[0];
 		await expect(chip).toHaveAttribute("href", `/dawn/tangled/commit/${commit.hash}`);
@@ -45,7 +44,6 @@
 		}
 	});
 
-	// a row is a subgrid of CommitRows' columns, so it needs that grid around it
 	const frame = "divide-y divide-border-default border-y border-border-default";
 </script>
 
diff --git a/web/src/lib/components/repo/CommitRow.svelte b/web/src/lib/components/repo/CommitRow.svelte
index c9f0cc7de..a3fb59698 100644
--- a/web/src/lib/components/repo/CommitRow.svelte
+++ b/web/src/lib/components/repo/CommitRow.svelte
@@ -39,9 +39,6 @@
 
 {#snippet author()}
 	<span class="flex min-w-0 items-center gap-1">
-		<!-- an author we resolved to an account gets their handle and a link to it.
-		a plain email address resolves to nobody, so the git name stays and the chip
-		mails them instead -->
 		{#if commit.authorHandle}
 			<User did={commit.authorDid} handle={commit.authorHandle} class="min-w-0" link />
 		{:else if commit.authorName && commit.authorEmail && !commit.authorDid}
diff --git a/web/src/lib/components/repo/EmptyRepo.svelte b/web/src/lib/components/repo/EmptyRepo.svelte
index 8bf7b3228..6a9024d06 100644
--- a/web/src/lib/components/repo/EmptyRepo.svelte
+++ b/web/src/lib/components/repo/EmptyRepo.svelte
@@ -8,10 +8,6 @@
 
 	interface Props {
 		repo: RepoInfo;
-		/**
-		 * Overrides the SSH key lookup, for deterministic stories/tests.
-		 * Left unset in real usage, in which case it's figured out from the API.
-		 */
 		hasSshKey?: boolean;
 	}
 
@@ -47,7 +43,6 @@
 			const result = await count(ctx, "sh.tangled.publicKey.countKeys", did);
 			return result.count > 0;
 		} catch {
-			// safe fallback: guide the owner through generating a key.
 			return false;
 		}
 	});
diff --git a/web/src/lib/components/repo/FileHistoryView.stories.svelte b/web/src/lib/components/repo/FileHistoryView.stories.svelte
index 727ad23e4..a5cf11f38 100644
--- a/web/src/lib/components/repo/FileHistoryView.stories.svelte
+++ b/web/src/lib/components/repo/FileHistoryView.stories.svelte
@@ -14,7 +14,6 @@
 		when
 	});
 
-	// two months so the grouping shows, newest first like the log itself
 	const commits = [
 		commit(1, "2026-08-29T09:00:00Z"),
 		commit(2, "2026-08-22T09:00:00Z"),
@@ -36,7 +35,6 @@
 		const path = canvas.getByRole("link", { name: "src/lib/index.ts" });
 		await expect(path).toHaveAttribute("href", "/dawn/tangled/blob/main/src/lib/index.ts");
 
-		// desktop and mobile rows each render the sha cluster
 		await expect(canvas.getAllByTitle("Copy SHA")).toHaveLength(commits.length * 2);
 		const chip = canvas.getAllByRole("link", { name: commits[0].shortHash })[0];
 		await expect(chip).toHaveAttribute("href", `/dawn/tangled/commit/${commits[0].hash}`);
diff --git a/web/src/lib/components/repo/RefSelector.svelte b/web/src/lib/components/repo/RefSelector.svelte
index 568099c80..58caa5ea1 100644
--- a/web/src/lib/components/repo/RefSelector.svelte
+++ b/web/src/lib/components/repo/RefSelector.svelte
@@ -31,8 +31,6 @@
 		}
 	});
 
-	// no counts in the headings: the knot caps how many refs it hands back, so the length here
-	// is the loaded count rather than the repo's total, and it would not track the filter either
 	const options = $derived<SelectOption[]>([
 		...branches.map((branch) => ({
 			value: branch,
diff --git a/web/src/lib/components/repo/RepoIndexView.stories.svelte b/web/src/lib/components/repo/RepoIndexView.stories.svelte
index e00b951d0..90ef46e58 100644
--- a/web/src/lib/components/repo/RepoIndexView.stories.svelte
+++ b/web/src/lib/components/repo/RepoIndexView.stories.svelte
@@ -176,7 +176,6 @@
 			repo,
 			data,
 			bobbinUrl: "https://bobbin.example.test",
-			// every third commit is left without a run, so all three cases show
 			pipelineStatuses: Promise.resolve(
 				pipelinesByCommitHash(commits.map((commit) => commit.hash))
 			)
diff --git a/web/src/lib/components/repo/StarButton.stories.svelte b/web/src/lib/components/repo/StarButton.stories.svelte
index b2874a3a9..15be805ca 100644
--- a/web/src/lib/components/repo/StarButton.stories.svelte
+++ b/web/src/lib/components/repo/StarButton.stories.svelte
@@ -41,16 +41,12 @@
 		await waitFor(() => expect(button).toBeEnabled());
 	};
 
-	// clicking star: the icon swaps to a spinner while the write is in flight, then the
-	// star swaps to star-off and the label crossfades to "Unstar"
 	const starring = async ({ canvas }: PlayContext) => {
 		const button = await canvas.findByRole("button", { name: "Star" });
 		await userEvent.click(button);
 		await waitFor(() => expect(canvas.getByRole("button", { name: "Unstar" })).toBeVisible());
 	};
 
-	// a hung write: the button commits to "Unstar" straight away and stays there while the
-	// write is still out, with only aria-busy reporting that it has not settled
 	const starringLoading = async ({ canvas }: PlayContext) => {
 		const button = await canvas.findByRole("button", { name: "Star" });
 		await userEvent.click(button);
diff --git a/web/src/lib/components/repo/StarButton.svelte b/web/src/lib/components/repo/StarButton.svelte
index 68ce73c6b..b322c7e98 100644
--- a/web/src/lib/components/repo/StarButton.svelte
+++ b/web/src/lib/components/repo/StarButton.svelte
@@ -107,7 +107,6 @@
 	const toggle = async () => {
 		const agent = auth.agent;
 		if (!agent || !relation.known || relation.loading || !repoDid) return;
-		// every read happens before begin(), which flips the relation to the intended state
 		const wasStarred = relation.active;
 		const existingRkey = relation.rkey;
 		const delta = wasStarred ? -1 : 1;
@@ -175,7 +174,6 @@
 </div>
 
 <style>
-	/* the three faces share one grid cell, so the icon never nudges the label as they swap */
 	.faces :global(.face) {
 		grid-column: 1;
 		grid-row: 1;
diff --git a/web/src/lib/components/repo/SubscribeButton.stories.svelte b/web/src/lib/components/repo/SubscribeButton.stories.svelte
index 197a4b23d..4fc116f4f 100644
--- a/web/src/lib/components/repo/SubscribeButton.stories.svelte
+++ b/web/src/lib/components/repo/SubscribeButton.stories.svelte
@@ -58,16 +58,11 @@
 
 	type PlayContext = Pick<StoryContext<Record<string, unknown>>, "canvas">;
 
-	// the two labels are layered in one grid cell so the box never resizes, so the
-	// button's text content always holds both words — assert on the accessible name,
-	// which comes from the single sr-only label.
 	const watchButton = (canvas: PlayContext["canvas"]) =>
 		canvas.findByRole("button", { name: /^watch$/i });
 	const unwatchButton = (canvas: PlayContext["canvas"]) =>
 		canvas.findByRole("button", { name: /^unwatch$/i });
 
-	// the initial read is still in flight: the button just reads "Watch" — there is no
-	// loading state, and a click before the read lands is ignored
 	const loadingState = async ({ canvas }: PlayContext) => {
 		await expect(await watchButton(canvas)).toBeVisible();
 	};
@@ -82,8 +77,6 @@
 		await waitFor(() => expect(button).toBeEnabled());
 	};
 
-	// clicking watch: the icon swaps to a spinner while the request is in flight, then
-	// the eye swaps to eye-off and the label crossfades to "Unwatch"
 	const subscribing = async ({ canvas }: PlayContext) => {
 		const button = await watchButton(canvas);
 		await waitFor(() => expect(button).toBeEnabled());
diff --git a/web/src/lib/components/repo/SubscribeButton.svelte b/web/src/lib/components/repo/SubscribeButton.svelte
index 7ab3007f0..6a20373f3 100644
--- a/web/src/lib/components/repo/SubscribeButton.svelte
+++ b/web/src/lib/components/repo/SubscribeButton.svelte
@@ -126,7 +126,6 @@
 <span role="status" aria-live="polite" class="sr-only">{error ?? ""}</span>
 
 <style>
-	/* the three faces share one grid cell, so the icon never nudges the label as they swap */
 	.faces :global(.face) {
 		grid-column: 1;
 		grid-row: 1;
diff --git a/web/src/lib/components/repo/pipelines/Elapsed.stories.svelte b/web/src/lib/components/repo/pipelines/Elapsed.stories.svelte
index 4a9451eca..dd2b4b0f1 100644
--- a/web/src/lib/components/repo/pipelines/Elapsed.stories.svelte
+++ b/web/src/lib/components/repo/pipelines/Elapsed.stories.svelte
@@ -14,18 +14,13 @@
 	});
 </script>
 
-<!-- a step that ended: the time it took, and it never moves again -->
 <Story name="Finished" />
 
-<!-- a step still going: no end frame yet, so the timer counts up every second -->
 <Story name="Running" args={{ start: Date.now() - 12_000, end: undefined }} />
 
-<!-- killed mid-step: no end frame and the run is over, so nobody knows when it died
-     and nothing is shown -->
 <Story
 	name="Killed mid-step"
 	args={{ start: Date.now() - 12_000, end: undefined, running: false }}
 />
 
-<!-- the spindle has not reported a start -->
 <Story name="Not started" args={{ start: undefined, end: undefined }} />
diff --git a/web/src/lib/components/repo/pipelines/Elapsed.svelte b/web/src/lib/components/repo/pipelines/Elapsed.svelte
index e55d08d3f..3472090e3 100644
--- a/web/src/lib/components/repo/pipelines/Elapsed.svelte
+++ b/web/src/lib/components/repo/pipelines/Elapsed.svelte
@@ -7,7 +7,6 @@
 		start?: number;
 		/** epoch ms; while absent the timer keeps counting */
 		end?: number;
-		/** off once the step can no longer finish; a step that never reported an end then shows nothing, because nobody knows when it died */
 		running?: boolean;
 		class?: ClassValue | null;
 	}
@@ -24,8 +23,6 @@
 
 	const elapsed = $derived.by(() => {
 		if (start === undefined || Number.isNaN(start)) return null;
-		// counting from a start whose end never came measures how long ago the step
-		// began, which grows forever and is not a duration
 		if (end === undefined && !running) return null;
 		return Math.max(0, (end ?? now) - start);
 	});
diff --git a/web/src/lib/components/repo/pipelines/PipelineCardContent.svelte b/web/src/lib/components/repo/pipelines/PipelineCardContent.svelte
index ff1307c41..96c42c952 100644
--- a/web/src/lib/components/repo/pipelines/PipelineCardContent.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineCardContent.svelte
@@ -3,8 +3,6 @@
 
 	export const pipelineCardContent = tv({
 		slots: {
-			// does not wrap: a long branch name wraps inside the trigger group instead, so the
-			// sha stays pinned top-right
 			header: "flex items-start justify-between gap-3 pb-2 md:pb-0",
 			trigger: "flex min-w-0 flex-wrap items-center gap-x-1.5 gap-y-1",
 			triggerRow: "flex flex-wrap items-center gap-x-1.5 gap-y-1 text-foreground-default",
@@ -20,7 +18,6 @@
 			durationIcon: "size-3 shrink-0"
 		},
 		variants: {
-			// the trigger line is only a link once a workflow exists to open
 			linked: {
 				true: { triggerRow: "no-underline hover:underline" },
 				false: {}
@@ -65,7 +62,6 @@
 
 	const duration = $derived(totalDuration(pipeline));
 
-	// links to the first workflow's logs, plain text until a spindle reports one
 	const href = $derived(
 		pipeline.workflows.length > 0
 			? resolve(
diff --git a/web/src/lib/components/repo/pipelines/PipelineEmptyState.svelte b/web/src/lib/components/repo/pipelines/PipelineEmptyState.svelte
index 7969204b3..c8387944f 100644
--- a/web/src/lib/components/repo/pipelines/PipelineEmptyState.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineEmptyState.svelte
@@ -44,7 +44,6 @@
 	</li>
 {/snippet}
 
-<!-- an empty tab almost always means CI was never set up, so show the setup steps -->
 <div class={classes.root()}>
 	<Layers2 class={classes.icon()} aria-hidden="true" />
 
@@ -69,7 +68,6 @@
 {/snippet}
 
 {#snippet configure()}
-	<!-- plain anchor: Button's href only takes internal paths -->
 	Configure your CI/CD
 	<a
 		href="https://docs.tangled.org/spindles.html#pipelines"
diff --git a/web/src/lib/components/repo/pipelines/PipelineList.stories.svelte b/web/src/lib/components/repo/pipelines/PipelineList.stories.svelte
index 93d78da30..854e0e83d 100644
--- a/web/src/lib/components/repo/pipelines/PipelineList.stories.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineList.stories.svelte
@@ -72,14 +72,12 @@
 <Story name="Default" asChild>
 	<PipelineList ownerHandle="tangled.org" {ownerDid} repoName="core" {pipelines} />
 </Story>
-<!-- no runs at all: the setup steps -->
 <Story name="Empty" asChild parameters={owner}>
 	<PipelineList ownerHandle="tangled.org" {ownerDid} repoName="core" pipelines={[]} />
 </Story>
 <Story name="Empty visitor" asChild>
 	<PipelineList ownerHandle="tangled.org" {ownerDid} repoName="core" pipelines={[]} />
 </Story>
-<!-- runs exist, none match the trigger filter -->
 <Story name="Filtered out" asChild>
 	<PipelineList ownerHandle="tangled.org" {ownerDid} repoName="core" pipelines={[]} filtered />
 </Story>
diff --git a/web/src/lib/components/repo/pipelines/PipelineList.svelte b/web/src/lib/components/repo/pipelines/PipelineList.svelte
index f32533159..ea306dd52 100644
--- a/web/src/lib/components/repo/pipelines/PipelineList.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineList.svelte
@@ -17,7 +17,6 @@
 		repoDid?: string;
 		filter?: PipelineFilter;
 		pipelines: PipelineSummary[];
-		/** repo has runs, they just do not match — show "no match" instead of the setup steps */
 		filtered?: boolean;
 		/** fork repo did -> `owner/name`, streams in behind the list */
 		forkLabels?: Promise<Record<string, string>>;
diff --git a/web/src/lib/components/repo/pipelines/PipelineSearch.stories.svelte b/web/src/lib/components/repo/pipelines/PipelineSearch.stories.svelte
index 169edb50c..805ea2599 100644
--- a/web/src/lib/components/repo/pipelines/PipelineSearch.stories.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineSearch.stories.svelte
@@ -13,5 +13,4 @@
 </script>
 
 <Story name="Default" />
-<!-- a non-default tab rides along in a hidden field so searching keeps the filter -->
 <Story name="Within a trigger tab" args={{ filter: "pull_request" }} />
diff --git a/web/src/lib/components/repo/pipelines/PipelineSearch.svelte b/web/src/lib/components/repo/pipelines/PipelineSearch.svelte
index 0e1ee9da7..a932a531e 100644
--- a/web/src/lib/components/repo/pipelines/PipelineSearch.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineSearch.svelte
@@ -9,7 +9,6 @@
 			clear: "absolute right-0.5"
 		},
 		variants: {
-			// room for the clear button so the text does not run under it
 			filled: {
 				true: { input: "pr-9" },
 				false: {}
@@ -30,14 +29,12 @@
 	import type { PipelineFilter } from "./pipeline";
 
 	interface Props {
-		/** kept in the form so searching does not reset the tab */
 		filter: PipelineFilter;
 	}
 
 	let { filter }: Props = $props();
 
 	let form: HTMLFormElement;
-	// seed from the url so the query (and the clear button) survive a submit
 	let value = $state(page.url.searchParams.get("q") ?? "");
 
 	const clear = () => {
diff --git a/web/src/lib/components/repo/pipelines/PipelineStatusIcon.svelte b/web/src/lib/components/repo/pipelines/PipelineStatusIcon.svelte
index d437c966a..f2dd324e9 100644
--- a/web/src/lib/components/repo/pipelines/PipelineStatusIcon.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineStatusIcon.svelte
@@ -10,7 +10,6 @@
 	import X from "$icon/x";
 	import type { PipelineStatus } from "$lib/components/repo/types";
 
-	/** same icon per status as the appview's workflowSymbol fragment */
 	export const STATUS_ICONS: Record<PipelineStatus, Component<SvelteHTMLElements["svg"]>> = {
 		pending: CircleDashed,
 		running: RefreshCw,
@@ -20,7 +19,6 @@
 		cancelled: CircleSlash
 	};
 
-	// leave `status` off to let the icon inherit its colour, e.g. inside a Tag
 	export const pipelineStatusIcon = tv({
 		base: "size-3 shrink-0",
 		variants: {
@@ -41,7 +39,6 @@
 <script lang="ts">
 	interface Props {
 		status: PipelineStatus;
-		/** off inside a Tag */
 		colored?: boolean;
 		class?: string;
 	}
diff --git a/web/src/lib/components/repo/pipelines/PipelineSymbol.svelte b/web/src/lib/components/repo/pipelines/PipelineSymbol.svelte
index c1124781c..b5766f333 100644
--- a/web/src/lib/components/repo/pipelines/PipelineSymbol.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineSymbol.svelte
@@ -2,7 +2,7 @@
 	import { tv } from "tailwind-variants";
 	import type { PipelineStatus } from "$lib/components/repo/types";
 
-	/** the ring reuses the icon colours, so a status reads the same either way */
+	// must match STATUS_STROKES to PipelineStatusIcon's colours or the ring/icon disagree
 	export const STATUS_STROKES: Record<PipelineStatus, string> = {
 		pending: "stroke-foreground-placeholder",
 		running: "stroke-foreground-warning",
@@ -14,7 +14,6 @@
 
 	export const pipelineSymbol = tv({
 		slots: {
-			// the glyph that stands in when the ring would be one flat colour
 			icon: "size-4 shrink-0",
 			waiting: "size-4 shrink-0 text-foreground-muted",
 			// -rotate-90 puts the first arc at twelve o'clock instead of three
@@ -39,7 +38,6 @@
 
 	let { pipeline, class: className }: Props = $props();
 
-	// one arc per status that actually occurs, laid out clockwise in STATUS_ORDER
 	const arcs = $derived.by(() => {
 		const counts = statusCounts(pipeline);
 		const total = pipeline.workflows.length;
@@ -56,17 +54,14 @@
 </script>
 
 {#if arcs.length === 0}
-	<!-- no spindle has reported a workflow yet, so there is nothing to apportion -->
 	<Hourglass class={classes.waiting({ class: className })} aria-hidden="true" />
 {:else if arcs.length === 1}
-	<!-- every workflow agrees: a full ring of one colour says less than the status' own icon -->
 	<PipelineStatusIcon
 		status={arcs[0].status}
 		colored
 		class={classes.icon({ class: className })}
 	/>
 {:else}
-	<!-- the arcs always add up to the whole circle, so the ring needs no track under them -->
 	<svg class={classes.ring({ class: className })} viewBox="0 0 20 20" aria-hidden="true">
 		{#each arcs as arc (arc.status)}
 			<circle
diff --git a/web/src/lib/components/repo/pipelines/PipelineToolbar.svelte b/web/src/lib/components/repo/pipelines/PipelineToolbar.svelte
index 00930ae00..95f61327b 100644
--- a/web/src/lib/components/repo/pipelines/PipelineToolbar.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineToolbar.svelte
@@ -3,7 +3,6 @@
 
 	export const pipelineToolbar = tv({
 		slots: {
-			// same grid as IssueToolbar
 			root: "grid grid-cols-[auto_1fr_auto] gap-2",
 			search: "col-span-3 sm:col-span-1 sm:col-start-2",
 			group: "sm:row-start-1",
@@ -33,7 +32,6 @@
 		ownerHandle: string;
 		repoName: string;
 		filter: PipelineFilter;
-		/** how many runs match the tab and query */
 		total: number | Promise<number>;
 	}
 
@@ -41,7 +39,6 @@
 
 	const base = $derived(`/${ownerHandle}/${repoName}/pipelines`);
 
-	// keep the query when switching tabs
 	const segmentHref = (kind: PipelineFilter) => {
 		const query = page.url.searchParams.get("q");
 		const suffix = query ? `&q=${encodeURIComponent(query)}` : "";
@@ -57,7 +54,6 @@
 	</div>
 
 	<ButtonGroup class={classes.group()}>
-		<!-- no manual segment: the appview only filters push and pull request -->
 		<Button
 			size="small"
 			href={segmentHref("all")}
diff --git a/web/src/lib/components/repo/pipelines/PipelineWorkflows.stories.svelte b/web/src/lib/components/repo/pipelines/PipelineWorkflows.stories.svelte
index c83541332..684d2ebe4 100644
--- a/web/src/lib/components/repo/pipelines/PipelineWorkflows.stories.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineWorkflows.stories.svelte
@@ -17,16 +17,13 @@
 	});
 </script>
 
-<!-- the card's trigger: how many workflows, and how many have settled -->
 <Story name="Count" />
 <Story name="Count waiting" args={{ pipeline: waiting }} />
 
-<!-- the same tally as a bare link, for a row that must align with plain text -->
 <Story name="Link" args={{ link: true }} />
 <Story name="Link waiting" args={{ link: true, pipeline: waiting }} />
 <Story name="Link symbol" args={{ link: true, variant: "symbol", summary: "long" }} />
 
-<!-- the appview's pipelineSymbol: a status ring sized for a commit or PR header -->
 <Story name="Symbol" args={{ variant: "symbol" }} />
 <Story name="Symbol long" args={{ variant: "symbol", summary: "long" }} />
 <Story name="Symbol mixed" args={{ variant: "symbol", pipeline: mixed, summary: "long" }} />
diff --git a/web/src/lib/components/repo/pipelines/PipelineWorkflows.svelte b/web/src/lib/components/repo/pipelines/PipelineWorkflows.svelte
index ecb39dc3a..070363cbb 100644
--- a/web/src/lib/components/repo/pipelines/PipelineWorkflows.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineWorkflows.svelte
@@ -9,7 +9,6 @@
 			trigger: "flex items-center gap-2",
 			icon: "size-3 shrink-0",
 			symbol: "",
-			// Button hugs its children, so stretch that span to get a two-column row
 			item: "[&>span]:w-full",
 			row: "flex w-full items-center justify-between gap-2",
 			name: "flex min-w-0 items-center gap-1.5",
@@ -19,9 +18,7 @@
 		},
 		variants: {
 			variant: {
-				// "2/3 workflows" with a chevron, for a card that has room to spell it out
 				count: { symbol: "size-4" },
-				// the appview's pipelineSymbol: a status ring plus a bare tally
 				symbol: { trigger: "gap-1.5" }
 			}
 		},
@@ -53,19 +50,10 @@
 		repoName: string;
 		pipeline: PipelineSummary;
 		variant?: PipelineWorkflowsVariants["variant"];
-		/**
-		 * symbol variant only: "2/3" against the full "2/3 passed, 1/3 failed" breakdown, or
-		 * "none" for a bare symbol where the column is too narrow to spell anything out
-		 */
 		summary?: "short" | "long" | "none";
 		icon?: Component<SvelteHTMLElements["svg"]>;
 		iconClass?: string;
 		size?: ButtonVariants["size"];
-		/**
-		 * a bare link to the first workflow instead of the dropdown: no button padding and no
-		 * type size of its own, so it lines up with the text beside it. The workflow list is
-		 * unreachable this way, since an <a> cannot open a popover.
-		 */
 		link?: boolean;
 	}
 
@@ -102,7 +90,6 @@
 {/snippet}
 
 {#if count === 0}
-	<!-- no workflows yet, so nothing to open -->
 	<ShimmerText color="inherit" duration={3} delay={0} class={classes.waitingWrap()}>
 		{#if link}
 			<span
diff --git a/web/src/lib/components/repo/pipelines/StepStatusIcon.stories.svelte b/web/src/lib/components/repo/pipelines/StepStatusIcon.stories.svelte
index 7000edc36..a7aeb16f7 100644
--- a/web/src/lib/components/repo/pipelines/StepStatusIcon.stories.svelte
+++ b/web/src/lib/components/repo/pipelines/StepStatusIcon.stories.svelte
@@ -14,7 +14,6 @@
 </script>
 
 <script lang="ts">
-	// the pop only fires on a status change, so a still frame can never show it
 	const order: StepStatus[] = ["pending", "active", "done", "error"];
 	let index = $state(0);
 	const cycling = $derived(order[index]);
@@ -29,7 +28,6 @@
 <Story name="Active" args={{ status: "active" }} />
 <Story name="Done" args={{ status: "done" }} />
 <Story name="Error" args={{ status: "error" }} />
-<!-- walks the four states on a timer so the tick and the cross can be seen arriving -->
 <Story name="Cycling">
 	{#snippet template()}
 		<div class="flex items-center gap-2 font-sans typography-paragraph-regular">
diff --git a/web/src/lib/components/repo/pipelines/StepStatusIcon.svelte b/web/src/lib/components/repo/pipelines/StepStatusIcon.svelte
index be3b34320..0d986ab7e 100644
--- a/web/src/lib/components/repo/pipelines/StepStatusIcon.svelte
+++ b/web/src/lib/components/repo/pipelines/StepStatusIcon.svelte
@@ -31,7 +31,6 @@
 
 	interface Props {
 		status: StepStatus;
-		/** false when the step's state was settled before it appeared, so nothing pops */
 		animate?: boolean;
 		class?: string;
 	}
@@ -44,9 +43,6 @@
 		mounted = true;
 	});
 
-	// nothing pops on the first paint. reading the flags untracked is what keeps it
-	// that way: this only recomputes when the status changes, so flipping one of them
-	// a frame later cannot hand the animation to a chip already sitting on screen
 	const popping = $derived.by(() => {
 		void status;
 		return untrack(() => mounted && animate);
diff --git a/web/src/lib/components/repo/pipelines/WorkflowLogs.stories.svelte b/web/src/lib/components/repo/pipelines/WorkflowLogs.stories.svelte
index ebb53aca4..4e9e2d275 100644
--- a/web/src/lib/components/repo/pipelines/WorkflowLogs.stories.svelte
+++ b/web/src/lib/components/repo/pipelines/WorkflowLogs.stories.svelte
@@ -11,8 +11,6 @@
 		workflowLog
 	} from "$fixtures/pipelines";
 
-	// the jump can only park a header at the top edge if there is log below it to
-	// scroll through, so the last step carries a real tail
 	const deepWorkflowLog = workflowLog.map((step, index) =>
 		index === workflowLog.length - 1
 			? {
@@ -40,9 +38,6 @@
 <script lang="ts">
 	import type { LogStep } from "./logs";
 
-	// the tail stories need a log that actually grows, because the whole point is
-	// what the viewport does between two frames. one feed each, or whichever story
-	// you open second starts on an exhausted tail
 	const feed = (every = 250, frames = 1) => {
 		const tail = createLogTail();
 		let steps = $state<LogStep[]>(tail.advance());
@@ -62,8 +57,6 @@
 		};
 	};
 
-	// a flush has to land after the click, so the play function drives it rather than
-	// a timer
 	const drivenLog = (initial: LogStep[]) => {
 		let steps = $state.raw<LogStep[]>(initial);
 		const last = () => steps[steps.length - 1];
@@ -84,7 +77,6 @@
 	const unfoldedByHand = drivenLog(runningWorkflowLog);
 	const foldedByHand = drivenLog(runningWorkflowLog);
 
-	// the rail drives the log through this, the way WorkflowView wires it
 	let railJump: ((id: number) => void) | undefined;
 
 	const landedOnTop = (element: Element | null) => {
@@ -99,7 +91,6 @@
 
 	const live = feed();
 	const replayed = feed();
-	// the app flushes once a frame, so a busy step lands several lines a tick
 	const burst = feed(60, 2);
 </script>
 
@@ -121,35 +112,23 @@
 <Story name="Stream error" args={{ status: "done", error: "workflow not found" }} />
 <!-- 4k lines virtualized -->
 <Story name="Long" args={{ steps: longWorkflowLog }} />
-<!-- a growing log on a live run: opens on the tail and keeps following it until
-     you scroll or select, then hands the viewport over and offers the way back.
-     the steps go through the template, because args are a snapshot: storybook
-     reads them once per story and never sees the feed move -->
 <Story name="Live tail" args={{ status: "streaming", workflowStatus: "running" }}>
 	{#snippet template(args)}
 		<WorkflowLogs {...args} steps={live.steps} />
 	{/snippet}
 </Story>
-<!-- the same growing log on a finished run: opens at the first step and stays put -->
 <Story name="Replayed tail" args={{ status: "streaming", workflowStatus: "success" }}>
 	{#snippet template(args)}
 		<WorkflowLogs {...args} steps={replayed.steps} />
 	{/snippet}
 </Story>
-<!-- lines landing every frame, the way a busy step really arrives: scrolling away
-     still has to take the viewport on the first try -->
 <Story name="Bursting tail" args={{ status: "streaming", workflowStatus: "running" }}>
 	{#snippet template(args)}
 		<WorkflowLogs {...args} steps={burst.steps} />
 	{/snippet}
 </Story>
-<!-- the run died on its last step: the failure stays open with everything above it
-     folded, and the cross carries the outcome -->
 <Story name="Failed run" args={{ steps: failedWorkflowLog, workflowStatus: "failed" }} />
-<!-- killed mid-step, so the last step has a start and no end: its timer shows the
-     time it reached instead of counting up forever -->
 <Story name="Killed mid-step" args={{ steps: cancelledWorkflowLog, workflowStatus: "cancelled" }} />
-<!-- the rail's jump has to open the step, not land the reader on a closed header -->
 <Story
 	name="Jump to a folded step"
 	args={{ steps: deepWorkflowLog }}
@@ -171,7 +150,6 @@
 		<WorkflowLogs {...args} onready={(jump) => (railJump = jump)} />
 	{/snippet}
 </Story>
-<!-- a step opened by hand stays open through the next flush -->
 <Story
 	name="Opened by hand"
 	args={{ status: "streaming", workflowStatus: "running" }}
@@ -191,7 +169,6 @@
 		<WorkflowLogs {...args} steps={unfoldedByHand.steps} />
 	{/snippet}
 </Story>
-<!-- and a step closed by hand stays closed, even once the run folds it by itself -->
 <Story
 	name="Closed by hand"
 	args={{ status: "streaming", workflowStatus: "running" }}
diff --git a/web/src/lib/components/repo/pipelines/WorkflowLogs.svelte b/web/src/lib/components/repo/pipelines/WorkflowLogs.svelte
index 2ad83b62d..1f15f353b 100644
--- a/web/src/lib/components/repo/pipelines/WorkflowLogs.svelte
+++ b/web/src/lib/components/repo/pipelines/WorkflowLogs.svelte
@@ -23,8 +23,6 @@
 			first: { true: { body: "pt-1.5" }, false: {} },
 			// last row rounds bottom corners
 			last: { true: { body: "rounded-b border-b pb-1.5" }, false: {} },
-			// the chip and the label carry the state on their own. tinting the row
-			// would too: background-danger-subtle is far too loud over the card
 			stepStatus: {
 				pending: { name: "text-foreground-muted" },
 				active: { name: "font-medium" },
@@ -44,13 +42,8 @@
 		gap: 8
 	};
 
-	// slack for a fractional scrollTop. it has to stay under one line, or a single
-	// appended line still reads as "at the end" and the tail creeps along after the
-	// reader took over
 	const END_SLACK = 8;
 
-	// a row measuring taller than its estimate parks the viewport short of the end,
-	// so anything tighter than this strands the follow there
 	const NEAR_END = 70;
 
 	const distanceFromEnd = (scroller: HTMLElement): number =>
@@ -87,45 +80,31 @@
 	interface Props {
 		steps: LogStep[];
 		status: LogStreamStatus;
-		// where the workflow itself stands, which is what tells a finished step from a running one
 		workflowStatus: PipelineStatus;
 		// stream error frame if spindle sent one
 		error?: string | null;
-		// hands the parent the jump, so a step rail can drive this viewport
 		onready?: (scrollToStep: (id: number) => void) => void;
-		// the step whose header is pinned, reported only when it changes
 		onvisiblestep?: (id: number | undefined) => void;
 	}
 
 	let { steps, status, workflowStatus, error = null, onready, onvisiblestep }: Props = $props();
 
-	// the run is still going, so the tail is worth following
 	const live = $derived(isLive(workflowStatus));
 
-	// a run that was already over when the log opened has no news to break: every step
-	// state was settled before we got here, so nothing pops on its way in
 	const animate = untrack(() => isLive(workflowStatus));
 
 	let viewport = $state<HTMLDivElement | null>(null);
 	let scrollTop = $state(0);
-	// the reader scrolled away from the tail and owns the viewport until they come back
 	let detached = $state(false);
-	// a selection in flight, so new lines must not pull the text out from under it
 	let selecting = $state(false);
 	let pressing = $state(false);
-	// our own scrolling lands on this offset and the reader's never does
 	let ownedOffset: number | null = null;
 	let openedAtTail = false;
-	// what the reader decided about a step, open or closed. a decision outranks the
-	// policy in both directions, and goes on outranking it
 	const opened = new SvelteMap<number, boolean>();
-	// steps the run folded by itself. kept rather than recomputed, or a step the
-	// reader opened by hand would slam shut on the next frame
 	const autoFolded = new SvelteSet<number>();
 	let foldedOnLoad = false;
 	const lastStatus: Record<number, StepStatus> = {};
 
-	// a press counts, or collapsing a selection mid-drag jumps the text under the cursor
 	const holding = $derived(selecting || pressing);
 	const following = $derived(live && !detached && !holding);
 
@@ -136,7 +115,6 @@
 		const decided = opened.get(step.id);
 		if (decided !== undefined) return !decided;
 		const stepStatus = statuses[index];
-		// the failure, whatever is running and the tail of the log stay open
 		const open =
 			stepStatus === "error" || stepStatus === "active" || index === steps.length - 1;
 		return !open && (step.system || autoFolded.has(step.id));
@@ -158,8 +136,6 @@
 		return indexes;
 	};
 
-	// every scroll the virtualizer performs comes through here, which is how the
-	// scroll handler tells our own scrolling apart from the reader's
 	const scrollToFn: VirtualizerOptions<HTMLDivElement, HTMLElement>["scrollToFn"] = (
 		offset,
 		options,
@@ -172,8 +148,6 @@
 	const ownsViewport = (scroller: HTMLElement): boolean => {
 		if (ownedOffset === null) return false;
 		if (Math.abs(scroller.scrollTop - ownedOffset) <= OFFSET_SLACK) return true;
-		// we asked for more than the element had to give and it saturated at the end,
-		// which is still our scroll and must not read as the reader returning
 		return ownedOffset > scroller.scrollTop && distanceFromEnd(scroller) <= OFFSET_SLACK;
 	};
 
@@ -205,15 +179,11 @@
 				// riding the tail holds the bottom edge still through a remeasure. reading
 				// holds the top edge, or a corrected estimate drifts the text downward
 				anchorTo: anchor,
-				// the virtualizer only follows when the viewport already sat at the end,
-				// so a reader who scrolled up keeps their place
 				followOnAppend: follow
 			})
 		);
 	});
 
-	// a live run opens on its tail. a finished one opens at the first step, the way
-	// you read a log you already know the end of
 	$effect(() => {
 		const instance = $virtualizer;
 		if (openedAtTail || !live || !viewport || rows.length === 0) return;
@@ -224,8 +194,6 @@
 		instance.scrollToEnd();
 	});
 
-	// a run that was already over when the page opened folds its finished steps at
-	// once, so the reader lands on the outcome instead of a wall of setup
 	$effect(() => {
 		const current = steps;
 		const settled = !live;
@@ -241,10 +209,6 @@
 		});
 	});
 
-	// folding a step above the viewport takes height out from over the reader and
-	// yanks the line they were on. riding the tail the bottom edge is pinned, so
-	// the fold costs nothing — detached or mid-selection it costs them their place,
-	// and the step stays open
 	$effect(() => {
 		const current = steps;
 		const currentStatuses = statuses;
@@ -280,7 +244,6 @@
 	const onwheel = (event: WheelEvent) => {
 		const scroller = viewport;
 		if (!scroller || event.deltaY >= 0) return;
-		// a wheel over a log that fits moves nothing, so it takes nothing over
 		if (scroller.scrollTop === 0) return;
 		detached = true;
 	};
@@ -311,7 +274,6 @@
 			scroller.contains(selection.anchorNode);
 	};
 
-	// a hold parks the viewport too far back for the virtualizer to re-arm itself
 	let wasHolding = false;
 	$effect(() => {
 		if (holding) {
@@ -333,16 +295,12 @@
 
 	const revealStep = async (id: number) => {
 		if (!steps.some((step) => step.id === id)) return;
-		// asking for a step is the reader taking the viewport, so the tail lets go of it
 		detached = true;
 		opened.set(id, true);
-		// the step has to be open and its rows laid out before we aim at an offset, or
-		// the scroll targets the shape the log had while it was still folded
 		await tick();
 		const index = rows.findIndex((row) => row.kind === "step" && row.step.id === id);
 		if (index === -1) return;
 		$virtualizer.scrollToIndex(index, { align: "start" });
-		// the scroll lands a frame later, and the row cannot take focus until it does
 		await frame();
 		await tick();
 		const header = viewport?.querySelector<HTMLElement>(`[data-index="${index}"] button`);
@@ -389,8 +347,6 @@
 		return { ...activeStep, offset };
 	});
 
-	// at the very top no header is pinned yet, and what the reader is looking at is
-	// the first step
 	const visibleStep = $derived.by(() => {
 		if (stickyInfo) return stickyInfo.step.id;
 		const first = rows[0];
diff --git a/web/src/lib/components/repo/pipelines/WorkflowSidebar.stories.svelte b/web/src/lib/components/repo/pipelines/WorkflowSidebar.stories.svelte
index 162f9c50b..2f642d0c5 100644
--- a/web/src/lib/components/repo/pipelines/WorkflowSidebar.stories.svelte
+++ b/web/src/lib/components/repo/pipelines/WorkflowSidebar.stories.svelte
@@ -30,8 +30,6 @@
 	name="Mixed outcomes"
 	args={{ workflows: pipelines[1].workflows, active: "test", createdAt: pipelines[1].createdAt }}
 />
-<!-- the step rail nests inside the active card, below its divider, at the width of the real column.
-     a running workflow shows it straight away -->
 <Story name="With steps">
 	{#snippet template(args)}
 		<div class="w-60">
@@ -43,7 +41,6 @@
 		</div>
 	{/snippet}
 </Story>
-<!-- a run that was already over folds its rail away, and the card unfolds it when pressed -->
 <Story
 	name="Finished, folded"
 	args={{
diff --git a/web/src/lib/components/repo/pipelines/WorkflowSidebar.svelte b/web/src/lib/components/repo/pipelines/WorkflowSidebar.svelte
index 755f1225b..8ffc158e1 100644
--- a/web/src/lib/components/repo/pipelines/WorkflowSidebar.svelte
+++ b/web/src/lib/components/repo/pipelines/WorkflowSidebar.svelte
@@ -1,8 +1,6 @@
 <script module lang="ts">
 	import { tv } from "tailwind-variants";
 
-	// the chrome that says "this is the workflow you are looking at", worn either by the
-	// card itself or, once the card has a step rail nested in it, by the wrapper
 	const ACTIVE_CHROME = "border-border-disabled bg-background-default dark:bg-background-subtle";
 
 	export const workflowSidebar = tv({
@@ -23,8 +21,6 @@
 			status: "flex min-w-0 items-center gap-1.5",
 			label: "truncate font-semibold text-foreground-default",
 			duration: "shrink-0 text-foreground-muted tabular-nums",
-			// recessed a step below the card's own surface, and inverted the same way the
-			// card's own background does between themes, so it reads as sunken in both
 			extra: "min-w-0 bg-background-subtle p-1 dark:bg-background-default"
 		},
 		variants: {
@@ -58,7 +54,6 @@
 		active: string;
 		/** falls back to the run's own stamp for a workflow the spindle hasn't started */
 		createdAt: string;
-		/** rendered right under the active workflow's card */
 		activeExtra?: Snippet;
 	}
 
@@ -75,9 +70,6 @@
 
 	const railId = $props.id();
 
-	// a run still going is news, so its steps are already open. a run you came to read
-	// after the fact opens on the header alone and unfolds when you ask. settled once,
-	// at mount: a run that finishes while you watch has no business folding itself shut
 	let expanded = $state(
 		untrack(() => {
 			const current = workflows.find((workflow) => workflow.name === active);
@@ -109,9 +101,6 @@
 	{#each workflows as workflow (workflow.name)}
 		{#if workflow.name === active && activeExtra}
 			<div class={classes().wrapper()}>
-				<!-- already the workflow on screen, so the card has nowhere to go: pressing it
-				     folds the rail instead. reaching it from another card is the navigation,
-				     and the fold only comes into play once you are here -->
 				<button
 					type="button"
 					class={classes().header()}
diff --git a/web/src/lib/components/repo/pipelines/WorkflowSteps.stories.svelte b/web/src/lib/components/repo/pipelines/WorkflowSteps.stories.svelte
index 98b4d41e8..fcfc436ab 100644
--- a/web/src/lib/components/repo/pipelines/WorkflowSteps.stories.svelte
+++ b/web/src/lib/components/repo/pipelines/WorkflowSteps.stories.svelte
@@ -25,9 +25,6 @@
 	import WorkflowRunReplay from "../../../../../.storybook/WorkflowRunReplay.svelte";
 	import { createLogAccumulator, type LogStep } from "./logs";
 
-	// a step's start and its end land in different flushes, and the accumulator
-	// fills the same step object both times, which is where the rail used to stop
-	// noticing the step had finished
 	const finishing = () => {
 		const accumulator = createLogAccumulator();
 		const at = (seconds: number) =>
@@ -69,20 +66,14 @@
 	const twoFlush = finishing();
 </script>
 
-<!-- a finished successful run: every step done, every duration shown, and nothing
-     animating — the states were settled before the rail ever appeared -->
 <Story name="Default" />
 
-<!-- a run mid-flight: the last step shimmers and its duration stays hidden until it finishes -->
 <Story name="Running" args={{ steps: runningWorkflowLog, workflowStatus: "running" }} />
 
-<!-- a run that died on its last step -->
 <Story name="Failed" args={{ steps: failedWorkflowLog, workflowStatus: "failed" }} />
 
-<!-- killed mid-step: the open step never got an end frame -->
 <Story name="Cancelled" args={{ steps: cancelledWorkflowLog, workflowStatus: "cancelled" }} />
 
-<!-- interactive rows: selecting a step logs which one, for the sidebar's click-to-jump wiring -->
 <Story
 	name="Selectable"
 	args={{
@@ -92,7 +83,6 @@
 	}}
 />
 
-<!-- the step ends a flush after it started, the way a live run really arrives -->
 <Story
 	name="Finishing mid-stream"
 	args={{ workflowStatus: "running" }}
@@ -105,7 +95,6 @@
 	{/snippet}
 </Story>
 
-<!-- the rail filling in on a live run: every tick pops as its step closes -->
 <Story name="Run passing">
 	{#snippet template()}
 		<WorkflowRunReplay create={() => createWorkflowRun()}>
@@ -116,8 +105,6 @@
 	{/snippet}
 </Story>
 
-<!-- a live run that dies on "run tests". the spindle starts nothing after a failed
-     step, so a run never shows more than one cross -->
 <Story name="Run failing midway">
 	{#snippet template()}
 		<WorkflowRunReplay create={() => createWorkflowRun({ failAt: 3 })}>
@@ -128,7 +115,6 @@
 	{/snippet}
 </Story>
 
-<!-- everything fails: the very first step dies, so the run is one cross and nothing else -->
 <Story name="Run failing at the first step">
 	{#snippet template()}
 		<WorkflowRunReplay create={() => createWorkflowRun({ failAt: 0 })}>
@@ -139,7 +125,6 @@
 	{/snippet}
 </Story>
 
-<!-- killed while "run tests" was open: that step never closes, so it keeps no duration -->
 <Story name="Run cancelled">
 	{#snippet template()}
 		<WorkflowRunReplay create={() => createWorkflowRun({ cancelAt: 3 })}>
@@ -150,8 +135,6 @@
 	{/snippet}
 </Story>
 
-<!-- joining a run already in flight: the steps that were already over sit there, and
-     only the ones that close while you watch pop -->
 <Story name="Run joined mid-flight">
 	{#snippet template()}
 		<WorkflowRunReplay create={() => createWorkflowRun()} from={9}>
diff --git a/web/src/lib/components/repo/pipelines/WorkflowSteps.svelte b/web/src/lib/components/repo/pipelines/WorkflowSteps.svelte
index 56d0edb0f..f6e8fe2bd 100644
--- a/web/src/lib/components/repo/pipelines/WorkflowSteps.svelte
+++ b/web/src/lib/components/repo/pipelines/WorkflowSteps.svelte
@@ -43,9 +43,7 @@
 	interface Props {
 		steps: LogStep[];
 		workflowStatus: PipelineStatus;
-		/** the step the log viewport is currently showing, if any */
 		current?: number;
-		/** jump the log to a step */
 		onselect?: (id: number) => void;
 		ariaLabel?: string;
 	}
@@ -61,14 +59,8 @@
 	const classes = workflowSteps;
 	const statuses = $derived(stepStatuses(steps, workflowStatus));
 
-	// a run that was already over when the rail appeared has no news to break: every
-	// state was settled before we got here, so the ticks are simply there. a run we
-	// joined mid-flight keeps them arriving one by one
 	const animate = untrack(() => isLive(workflowStatus));
 
-	// the accumulator fills steps in place, so a keyed each over the step objects
-	// themselves never sees a step finish — the item reference never changes. these
-	// rows are rebuilt on every publish, which is what makes the row re-render
 	const rows = $derived(
 		steps.map((step, i) => ({
 			id: step.id,
@@ -81,10 +73,6 @@
 		}))
 	);
 
-	// a run can flip through several steps a second, so the live region is told about it
-	// half a beat late rather than on every transition. going through a derived is what
-	// keeps the wait finite: a busy step flushes a new `steps` every frame without
-	// changing the sentence, and only a new sentence may restart the timer
 	const message = $derived(narrate(steps, workflowStatus));
 	let spoken = $state("");
 	$effect(() => {
@@ -112,7 +100,6 @@
 						{row.name}
 					{/if}
 				</span>
-				<!-- the span stays mounted before the step ends so it has something to fade in; aria-hidden keeps the empty value out of the accessibility tree -->
 				<span class={slots.duration()} aria-hidden={revealed ? undefined : "true"}>
 					{row.duration}
 				</span>
diff --git a/web/src/lib/components/repo/pipelines/WorkflowView.stories.svelte b/web/src/lib/components/repo/pipelines/WorkflowView.stories.svelte
index b3fed12d6..86bcc5e4f 100644
--- a/web/src/lib/components/repo/pipelines/WorkflowView.stories.svelte
+++ b/web/src/lib/components/repo/pipelines/WorkflowView.stories.svelte
@@ -43,8 +43,6 @@
 <script lang="ts">
 	import type { LogStep } from "./logs";
 
-	// a log that actually grows, so a rail jump can be checked against a moving tail
-	// instead of a fixed fixture
 	const feed = () => {
 		const tail = createLogTail();
 		let steps = $state<LogStep[]>(tail.advance());
@@ -65,10 +63,7 @@
 	const live = feed();
 </script>
 
-<!-- every step done: the rail under the active card carries a tick each -->
 <Story name="Default" />
-<!-- run still going: the open step keeps counting, the rail shimmers on it, and the
-     sidebar shows pending siblings -->
 <Story
 	name="Streaming"
 	args={{
@@ -78,8 +73,6 @@
 		status: "streaming"
 	}}
 />
-<!-- failed workflow, single-line spindle error above the logs, and the rail marks the
-     step it died on with a cross -->
 <Story
 	name="Failed workflow"
 	args={{ pipeline: mixed, workflow: mixed.workflows[1], steps: failedWorkflowLog }}
@@ -89,8 +82,6 @@
 	name="Workflow error details"
 	args={{ pipeline: refusedRun, workflow: refused, steps: [] }}
 />
-<!-- killed mid-step: the last step has a start and no end, so neither the log header nor
-     the rail invents a duration for it -->
 <Story
 	name="Cancelled"
 	args={{ pipeline: killed, workflow: killed.workflows[0], steps: cancelledWorkflowLog }}
@@ -105,10 +96,6 @@
 <!-- socket dropped mid-stream -->
 <Story name="Reconnecting" args={{ status: "connecting" }} />
 <Story name="Stream error" args={{ steps: [], error: "workflow not found" }} />
-<!-- log growing on a live run: the rail keeps shimmering on the active step while the
-     viewport stays put through a rail jump, unmoved by the new lines still arriving.
-     the steps go through the template, because args are a snapshot: storybook reads
-     them once per story and never sees the feed move -->
 <Story
 	name="Live tail"
 	args={{
diff --git a/web/src/lib/components/repo/pipelines/WorkflowView.svelte b/web/src/lib/components/repo/pipelines/WorkflowView.svelte
index 715693e5c..a886fbc69 100644
--- a/web/src/lib/components/repo/pipelines/WorkflowView.svelte
+++ b/web/src/lib/components/repo/pipelines/WorkflowView.svelte
@@ -30,8 +30,6 @@
 		error = null
 	}: Props = $props();
 
-	// the two levels talk through here: the log says what it is showing, the rail says
-	// where to go
 	let visibleStep = $state<number | undefined>(undefined);
 	let scrollToStep = $state<((id: number) => void) | undefined>(undefined);
 </script>
diff --git a/web/src/lib/components/repo/pipelines/logs.ts b/web/src/lib/components/repo/pipelines/logs.ts
index 6de7143b4..9038a43d8 100644
--- a/web/src/lib/components/repo/pipelines/logs.ts
+++ b/web/src/lib/components/repo/pipelines/logs.ts
@@ -123,11 +123,8 @@ export const rowKey = (row: LogRow): string => {
 	}
 };
 
-// "pending" never comes out of a live stream — a step only exists once its first frame arrives — it's here for a future plan-driven skeleton
 export type StepStatus = "pending" | "active" | "done" | "error";
 
-// the spindle writes a step's end frame unconditionally, before it checks whether the step errored,
-// and stops starting new steps the moment one does — so the failing step is always the last one present
 export const stepStatuses = (steps: LogStep[], workflow: PipelineStatus): StepStatus[] => {
 	if (steps.length === 0) return [];
 	const last = steps.length - 1;
@@ -141,7 +138,6 @@ export const stepStatuses = (steps: LogStep[], workflow: PipelineStatus): StepSt
 	return steps.map((_, i) => (i === last ? "error" : "done"));
 };
 
-// one sentence for a screen-reader live region
 export const narrate = (steps: LogStep[], workflow: PipelineStatus): string => {
 	if (steps.length === 0) return isLive(workflow) ? "Waiting for the spindle" : "";
 
diff --git a/web/src/lib/components/repo/pipelines/pipeline.ts b/web/src/lib/components/repo/pipelines/pipeline.ts
index 36205ab91..1a351e124 100644
--- a/web/src/lib/components/repo/pipelines/pipeline.ts
+++ b/web/src/lib/components/repo/pipelines/pipeline.ts
@@ -1,15 +1,11 @@
-// mirrors the helpers on types.Pipeline in types/pipeline.go
-
 import type {
 	PipelineStatus,
 	PipelineSummary,
 	PipelineTriggerKind
 } from "$lib/components/repo/types";
 
-/** the trigger tabs */
 export type PipelineFilter = "all" | PipelineTriggerKind;
 
-/** what search looks at. a real bobbin query has to cover the same fields. */
 export const matchesQuery = (pipeline: PipelineSummary, query: string): boolean => {
 	const needle = query.trim().toLowerCase();
 	if (!needle) return true;
@@ -23,7 +19,6 @@ export const matchesQuery = (pipeline: PipelineSummary, query: string): boolean
 	return haystack.some((field) => field.toLowerCase().includes(needle));
 };
 
-/** the order the breakdown lists statuses in */
 export const STATUS_ORDER: PipelineStatus[] = [
 	"success",
 	"failed",
@@ -55,9 +50,7 @@ export const statusCounts = (pipeline: PipelineSummary): Record<PipelineStatus,
 	return counts;
 };
 
-/** one status for the whole run. anything still going wins, so an in-flight run says so. */
 export const aggregateStatus = (pipeline: PipelineSummary): PipelineStatus => {
-	// no workflows yet means no spindle has picked it up
 	if (pipeline.workflows.length === 0) return "pending";
 
 	const counts = statusCounts(pipeline);
@@ -69,17 +62,14 @@ export const aggregateStatus = (pipeline: PipelineSummary): PipelineStatus => {
 	return "success";
 };
 
-/** how many workflows are done — everything except pending and running */
 export const finishedCount = (pipeline: PipelineSummary): number => {
 	const counts = statusCounts(pipeline);
 	return counts.success + counts.failed + counts.timeout + counts.cancelled;
 };
 
-/** "2/3" — how many workflows passed, for spots too tight for the breakdown */
 export const shortSummary = (pipeline: PipelineSummary): string =>
 	`${statusCounts(pipeline).success}/${pipeline.workflows.length}`;
 
-/** "2/3 passed, 1/3 failed" */
 export const longSummary = (pipeline: PipelineSummary): string => {
 	const counts = statusCounts(pipeline);
 	const total = pipeline.workflows.length;
@@ -88,7 +78,6 @@ export const longSummary = (pipeline: PipelineSummary): string => {
 		.join(", ");
 };
 
-/** sum of the workflows, not wall time across the run */
 export const totalDuration = (pipeline: PipelineSummary): number =>
 	pipeline.workflows.reduce((sum, workflow) => sum + workflow.duration, 0);
 
diff --git a/web/src/lib/components/repo/pulls/PullApproveCi.svelte b/web/src/lib/components/repo/pulls/PullApproveCi.svelte
index 9f170a453..33f6f1f29 100644
--- a/web/src/lib/components/repo/pulls/PullApproveCi.svelte
+++ b/web/src/lib/components/repo/pulls/PullApproveCi.svelte
@@ -1,22 +1,7 @@
 <script module lang="ts">
-	/**
-	 * What the approval needs from outside this component. Nothing fills it in yet, so the
-	 * approval never shows in the app — only the stories drive it.
-	 *
-	 * Whoever picks this up: the first two are reachable with code already in the repo.
-	 * hasPipeline is queryPipelines from $lib/api/spindle, called the way PipelineList
-	 * already calls it, narrowed to the round's head. changedWorkflows is the round's diff
-	 * from $lib/api/pullDiff, keeping the paths under .tangled/workflows. approve is the
-	 * only new piece: sh.tangled.ci.triggerPipeline is a procedure, so it wants an
-	 * authenticated spindle client, and every spindle call here so far has been a read.
-	 */
 	export interface PullCiApproval {
-		/** a pipeline already exists for the round's head, so there is nothing to approve */
 		hasPipeline: boolean;
-		/** workflow files this round changed; a non-empty list makes the warning loud */
 		changedWorkflows: string[];
-		/** dispatch the pipeline for this round. hasPipeline is stale until the caller
-		    invalidates the load, so the button only retires for this component's lifetime */
 		approve: () => Promise<void>;
 	}
 </script>
@@ -47,8 +32,6 @@
 		approved = true;
 	});
 
-	// a round that edits its own workflows is the case worth reading twice: the patch
-	// under review is also the code about to run
 	const changed = $derived(changedWorkflows.length > 0);
 </script>
 
diff --git a/web/src/lib/components/repo/pulls/PullDiff.svelte b/web/src/lib/components/repo/pulls/PullDiff.svelte
index 2d9ca56d5..96b01b030 100644
--- a/web/src/lib/components/repo/pulls/PullDiff.svelte
+++ b/web/src/lib/components/repo/pulls/PullDiff.svelte
@@ -108,7 +108,8 @@
 						<Button
 							href={downloadUrls.diff as "/"}
 							data-sveltekit-reload
-							icon={FileDiff}><span class="hidden sm:inline">Download diff</span></Button
+							icon={FileDiff}
+							><span class="hidden sm:inline">Download diff</span></Button
 						>
 					</span>
 				{/if}
diff --git a/web/src/lib/components/repo/tickets/Ticket.stories.svelte b/web/src/lib/components/repo/tickets/Ticket.stories.svelte
index 154db1a93..a207251a0 100644
--- a/web/src/lib/components/repo/tickets/Ticket.stories.svelte
+++ b/web/src/lib/components/repo/tickets/Ticket.stories.svelte
@@ -81,8 +81,6 @@ Knot will mint service-auth to access spindle as gitrepo's authority. This way,
 	{/snippet}
 </Story>
 
-<!-- signed in as someone else, with a moderation service configured: the body row gets a
-	report menu next to the reaction picker -->
 <Story name="Issue as Other User" parameters={{ auth: true, ...moderation }}>
 	{#snippet template(args)}
 		<Ticket {...args} ticket={{ ...args.ticket, author: otherAuthor }} />
diff --git a/web/src/lib/components/repo/types.ts b/web/src/lib/components/repo/types.ts
index 54425bdba..80bbe78d9 100644
--- a/web/src/lib/components/repo/types.ts
+++ b/web/src/lib/components/repo/types.ts
@@ -61,15 +61,12 @@ export interface PullSummary {
 	commentCount: number;
 }
 
-/** the spindle's workflow states, same strings as sh.tangled.ci.pipeline */
 export type PipelineStatus = "pending" | "running" | "success" | "failed" | "timeout" | "cancelled";
 
 export interface WorkflowSummary {
 	name: string;
 	status: PipelineStatus;
-	/** wall time in ms; 0 until the workflow finishes */
 	duration: number;
-	/** first line of the spindle's error, when it failed before running */
 	error?: string;
 	/** absent until the spindle picks the workflow up */
 	startedAt?: string;
@@ -82,11 +79,9 @@ export type PipelineTrigger =
 	| {
 			kind: "pull_request";
 			targetRef: string;
-			/** where the head came from — `handle/repo:branch` when it is a fork */
 			sourceLabel: string;
 			/** the fork's repo did, only when the head came from another repo */
 			sourceRepo?: string;
-			/** the pull page, absent when the pull record is gone */
 			pullPath?: string;
 	  }
 	| { kind: "manual" };
@@ -98,6 +93,5 @@ export interface PipelineSummary {
 	sha: string;
 	createdAt: string;
 	trigger: PipelineTrigger;
-	/** empty while the spindle has not reported back yet */
 	workflows: WorkflowSummary[];
 }
diff --git a/web/src/lib/components/settings/DocsButton.svelte b/web/src/lib/components/settings/DocsButton.svelte
index 2393a15c0..350e4bb56 100644
--- a/web/src/lib/components/settings/DocsButton.svelte
+++ b/web/src/lib/components/settings/DocsButton.svelte
@@ -10,8 +10,6 @@
 	let { href, label = "Documentation" }: Props = $props();
 </script>
 
-<!-- a plain anchor rather than <Button href>: Button's href is a ResolvedPathname
-     so the router can check it, and these point out of the app -->
 <a {href} rel="external noopener noreferrer" class={button()}>
 	<span
 		class="inline-flex min-w-0 items-center justify-center gap-[inherit] transition-transform duration-150 ease-in-out"
diff --git a/web/src/lib/components/settings/DrillDown.svelte b/web/src/lib/components/settings/DrillDown.svelte
index 483a775bd..2775d3667 100644
--- a/web/src/lib/components/settings/DrillDown.svelte
+++ b/web/src/lib/components/settings/DrillDown.svelte
@@ -7,7 +7,6 @@
 		backLabel: string;
 		backHref: string;
 		title: string;
-		/** pass an array to get one line each */
 		description?: string | string[];
 		children: Snippet;
 	}
@@ -19,8 +18,6 @@
 	);
 </script>
 
-<!-- Drill-downs are in-place content swaps: the sidebar stays put and the parent
-     tab stays active, so the only wayfinding is this back link above the title. -->
 <div class="flex items-center gap-2">
 	<a
 		href={resolve(backHref as "/")}
diff --git a/web/src/lib/components/settings/FormActions.svelte b/web/src/lib/components/settings/FormActions.svelte
index b9046f1f3..4168e3622 100644
--- a/web/src/lib/components/settings/FormActions.svelte
+++ b/web/src/lib/components/settings/FormActions.svelte
@@ -2,8 +2,6 @@
 	import type { Snippet } from "svelte";
 
 	interface Props {
-		/** destructive escape hatch that sits opposite the confirm pair, as on the
-		 *  avatar screen's "Remove avatar" */
 		start?: Snippet;
 		children: Snippet;
 	}
diff --git a/web/src/lib/components/settings/FormRow.svelte b/web/src/lib/components/settings/FormRow.svelte
index 16af2adac..8659f0db7 100644
--- a/web/src/lib/components/settings/FormRow.svelte
+++ b/web/src/lib/components/settings/FormRow.svelte
@@ -3,14 +3,10 @@
 
 	interface Props {
 		label: string;
-		/** renders a muted "(optional)" after the label, as on the webhook secret */
 		optional?: boolean;
-		/** pass an array to get one line each */
 		description?: string | string[];
 		for?: string;
-		/** top-align the control when it is taller than the label, e.g. a checkbox list */
 		align?: "center" | "start";
-		/** the control — Figma sizes these to 320px on the right of the row */
 		children: Snippet;
 	}
 
diff --git a/web/src/lib/components/settings/SettingsBlock.svelte b/web/src/lib/components/settings/SettingsBlock.svelte
index 43b35adc3..ba1d67d24 100644
--- a/web/src/lib/components/settings/SettingsBlock.svelte
+++ b/web/src/lib/components/settings/SettingsBlock.svelte
@@ -3,10 +3,8 @@
 	import Separator from "$lib/components/ui/Separator.svelte";
 
 	interface Props {
-		/** Figma uses 16px on General's label blocks and 14px on Access/Pipelines */
 		title?: string;
 		titleSize?: "regular" | "large";
-		/** pass an array to get one line each */
 		description?: string | string[];
 		action?: Snippet;
 		separator?: boolean;
@@ -29,8 +27,6 @@
 
 <div class="flex w-full flex-col gap-4">
 	{#if title || lines.length > 0 || action}
-		<!-- the action sits on the last line of the description, not its middle — until
-		     the description needs the whole phone width, where it drops below instead -->
 		<div
 			class="flex w-full flex-col gap-2 sm:flex-row sm:items-end sm:justify-between sm:gap-16"
 		>
diff --git a/web/src/lib/components/settings/SettingsEmpty.svelte b/web/src/lib/components/settings/SettingsEmpty.svelte
index 910433b72..63ce493a6 100644
--- a/web/src/lib/components/settings/SettingsEmpty.svelte
+++ b/web/src/lib/components/settings/SettingsEmpty.svelte
@@ -6,8 +6,6 @@
 	let { message }: Props = $props();
 </script>
 
-<!-- the settings screens use a single-row card rather than the tall, italic
-     EmptyState the rest of the app uses -->
 <div
 	class="flex w-full items-center justify-center rounded-sm border border-border-default px-4 py-3 typography-paragraph-regular text-foreground-muted"
 >
diff --git a/web/src/lib/components/settings/SettingsEntry.svelte b/web/src/lib/components/settings/SettingsEntry.svelte
index 2cdb83a1f..0f35e1d32 100644
--- a/web/src/lib/components/settings/SettingsEntry.svelte
+++ b/web/src/lib/components/settings/SettingsEntry.svelte
@@ -6,7 +6,6 @@
 		icon?: Component<SvelteHTMLElements["svg"]>;
 		title: string;
 		tags?: Snippet;
-		/** secondary lines under the title — fingerprints, "added 2 months ago" */
 		meta?: Snippet;
 		actions?: Snippet;
 	}
@@ -16,8 +15,6 @@
 	const Glyph = $derived(icon);
 </script>
 
-<!-- The meta lines — fingerprints, URLs — need the full width of a phone, so the
-     trailing buttons drop under them and stay left-aligned with the title. -->
 <div
 	class="flex min-h-8 w-full flex-col gap-2 sm:flex-row sm:items-center sm:justify-between sm:gap-4"
 >
diff --git a/web/src/lib/components/settings/SettingsList.svelte b/web/src/lib/components/settings/SettingsList.svelte
index 951228913..34fe35e5a 100644
--- a/web/src/lib/components/settings/SettingsList.svelte
+++ b/web/src/lib/components/settings/SettingsList.svelte
@@ -2,11 +2,6 @@
 	import { tv, type VariantProps } from "tailwind-variants";
 
 	export const settingsList = tv({
-		// Figma lays these cards out as [row, separator, row] with an 8px gap, so every
-		// row carries 8px of its own padding and divide-y draws the hairline between two
-		// of them — the line ends up centred in the space rather than flush against the
-		// row above. That leaves py-1 for the card itself, which is the rest of the 12px
-		// Figma puts between the card edge and the first row.
 		base: "flex w-full flex-col divide-y divide-border-default rounded-sm border border-border-default py-1 *:py-2",
 		variants: {
 			padding: {
diff --git a/web/src/lib/components/settings/SettingsNav.stories.svelte b/web/src/lib/components/settings/SettingsNav.stories.svelte
index 5a7b3efc6..927c9caa7 100644
--- a/web/src/lib/components/settings/SettingsNav.stories.svelte
+++ b/web/src/lib/components/settings/SettingsNav.stories.svelte
@@ -32,8 +32,6 @@
 	});
 </script>
 
-<!-- the frame stretches to its container in the settings layout, so the stories put it
-     in a tall box rather than letting it hug its items -->
 <Story name="Default">
 	{#snippet template(args)}
 		<div class="flex h-142 w-44 items-stretch">
@@ -50,8 +48,6 @@
 	{/snippet}
 </Story>
 
-<!-- the sidebar is a md-and-up shape: narrow the browser under 768px and this story
-     renders the select it collapses into instead -->
 <Story name="Collapsed">
 	{#snippet template(args)}
 		<div class="flex w-94.5 items-stretch">
diff --git a/web/src/lib/components/settings/SettingsNav.svelte b/web/src/lib/components/settings/SettingsNav.svelte
index 44490a9ba..457d2b902 100644
--- a/web/src/lib/components/settings/SettingsNav.svelte
+++ b/web/src/lib/components/settings/SettingsNav.svelte
@@ -28,11 +28,7 @@
 	};
 </script>
 
-<!-- Below md the panel is only as wide as the phone, so the sidebar collapses into
-     a native picker rather than seven rows that push the page content off-screen.
-     The hairline under it stands in for the sidebar's edge. -->
 <div class="flex w-full flex-col gap-4 md:hidden">
-	<!-- the active tab lives in the url, so navigation is what updates it: no two way binding -->
 	<Select {options} value={active} onSelect={jump} {label} icon={ActiveGlyph} />
 	<Separator />
 </div>
diff --git a/web/src/lib/components/settings/SettingsPanel.stories.svelte b/web/src/lib/components/settings/SettingsPanel.stories.svelte
index 6f709b03a..50db5b72b 100644
--- a/web/src/lib/components/settings/SettingsPanel.stories.svelte
+++ b/web/src/lib/components/settings/SettingsPanel.stories.svelte
@@ -42,8 +42,6 @@
 	});
 </script>
 
-<!-- Narrow the browser under 768px to see the nav collapse into its select and the
-     panel go full-bleed; under 640px the rows drop their controls onto a second line. -->
 <Story name="User settings">
 	<SettingsPanel items={userItems} active="keys">
 		<SettingsHeader
diff --git a/web/src/lib/components/settings/SettingsPanel.svelte b/web/src/lib/components/settings/SettingsPanel.svelte
index 217fe9639..888dc4364 100644
--- a/web/src/lib/components/settings/SettingsPanel.svelte
+++ b/web/src/lib/components/settings/SettingsPanel.svelte
@@ -12,9 +12,6 @@
 	let { items, active, label, children }: Props = $props();
 </script>
 
-<!-- Two shapes for one screen: a bordered card with the nav down its left edge on
-     desktop, and below md a full-bleed panel that only keeps its top and bottom
-     hairlines, since the phone frame already supplies the side margins. -->
 <div
 	class="flex w-full flex-col items-stretch gap-4 border-y border-border-default bg-background-default px-3 pt-3 pb-6 md:min-h-150 md:flex-row md:items-start md:overflow-hidden md:rounded-sm md:border md:p-0"
 >
diff --git a/web/src/lib/components/settings/SettingsRow.svelte b/web/src/lib/components/settings/SettingsRow.svelte
index ce82940c7..5666315e9 100644
--- a/web/src/lib/components/settings/SettingsRow.svelte
+++ b/web/src/lib/components/settings/SettingsRow.svelte
@@ -3,21 +3,12 @@
 	import type { SvelteHTMLElements } from "svelte/elements";
 
 	interface Props {
-		/** plain-text label — omit and render whatever you need through `label` */
 		title?: string;
-		/** pass an array to get one line each */
 		description?: string | string[];
 		icon?: Component<SvelteHTMLElements["svg"]>;
-		/** replaces `title`/`icon` when the leading side is more than a label */
 		label?: Snippet;
 		children?: Snippet;
-		/** top-align the control instead of centring it, for tall right-hand content */
 		align?: "center" | "start";
-		/**
-		 * drop the trailing controls onto their own line below sm. Set it wherever the
-		 * design does: rows carrying a 320px field, a long identifier, or a labelled
-		 * button next to a wide leading block. Short label/toggle pairs stay on one line.
-		 */
 		stack?: boolean;
 		class?: string;
 	}
@@ -70,7 +61,6 @@
 		</span>
 	{/if}
 	{#if children}
-		<!-- a field that wants the whole width says so with `w-full sm:w-80` and fills it instead -->
 		<div
 			class="flex items-center gap-2 {stack
 				? 'w-full justify-end sm:w-auto sm:shrink-0'
diff --git a/web/src/lib/components/settings/SettingsSection.svelte b/web/src/lib/components/settings/SettingsSection.svelte
index 52852870e..e6a5194c8 100644
--- a/web/src/lib/components/settings/SettingsSection.svelte
+++ b/web/src/lib/components/settings/SettingsSection.svelte
@@ -3,9 +3,7 @@
 	import SettingsList from "./SettingsList.svelte";
 
 	interface Props {
-		/** omit for the leading card, which Figma leaves unlabelled */
 		title?: string;
-		/** gap between the heading and its card — 12px on the user pages, 16 on repo */
 		headingGap?: "3" | "4";
 		framed?: boolean;
 		children: Snippet;
diff --git a/web/src/lib/components/settings/SettingsToolbar.svelte b/web/src/lib/components/settings/SettingsToolbar.svelte
index 4fbab22f1..6e35d8828 100644
--- a/web/src/lib/components/settings/SettingsToolbar.svelte
+++ b/web/src/lib/components/settings/SettingsToolbar.svelte
@@ -5,7 +5,6 @@
 	interface Props {
 		start?: Snippet;
 		end?: Snippet;
-		/** the hairline under the toolbar, drawn in every Figma tab that has one */
 		separator?: boolean;
 	}
 
diff --git a/web/src/lib/components/settings/ThemePicker.svelte b/web/src/lib/components/settings/ThemePicker.svelte
index afa13dc54..0c9249f07 100644
--- a/web/src/lib/components/settings/ThemePicker.svelte
+++ b/web/src/lib/components/settings/ThemePicker.svelte
@@ -12,8 +12,6 @@
 	const name = $props.id();
 </script>
 
-<!-- three 135px thumbnails need 437px, so on a phone they wrap two-up and Dark
-     drops onto a second line -->
 <div class="flex w-full flex-wrap gap-4 sm:w-auto">
 	<label class="flex w-33.75 cursor-pointer flex-col gap-2">
 		<span
diff --git a/web/src/lib/components/settings/ThemePreview.svelte b/web/src/lib/components/settings/ThemePreview.svelte
index 6a1080fea..b6f813066 100644
--- a/web/src/lib/components/settings/ThemePreview.svelte
+++ b/web/src/lib/components/settings/ThemePreview.svelte
@@ -1,14 +1,4 @@
 <script module lang="ts">
-	/**
-	 * The Light and Dark thumbnails in Figma are a little mock of the UI built from
-	 * plain rectangles. Both share one geometry and differ only in palette, so the
-	 * shapes live here once and the colours come in as a literal map.
-	 *
-	 * Those literals are deliberate: a Light thumbnail has to keep looking light
-	 * while the app itself is in dark mode, so it cannot use semantic tokens. The
-	 * Auto thumbnail is the exception and does use them — following the system is
-	 * the whole point of that option.
-	 */
 	type Role = "surface" | "strong" | "placeholder" | "muted" | "subtle" | "success" | "faint";
 
 	interface Rect {
@@ -19,7 +9,6 @@
 		role: Role;
 	}
 
-	// coordinates are Figma's, in a 135 × 84 box
 	const RECTS: Rect[] = [
 		{ x: 0, y: 0, w: 135, h: 6, role: "surface" },
 		{ x: 11.3, y: 1.5, w: 9, h: 3, role: "strong" },
@@ -63,7 +52,6 @@
 			surface: "#1f2937",
 			strong: "#f3f4f6",
 			placeholder: "#9ca3af",
-			// dark drops the muted/subtle distinction — both resolve to gray-400
 			muted: "#9ca3af",
 			subtle: "#9ca3af",
 			success: "#4ade80",
diff --git a/web/src/lib/components/settings/tabs/ProfileTab.svelte b/web/src/lib/components/settings/tabs/ProfileTab.svelte
index 04a59c176..bcf363883 100644
--- a/web/src/lib/components/settings/tabs/ProfileTab.svelte
+++ b/web/src/lib/components/settings/tabs/ProfileTab.svelte
@@ -45,8 +45,6 @@
 
 	let form = $state(structuredClone(EMPTY));
 
-	// Figma keeps Save disabled until something actually changed, and only then
-	// reveals Reset and the "Unsaved changes" note
 	const dirty = $derived(JSON.stringify(form) !== JSON.stringify(EMPTY));
 	const reset = () => (form = structuredClone(EMPTY));
 
@@ -102,7 +100,6 @@
 			<CodeChip>{user?.handle ?? "…"}</CodeChip>
 			<Button variant="ghost" href="/settings/profile/handle">Change</Button>
 		</SettingsRow>
-		<!-- a DID is too long to sit beside its label on a phone; a PDS hostname is not -->
 		<SettingsRow title="Decentralized Identifier (DID)" stack>
 			<CodeChip class="w-full break-all sm:w-auto">{user?.did ?? "…"}</CodeChip>
 		</SettingsRow>
diff --git a/web/src/lib/components/ui/Avatar.svelte b/web/src/lib/components/ui/Avatar.svelte
index b33d9b642..723db07ac 100644
--- a/web/src/lib/components/ui/Avatar.svelte
+++ b/web/src/lib/components/ui/Avatar.svelte
@@ -1,9 +1,6 @@
 <script module lang="ts">
 	import { tv, type VariantProps } from "tailwind-variants";
 
-	// the sizes the design system names, from Figma's User component (node 723:254).
-	// Size=Header is not a rung here: it draws the same 26px circle as Size=Large
-	// and differs only in the text style beside it.
 	export const avatar = tv({
 		base: "shrink-0 rounded-full border border-border-default",
 		variants: {
@@ -25,9 +22,6 @@
 
 	export type AvatarSize = NonNullable<VariantProps<typeof avatar>["size"]>;
 
-	// the spacing unit is 4px, so these are the class numbers times four. the avatar is
-	// fetched at twice this so that it stays sharp at 2x. `full` has no size of its own,
-	// the layout decides it, so there is nothing to fetch at.
 	const sizePx = {
 		mini: 13,
 		small: 17,
diff --git a/web/src/lib/components/ui/Button.svelte b/web/src/lib/components/ui/Button.svelte
index cd7a231b6..4c9a37e72 100644
--- a/web/src/lib/components/ui/Button.svelte
+++ b/web/src/lib/components/ui/Button.svelte
@@ -7,7 +7,6 @@
 			"transition-colors duration-150 ease-in-out",
 			"hover:no-underline",
 			"focus-visible:outline-2 focus-visible:outline-offset-2",
-			// Figma models disabled as a distinct fill/text pair, not a dimmed enabled state
 			"disabled:pointer-events-none aria-disabled:pointer-events-none"
 		],
 		variants: {
@@ -32,8 +31,6 @@
 					"focus-visible:outline-border-focus",
 					"disabled:text-foreground-disabled aria-disabled:text-foreground-disabled"
 				],
-				// the outline is what carries the variant, so dropping it would read as a
-				// different button.
 				danger: [
 					"border border-border-default bg-background-default text-foreground-danger",
 					"hover:bg-background-subtle",
@@ -53,11 +50,6 @@
 					"disabled:border-border-subtle disabled:text-foreground-warning-disabled aria-disabled:text-foreground-warning-disabled"
 				]
 			},
-			// the min-h is the button's real height (32/36/40 in Figma), so py has to stay
-			// small enough that line-height + padding + border never exceeds it — otherwise a
-			// button with a label grows past the min-h while an icon-only one stays on it, and
-			// the two render at different heights side by side. py only takes over as the
-			// floor when a label wraps to a second line.
 			size: {
 				mini: "min-h-6 gap-1 px-1 py-0.5 typography-paragraph-mini",
 				small: "min-h-8 gap-1.5 px-2 py-1 typography-paragraph-small",
@@ -153,8 +145,7 @@
 </script>
 
 {#snippet content()}
-	<!-- single wrapper so the press animation moves the label/icon, not the button box.
-	     the transition matches the ::before shadow's so both halves of the press ease together. -->
+	<!-- the transition matches the ::before shadow's so both halves of the press ease together. -->
 	<span
 		class="inline-flex min-w-0 items-center justify-center gap-[inherit] transition-transform duration-150 ease-in-out"
 	>
diff --git a/web/src/lib/components/ui/ButtonGroup.svelte b/web/src/lib/components/ui/ButtonGroup.svelte
index 807547805..c23f75ff1 100644
--- a/web/src/lib/components/ui/ButtonGroup.svelte
+++ b/web/src/lib/components/ui/ButtonGroup.svelte
@@ -19,14 +19,7 @@
 					"[&>*>button]:border-y-0",
 					"[&>*:not(:first-child)>button]:[--btn-radius-l:0px]",
 					"[&>*:not(:last-child)>button]:[--btn-radius-r:0px]",
-					// children overlap by 1px so adjacent borders collapse into a single seam, which
-					// also means a child's fill paints into its neighbour's border column. ghost
-					// segments have a transparent border and nothing to repaint there, so every
-					// bordered child has to sit above them — otherwise hovering a ghost rubs out the
-					// selected segment's border on whichever edge they share.
 					"[&>*:not([data-variant=ghost])]:z-10",
-					// the group clips overflow, so an outward focus ring gets cut off at its edges and
-					// by bordered neighbours. draw it inside the child instead.
 					"[&>*:focus-visible]:-outline-offset-2"
 				]
 			},
diff --git a/web/src/lib/components/ui/ColorBall.svelte b/web/src/lib/components/ui/ColorBall.svelte
index 833aa9700..f58181a3f 100644
--- a/web/src/lib/components/ui/ColorBall.svelte
+++ b/web/src/lib/components/ui/ColorBall.svelte
@@ -10,7 +10,6 @@
 				large: "size-8"
 			}
 		},
-		// the language dot is by far the common case, so the smallest rung is the default here
 		defaultVariants: {
 			size: "small"
 		}
@@ -21,7 +20,6 @@
 
 <script lang="ts">
 	interface Props {
-		/** any CSS colour, e.g. a language colour or a label's hex */
 		color: string;
 		size?: ColorBallVariants["size"];
 		class?: string;
diff --git a/web/src/lib/components/ui/Combobox.svelte b/web/src/lib/components/ui/Combobox.svelte
index 1c04b21d3..01a74ecdc 100644
--- a/web/src/lib/components/ui/Combobox.svelte
+++ b/web/src/lib/components/ui/Combobox.svelte
@@ -1,8 +1,6 @@
 <script module lang="ts">
 	import { tv, type VariantProps } from "tailwind-variants";
 
-	// the box, its border and its state colours come from selectField, shared with the native
-	// rendering so flipping `rich` on a Select cannot change how the field looks
 	export const combobox = tv({
 		slots: {
 			root: "relative inline-block w-full",
@@ -41,8 +39,6 @@
 
 	interface Props {
 		options: SelectOption[];
-		/** two-way; the selected option's value. Pass without `bind:` when the truth lives
-		 *  elsewhere — a ref in the url, say — and let `onSelect` do the navigating. */
 		value?: string;
 		onSelect?: (value: string) => void;
 		placeholder?: string;
@@ -50,13 +46,11 @@
 		emptyLabel?: string;
 		label?: string;
 		icon?: Component<SvelteHTMLElements["svg"]>;
-		/** take filtering over, e.g. to query a server: `options` is then rendered as given */
 		onSearch?: (query: string) => void;
 		loading?: boolean;
 		error?: boolean;
 		disabled?: boolean;
 		align?: SelectAlign;
-		/** lets a Field's label point at this control */
 		id?: string;
 		class?: string;
 		panelClass?: string;
@@ -98,8 +92,6 @@
 	let open = $state(false);
 	let search = $state("");
 	let activeIndex = $state(-1);
-	// only keyboard navigation scrolls the list: doing it on hover yanks the row out from
-	// under the pointer
 	let scrollActiveIntoView = false;
 
 	let triggerEl = $state<HTMLButtonElement>();
@@ -134,8 +126,6 @@
 	);
 
 	const selected = $derived(options.find((option) => option.value === value));
-	// a value with no matching option still deserves a label: the ref selector can be sitting
-	// on a commit sha, or on a branch past the point the list was capped
 	const triggerLabel = $derived(selected ? (selected.label ?? selected.value) : value);
 
 	const classes = $derived(combobox({ placeholder: triggerLabel === "" || undefined }));
@@ -214,7 +204,6 @@
 				if (selectable.length > 0) setActive(selectable[selectable.length - 1], true);
 				break;
 			case "Enter": {
-				// a bare Enter in a form would submit it, whether or not a row is active
 				event.preventDefault();
 				const option = visible[activeIndex];
 				if (option) select(option);
diff --git a/web/src/lib/components/ui/CopyButton.svelte b/web/src/lib/components/ui/CopyButton.svelte
index 52d0e3850..77c48ad02 100644
--- a/web/src/lib/components/ui/CopyButton.svelte
+++ b/web/src/lib/components/ui/CopyButton.svelte
@@ -22,7 +22,6 @@
 		copiedLabel?: string;
 		errorLabel?: string;
 		showLabel?: boolean;
-		/** temporary A/B switch: morph the icon instead of crossfading the three faces */
 		morph?: boolean;
 		timeout?: number;
 		variant?: ButtonVariants["variant"];
@@ -126,8 +125,6 @@
 </Button>
 
 <style>
-	/* the three faces share one grid cell, so the button never resizes as they
-	   swap and the label column stays as wide as its longest word */
 	.cell :global(.layer),
 	.label {
 		grid-column: 1;
diff --git a/web/src/lib/components/ui/Dropdown.svelte b/web/src/lib/components/ui/Dropdown.svelte
index 26bdd00a2..05bff22f4 100644
--- a/web/src/lib/components/ui/Dropdown.svelte
+++ b/web/src/lib/components/ui/Dropdown.svelte
@@ -99,8 +99,6 @@
 	const focusTrigger = () => {
 		triggerElement?.focus();
 	};
-	// intentionally not $state: only used for imperative focus, and reactive
-	// reads inside DropdownItem's register $effect would loop it forever
 	let items: HTMLElement[] = [];
 
 	const close = () => {
@@ -166,9 +164,6 @@
 
 	setContext("dropdown-close", close);
 	setContext("dropdown-register", (el: HTMLElement) => {
-		// insert in DOM order, not mount order, since conditionally rendered
-		// items can register after already-registered items that appear later
-		// in the DOM
 		const index = items.findIndex(
 			(item) => item.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_PRECEDING
 		);
diff --git a/web/src/lib/components/ui/Field.svelte b/web/src/lib/components/ui/Field.svelte
index 0eca66202..8074382b3 100644
--- a/web/src/lib/components/ui/Field.svelte
+++ b/web/src/lib/components/ui/Field.svelte
@@ -8,8 +8,6 @@
 			subtitle: "typography-paragraph-small text-foreground-muted"
 		},
 		variants: {
-			// settings forms label their fields in small caps; the onboarding steps use
-			// sentence case, so the casing is a variant rather than baked into the slot
 			labelCase: {
 				upper: { label: "tracking-wide uppercase" },
 				normal: { label: "" }
diff --git a/web/src/lib/components/ui/Input.svelte b/web/src/lib/components/ui/Input.svelte
index eaa3dec4e..080076583 100644
--- a/web/src/lib/components/ui/Input.svelte
+++ b/web/src/lib/components/ui/Input.svelte
@@ -1,6 +1,4 @@
 <script lang="ts">
-	// inputField and InputTag live in ./inputField, which owns what both renderings read;
-	// re-exporting them from here trips eslint's no-import-assign on module scripts
 	import type { Component, Snippet } from "svelte";
 	import type { HTMLInputAttributes, SvelteHTMLElements } from "svelte/elements";
 	import {
@@ -25,35 +23,22 @@
 		suffixClass?: string;
 		element?: HTMLInputElement;
 		class?: string;
-		/** Turn the field into a token editor: it still takes a draft, but what's committed lands
-		 *  as a removable chip beside the caret. Same box, same states — reach for it once one
-		 *  value stops being enough. */
 		rich?: boolean;
 		// rich only
-		/** two-way; the tokens the field holds. A bare `value` is a tag, a `field` makes it a filter. */
 		tags?: InputTag[];
-		/** hard ceiling on tags; native `max` still reaches the plain input */
 		maxTags?: number;
-		/** what commits the draft: Enter, a typed space, a typed comma, or any mix. Defaults to
-		 *  Enter alone. Whatever's in here splits a paste too. */
 		commitOn?: TagCommitKey[];
 		allowDuplicates?: boolean;
-		/** vet a candidate before it lands; return a string to say why it didn't */
 		validate?: (value: string) => boolean | string;
-		/** typeahead source. Anything already added is dropped from the list. */
 		suggestions?: InputTag[];
-		/** take filtering over, e.g. to query a server: `suggestions` is then rendered as given */
 		onSearch?: (query: string) => void;
 		onAdd?: (tag: InputTag) => void;
 		onRemove?: (tag: InputTag) => void;
-		/** persistent helper text; a rejection cross-fades over it */
 		hint?: string;
 		emptyLabel?: string;
 		label?: string;
 		panelClass?: string;
-		/** the body of a chip — this is where a User, a ColorBall, an avatar stack goes */
 		tag?: Snippet<[InputTag]>;
-		/** the body of a suggestion row; defaults to the chip's rendering */
 		suggestion?: Snippet<[InputTag]>;
 	}
 
diff --git a/web/src/lib/components/ui/Link.svelte b/web/src/lib/components/ui/Link.svelte
index a2cf9c0f3..f6521274d 100644
--- a/web/src/lib/components/ui/Link.svelte
+++ b/web/src/lib/components/ui/Link.svelte
@@ -12,8 +12,6 @@
 				warning:
 					"text-foreground-link-warning hover:text-foreground-link-warning-hover focus-visible:outline-foreground-link-warning",
 				danger: "text-foreground-link-danger hover:text-foreground-link-danger-hover focus-visible:outline-foreground-link-danger",
-				// takes its color from whatever it sits in, for a link inside a row of
-				// plain text that should read as text until you hover it
 				inherit: "text-inherit focus-visible:outline-border-focus"
 			},
 			size: {
diff --git a/web/src/lib/components/ui/MarkdownEditor.svelte b/web/src/lib/components/ui/MarkdownEditor.svelte
index 57388143e..a567ceb20 100644
--- a/web/src/lib/components/ui/MarkdownEditor.svelte
+++ b/web/src/lib/components/ui/MarkdownEditor.svelte
@@ -36,8 +36,6 @@
 	}: Props = $props();
 
 	const surface = $derived(transparent ? "bg-transparent" : "bg-background-default");
-	// the preview pane replaces the field in place, so it has to carry the field's own
-	// height and inset — otherwise the whole editor resizes every time you switch tabs.
 	const pane = `rounded border border-border-default px-2.5 py-2 ${textareaMinHeight}`;
 
 	let preview = $state<Promise<string> | null>(null);
diff --git a/web/src/lib/components/ui/Modal.svelte b/web/src/lib/components/ui/Modal.svelte
index c67bbc25b..1cb33ec42 100644
--- a/web/src/lib/components/ui/Modal.svelte
+++ b/web/src/lib/components/ui/Modal.svelte
@@ -56,9 +56,8 @@
 	let panel = $state<HTMLDialogElement>();
 	const titleId = $props.id();
 
-	// the top layer still needs a rendered element, so a modal opened from inside a
-	// popover (a dropdown item, say) would go dark with the popover that closes behind
-	// it. living on <body> keeps it clear of anything that hides its ancestors.
+	// portals to <body>: a modal opened from inside a popover must not go dark when
+	// that popover's top-layer entry closes.
 	const toBody = (node: HTMLElement) => {
 		document.body.appendChild(node);
 		return () => node.remove();
@@ -124,10 +123,6 @@
 		overflow: hidden;
 	}
 
-	/* the panel rides in on a spring (stiffness 420, damping 36, mass 0.9) sampled
-	   over its 300ms settle, while the fade finishes at 160ms — so it is fully
-	   painted while still travelling its last couple of pixels. leaving is a plain
-	   curve, shorter and closer in, because a dismissal should not linger. */
 	.modal-panel {
 		--modal-spring: linear(
 			0,
diff --git a/web/src/lib/components/ui/MoreMenu.svelte b/web/src/lib/components/ui/MoreMenu.svelte
index b65ae7897..d137eb510 100644
--- a/web/src/lib/components/ui/MoreMenu.svelte
+++ b/web/src/lib/components/ui/MoreMenu.svelte
@@ -2,14 +2,6 @@
 	import EllipsisVertical from "$icon/ellipsis-vertical";
 	import Dropdown, { type DropdownProps } from "./Dropdown.svelte";
 
-	/**
-	 * The secondary actions of a thing, behind one ellipsis. It is a Dropdown with a
-	 * settled trigger, so anything Dropdown takes passes straight through — reach for
-	 * Dropdown itself when the trigger has to say something else.
-	 *
-	 * `label` names the button for screen readers and has to say *which* thing it acts
-	 * on: a list of rows each answering "More actions" gives no way to tell them apart.
-	 */
 	type Props = Omit<DropdownProps, "trigger" | "variant" | "label"> & { label: string };
 
 	let {
diff --git a/web/src/lib/components/ui/MorphIcon.svelte b/web/src/lib/components/ui/MorphIcon.svelte
index 87ce4c6a4..42b2c38c4 100644
--- a/web/src/lib/components/ui/MorphIcon.svelte
+++ b/web/src/lib/components/ui/MorphIcon.svelte
@@ -1,13 +1,9 @@
 <script lang="ts">
-	// the only file that imports morphicons. it is a young package, so keeping the
-	// whole third-party surface behind one wrapper means swapping it later is one
-	// file, not a sweep across every morph in the app.
 	import { MorphIcon as Morph, type IconInput, type MorphIconProps } from "morphicons/svelte";
 
 	interface Props {
 		icon: IconInput;
 		spring?: MorphIconProps["spring"];
-		/** names the icon for screen readers; without it the svg is decorative */
 		label?: string;
 		class?: string;
 	}
diff --git a/web/src/lib/components/ui/Select.svelte b/web/src/lib/components/ui/Select.svelte
index 9bad43760..566513152 100644
--- a/web/src/lib/components/ui/Select.svelte
+++ b/web/src/lib/components/ui/Select.svelte
@@ -1,6 +1,4 @@
 <script lang="ts">
-	// SelectOption and SelectAlign live in ./selectField, which owns the shape both renderings
-	// read; re-exporting them from here trips eslint's no-import-assign on module scripts
 	import ChevronDown from "$icon/chevron-down";
 	import type { Component, Snippet } from "svelte";
 	import type { SvelteHTMLElements } from "svelte/elements";
@@ -9,22 +7,14 @@
 
 	interface Props {
 		options: SelectOption[];
-		/** two-way; the selected option's value. Pass without `bind:` when the truth lives
-		 *  elsewhere — a ref in the url, say — and let `onSelect` do the navigating. */
 		value?: string;
-		/** Swap the native control for a searchable listbox. Same options, same box: reach for it
-		 *  once a list is long enough that scanning it beats reading it. */
 		rich?: boolean;
 		onSelect?: (value: string) => void;
-		/** the empty row shown first, e.g. "Choose stat"; picking it clears the value */
 		placeholder?: string;
 		label?: string;
-		/** the icon stands for the current selection, so keep it in step with `value`
-		 *  rather than the list. */
 		icon?: Component<SvelteHTMLElements["svg"]>;
 		error?: boolean;
 		disabled?: boolean;
-		/** lets a Field's label point at this control */
 		id?: string;
 		class?: string;
 		searchPlaceholder?: string;
@@ -58,8 +48,6 @@
 		footer
 	}: Props = $props();
 
-	// a native optgroup has to nest.
-	// the rich rendering keeps the array flat and emits headings between rows instead.
 	const groups = $derived(
 		options.reduce<{ label?: string; options: SelectOption[] }[]>((groups, option) => {
 			const last = groups.at(-1);
diff --git a/web/src/lib/components/ui/ShimmerText.svelte b/web/src/lib/components/ui/ShimmerText.svelte
index 9b7d809b1..a5cf63c64 100644
--- a/web/src/lib/components/ui/ShimmerText.svelte
+++ b/web/src/lib/components/ui/ShimmerText.svelte
@@ -2,7 +2,6 @@
 	import { tv, type VariantProps } from "tailwind-variants";
 
 	export const shimmerText = tv({
-		// the sweep is sized by the text rather than by the column
 		base: "inline-block w-fit",
 		variants: {
 			color: {
@@ -28,15 +27,9 @@
 	import type { Snippet } from "svelte";
 	import type { HTMLAttributes } from "svelte/elements";
 
-	// text whose own colour is swept by a lighter (or, in dark mode, darker)
-	// highlight — for pending states like "cloning", "running", "waiting for a
-	// runner". Ported from spelte.dev/docs/shimmer-text, with the js animation
-	// dropped for plain css and the palette swapped for our semantic tokens.
 	interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, "class" | "children"> {
 		color?: ShimmerTextVariants["color"];
-		/** seconds for one full cycle — the sweep takes half of it, then it rests */
 		duration?: number;
-		/** seconds to wait before the first sweep, for staggering several lines */
 		delay?: number;
 		class?: string;
 		children: Snippet;
@@ -97,8 +90,6 @@
 		animation: shimmer var(--shimmer-duration) linear var(--shimmer-delay) infinite;
 	}
 
-	/* parked off to the left, the gradient never shows and the flat
-	   background-color paints the text in its own colour */
 	@media (prefers-reduced-motion: reduce) {
 		.shimmer {
 			animation: none;
diff --git a/web/src/lib/components/ui/Tabs.svelte b/web/src/lib/components/ui/Tabs.svelte
index 15ad8aca4..47c105fec 100644
--- a/web/src/lib/components/ui/Tabs.svelte
+++ b/web/src/lib/components/ui/Tabs.svelte
@@ -28,7 +28,6 @@
 					plate: "rounded-sm border border-border-navigation-item-active bg-background-navigation-item",
 					item: "min-h-8 w-full gap-1.5 overflow-hidden rounded-sm border border-transparent px-3 py-1.5 typography-paragraph-regular text-foreground-default transition-colors duration-150 ease-in-out focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-border-focus",
 					icon: "size-3.5 shrink-0",
-					// Figma clips the item rather than letting a long label wrap it taller
 					label: "min-w-0 truncate",
 					count: "ml-auto"
 				},
@@ -117,7 +116,6 @@
 		class: navClass
 	}: Props = $props();
 
-	// resolved up front so the plate can match hrefs against the destination url
 	const items = $derived(
 		defs.map((tab) => ({
 			...tab,
@@ -127,9 +125,6 @@
 		}))
 	);
 
-	// the plate follows where we're heading rather than where we are, so it leaves
-	// the moment you click instead of waiting on the route's load; aria-current
-	// stays behind on the page that's still on screen
 	const selected = $derived.by(() => {
 		const dest = navigating.to?.url;
 		if (!dest) return active;
@@ -183,9 +178,6 @@
 		return () => observer.disconnect();
 	});
 
-	// the first placement lands instantly so the plate never slides in from nowhere;
-	// until it happens the selected tab wears the chrome itself, which is also what
-	// server-rendered and script-less pages get
 	let placed = false;
 	$effect(() => {
 		if (!box) return;
diff --git a/web/src/lib/components/ui/TagInput.svelte b/web/src/lib/components/ui/TagInput.svelte
index da5eee9e9..e7b408910 100644
--- a/web/src/lib/components/ui/TagInput.svelte
+++ b/web/src/lib/components/ui/TagInput.svelte
@@ -1,22 +1,14 @@
 <script module lang="ts">
 	import { tv, type VariantProps } from "tailwind-variants";
 
-	// the box, its border and its state colours come from inputField, shared with the plain
-	// rendering so flipping `rich` on an Input cannot change how the field looks
 	export const tagInput = tv({
 		slots: {
 			root: "relative inline-flex w-full flex-col",
-			// content-center is what centres a single row of tags on the min-h the size sets,
-			// the way a plain input centres its text
 			list: "flex min-w-0 flex-1 flex-wrap content-center items-center",
 			item: "flex min-w-0",
 			draftItem: "flex min-w-0 flex-1 items-center",
 			chip: "max-w-full",
-			// the leading icon pins to the first row rather than centring across all of them,
-			// so it stays put as tags wrap
 			icon: "text-foreground-subtle",
-			// dimmed off the chip's own colour rather than a fixed token: a filter can sit on any
-			// of Tag's six fills, and a muted grey goes muddy on the coloured ones in dark
 			field: "shrink-0 opacity-70",
 			label: "truncate",
 			remove: "text-foreground-inherit -mr-0.5 flex min-h-0 shrink-0 rounded-xs p-0 transition-colors focus-visible:outline-1 focus-visible:outline-offset-1 focus-visible:outline-border-focus",
@@ -28,8 +20,6 @@
 			optionLabel: "min-w-0 flex-1 truncate",
 			empty: "px-2 py-6 text-center text-foreground-muted",
 			footer: "mt-1.5 flex items-start gap-2",
-			// hint and rejection share one grid cell so one can cross-fade over the other
-			// without the footer changing height
 			message: "grid min-w-0 flex-1",
 			hint: "col-start-1 row-start-1 text-foreground-muted transition-opacity duration-200",
 			rejection:
@@ -59,9 +49,6 @@
 					panel: "typography-paragraph-regular"
 				}
 			},
-			// once a chip is in the row it says what the field is for better than the placeholder
-			// does, so the placeholder gets out of the way — fading, since the chip it makes room
-			// for arrives on a spring rather than appearing
 			hasTags: {
 				true: { draft: "placeholder:opacity-0" },
 				false: {}
@@ -75,17 +62,9 @@
 
 	export type TagInputVariants = VariantProps<typeof tagInput>;
 
-	// interior.dev's chip spring (stiffness 700, damping 46, mass 0.5) refitted to svelte/motion's
-	// per-frame coefficients, the same way Tabs and Pagination carry theirs — 0.4% rms off the
-	// original step response
 	const CHIP = { stiffness: 0.146, damping: 0.64 };
-	// how long the row takes to close over a chip that left — shared by the chips flipping into
-	// place and by the draft sliding after them
 	const REFLOW = 220;
-	// exit is a plain ease-in upstream too, so it stays a transition rather than a spring
 	const EXIT = 180;
-	// the leaving chip drifts a little way into the gap it vacates, as a share of its own width.
-	// Bounded, because a full width would slide it clean over its left-hand neighbour.
 	const EXIT_DRIFT = { share: 0.3, min: 10, max: 28 };
 	const REJECTION_LINGER = 2400;
 </script>
@@ -110,42 +89,28 @@
 	import Button from "$lib/components/ui/Button.svelte";
 
 	interface Props extends Omit<HTMLInputAttributes, "class" | "value" | "size" | "list"> {
-		/** two-way; the tokens the field holds, tags and filters alike */
 		tags?: InputTag[];
-		/** two-way; the uncommitted draft sitting after the last tag */
 		value?: string;
 		size?: InputFieldVariants["size"];
 		error?: boolean;
 		disabled?: boolean;
 		loading?: boolean;
 		iconLeft?: Component<SvelteHTMLElements["svg"]>;
-		/** hard ceiling; shows a counter and turns further drafts away. Not `max`, which stays the
-		 *  native numeric attribute the plain rendering forwards. */
 		maxTags?: number;
-		/** what commits the draft: hitting Enter, typing a space, typing a comma, or any mix of
-		 *  the three. Whatever's in here splits a paste too. */
 		commitOn?: TagCommitKey[];
 		allowDuplicates?: boolean;
-		/** vet a candidate before it lands; return a string to say why it didn't */
 		validate?: (value: string) => boolean | string;
-		/** typeahead source. Anything already added is dropped from the list. */
 		suggestions?: InputTag[];
-		/** take filtering over, e.g. to query a server: `suggestions` is then rendered as given */
 		onSearch?: (query: string) => void;
 		onAdd?: (tag: InputTag) => void;
 		onRemove?: (tag: InputTag) => void;
-		/** persistent helper text; a rejection cross-fades over it */
 		hint?: string;
 		emptyLabel?: string;
-		/** names the field for screen readers */
 		label?: string;
-		/** the draft input, for callers that have to focus or measure it */
 		element?: HTMLInputElement;
 		class?: string;
 		panelClass?: string;
-		/** the body of a chip — this is where a User, a ColorBall, an avatar stack goes */
 		tag?: Snippet<[InputTag]>;
-		/** the body of a suggestion row; defaults to the chip's rendering */
 		suggestion?: Snippet<[InputTag]>;
 	}
 
@@ -184,31 +149,22 @@
 	// stylesheet; naming it explicitly is also what keeps the panel off the viewport corner
 	const anchorName = `--tag-input-${panelId.replace(/[^a-zA-Z0-9_-]/g, "-")}`;
 
-	/** index of the chip Backspace has highlighted but not yet removed, -1 for none */
 	let armed = $state(-1);
 	let rejection = $state<TagRejection>();
 	let rejectionDetail = $state<string>();
 	let rejectionTimer: ReturnType<typeof setTimeout>;
 	let announcement = $state("");
 	let draftFocused = $state(false);
-	/** Escape hides the panel without blurring, so it needs its own flag — reusing the focus
-	 *  one would keep the panel shut for the rest of the visit */
 	let dismissed = $state(false);
 	let activeIndex = $state(-1);
 
 	let panelEl = $state<HTMLElement>();
 	let optionsEl = $state<HTMLElement>();
 
-	// one spring covers both chip moments: a new chip springs up from 0.9, and a chip a duplicate
-	// landed on springs back down from 1.12. Only the chip at `popIndex` reads it, so there is no
-	// need for one spring per tag.
 	const pop = new Spring({ scale: 1, opacity: 1 }, CHIP);
 	let popIndex = $state(-1);
 
 	const atLimit = $derived(maxTags !== undefined && tags.length >= maxTags);
-	// what makes two tags the same tag: the pair, not the two halves glued together. A value
-	// is free to contain spaces, so joining on one would let `author` + `a b` collide with
-	// `author a` + `b`.
 	const identity = (tag: InputTag) => JSON.stringify([tag.field ?? "", tag.value]);
 	const chosen = $derived(new Set(tags.map(identity)));
 
@@ -224,11 +180,7 @@
 		).filter((option) => allowDuplicates || !chosen.has(identity(option)))
 	);
 
-	// a duplicate value is legal when allowDuplicates is on, so the key carries which occurrence
-	// this is — otherwise the second copy collides with the first and the each block throws
 	const rows = $derived.by(() => {
-		// a null-prototype bag, not a Map: this is a throwaway counter inside the derived, and a
-		// plain object can't be mistaken for the reactive state SvelteMap exists for
 		const seen: Record<string, number> = Object.create(null);
 		return tags.map((tag, index) => {
 			const key = identity(tag);
@@ -243,8 +195,6 @@
 	const iconSize = $derived(size === "large" ? "size-5" : "size-4");
 	const glyphSize = $derived(size === "large" ? "size-3.5" : "size-3");
 
-	// Enter is a key, so the keydown handler takes it; space and comma arrive as text, so they're
-	// caught as the draft changes. Both readings come off the same list.
 	const commitsOnEnter = $derived(commitOn.includes("enter"));
 	const separators = $derived(commitOn.map((key) => TAG_COMMIT_CHARS[key]));
 	// newline, space and comma all stand for themselves inside a character class, so there is
@@ -271,7 +221,6 @@
 		pop.target = { scale: 1, opacity: 1 };
 	};
 
-	/** Commit a candidate. Returns whether it landed, so the caller knows to clear the draft. */
 	const add = (candidate: InputTag | string) => {
 		if (disabled) return false;
 
@@ -325,7 +274,6 @@
 		element?.focus();
 	};
 
-	/** Commit everything before the last separator, and hand back what should stay in the draft. */
 	const commitSplit = (raw: string, keepTail: boolean) => {
 		const parts = raw.split(splitter);
 		const tail = keepTail ? (parts.pop() ?? "") : "";
@@ -335,8 +283,6 @@
 
 	const setDraft = (next: string) => {
 		value = next;
-		// the element has to be written directly too: typing "a," leaves `value` at "a", so the
-		// attribute never changes and the comma would sit there in the DOM
 		if (element) element.value = next;
 	};
 
@@ -384,13 +330,10 @@
 				break;
 			case "Enter": {
 				const option = open ? visible[activeIndex] : undefined;
-				// taking the highlighted suggestion is what the panel is there for, no matter what
-				// commits a typed draft
 				if (option) {
 					event.preventDefault();
 					pick(option);
 				} else if (commitsOnEnter) {
-					// a bare Enter in a form would submit it, whether or not the draft lands
 					event.preventDefault();
 					if (add(value)) setDraft("");
 				}
@@ -400,7 +343,6 @@
 			case "Backspace":
 				if (value !== "" || tags.length === 0) break;
 				event.preventDefault();
-				// first press highlights the last chip, second one takes it
 				if (armed === -1) armed = tags.length - 1;
 				else removeAt(armed);
 				break;
@@ -431,8 +373,7 @@
 		}
 	};
 
-	// clicking the field's padding or the gaps between chips should land in the draft, the way
-	// clicking anywhere in a plain input does. pointerdown, so it beats the browser's own focus.
+	// pointerdown, so it beats the browser's own focus.
 	const onPointerDown = (event: PointerEvent) => {
 		if (disabled || (event.target as HTMLElement).closest("button")) return;
 		if (event.target === element) return;
@@ -451,14 +392,8 @@
 		else if (!wantsPanel && shown) el.hidePopover();
 	});
 
-	// fade and shrink, plus a short drift the way the row is closing. This is svelte's own `scale`
-	// shape, hand-rolled only because it has to carry the drift too.
 	const chipExit = (node: Element) => {
 		const el = node as HTMLElement;
-		// svelte pulls a leaving chip out of the flex flow and pins it back in place with an inline
-		// transform, since as the sole absolute child the browser would otherwise park it at the
-		// row's left edge. Keep that in front of ours, the way the built-in transitions do, or every
-		// chip but the first teleports before it fades.
 		const held = getComputedStyle(el).transform;
 		const drift = Math.min(
 			EXIT_DRIFT.max,
@@ -474,11 +409,6 @@
 
 	let draftItemEl = $state<HTMLLIElement>();
 
-	/** The chips after a removed one slide into the gap, and that sweep is what makes a removal
-	 *  read as a removal. The draft sits outside the each block, so it can't take an `animate:`
-	 *  directive and was snapping across instead — which is what made the LAST chip look like a
-	 *  bare fade: with nothing behind it, the draft is the only thing left to move. So FLIP it by
-	 *  hand around whatever changes the row, on the same curve the chips get. */
 	const sweepDraft = (change: () => void) => {
 		const el = draftItemEl;
 		const from = el?.getBoundingClientRect().left;
@@ -518,9 +448,6 @@
 </script>
 
 <div class={slots.root()}>
-	<!-- the box is chrome around the real controls, and the pointerdown is a mouse-only
-	     convenience — a keyboard reaches the draft by tabbing to it, so there is no key handler
-	     to pair with. role=presentation says that rather than inventing a widget role. -->
 	<div
 		class={box}
 		role="presentation"
@@ -555,14 +482,6 @@
 							<span class={slots.label()}>{labelOf(tag)}</span>
 						{/if}
 						{#if !disabled}
-							<!-- <button
-								type="button"
-								class={slots.remove()}
-								aria-label="Remove {labelOf(tag)}"
-								onclick={() => removeAt(index)}
-							>
-								<X class={glyphSize} aria-hidden="true" />
-							</button> -->
 							<Button
 								class={slots.remove()}
 								aria-label="Remove {labelOf(tag)}"
@@ -615,8 +534,6 @@
 		{/if}
 	</div>
 
-	<!-- no suggestions means no typeahead, so the popover isn't built at all rather than sitting
-	     in the top layer empty -->
 	{#if suggestions.length > 0}
 		<div
 			bind:this={panelEl}
diff --git a/web/src/lib/components/ui/Textarea.svelte b/web/src/lib/components/ui/Textarea.svelte
index fbedcc389..65f7f0e26 100644
--- a/web/src/lib/components/ui/Textarea.svelte
+++ b/web/src/lib/components/ui/Textarea.svelte
@@ -13,12 +13,8 @@
 				"flex-1 self-stretch bg-transparent py-2 outline-none placeholder:text-foreground-placeholder read-only:resize-none disabled:cursor-not-allowed disabled:resize-none"
 		},
 		variants: {
-			// the floor has to live on the textarea, not the root: the resize handle only ever
-			// shrinks the textarea, so a min-height on the root would let the handle drag past the
-			// box's own minimum and leave dead space under the field. `regular` keeps
-			// textareaMinHeight above in sync — it's 2px shorter because the root's border sits
-			// outside it. `small` is for short fields (an ssh key, a one-line note) where the
-			// editor-sized floor would swallow the form.
+			// `regular` keeps textareaMinHeight above in sync — it's 2px shorter because the
+			// root's border sits outside it.
 			size: {
 				regular: { textarea: "min-h-63.5" },
 				small: { textarea: "min-h-20" },
@@ -99,8 +95,6 @@
 		textareaField({ error, disabled, readonly, resizeable, size })
 	);
 
-	// the root carries no text inset, so the scrollbar and the resize handle sit flush
-	// against the border.
 	const textareaPadding = $derived(
 		[iconLeft ? "" : "pl-2.5", loading ? "pr-[1.875rem]" : iconRight ? "" : "pr-2.5"]
 			.filter(Boolean)
diff --git a/web/src/lib/components/ui/Tooltip.svelte b/web/src/lib/components/ui/Tooltip.svelte
index 45ee540a9..c75bc21a7 100644
--- a/web/src/lib/components/ui/Tooltip.svelte
+++ b/web/src/lib/components/ui/Tooltip.svelte
@@ -3,8 +3,6 @@
 
 	export const tooltip = tv({
 		slots: {
-			// the wrapper is the anchor: it has to hug its child so the tooltip lines up with
-			// the trigger and not with a full-width box around it
 			wrapper: "inline-flex",
 			// overflow-visible undoes the UA stylesheet's `overflow: auto` on [popover], which
 			// would otherwise clip the arrow off at the bubble's padding box
@@ -30,8 +28,6 @@
 	// module-level singleton the way Dropdown keeps its groups.
 	let openTooltip: (() => void) | undefined;
 
-	// once a tooltip has been shown, moving to a neighbouring trigger inside this window
-	// opens instantly — a toolbar of icon buttons feels broken if every hop re-waits.
 	const SKIP_DELAY = 300;
 	let lastHiddenAt = 0;
 </script>
@@ -89,7 +85,6 @@
 	const resolvedSide = $derived(measuredSide ?? side);
 	let arrowOffset = $state(0);
 
-	// keeps the arrow clear of the bubble's rounded corners when the trigger sits near one end
 	const ARROW_INSET = 8;
 
 	const measureArrow = () => {
@@ -98,7 +93,6 @@
 		const trigger = wrapperEl.getBoundingClientRect();
 		if (bubble.width === 0) return;
 
-		// only the axis the preferred side lives on can flip, so one comparison settles it
 		const vertical = side === "top" || side === "bottom";
 		measuredSide = vertical
 			? bubble.top >= trigger.bottom - 1
@@ -108,8 +102,6 @@
 				? "right"
 				: "left";
 
-		// centre the arrow on the trigger rather than on the bubble: near a viewport edge the
-		// bubble slides sideways to stay visible while the trigger stays put
 		const along = vertical
 			? trigger.left + trigger.width / 2 - bubble.left
 			: trigger.top + trigger.height / 2 - bubble.top;
@@ -171,8 +163,6 @@
 
 	$effect(() => {
 		if (!bubbleEl) return;
-		// keeps a consumer-driven `open` in sync with the popover; both calls are no-ops when
-		// the state already matches, so this cannot ping-pong with onToggle
 		if (open) bubbleEl.showPopover();
 		else bubbleEl.hidePopover();
 	});
@@ -181,8 +171,6 @@
 		if (disabled) hide();
 	});
 
-	// declared after the sync effect above so the popover is already rendered by the time this
-	// one measures — effects in the same flush run in declaration order
 	$effect(() => {
 		if (!open) return;
 		measureArrow();
@@ -190,8 +178,6 @@
 		const onKeydown = (event: KeyboardEvent) => {
 			if (event.key === "Escape") hide();
 		};
-		// the bubble tracks its anchor on scroll for free, but a flip mid-scroll would leave the
-		// arrow on the wrong edge, so re-measure whenever the geometry can have changed
 		document.addEventListener("keydown", onKeydown);
 		document.addEventListener("scroll", measureArrow, { capture: true, passive: true });
 		window.addEventListener("resize", measureArrow);
@@ -206,15 +192,10 @@
 		const wrapper = wrapperEl;
 		if (!wrapper) return;
 
-		// the handlers go on the wrapper rather than in the markup because a span carrying
-		// pointer handlers has no honest ARIA role to give the a11y lint — the interactive
-		// element is the consumer's child. pointerenter/leave don't bubble but do fire on the
-		// wrapper's own boundary, which encloses the trigger, so this is equivalent.
 		wrapper.addEventListener("pointerenter", onPointerEnter);
 		wrapper.addEventListener("pointerleave", hide);
 		wrapper.addEventListener("focusin", onFocusIn);
 		wrapper.addEventListener("focusout", hide);
-		// a click means the user acted; the label has served its purpose and is now in the way
 		wrapper.addEventListener("click", hide);
 
 		// point aria-describedby at whatever interactive element is inside rather than at the
@@ -295,8 +276,7 @@
 		}
 	}
 
-	/* the arrow exactly fills the 0.25rem gap, so its tip meets the trigger's edge.
-	   background-color: inherit keeps it in step with a bubbleClass that repaints the bubble. */
+	/* the arrow exactly fills the 0.25rem gap, so its tip meets the trigger's edge. */
 	.tooltip-bubble[data-arrow]::after {
 		content: "";
 		position: absolute;
diff --git a/web/src/lib/components/ui/User.svelte b/web/src/lib/components/ui/User.svelte
index 9a73015c2..2432210c0 100644
--- a/web/src/lib/components/ui/User.svelte
+++ b/web/src/lib/components/ui/User.svelte
@@ -44,9 +44,6 @@
 
 	export type UserVariants = VariantProps<typeof user>;
 
-	// the avatar names its own size rather than taking a class through a slot, so
-	// that it can pick the image width it needs. header and large share a rung
-	// because in Figma they differ only in the text style beside the circle.
 	const avatarSize = {
 		header: "large",
 		large: "large",
diff --git a/web/src/lib/components/ui/inputField.ts b/web/src/lib/components/ui/inputField.ts
index 9dc1f0d0c..6aade841d 100644
--- a/web/src/lib/components/ui/inputField.ts
+++ b/web/src/lib/components/ui/inputField.ts
@@ -3,24 +3,16 @@ import type { SvelteHTMLElements } from "svelte/elements";
 import { tv, type VariantProps } from "tailwind-variants";
 import type { TagVariants } from "./Tag.svelte";
 
-/** One token in a rich Input. On its own a tag is just a word; give it a `field` and it reads as
- *  a filter — `author: eti` — so tags and filters sit in the same array and remove the same way. */
 export interface InputTag {
-	/** identity: what a duplicate check compares, and what a committed draft becomes */
 	value: string;
-	/** shown instead of `value`; `value` is still what gets matched */
 	label?: string;
-	/** dim prefix inside the chip, which is what turns a tag into a filter */
 	field?: string;
 	color?: TagVariants["color"];
 	icon?: Component<SvelteHTMLElements["svg"]>;
 }
 
-/** why a draft was turned away: the footer says which, and a duplicate flashes the chip it hit */
 export type TagRejection = "duplicate" | "limit" | "invalid";
 
-/** what turns a draft into a chip. Pick any mix: `space` suits one-word tags, `comma` suits
- *  values that can hold spaces, `enter` is the safe default that never eats a keystroke. */
 export type TagCommitKey = "enter" | "space" | "comma";
 
 /** the character each key stands for. Typing one commits, and a pasted one splits — which is why
@@ -48,9 +40,6 @@ export const inputField = tv({
 			true: "cursor-not-allowed bg-background-inset text-foreground-disabled"
 		},
 		rich: {
-			// tags wrap onto more rows, so the box has to be free to grow past the min-h its size
-			// sets. items-stretch hands the full height to the tag list, which then centres its
-			// own rows — that way one row of tags sits exactly where a plain input's text sits.
 			true: "items-center",
 			false: ""
 		}
diff --git a/web/src/lib/components/ui/selectField.ts b/web/src/lib/components/ui/selectField.ts
index 2cafa91ed..c27432a50 100644
--- a/web/src/lib/components/ui/selectField.ts
+++ b/web/src/lib/components/ui/selectField.ts
@@ -1,23 +1,15 @@
 import { tv, type VariantProps } from "tailwind-variants";
 
-/** one row of a Select, in either rendering */
 export interface SelectOption {
 	value: string;
-	/** `value` is still matched when filtering */
 	label?: string;
-	/** right-aligned secondary text, e.g. "default" on a repo's default branch. rich only:
-	 *  a native `<option>` has nowhere to put it */
 	hint?: string;
-	/** consecutive options sharing one become a single optgroup or heading */
 	group?: string;
 	disabled?: boolean;
 }
 
 export type SelectAlign = "left" | "right";
 
-/** The box both renderings draw. Layout differs — a native select needs the chevron overlaid,
- *  the rich trigger lays it out inline — so each renderer appends its own padding and display,
- *  and only the border, fill and state colours live here. */
 export const selectField = tv({
 	slots: {
 		box: "w-full rounded-sm border bg-background-default transition-colors outline-none disabled:cursor-not-allowed",
diff --git a/web/src/lib/components/welcome/FinishStep.svelte b/web/src/lib/components/welcome/FinishStep.svelte
index fc39ad97b..295238bea 100644
--- a/web/src/lib/components/welcome/FinishStep.svelte
+++ b/web/src/lib/components/welcome/FinishStep.svelte
@@ -1,7 +1,6 @@
 <script module lang="ts">
 	import { tv, type VariantProps } from "tailwind-variants";
 
-	// mirrors the appview's onboarding/fragments/finish.html
 	export const tile = tv({
 		slots: {
 			root: "flex flex-col gap-2 rounded-sm border border-border-default p-4",
@@ -66,8 +65,6 @@
 		};
 	}
 
-	// the appview links /core, a shortcut route it owns; the svelte app addresses
-	// repositories as /[handle]/[repo]
 	const coreHref = resolve("/tangled.org/core" as "/");
 	const newRepoHref = resolve("/repo/new");
 
diff --git a/web/src/lib/components/welcome/SocialStep.svelte b/web/src/lib/components/welcome/SocialStep.svelte
index c50959b2a..4d4334715 100644
--- a/web/src/lib/components/welcome/SocialStep.svelte
+++ b/web/src/lib/components/welcome/SocialStep.svelte
@@ -15,7 +15,6 @@
 	}: {
 		people: PersonData[];
 		repos: RepoCardData[];
-		/** fires once the viewer has followed or starred anything on this step */
 		onInteract?: () => void;
 	} = $props();
 
diff --git a/web/src/lib/components/welcome/StepHeader.svelte b/web/src/lib/components/welcome/StepHeader.svelte
index f7829c1be..e7a65243c 100644
--- a/web/src/lib/components/welcome/StepHeader.svelte
+++ b/web/src/lib/components/welcome/StepHeader.svelte
@@ -1,7 +1,6 @@
 <script module lang="ts">
 	import { tv, type VariantProps } from "tailwind-variants";
 
-	// mirrors the appview's onboarding/* fragments
 	export const stepHeader = tv({
 		slots: {
 			root: "flex flex-col gap-2",
diff --git a/web/src/lib/components/welcome/Steps.svelte b/web/src/lib/components/welcome/Steps.svelte
index 349ed09fa..fa8e13cf5 100644
--- a/web/src/lib/components/welcome/Steps.svelte
+++ b/web/src/lib/components/welcome/Steps.svelte
@@ -59,12 +59,9 @@
 	interface Props {
 		items: readonly { key: string; label: string }[];
 		current: number;
-		/** highest step index reached; steps past it are not selectable */
 		furthest: number;
-		/** renders every step done, for the terminal step */
 		complete?: boolean;
 		onSelect: (index: number) => void;
-		/** accessible name for the list */
 		label?: string;
 	}
 
@@ -155,8 +152,6 @@
 					<span class={slot.label()}>{item.label}</span>
 				</button>
 			{:else}
-				<!-- a step past `furthest` is always upcoming: `current` never runs ahead
-				     of it, and `complete` only lands once every step is selectable -->
 				<span class={slot.control()} aria-hidden="true">
 					<span class={slot.marker()}>{index + 1}</span>
 					<span class={slot.label()}>{item.label}</span>
diff --git a/web/src/lib/components/welcome/WelcomeCard.svelte b/web/src/lib/components/welcome/WelcomeCard.svelte
index 5f5234372..ca0e40d0f 100644
--- a/web/src/lib/components/welcome/WelcomeCard.svelte
+++ b/web/src/lib/components/welcome/WelcomeCard.svelte
@@ -39,15 +39,12 @@
 	interface Props {
 		step: number;
 		furthest: number;
-		/** +1 when advancing, -1 when going back — decides which way the pane slides */
 		direction: number;
-		/** greens the advance button once the step has nothing left to do */
 		nextReady?: boolean;
 		nextLoading?: boolean;
 		onBack: () => void;
 		onNext: () => void;
 		onSelect: (index: number) => void;
-		/** rendered per step index, frozen at pane creation so the outgoing pane keeps its own content */
 		children: Snippet<[number]>;
 	}
 
@@ -162,9 +159,6 @@
 		style="{height === null ? '' : `height: ${height}px;`} {heightTransition}"
 	>
 		{#key step}
-			<!-- untrack freezes the index at creation: `children` is a live snippet, so
-			     without this the leaving pane would re-render with the new step's content
-			     halfway through its own exit transition -->
 			{@const frozen = untrack(() => step)}
 			<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
 			<div
diff --git a/web/src/lib/components/welcome/steps.ts b/web/src/lib/components/welcome/steps.ts
index 25c698ebe..b51b4e347 100644
--- a/web/src/lib/components/welcome/steps.ts
+++ b/web/src/lib/components/welcome/steps.ts
@@ -12,5 +12,4 @@ export type WelcomeStepKey = (typeof WELCOME_STEPS)[number]["key"];
 
 export const WELCOME_TOTAL = WELCOME_STEPS.length;
 
-/** the last step has nothing left to skip past */
 export const LAST_STEP = WELCOME_TOTAL - 1;
diff --git a/web/src/lib/format.ts b/web/src/lib/format.ts
index a63948e93..a5f697e4c 100644
--- a/web/src/lib/format.ts
+++ b/web/src/lib/format.ts
@@ -53,8 +53,6 @@ export const compactRelativeTime = (input: string | Date, now: Date = new Date()
 	return `${Math.floor(duration)}y ${suffix}`;
 };
 
-// mirrors the appview's durationFmt.
-// under a second reads "0s", so an instant run still differs from one that never ran.
 export const formatDuration = (ms: number): string => {
 	if (!Number.isFinite(ms) || ms < 0) return "";
 	const total = Math.floor(ms / 1000);
diff --git a/web/src/lib/motion/spring.ts b/web/src/lib/motion/spring.ts
index 62cc7b098..1f89f9e48 100644
--- a/web/src/lib/motion/spring.ts
+++ b/web/src/lib/motion/spring.ts
@@ -1,7 +1,6 @@
-// interior.dev's springs, sampled so CSS transitions and svelte transitions
-// run the identical curve. the closed form below branches on damping ratio:
-// overdamped and critically damped settle monotonically, underdamped
-// overshoots and settles into it — same sampling, different shape.
+// the closed form below branches on damping ratio: overdamped and critically
+// damped settle monotonically, underdamped overshoots and settles into it —
+// same sampling, different shape.
 const springEasing = (stiffness: number, damping: number, mass: number, duration: number) => {
 	const omega = Math.sqrt(stiffness / mass);
 	const zeta = damping / (2 * Math.sqrt(stiffness * mass));
@@ -33,28 +32,23 @@ const springEasing = (stiffness: number, damping: number, mass: number, duration
 const cssLinear = (easing: (t: number) => number, steps = 20) =>
 	`linear(${Array.from({ length: steps + 1 }, (_, i) => +easing(i / steps).toFixed(3)).join(", ")})`;
 
-/** rail markers and progress connectors */
 export const RAIL_DURATION = 400;
 export const railEasing = springEasing(520, 40, 0.5, RAIL_DURATION);
 export const RAIL_EASING = cssLinear(railEasing);
 
-/** interior's crossfade spring (260/34/0.8) — step panes, the card height that
-    follows them, and anything swapping one face for another. it settles in
-    659ms, so it is rescaled at a constant zeta to land inside the 300ms budget
-    without changing its shape. */
+/** natural settle is 659ms; rescaled at a constant zeta to land inside this
+    budget without changing its shape — duration and the physics constants
+    above are coupled. */
 export const CROSSFADE_DURATION = 280;
 export const crossfadeEasing = springEasing(1438, 80, 0.8, CROSSFADE_DURATION);
 export const CROSSFADE_EASING = cssLinear(crossfadeEasing);
 
-/** the tick/cross arriving in a step's status cell — interior.dev's POP */
 export const POP_DURATION = 300;
 export const popEasing = springEasing(640, 22, 0.7, POP_DURATION);
 export const POP_EASING = cssLinear(popEasing, 40);
 
-/** leaving is shorter and closer in, matching ui/Modal */
 export const EXIT_DURATION = 140;
 export const EXIT_EASING = "cubic-bezier(0.4, 0, 1, 1)";
 
-/** a stroke drawing itself on, interior's DRAW */
 export const DRAW_DURATION = 260;
 export const DRAW_EASING = "cubic-bezier(0.23, 1, 0.32, 1)";
diff --git a/web/src/lib/optimistic.svelte.ts b/web/src/lib/optimistic.svelte.ts
index 0ffabdac4..2509db9fb 100644
--- a/web/src/lib/optimistic.svelte.ts
+++ b/web/src/lib/optimistic.svelte.ts
@@ -66,7 +66,6 @@ export interface OptimisticRelation {
 	readonly active: boolean;
 	readonly loading: boolean;
 	readonly failed: boolean;
-	/** `intent` shows the outcome straight away and holds it until the write settles */
 	begin(intent?: boolean): void;
 	created(rkey: string): void;
 	deleted(): void;
diff --git a/web/src/lib/popoverExit.ts b/web/src/lib/popoverExit.ts
index a9d602ea1..90addbca7 100644
--- a/web/src/lib/popoverExit.ts
+++ b/web/src/lib/popoverExit.ts
@@ -36,7 +36,6 @@ const pinned = [
 	"height"
 ];
 
-/** where a `position: fixed` box in this parent resolves its origin from. */
 const fixedOrigin = (parent: HTMLElement) => {
 	const probe = document.createElement("div");
 	probe.style.cssText = "position:fixed;top:0;left:0;width:0;height:0";
@@ -62,7 +61,6 @@ export const popoverExit =
 			const parent = node.parentElement;
 			if (!parent) return;
 			const origin = fixedOrigin(parent);
-			// read the box while the popover is still open — a frame later it is gone
 			const box = node.getBoundingClientRect();
 			const pin: Record<string, string> = {
 				display: getComputedStyle(node).display,
diff --git a/web/src/routes/+layout.svelte b/web/src/routes/+layout.svelte
index 870ee223c..1d541913b 100644
--- a/web/src/routes/+layout.svelte
+++ b/web/src/routes/+layout.svelte
@@ -68,7 +68,6 @@
 	const isAuthShell = $derived(
 		page.url.pathname === "/login" || page.url.pathname.startsWith("/signup")
 	);
-	// the welcome flow runs its own steps chrome, so the bar and footer step aside
 	const isWelcomeShell = $derived(page.url.pathname === "/welcome");
 	const isMarketingShell = $derived(
 		!signedIn && (page.url.pathname === "/about" || page.url.pathname === "/")
diff --git a/web/src/routes/[handle]/[repo]/history/[ref]/[...path]/+page.ts b/web/src/routes/[handle]/[repo]/history/[ref]/[...path]/+page.ts
index 181e30ca7..4c2df3565 100644
--- a/web/src/routes/[handle]/[repo]/history/[ref]/[...path]/+page.ts
+++ b/web/src/routes/[handle]/[repo]/history/[ref]/[...path]/+page.ts
@@ -10,10 +10,7 @@ const COMMIT_LIMIT = 50;
 // enough of the real log to collect the repo's authors for the mock
 const AUTHOR_SAMPLE = 20;
 
-// the ref is a single encoded segment, `feature/x` arrives intact. the rest
-// param is already the path as git knows it
 export const load: PageLoad = async (event) => {
-	// a pathless history is the whole repo log, which lives at /commits
 	if (event.params.path === "") error(404, "Not found");
 	const parent = await event.parent();
 	const ref = event.params.ref;
@@ -35,7 +32,6 @@ export const load: PageLoad = async (event) => {
 					event.fetch
 				)
 			)
-			// a repo we cannot read still gets a history, just with invented names
 			.catch(() => []);
 		return mockFileHistory(repo.uri, path, authorsOf(sampled));
 	});
@@ -43,7 +39,6 @@ export const load: PageLoad = async (event) => {
 	const pageCount = historyPromise.then((history) =>
 		Math.max(Math.ceil(history.length / COMMIT_LIMIT), 1)
 	);
-	// a page past the end shows the last one, not an empty list
 	const commits = Promise.all([historyPromise, pageCount]).then(([history, count]) => {
 		const shown = Math.min(page, count);
 		return history.slice((shown - 1) * COMMIT_LIMIT, shown * COMMIT_LIMIT);
diff --git a/web/src/routes/[handle]/[repo]/pulls/[aturi]/[version]/[[range]]/PullViewPage.stories.svelte b/web/src/routes/[handle]/[repo]/pulls/[aturi]/[version]/[[range]]/PullViewPage.stories.svelte
index 4072662fa..5c8fc5f1d 100644
--- a/web/src/routes/[handle]/[repo]/pulls/[aturi]/[version]/[[range]]/PullViewPage.stories.svelte
+++ b/web/src/routes/[handle]/[repo]/pulls/[aturi]/[version]/[[range]]/PullViewPage.stories.svelte
@@ -62,7 +62,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 		rkey: pullRkey,
 		title: "web: wire up notifs ui",
 		body,
-		// the record allows an unrendered body, which the "No body" story leans on
 		bodyHtml: bodyHtml as string | null,
 		state: "open" as PullState,
 		createdAt: "2026-08-16T09:00:00Z",
@@ -86,7 +85,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 		versions: pullVersions
 	};
 
-	// the newest version, whole: what /pulls/<aturi>/latest lands on
 	const latest: PullView = {
 		mode: "diff",
 		version: pullVersions.length - 1,
@@ -128,8 +126,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 
 	const data = pageData();
 
-	// signing in as the pull's author unlocks the edit, close, merge and resubmit
-	// paths; anyone else only gets to comment
 	const asAuthor = { accounts: [pullAuthor] };
 	const asReviewer = { accounts: [pullCollaborator] };
 
@@ -145,8 +141,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 
 	type PlayContext = Pick<StoryContext<Record<string, unknown>>, "canvas">;
 
-	// a card's text is fetched only once it nears the viewport, so scrolling to it
-	// is what exercises the whole diff pipeline: payload, then the two blob reads
 	const diffRendered = async ({ canvas }: PlayContext) => {
 		const card = await canvas.findByText("src/lib/notifications.svelte.ts");
 		card.scrollIntoView();
@@ -156,8 +150,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 		);
 	};
 
-	// the spindle read the load will eventually make: no run yet, and nothing under
-	// .tangled/workflows touched by this round
 	const ciReady = (over: Partial<PullCiApproval> = {}): PullCiApproval => ({
 		hasPipeline: false,
 		changedWorkflows: [],
@@ -167,12 +159,9 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 
 	const changedWorkflows = [".tangled/workflows/ci.yml", ".tangled/workflows/release.yml"];
 
-	// opens the confirmation and hands back the dialog, which lives on <body> rather
-	// than in the story canvas
 	const openApproval = async ({ canvas }: PlayContext) => {
 		await userEvent.click(await canvas.findByRole("button", { name: "Approve CI" }));
 		const dialog = within(document.body).getByRole("dialog");
-		// the panel fades in, and an opacity-0 node doesn't count as visible yet
 		await waitFor(() => expect(dialog).toBeVisible());
 		return dialog;
 	};
@@ -197,7 +186,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- signed out: the diff and the discussion read, nothing acts -->
 <Story
 	name="Signed out"
 	parameters={{ auth: false }}
@@ -209,7 +197,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- a reviewer: comment and subscribe, no state changes -->
 <Story
 	name="As reviewer"
 	parameters={{ auth: asReviewer }}
@@ -220,8 +207,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- the author: close, merge, and a Resubmit that stays parked while the source
-     branch tip is the version already submitted -->
 <Story
 	name="As author"
 	parameters={{ auth: asAuthor }}
@@ -234,7 +219,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- the source branch moved past the newest version, so Resubmit arms -->
 <Story
 	name="Resubmittable"
 	parameters={{
@@ -246,8 +230,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- the merge check found conflicts: the rebase merge is barred, marking it
-     merged by hand is not -->
 <Story
 	name="Conflicted"
 	parameters={{ auth: asAuthor, pullFetch: { conflicted: true } }}
@@ -258,7 +240,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- push access on a spindled repo arms the CI approval for this fork-based round -->
 <Story
 	name="With push access"
 	args={{ data: pageData({ viewerCanPush: true, ci: ciReady() }) }}
@@ -268,7 +249,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- push access, but the spindle already ran this round: nothing left to approve -->
 <Story
 	name="CI already ran"
 	args={{ data: pageData({ viewerCanPush: true, ci: ciReady({ hasPipeline: true }) }) }}
@@ -281,7 +261,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- the plain approval: a fork's patch needs a vouch before it runs -->
 <Story
 	name="CI approval"
 	args={{ data: pageData({ viewerCanPush: true, ci: ciReady() }) }}
@@ -294,7 +273,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- the round edits its own workflows, so the confirmation names every file -->
 <Story
 	name="CI approval, workflows changed"
 	args={{ data: pageData({ viewerCanPush: true, ci: ciReady({ changedWorkflows }) }) }}
@@ -308,7 +286,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- approved: the button retires and the dialog confirms the run is queued -->
 <Story
 	name="CI approved"
 	args={{ data: pageData({ viewerCanPush: true, ci: ciReady() }) }}
@@ -324,7 +301,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- the spindle refused: the dialog holds open with the reason -->
 <Story
 	name="CI approval fails"
 	args={{
@@ -367,7 +343,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- a pull record with no submission yet: no commits, no diff -->
 <Story
 	name="No versions"
 	args={{ data: pageData({ pull: { versions: [] } }) }}
@@ -389,9 +364,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- the range narrowed to three commits: the commit rows dim outside it, the
-     diff answers with only the files those commits touched, and the discussion
-     hides comments pinned to a commit that fell out -->
 <Story
 	name="Commit range"
 	args={{
@@ -413,8 +385,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- v1..v2: the commit list turns into the change-id list and the diff becomes
-     an interdiff -->
 <Story
 	name="Interdiff"
 	args={{
@@ -436,7 +406,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- the same interdiff, narrowed to the one commit carrying a change id -->
 <Story
 	name="Interdiff, one change"
 	args={{
@@ -459,7 +428,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- both sides of the range resolve to the same tree -->
 <Story
 	name="Empty diff"
 	parameters={{ auth: asReviewer, pullFetch: { diff: "empty" } }}
@@ -493,14 +461,12 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- an empty body: the ticket falls back to its title alone -->
 <Story
 	name="No body"
 	args={{ data: pageData({ pull: { body: "", bodyHtml: null } }) }}
 	parameters={{ auth: asReviewer }}
 />
 
-<!-- already subscribed, so the bell offers to drop the subscription -->
 <Story
 	name="Subscribed"
 	parameters={{ auth: asReviewer, pullFetch: { subscription: "active" } }}
@@ -511,7 +477,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- subscribing: the button spins, then settles on Unsubscribe -->
 <Story
 	name="Subscribing"
 	parameters={{
@@ -536,7 +501,6 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- the subscription lookup failed, so the toggle stays put and says so -->
 <Story
 	name="Subscription unavailable"
 	parameters={{ auth: asReviewer, pullFetch: { subscription: "error" } }}
@@ -545,13 +509,10 @@ Depends on the hydrant filter change, so this is stacked on \`sv-fe\`.`;
 	}}
 />
 
-<!-- closing the discussion hands the diff the full width and leaves a button to
-     bring it back -->
 <Story
 	name="Discussion closed"
 	parameters={{ auth: asReviewer }}
 	play={async ({ canvas }) => {
-		// the panel's close control is icon-only, so it is reached through its header
 		const header = canvas.getByRole("heading", { name: "Comments" }).closest("div");
 		await userEvent.click(header!.querySelector("button")!);
 		await expect(canvas.queryByRole("heading", { name: "Comments" })).toBeNull();
diff --git a/web/src/routes/[handle]/[repo]/pulls/[aturi]/[version]/[[range]]/PullViewPage.svelte b/web/src/routes/[handle]/[repo]/pulls/[aturi]/[version]/[[range]]/PullViewPage.svelte
index cbcb10dad..76a13bfb9 100644
--- a/web/src/routes/[handle]/[repo]/pulls/[aturi]/[version]/[[range]]/PullViewPage.svelte
+++ b/web/src/routes/[handle]/[repo]/pulls/[aturi]/[version]/[[range]]/PullViewPage.svelte
@@ -385,16 +385,11 @@
 			repo: data.repo.repoDid,
 			name: pull.targetBranch
 		});
-		await mergeCommit(
-			agent,
-			data.publicConfig.knotMirrorUrl,
-			data.repo.knot,
-			{
-				target: { repo: data.repo.repoDid, branch: pull.targetBranch, commit: target.hash },
-				source: { repo: data.sourceRepoDid, commit: head },
-				style: "rebase"
-			}
-		);
+		await mergeCommit(agent, data.publicConfig.knotMirrorUrl, data.repo.knot, {
+			target: { repo: data.repo.repoDid, branch: pull.targetBranch, commit: target.hash },
+			source: { repo: data.sourceRepoDid, commit: head },
+			style: "rebase"
+		});
 		await putPullStatus(agent, data.uri, "merged");
 		pull = { ...pull, state: "merged" };
 	});
@@ -413,8 +408,6 @@
 
 	const sourceBranch = $derived(pull.source?.branch ?? "");
 
-	// a fork's workflows run only once someone with push access vouches for the round,
-	// and only while nothing has run for its head yet
 	const ciApproval = $derived(
 		canPush &&
 			pullState === "open" &&
diff --git a/web/src/routes/[handle]/[repo]/settings/hooks/new/+page.svelte b/web/src/routes/[handle]/[repo]/settings/hooks/new/+page.svelte
index 2a25fa26e..9be89302d 100644
--- a/web/src/routes/[handle]/[repo]/settings/hooks/new/+page.svelte
+++ b/web/src/routes/[handle]/[repo]/settings/hooks/new/+page.svelte
@@ -18,7 +18,7 @@
 
 	let url = $state("");
 	let secret = $state("");
-	// mocked — webhooks are not wired up yet. Push is preselected, as in the design.
+	// mocked — webhooks are not wired up yet. Push is preselected.
 	let events = $state<Record<string, boolean>>({
 		push: true,
 		renamed: false,
diff --git a/web/src/routes/[handle]/[repo]/settings/sites/+page.svelte b/web/src/routes/[handle]/[repo]/settings/sites/+page.svelte
index 7eff74ed9..a35de32e6 100644
--- a/web/src/routes/[handle]/[repo]/settings/sites/+page.svelte
+++ b/web/src/routes/[handle]/[repo]/settings/sites/+page.svelte
@@ -25,7 +25,7 @@
 
 	// mocked — sites config is backed by G7 and has no write path here. Rendering
 	// the deployed state so the live-status pair and Disable row are visible; an
-	// undeployed repo drops both, as in the first Figma frame.
+	// undeployed repo drops both.
 	const deployed = true;
 
 	const initial = {
diff --git a/web/src/routes/favicon.svg/+server.ts b/web/src/routes/favicon.svg/+server.ts
index 6d29ee008..5bf964d89 100644
--- a/web/src/routes/favicon.svg/+server.ts
+++ b/web/src/routes/favicon.svg/+server.ts
@@ -2,8 +2,6 @@ import { dev } from "$app/environment";
 import dolly from "../../../static/logos/dolly.svg?raw";
 import type { RequestHandler } from "./$types";
 
-// the logo is monochrome and tracks the color scheme, so we repaint the favicon
-// per environment to tell a local or next tab apart from production at a glance
 const devTint = "#d97706"; // --color-foreground-warning
 const nextTint = "#4338ca"; // --color-foreground-info
 
diff --git a/web/src/routes/notifications/+page.svelte b/web/src/routes/notifications/+page.svelte
index 293066127..5896be18c 100644
--- a/web/src/routes/notifications/+page.svelte
+++ b/web/src/routes/notifications/+page.svelte
@@ -43,9 +43,6 @@
 		(loaded.data ?? []).map((n) => (n.uri in overrides ? { ...n, read: overrides[n.uri] } : n))
 	);
 
-	// the unread tab filters on the data as it loaded, never on the local read
-	// state, so toggling a row restyles it in place instead of dropping it out of
-	// the list under the cursor. the next load re-derives the set.
 	const unreadOnLoad = $derived(
 		new Set((loaded.data ?? []).filter((n) => !n.read).map((n) => n.uri))
 	);
@@ -69,8 +66,6 @@
 		unread(all.filter((n) => notificationCategory(n.type) === "social"))
 	);
 
-	// on the unread tab an empty social column is dead weight, so the work column
-	// takes the full width instead
 	const showSocial = $derived(data.readFilter !== "unread" || social.length > 0);
 
 	const toggleRead = async (uri: string, read: boolean) => {
diff --git a/web/src/routes/settings/+layout.svelte b/web/src/routes/settings/+layout.svelte
index 5ea3e76f8..4e6e2b33d 100644
--- a/web/src/routes/settings/+layout.svelte
+++ b/web/src/routes/settings/+layout.svelte
@@ -27,7 +27,6 @@
 		{ id: "sites", label: "Sites", href: "/settings/sites", icon: Globe }
 	];
 
-	// a drill-down keeps its parent tab active, so match on the first segment only
 	const segment = $derived(page.url.pathname.replace(/^\/settings\/?/, "").split("/")[0]);
 	const active = $derived(segment && items.some((i) => i.id === segment) ? segment : "profile");
 </script>
diff --git a/web/src/routes/settings/profile/handle/+page.svelte b/web/src/routes/settings/profile/handle/+page.svelte
index 9020203e7..62db2b92c 100644
--- a/web/src/routes/settings/profile/handle/+page.svelte
+++ b/web/src/routes/settings/profile/handle/+page.svelte
@@ -34,8 +34,6 @@
 			{#if ownDomain}
 				<Input id="handle" bind:value={handle} placeholder="example.com" />
 			{:else}
-				<!-- the subdomain suffix lives inside the field, so borrow Input's own
-				     surface styling rather than re-deriving it -->
 				<div class={inputField({ class: "gap-0 overflow-hidden py-0 pr-0" })}>
 					<input
 						id="handle"
diff --git a/web/src/routes/welcome/+page.svelte b/web/src/routes/welcome/+page.svelte
index 97374b333..3acda0f9c 100644
--- a/web/src/routes/welcome/+page.svelte
+++ b/web/src/routes/welcome/+page.svelte
@@ -49,8 +49,6 @@
 		)
 	);
 
-	// green means "nothing left to do on this step", not "you may continue" —
-	// every field here is optional and Next is never blocked
 	const profileComplete = $derived(
 		(draft.avatarFile !== null || Boolean(loadedProfile?.avatar)) &&
 			[draft.description, draft.pronouns, draft.website].every((value) => value.trim() !== "")
-- 
2.54.0