diff --git a/web/src/lib/api/repoIndex.ts b/web/src/lib/api/repoIndex.ts
index 0d36ddde..93820135 100644
--- a/web/src/lib/api/repoIndex.ts
+++ b/web/src/lib/api/repoIndex.ts
@@ -121,8 +121,7 @@ export interface RepoIndexOptions {
 }
 
 // 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. one round trip
-// per distinct author, and a name we can't resolve just stays a name
+// for the handle and the row reads like the rest of the site.
 const withAuthorHandles = async (
 	commits: CommitSummary[],
 	bobbinUrl: string,
diff --git a/web/src/lib/components/repo/pipelines/PipelineStatusIcon.svelte b/web/src/lib/components/repo/pipelines/PipelineStatusIcon.svelte
index 173e3405..8d9420f1 100644
--- a/web/src/lib/components/repo/pipelines/PipelineStatusIcon.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineStatusIcon.svelte
@@ -41,7 +41,7 @@
 <script lang="ts">
 	interface Props {
 		status: PipelineStatus;
-		/** colour the icon itself; off inside a Tag */
+		/** off inside a Tag */
 		colored?: boolean;
 		class?: string;
 	}
diff --git a/web/src/lib/components/repo/pipelines/PipelineToolbar.svelte b/web/src/lib/components/repo/pipelines/PipelineToolbar.svelte
index b6ac604d..6e2266b1 100644
--- a/web/src/lib/components/repo/pipelines/PipelineToolbar.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineToolbar.svelte
@@ -3,7 +3,7 @@
 
 	export const pipelineToolbar = tv({
 		slots: {
-			// same grid as IssueToolbar: group, search, count. search gets its own row on mobile.
+			// 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",
diff --git a/web/src/lib/components/repo/pipelines/PipelineWorkflows.svelte b/web/src/lib/components/repo/pipelines/PipelineWorkflows.svelte
index ed251e27..7ac8b8fe 100644
--- a/web/src/lib/components/repo/pipelines/PipelineWorkflows.svelte
+++ b/web/src/lib/components/repo/pipelines/PipelineWorkflows.svelte
@@ -51,7 +51,6 @@
 		ownerHandle: string;
 		repoName: string;
 		pipeline: PipelineSummary;
-		/** how the trigger reads: a workflow count, or a status ring plus a tally */
 		variant?: PipelineWorkflowsVariants["variant"];
 		/**
 		 * symbol variant only: "2/3" against the full "2/3 passed, 1/3 failed" breakdown, or
diff --git a/web/src/lib/components/repo/pipelines/mock.ts b/web/src/lib/components/repo/pipelines/mock.ts
index 533c3955..d5fe9890 100644
--- a/web/src/lib/components/repo/pipelines/mock.ts
+++ b/web/src/lib/components/repo/pipelines/mock.ts
@@ -12,7 +12,6 @@ const base = Date.parse("2026-08-04T09:00:00Z");
 const ago = (mins: number) => new Date(base - minutes(mins)).toISOString();
 
 export const pipelines: PipelineSummary[] = [
-	// a run still in flight
 	{
 		id: "01K1XJ4WPQ0000000000000001",
 		sha: "9f2c1ab4d8e7350f6b1c2d9e4a5b6c7d8e9f0a1b",
@@ -24,7 +23,6 @@ export const pipelines: PipelineSummary[] = [
 			{ name: "lint", status: "pending", duration: 0 }
 		]
 	},
-	// mixed outcome
 	{
 		id: "01K1XJ4WPQ0000000000000002",
 		sha: "3d7e91c05fa2b8461d0e5c7a9b3f2e1d4c6a8b0f",
@@ -42,7 +40,6 @@ export const pipelines: PipelineSummary[] = [
 			{ name: "lint", status: "success", duration: 41_000 }
 		]
 	},
-	// all green
 	{
 		id: "01K1XJ4WPQ0000000000000003",
 		sha: "c1b4a7e2f9308d65b2a1c4e7f0d3b6a9c2e5f8b1",
@@ -54,7 +51,6 @@ export const pipelines: PipelineSummary[] = [
 			{ name: "lint", status: "success", duration: 39_000 }
 		]
 	},
-	// a spindle that never answered
 	{
 		id: "01K1XJ4WPQ0000000000000004",
 		sha: "7a0f3b8c1d2e4f5a6b7c8d9e0f1a2b3c4d5e6f70",
@@ -62,7 +58,6 @@ export const pipelines: PipelineSummary[] = [
 		trigger: { kind: "manual" },
 		workflows: []
 	},
-	// timed out
 	{
 		id: "01K1XJ4WPQ0000000000000005",
 		sha: "e5d4c3b2a1908f7e6d5c4b3a2918f7e6d5c4b3a2",
@@ -77,7 +72,6 @@ export const pipelines: PipelineSummary[] = [
 			{ name: "e2e", status: "timeout", duration: minutes(30) }
 		]
 	},
-	// cancelled mid-run
 	{
 		id: "01K1XJ4WPQ0000000000000006",
 		sha: "b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9",
diff --git a/web/src/lib/components/repo/types.ts b/web/src/lib/components/repo/types.ts
index 0b413c4c..68026664 100644
--- a/web/src/lib/components/repo/types.ts
+++ b/web/src/lib/components/repo/types.ts
@@ -95,7 +95,6 @@ export type PipelineTriggerKind = PipelineTrigger["kind"];
 
 export interface PipelineSummary {
 	id: string;
-	/** the commit the spindle checked out */
 	sha: string;
 	createdAt: string;
 	trigger: PipelineTrigger;
diff --git a/web/src/lib/components/settings/DrillDown.svelte b/web/src/lib/components/settings/DrillDown.svelte
index 35694911..483a775b 100644
--- a/web/src/lib/components/settings/DrillDown.svelte
+++ b/web/src/lib/components/settings/DrillDown.svelte
@@ -4,7 +4,6 @@
 	import ArrowLeft from "$icon/arrow-left";
 
 	interface Props {
-		/** label of the tab being returned to, e.g. "Keys" */
 		backLabel: string;
 		backHref: string;
 		title: string;
diff --git a/web/src/lib/components/settings/FormRow.svelte b/web/src/lib/components/settings/FormRow.svelte
index 98f651d6..16af2ada 100644
--- a/web/src/lib/components/settings/FormRow.svelte
+++ b/web/src/lib/components/settings/FormRow.svelte
@@ -5,7 +5,7 @@
 		label: string;
 		/** renders a muted "(optional)" after the label, as on the webhook secret */
 		optional?: boolean;
-		/** helper copy under the label; pass an array to get one line each */
+		/** 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 */
diff --git a/web/src/lib/components/settings/SettingsBlock.svelte b/web/src/lib/components/settings/SettingsBlock.svelte
index 137278c5..02face3b 100644
--- a/web/src/lib/components/settings/SettingsBlock.svelte
+++ b/web/src/lib/components/settings/SettingsBlock.svelte
@@ -5,11 +5,9 @@
 		/** Figma uses 16px on General's label blocks and 14px on Access/Pipelines */
 		title?: string;
 		titleSize?: "regular" | "large";
-		/** muted copy under the title; pass an array to get one line each */
+		/** pass an array to get one line each */
 		description?: string | string[];
-		/** trailing action, bottom-aligned against the description */
 		action?: Snippet;
-		/** the hairline between the header and the content */
 		separator?: boolean;
 		children?: Snippet;
 	}
diff --git a/web/src/lib/components/settings/SettingsEntry.svelte b/web/src/lib/components/settings/SettingsEntry.svelte
index b2d28c41..4b41c94e 100644
--- a/web/src/lib/components/settings/SettingsEntry.svelte
+++ b/web/src/lib/components/settings/SettingsEntry.svelte
@@ -5,11 +5,9 @@
 	interface Props {
 		icon?: Component<SvelteHTMLElements["svg"]>;
 		title: string;
-		/** badges rendered inline after the title */
 		tags?: Snippet;
 		/** secondary lines under the title — fingerprints, "added 2 months ago" */
 		meta?: Snippet;
-		/** trailing buttons */
 		actions?: Snippet;
 	}
 
diff --git a/web/src/lib/components/settings/SettingsHeader.svelte b/web/src/lib/components/settings/SettingsHeader.svelte
index 83efd598..497b3057 100644
--- a/web/src/lib/components/settings/SettingsHeader.svelte
+++ b/web/src/lib/components/settings/SettingsHeader.svelte
@@ -4,7 +4,6 @@
 	interface Props {
 		title: string;
 		description?: string;
-		/** right-aligned control that sits on the title's baseline row */
 		action?: Snippet;
 	}
 
diff --git a/web/src/lib/components/settings/SettingsRow.svelte b/web/src/lib/components/settings/SettingsRow.svelte
index 033dda74..ce82940c 100644
--- a/web/src/lib/components/settings/SettingsRow.svelte
+++ b/web/src/lib/components/settings/SettingsRow.svelte
@@ -5,12 +5,11 @@
 	interface Props {
 		/** plain-text label — omit and render whatever you need through `label` */
 		title?: string;
-		/** muted explanation under the title; pass an array to get one line each */
+		/** 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;
-		/** trailing controls: buttons, toggles, code chips */
 		children?: Snippet;
 		/** top-align the control instead of centring it, for tall right-hand content */
 		align?: "center" | "start";
@@ -71,8 +70,7 @@
 		</span>
 	{/if}
 	{#if children}
-		<!-- stacked, the controls take the full line and align right; a field that wants
-		     the whole width says so with `w-full sm:w-80` and fills it instead -->
+		<!-- 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/SettingsSaveBar.svelte b/web/src/lib/components/settings/SettingsSaveBar.svelte
index 48c45a08..40ecf1ae 100644
--- a/web/src/lib/components/settings/SettingsSaveBar.svelte
+++ b/web/src/lib/components/settings/SettingsSaveBar.svelte
@@ -12,8 +12,6 @@
 	let { dirty, onreset, onsave }: Props = $props();
 </script>
 
-<!-- Figma keeps Save disabled until something changed, and only then reveals Reset
-     and the "Unsaved changes" note beside it -->
 <div class="flex shrink-0 items-center gap-4">
 	{#if dirty}
 		<Button icon={RotateCcw} onclick={onreset}>Reset</Button>
diff --git a/web/src/lib/components/settings/SettingsSection.svelte b/web/src/lib/components/settings/SettingsSection.svelte
index cbd26447..52852870 100644
--- a/web/src/lib/components/settings/SettingsSection.svelte
+++ b/web/src/lib/components/settings/SettingsSection.svelte
@@ -7,7 +7,6 @@
 		title?: string;
 		/** gap between the heading and its card — 12px on the user pages, 16 on repo */
 		headingGap?: "3" | "4";
-		/** set false when the children provide their own container(s) */
 		framed?: boolean;
 		children: Snippet;
 	}
diff --git a/web/src/lib/components/settings/SettingsToolbar.svelte b/web/src/lib/components/settings/SettingsToolbar.svelte
index 2e57ce1e..27eeab51 100644
--- a/web/src/lib/components/settings/SettingsToolbar.svelte
+++ b/web/src/lib/components/settings/SettingsToolbar.svelte
@@ -2,7 +2,6 @@
 	import type { Snippet } from "svelte";
 
 	interface Props {
-		/** left-hand actions — omit and the trailing actions stay flush right */
 		start?: Snippet;
 		end?: Snippet;
 		/** the hairline under the toolbar, drawn in every Figma tab that has one */
diff --git a/web/src/lib/components/settings/ThemePicker.svelte b/web/src/lib/components/settings/ThemePicker.svelte
index 6ed1c525..afa13dc5 100644
--- a/web/src/lib/components/settings/ThemePicker.svelte
+++ b/web/src/lib/components/settings/ThemePicker.svelte
@@ -16,8 +16,6 @@
      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">
-		<!-- Auto is the one thumbnail that tracks the live theme, since that is
-		     exactly what the option does -->
 		<span
 			class="flex aspect-135/84 w-full items-center justify-center rounded-sm border border-border-default bg-background-default"
 			aria-hidden="true"
diff --git a/web/src/lib/components/shell/Topbar.svelte b/web/src/lib/components/shell/Topbar.svelte
index dc8f449d..d14b2980 100644
--- a/web/src/lib/components/shell/Topbar.svelte
+++ b/web/src/lib/components/shell/Topbar.svelte
@@ -25,7 +25,7 @@
 					actions: "gap-2"
 				}
 			},
-			// The signing-in placeholder wraps a spinner, so its ball gets a border and tighter gap.
+			// The signing-in placeholder wraps a spinner.
 			pending: {
 				true: {
 					identity: "gap-1",
diff --git a/web/src/lib/components/ui/Avatar.svelte b/web/src/lib/components/ui/Avatar.svelte
index ce5cb5c4..6ce20079 100644
--- a/web/src/lib/components/ui/Avatar.svelte
+++ b/web/src/lib/components/ui/Avatar.svelte
@@ -25,10 +25,9 @@
 
 	export type AvatarSize = NonNullable<VariantProps<typeof avatar>["size"]>;
 
-	// what each rung above renders at, in css pixels — 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.
+	// 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.stories.svelte b/web/src/lib/components/ui/Button.stories.svelte
index 7e4d373c..6dbb3c83 100644
--- a/web/src/lib/components/ui/Button.stories.svelte
+++ b/web/src/lib/components/ui/Button.stories.svelte
@@ -67,7 +67,7 @@
 <Story name="Icon right" args={{ icon: ChevronRight, iconSide: "right" }}>Next</Story>
 <Story name="Icon only" args={{ icon: Star, "aria-label": "Star" }} />
 
-<!-- the icon rides the same gap and scales with the size variant: size-4 up to lg, size-5 at lg. -->
+<!-- the icon rides the same gap and scales with the size variant. -->
 <Story name="Icon sizes" asChild>
 	<div class="flex items-center gap-3">
 		<Button size="small" icon={Star}>Small</Button>
diff --git a/web/src/lib/components/ui/Button.svelte b/web/src/lib/components/ui/Button.svelte
index c3773f73..d9cf8fca 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",
-			// each variant paints its own disabled surface (see the variant blocks) —
 			// Figma models disabled as a distinct fill/text pair, not a dimmed enabled state
 			"disabled:pointer-events-none aria-disabled:pointer-events-none"
 		],
@@ -33,10 +32,8 @@
 					"focus-visible:outline-border-focus",
 					"disabled:text-foreground-disabled aria-disabled:text-foreground-disabled"
 				],
-				// danger / success / warning are outline buttons in Figma: default surface +
-				// border, colored text only (bound to the fg-* tokens), no accent fill. They
-				// keep that surface when disabled and only fade the label — the outline is
-				// what carries the variant, so dropping it would read as a different button.
+				// 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",
@@ -73,8 +70,6 @@
 			}
 		},
 		compoundVariants: [
-			// raised variants draw inset depth via a ::before layer. pressing shifts the
-			// content wrapper rather than the button itself, so the box stays put.
 			{
 				variant: "default",
 				insetShadow: true,
@@ -156,8 +151,7 @@
 
 {#snippet content()}
 	<!-- single wrapper so the press animation moves the label/icon, not the button box.
-	     gap-[inherit] keeps the size variant's gap working across the extra level, and 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/ButtonCard.svelte b/web/src/lib/components/ui/ButtonCard.svelte
index c42eb863..f85a4d1a 100644
--- a/web/src/lib/components/ui/ButtonCard.svelte
+++ b/web/src/lib/components/ui/ButtonCard.svelte
@@ -23,7 +23,6 @@
 			}
 		},
 		compoundVariants: [
-			// raised variants draw inset depth via a ::before layer.
 			{
 				variant: "default",
 				insetShadow: true,
diff --git a/web/src/lib/components/ui/Checkbox.stories.svelte b/web/src/lib/components/ui/Checkbox.stories.svelte
index 7649ff3d..4bc3d559 100644
--- a/web/src/lib/components/ui/Checkbox.stories.svelte
+++ b/web/src/lib/components/ui/Checkbox.stories.svelte
@@ -19,7 +19,6 @@
 	});
 </script>
 
-<!-- Checkbox content comes through its `children` snippet, provided here as Story slot content. -->
 <Story name="Default">Item</Story>
 <Story name="Checked" args={{ checked: true }}>Item</Story>
 <Story name="Indeterminate" args={{ indeterminate: true }}>Item</Story>
diff --git a/web/src/lib/components/ui/Combobox.svelte b/web/src/lib/components/ui/Combobox.svelte
index c94941da..6b925297 100644
--- a/web/src/lib/components/ui/Combobox.svelte
+++ b/web/src/lib/components/ui/Combobox.svelte
@@ -47,13 +47,10 @@
 		 *  elsewhere — a ref in the url, say — and let `onSelect` do the navigating. */
 		value?: string;
 		onSelect?: (value: string) => void;
-		/** trigger text while nothing is selected */
 		placeholder?: string;
 		searchPlaceholder?: string;
 		emptyLabel?: string;
-		/** names the trigger and the listbox for screen readers */
 		label?: string;
-		/** decorative glyph on the trigger's leading edge, standing for the current selection */
 		icon?: Component<SvelteHTMLElements["svg"]>;
 		/** take filtering over, e.g. to query a server: `options` is then rendered as given */
 		onSearch?: (query: string) => void;
@@ -61,11 +58,10 @@
 		error?: boolean;
 		disabled?: boolean;
 		align?: SelectAlign;
-		/** goes on the trigger, so a Field's label can point at it */
+		/** lets a Field's label point at this control */
 		id?: string;
 		class?: string;
 		panelClass?: string;
-		/** pinned below the list, e.g. a "view all branches" link */
 		footer?: Snippet;
 	}
 
@@ -120,8 +116,6 @@
 				)
 	);
 
-	// a heading per run of same-group options, so grouping falls out of the array's order
-	// instead of needing a nested shape
 	const rows = $derived(
 		visible.map((option, index) => ({
 			option,
@@ -153,7 +147,6 @@
 	const move = (delta: number) => {
 		if (selectable.length === 0) return;
 		const current = selectable.indexOf(activeIndex);
-		// from nowhere, ArrowDown lands on the first option and ArrowUp on the last
 		const next =
 			current === -1
 				? delta > 0
@@ -180,7 +173,6 @@
 		open = newState === "open";
 		if (!open) return;
 
-		// every open starts from a clean slate, with the current selection under the cursor
 		search = "";
 		onSearch?.("");
 		const selectedIndex = options.findIndex((option) => option.value === value);
@@ -198,7 +190,6 @@
 	const onSearchInput = (event: Event) => {
 		search = (event.currentTarget as HTMLInputElement).value;
 		onSearch?.(search.trim());
-		// the old active row is gone or has moved: start over at the top of what is left
 		setActive(selectable[0] ?? -1, true);
 	};
 
diff --git a/web/src/lib/components/ui/Dropdown.stories.svelte b/web/src/lib/components/ui/Dropdown.stories.svelte
index 019f1d70..2c535253 100644
--- a/web/src/lib/components/ui/Dropdown.stories.svelte
+++ b/web/src/lib/components/ui/Dropdown.stories.svelte
@@ -14,9 +14,7 @@
 	});
 </script>
 
-<!-- Dropdown's `trigger` and `children` are snippet props, so the trigger content is
-	declared once below and passed by reference; every story renders via `asChild` rather
-	than through the args table. Click the trigger in the canvas to open the menu —
+<!-- Click the trigger in the canvas to open the menu —
 	`open` is internal state, not a prop. -->
 
 {#snippet menuTrigger()}
@@ -84,7 +82,6 @@
 	</div>
 </Story>
 
-<!-- DropdownItem states: plain text, with icon, as a link (href), and the danger variant. -->
 <Story name="Item states" asChild>
 	<Dropdown trigger={menuTrigger} label="Menu">
 		<DropdownItem>Plain item</DropdownItem>
diff --git a/web/src/lib/components/ui/Field.stories.svelte b/web/src/lib/components/ui/Field.stories.svelte
index 352487c9..24a54b91 100644
--- a/web/src/lib/components/ui/Field.stories.svelte
+++ b/web/src/lib/components/ui/Field.stories.svelte
@@ -20,8 +20,7 @@
 	});
 </script>
 
-<!-- Field wraps any form control via its `children` snippet, which receives the id the
-     label points at, so the control never has to hardcode one. The snippet goes through
+<!-- The snippet goes through
      `args` like any other prop, which also keeps it out of the controls' way. -->
 {#snippet textInput({ id }: { id: string })}
 	<input
diff --git a/web/src/lib/components/ui/Input.stories.svelte b/web/src/lib/components/ui/Input.stories.svelte
index 7ea5dd5b..9166b7a4 100644
--- a/web/src/lib/components/ui/Input.stories.svelte
+++ b/web/src/lib/components/ui/Input.stories.svelte
@@ -78,7 +78,7 @@
 	</div>
 </Story>
 
-<!-- the icon rides the size variant's gap and steps up to size-5 at lg, as in Button. -->
+<!-- the icon rides the size variant's gap, as in Button. -->
 <Story name="Icon sizes" asChild>
 	<div class="flex items-center gap-3">
 		<Input size="small" iconLeft={Search} placeholder="Small" />
@@ -87,7 +87,6 @@
 	</div>
 </Story>
 
-<!-- proof of the alignment claim: matched sizes, identical box heights. -->
 <Story name="With Button" asChild>
 	<div class="flex flex-col items-start gap-3">
 		{#each ["small", "regular", "large"] as const as s (s)}
diff --git a/web/src/lib/components/ui/Link.stories.svelte b/web/src/lib/components/ui/Link.stories.svelte
index f4becbbe..95c3c7b8 100644
--- a/web/src/lib/components/ui/Link.stories.svelte
+++ b/web/src/lib/components/ui/Link.stories.svelte
@@ -27,7 +27,6 @@
 	});
 </script>
 
-<!-- Link content comes through its `children` snippet, provided here as Story slot content. -->
 <Story name="Default">Link</Story>
 <Story name="Success" args={{ variant: "success" }}>Confirmed</Story>
 <Story name="Warning" args={{ variant: "warning" }}>Careful</Story>
diff --git a/web/src/lib/components/ui/Radio.stories.svelte b/web/src/lib/components/ui/Radio.stories.svelte
index 52dfe7a5..1c2b85c0 100644
--- a/web/src/lib/components/ui/Radio.stories.svelte
+++ b/web/src/lib/components/ui/Radio.stories.svelte
@@ -19,7 +19,6 @@
 	});
 </script>
 
-<!-- Radio content comes through its `children` snippet, provided here as Story slot content. -->
 <Story name="Default">Option</Story>
 <Story name="Checked" args={{ group: "a" }}>Option</Story>
 <Story name="Disabled" args={{ disabled: true }}>Option</Story>
diff --git a/web/src/lib/components/ui/Select.svelte b/web/src/lib/components/ui/Select.svelte
index 1a848aad..ed75110b 100644
--- a/web/src/lib/components/ui/Select.svelte
+++ b/web/src/lib/components/ui/Select.svelte
@@ -16,19 +16,17 @@
 		 *  once a list is long enough that scanning it beats reading it. */
 		rich?: boolean;
 		onSelect?: (value: string) => void;
-		/** empty-value row shown first, e.g. "Choose stat". Selectable, so it also clears. */
+		/** the empty row shown first, e.g. "Choose stat"; picking it clears the value */
 		placeholder?: string;
-		/** names the control for screen readers */
 		label?: string;
-		/** glyph pinned to the leading edge, mirroring the chevron. Decorative — it stands for
-		 *  the current selection, so keep it in step with `value` rather than the list. */
+		/** 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;
-		/** goes on the control itself, so a Field's label can point at it */
+		/** lets a Field's label point at this control */
 		id?: string;
 		class?: string;
-		// rich only
 		searchPlaceholder?: string;
 		emptyLabel?: string;
 		/** take filtering over, e.g. to query a server: `options` is then rendered as given */
@@ -36,7 +34,6 @@
 		loading?: boolean;
 		align?: SelectAlign;
 		panelClass?: string;
-		/** pinned below the list, e.g. a "view all branches" link */
 		footer?: Snippet;
 	}
 
@@ -61,7 +58,7 @@
 		footer
 	}: Props = $props();
 
-	// a native optgroup has to nest, so the flat array is folded into runs of the same group.
+	// 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) => {
diff --git a/web/src/lib/components/ui/ShimmerText.svelte b/web/src/lib/components/ui/ShimmerText.svelte
index 307537c1..9b7d809b 100644
--- a/web/src/lib/components/ui/ShimmerText.svelte
+++ b/web/src/lib/components/ui/ShimmerText.svelte
@@ -2,12 +2,10 @@
 	import { tv, type VariantProps } from "tailwind-variants";
 
 	export const shimmerText = tv({
-		// w-fit keeps the box hugging the glyphs inside a stretching flex or grid
-		// parent, so the sweep is sized by the text rather than by the column
+		// the sweep is sized by the text rather than by the column
 		base: "inline-block w-fit",
 		variants: {
 			color: {
-				/** keep whatever colour the surrounding text already has */
 				inherit: "",
 				default: "text-foreground-default",
 				muted: "text-foreground-muted",
@@ -70,7 +68,6 @@
 		from {
 			background-position-x: -100%;
 		}
-		/* the sweep is done at the halfway mark; the rest of the cycle is a pause */
 		50%,
 		to {
 			background-position-x: 250%;
diff --git a/web/src/lib/components/ui/Tabs.stories.svelte b/web/src/lib/components/ui/Tabs.stories.svelte
index 11de46a3..32f72514 100644
--- a/web/src/lib/components/ui/Tabs.stories.svelte
+++ b/web/src/lib/components/ui/Tabs.stories.svelte
@@ -31,7 +31,7 @@
 <Story name="SecondActive" args={{ active: "repos" }} />
 <Story name="WithoutIcons" args={{ tabs: plainTabs, active: "open" }} />
 <!-- the vertical variant is the settings sidebar shape: it stretches to its container
-     rather than hugging its items, so the stories give it a tall narrow box -->
+     rather than hugging its items -->
 <Story name="Vertical" args={{ vertical: true }}>
 	{#snippet template(args)}
 		<div class="flex h-80 w-44 items-stretch">
diff --git a/web/src/lib/components/ui/Tabs.svelte b/web/src/lib/components/ui/Tabs.svelte
index 6841cfff..f1858e7e 100644
--- a/web/src/lib/components/ui/Tabs.svelte
+++ b/web/src/lib/components/ui/Tabs.svelte
@@ -29,8 +29,7 @@
 						"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; an
-					// ellipsis keeps that height without hiding the label outright
+					// Figma clips the item rather than letting a long label wrap it taller
 					label: "min-w-0 truncate",
 					count: "ml-auto"
 				},
@@ -134,8 +133,6 @@
 		let bestLength = -1;
 		for (const item of items) {
 			if (item.url === dest.pathname + dest.search) return item.id;
-			// a plain path also owns everything nested under it, so an issue page
-			// keeps the issues tab lit; a query-scoped tab only matches exactly
 			if (item.url.includes("?")) continue;
 			const owns = dest.pathname === item.url || dest.pathname.startsWith(`${item.url}/`);
 			if (owns && item.url.length > bestLength) {
diff --git a/web/src/lib/components/ui/Tag.svelte b/web/src/lib/components/ui/Tag.svelte
index 7cd926cc..9327339b 100644
--- a/web/src/lib/components/ui/Tag.svelte
+++ b/web/src/lib/components/ui/Tag.svelte
@@ -37,7 +37,6 @@
 	interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, "class" | "children"> {
 		color?: TagVariants["color"];
 		size?: TagVariants["size"];
-		/** Optional leading icon component (e.g. `import Hash from "$icon/hash"`). */
 		icon?: Component<SvelteHTMLElements["svg"]>;
 		class?: string;
 		iconClass?: string;
diff --git a/web/src/lib/components/ui/Textarea.svelte b/web/src/lib/components/ui/Textarea.svelte
index 7e942859..f8b6d33e 100644
--- a/web/src/lib/components/ui/Textarea.svelte
+++ b/web/src/lib/components/ui/Textarea.svelte
@@ -98,9 +98,8 @@
 		textareaField({ error, disabled, readonly, resizeable, size })
 	);
 
-	// The root no longer carries the text inset (so the scrollbar/resize handle can sit flush
-	// against the border) — the textarea itself owns its horizontal padding, collapsing to 0 on
-	// whichever side an icon (or the loading spinner) already provides the inset instead.
+	// 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/Toggle.stories.svelte b/web/src/lib/components/ui/Toggle.stories.svelte
index 4bc86f15..f9831aed 100644
--- a/web/src/lib/components/ui/Toggle.stories.svelte
+++ b/web/src/lib/components/ui/Toggle.stories.svelte
@@ -19,7 +19,6 @@
 	});
 </script>
 
-<!-- Toggle content comes through its `children` snippet, provided here as Story slot content. -->
 <Story name="Default">Label</Story>
 <Story name="Checked" args={{ checked: true }}>Label</Story>
 <Story name="Disabled" args={{ disabled: true }}>Label</Story>
diff --git a/web/src/lib/components/ui/Toggle.svelte b/web/src/lib/components/ui/Toggle.svelte
index cf28efce..86b21aa7 100644
--- a/web/src/lib/components/ui/Toggle.svelte
+++ b/web/src/lib/components/ui/Toggle.svelte
@@ -5,7 +5,6 @@
 	interface Props extends Omit<HTMLInputAttributes, "type" | "class" | "checked" | "children"> {
 		checked?: boolean;
 		disabled?: boolean;
-		/** `inline` hugs the label, `block` stretches it to fill the row. */
 		layout?: "inline" | "block";
 		class?: string;
 		children?: Snippet;
diff --git a/web/src/lib/components/ui/Tooltip.stories.svelte b/web/src/lib/components/ui/Tooltip.stories.svelte
index fb43523c..02392278 100644
--- a/web/src/lib/components/ui/Tooltip.stories.svelte
+++ b/web/src/lib/components/ui/Tooltip.stories.svelte
@@ -11,8 +11,7 @@
 	});
 </script>
 
-<!-- Tooltip's `children` is the trigger it wraps, so every story renders via `asChild`
-	rather than through the args table. Hover or tab to the trigger in the canvas — `open`
+<!-- Hover or tab to the trigger in the canvas — `open`
 	is internal state unless you bind it. The stories pad generously because the bubble is
 	a popover in the top layer and would otherwise sit over the canvas edge. -->
 
@@ -43,7 +42,6 @@
 	</div>
 </Story>
 
-<!-- the canonical use: an icon-only button whose aria-label and tooltip say the same thing -->
 <Story name="Icon button" asChild>
 	<div class="flex justify-center p-16">
 		<Tooltip content="New issue">
@@ -52,7 +50,6 @@
 	</div>
 </Story>
 
-<!-- `content` also takes a snippet when a single string is not enough -->
 <Story name="Rich content" asChild>
 	<div class="flex justify-center p-16">
 		<Tooltip content={richContent}>
@@ -61,7 +58,7 @@
 	</div>
 </Story>
 
-<!-- `delay={0}` opens on hover with no wait. Note that once any tooltip has been shown,
+<!-- Note that once any tooltip has been shown,
 	moving to a neighbouring trigger opens instantly regardless of delay. -->
 <Story name="No delay" asChild>
 	<div class="flex justify-center gap-2 p-16">
@@ -75,7 +72,7 @@
 </Story>
 
 <!-- the arrow points at whichever edge the bubble actually landed on, so it stays correct
-	even when the preferred side had to flip. `arrow={false}` drops it. -->
+	even when the preferred side had to flip. -->
 <Story name="No arrow" asChild>
 	<div class="flex justify-center p-16">
 		<Tooltip content="No pointer" arrow={false}>
diff --git a/web/src/lib/components/ui/Tooltip.svelte b/web/src/lib/components/ui/Tooltip.svelte
index 743e440a..0cc99683 100644
--- a/web/src/lib/components/ui/Tooltip.svelte
+++ b/web/src/lib/components/ui/Tooltip.svelte
@@ -42,7 +42,6 @@
 	import { onMount } from "svelte";
 
 	interface Props {
-		/** Tooltip body: a plain string for the common case, a snippet for rich content. */
 		content: string | Snippet;
 		side?: TooltipVariants["side"];
 		/** ms to wait before opening on hover. Keyboard focus always opens immediately. */
@@ -51,7 +50,6 @@
 		disabled?: boolean;
 		/** Two-way: set it to drive the tooltip yourself, e.g. a transient "Copied!". */
 		open?: boolean;
-		/** Draw the little pointer at the trigger. */
 		arrow?: boolean;
 		id?: string;
 		class?: string;
diff --git a/web/src/lib/components/ui/selectField.ts b/web/src/lib/components/ui/selectField.ts
index ef75e1cf..2cafa91e 100644
--- a/web/src/lib/components/ui/selectField.ts
+++ b/web/src/lib/components/ui/selectField.ts
@@ -3,7 +3,7 @@ import { tv, type VariantProps } from "tailwind-variants";
 /** one row of a Select, in either rendering */
 export interface SelectOption {
 	value: string;
-	/** shown instead of `value`; `value` is still matched when filtering */
+	/** `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 */
diff --git a/web/src/lib/components/welcome/FinishStep.svelte b/web/src/lib/components/welcome/FinishStep.svelte
index 904a900c..afd543ca 100644
--- a/web/src/lib/components/welcome/FinishStep.svelte
+++ b/web/src/lib/components/welcome/FinishStep.svelte
@@ -1,8 +1,7 @@
 <script module lang="ts">
 	import { tv, type VariantProps } from "tailwind-variants";
 
-	// the finish bento: a two-column grid where one tile runs the full width and
-	// another spans both rows (appview onboarding/fragments/finish.html)
+	// 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",
@@ -17,8 +16,6 @@
 				tall: { root: "sm:row-span-2" },
 				single: { root: "" }
 			},
-			// the community row's tiles are themselves the link, so they need the hover
-			// surface and the tighter gap the four bento tiles don't want
 			link: {
 				true: {
 					root: "flex-1 gap-1 no-underline transition-colors hover:bg-background-subtle hover:no-underline"
diff --git a/web/src/lib/components/welcome/ProfileStep.svelte b/web/src/lib/components/welcome/ProfileStep.svelte
index a8e0a224..3e9e6342 100644
--- a/web/src/lib/components/welcome/ProfileStep.svelte
+++ b/web/src/lib/components/welcome/ProfileStep.svelte
@@ -22,8 +22,7 @@
 
 	const slot = avatarPicker();
 
-	// no upload endpoint wired up: the preview is a local object url, which is all
-	// the appview shows before its hx-post to /profile/avatar comes back
+	// no upload endpoint wired up here; the appview hx-posts to /profile/avatar
 	const pick = (event: Event) => {
 		const file = (event.currentTarget as HTMLInputElement).files?.[0];
 		if (!file) return;
diff --git a/web/src/lib/components/welcome/StepHeader.svelte b/web/src/lib/components/welcome/StepHeader.svelte
index 3a5dff2f..0967edfd 100644
--- a/web/src/lib/components/welcome/StepHeader.svelte
+++ b/web/src/lib/components/welcome/StepHeader.svelte
@@ -1,7 +1,7 @@
 <script module lang="ts">
 	import { tv, type VariantProps } from "tailwind-variants";
 
-	// every step opens with the same title/subtitle pair (appview onboarding/* fragments)
+	// 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 c0833305..f99c80e7 100644
--- a/web/src/lib/components/welcome/Steps.svelte
+++ b/web/src/lib/components/welcome/Steps.svelte
@@ -2,9 +2,7 @@
 	import { tv, type VariantProps } from "tailwind-variants";
 
 	// the numbered rail from Figma node 191:6514 — same shape as the appview's
-	// onboarding/fragments/steps, restyled onto the design-system tokens. the three
-	// states differ only in the marker fill and the label colour, so they are one
-	// variant across two slots rather than three hand-written class strings.
+	// onboarding/fragments/steps, restyled onto the design-system tokens.
 	export const steps = tv({
 		slots: {
 			root: "flex w-full items-center gap-2",
@@ -51,7 +49,6 @@
 
 	let { items, current }: Props = $props();
 
-	// root and connector take no variant, so they resolve once
 	const shell = steps();
 
 	const stateOf = (index: number): StepState =>
diff --git a/web/src/lib/components/welcome/WelcomeCard.svelte b/web/src/lib/components/welcome/WelcomeCard.svelte
index 97136fff..112e0067 100644
--- a/web/src/lib/components/welcome/WelcomeCard.svelte
+++ b/web/src/lib/components/welcome/WelcomeCard.svelte
@@ -5,8 +5,6 @@
 		slots: {
 			root: "overflow-hidden rounded-sm border border-border-default bg-background-default shadow-xs",
 			header: "overflow-x-auto border-b border-border-default px-6 py-5",
-			// grid so the outgoing and incoming panes share one cell and cross-fade in
-			// place; overflow-hidden is what keeps the swipe inside the card
 			body: "grid overflow-hidden p-6",
 			pane: "col-start-1 row-start-1 min-w-0",
 			footer: "flex items-center justify-between gap-4 border-t border-border-default px-6 py-4"
diff --git a/web/src/lib/components/welcome/draft.svelte.ts b/web/src/lib/components/welcome/draft.svelte.ts
index 2cbf848e..6822a7ef 100644
--- a/web/src/lib/components/welcome/draft.svelte.ts
+++ b/web/src/lib/components/welcome/draft.svelte.ts
@@ -1,4 +1,4 @@
-// what the user has entered so far. the step panes are destroyed and recreated on
+// the step panes are destroyed and recreated on
 // every transition, so this cannot live inside them — the appview has the same
 // split for a different reason, keeping progress in the `onboarding` table and the
 // profile/keys on the record, so wiring this up later means replacing the module
diff --git a/web/src/lib/components/welcome/mock.ts b/web/src/lib/components/welcome/mock.ts
index 4aff06c7..083c9ba3 100644
--- a/web/src/lib/components/welcome/mock.ts
+++ b/web/src/lib/components/welcome/mock.ts
@@ -1,4 +1,4 @@
-// stand-in data for the welcome flow. the appview fills these from
+// the appview fills these lists from
 // OnboardingSocial / OnboardingKeys; nothing here is wired to an api yet, so the
 // step components read from this module and a real load later replaces it.
 
@@ -13,7 +13,7 @@ export interface MockKey {
 
 const did = (name: string) => `did:plc:${name.replace(/[^a-z0-9]/g, "")}welcome`;
 
-/** OnboardingSocial's People — suggested accounts to follow */
+/** OnboardingSocial's People */
 export const people: PersonData[] = [
 	{
 		did: did("alphaone"),
@@ -78,7 +78,7 @@ export const trendingRepos: RepoCardData[] = [
 	}
 ];
 
-/** OnboardingKeys' PubKeys — starts empty, the step adds to it */
+/** OnboardingKeys' PubKeys */
 export const initialKeys: MockKey[] = [];
 
 /**
diff --git a/web/src/lib/components/welcome/steps.ts b/web/src/lib/components/welcome/steps.ts
index 82d5ddc5..1a4de1db 100644
--- a/web/src/lib/components/welcome/steps.ts
+++ b/web/src/lib/components/welcome/steps.ts
@@ -1,4 +1,4 @@
-// the onboarding steps, mirroring appview/models/onboarding.go. the appview
+// mirrors appview/models/onboarding.go. the appview
 // persists the index in the `onboarding` table, so these values are storage
 // keys, not just display order — keep them aligned with the Go constants.
 export const WELCOME_STEPS = [
@@ -12,5 +12,5 @@ export type WelcomeStepKey = (typeof WELCOME_STEPS)[number]["key"];
 
 export const WELCOME_TOTAL = WELCOME_STEPS.length;
 
-/** the last step is the summary — there is nothing left to skip past it */
+/** 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 2cf373b7..580948a1 100644
--- a/web/src/lib/format.ts
+++ b/web/src/lib/format.ts
@@ -53,7 +53,7 @@ export const compactRelativeTime = (input: string | Date, now: Date = new Date()
 	return `${Math.floor(duration)}y ${suffix}`;
 };
 
-// the appview's durationFmt: non-zero chunks, largest first ("1h 3m 20s").
+// 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 "";
diff --git a/web/src/routes/[handle]/[repo]/settings/+page.svelte b/web/src/routes/[handle]/[repo]/settings/+page.svelte
index a2d9b706..6b212491 100644
--- a/web/src/routes/[handle]/[repo]/settings/+page.svelte
+++ b/web/src/routes/[handle]/[repo]/settings/+page.svelte
@@ -77,7 +77,6 @@
 </div>
 
 <div class="flex w-full flex-col gap-10">
-	<!-- the leading pair of cards carries no heading in the design -->
 	<div class="flex w-full flex-col gap-4">
 		<SettingsList>
 			<SettingsRow title="Description" stack>
diff --git a/web/src/routes/[handle]/[repo]/settings/hooks/+page.svelte b/web/src/routes/[handle]/[repo]/settings/hooks/+page.svelte
index 963691b4..121b4b47 100644
--- a/web/src/routes/[handle]/[repo]/settings/hooks/+page.svelte
+++ b/web/src/routes/[handle]/[repo]/settings/hooks/+page.svelte
@@ -63,9 +63,6 @@
 	{:else}
 		<SettingsList>
 			{#each hooks as hook (hook.id)}
-				<!-- the toggle rides the top-right corner while the actions sit under it,
-				     so this row is a two-column block rather than a SettingsRow. On a
-				     phone the two columns stack and the actions spread across the width. -->
 				<div class="flex w-full flex-col gap-4 sm:flex-row sm:items-start sm:justify-between">
 					<div class="flex min-w-0 flex-col gap-1">
 						<CodeChip class="w-fit break-all">{hook.url}</CodeChip>
diff --git a/web/src/routes/[handle]/[repo]/settings/labels/new/+page.svelte b/web/src/routes/[handle]/[repo]/settings/labels/new/+page.svelte
index 9d501526..4e43a0b6 100644
--- a/web/src/routes/[handle]/[repo]/settings/labels/new/+page.svelte
+++ b/web/src/routes/[handle]/[repo]/settings/labels/new/+page.svelte
@@ -16,7 +16,6 @@
 
 	const back = $derived(`/${data.repo.ownerHandle}/${data.repo.name}/settings`);
 
-	// the eight swatches from the design
 	const COLORS = [
 		"#ef4444",
 		"#3b82f6",
diff --git a/web/src/routes/[handle]/[repo]/settings/sites/+page.svelte b/web/src/routes/[handle]/[repo]/settings/sites/+page.svelte
index 8af8b290..e1638c69 100644
--- a/web/src/routes/[handle]/[repo]/settings/sites/+page.svelte
+++ b/web/src/routes/[handle]/[repo]/settings/sites/+page.svelte
@@ -37,7 +37,6 @@
 	const dirty = $derived(JSON.stringify(form) !== JSON.stringify(initial));
 	const reset = () => (form = { ...initial });
 
-	// the "(default)" marker is display-only; the value stays the plain branch name
 	const branches = $derived([
 		{ value: data.repo.defaultBranch, label: `${data.repo.defaultBranch} (default)` },
 		{ value: "develop", label: "develop" }
diff --git a/web/src/routes/settings/+layout.svelte b/web/src/routes/settings/+layout.svelte
index 02c10c16..a5b82740 100644
--- a/web/src/routes/settings/+layout.svelte
+++ b/web/src/routes/settings/+layout.svelte
@@ -31,8 +31,6 @@
 	<title>Settings &middot; Tangled</title>
 </svelte:head>
 
-<!-- the panel runs edge to edge on a phone, so the page gutters and the generous
-     desktop breathing room only kick in from md up -->
 <div class="flex w-full flex-col items-center md:px-4 md:pt-16 md:pb-32">
 	<div class="flex w-full max-w-300 flex-col">
 		<SettingsPanel {items} {active}>