refactor(web): remove and correct stale comments in the site and videos

apps/web/app/(marketing)/share/badge/route.ts

@@ -2,10 +2,6 @@ import { getScoreData, parseScoreQuery } from "@/lib/score";
 
 const LABEL = "Docker Doctor";
 
-// Color-only variant of the same thresholds as `getScoreData` in
-// `@/lib/score` (which mirrors `SCORE_BUCKETS` in
-// `packages/core/src/scoring.ts` -- see the note there on why this
-// isn't unified via an `@docker-doctor/core` import).
 const getScoreColor = (score: number): string => {
   const { label } = getScoreData(score);
 

apps/web/app/globals.css

@@ -117,7 +117,6 @@
   /* iOS-like drawer curve (from Ionic Framework) */
   --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
 
-  /* Global Scrollbar Colors */
   --scrollbar-track: transparent;
   --scrollbar-thumb: oklch(0.8 0 0);
   --scrollbar-thumb-hover: oklch(0.65 0 0);
@@ -180,7 +179,6 @@
   --shadow-border: 0 0 0 1px #ffffff14;
   --shadow-custom: 0 0 0 1px #ffffff14;
 
-  /* Global Scrollbar Colors */
   --scrollbar-track: transparent;
   --scrollbar-thumb: oklch(0.3 0 0);
   --scrollbar-thumb-hover: oklch(0.45 0 0);

apps/web/app/llms-full.txt/route.ts

@@ -1,7 +1,6 @@
 import { getLLMText } from "@/lib/get-llm-text";
 import { source } from "@/lib/source";
 
-// cached forever
 export const revalidate = false;
 
 const serveFullLlmsText = async () => {

apps/web/app/llms.txt/route.ts

@@ -2,7 +2,6 @@ import { llms } from "fumadocs-core/source/llms";
 
 import { source } from "@/lib/source";
 
-// cached forever
 export const revalidate = false;
 
 const serveLlmsIndex = () =>

apps/web/components/claude/claude-thinking.tsx

@@ -52,7 +52,6 @@ const usePrefersReducedMotion = () =>
     () => false
   );
 
-// Calls tick every `ms` milliseconds. Returns the cleanup that stops it.
 const startInterval = (tick: () => void, ms: number): (() => void) => {
   const id = setInterval(tick, ms);
 

apps/web/components/copy-button.tsx

@@ -7,8 +7,6 @@ import type { ComponentProps } from "react";
 
 import { cn } from "@/lib/utils";
 
-// Calls onReset after the check mark has shown for two seconds. Returns the
-// cleanup that cancels it.
 const startResetTimer = (onReset: () => void): (() => void) => {
   const timer = setTimeout(onReset, 2000);
 

apps/web/components/docs/mobile-toc.tsx

@@ -8,8 +8,6 @@ import type { RefObject } from "react";
 
 import { TocLink } from "@/components/docs/toc";
 
-// Closes the panel on Escape and moves focus back to its summary. Returns the
-// cleanup that stops listening.
 const closeOnEscape = (
   details: HTMLDetailsElement,
   summaryRef: RefObject<HTMLElement | null>

apps/web/components/docs/sidebar.tsx

@@ -20,8 +20,8 @@ const isTextName = (name: ReactNode): name is string | number =>
 const nameKey = (node: PageTreeNode): string =>
   isTextName(node.name) ? String(node.name) : node.type;
 
-// Every page-tree node carries a stable `$id`; pages also have a unique
-// `url`. Prefer those over the array index so keys survive reordering.
+// Prefer a node's `$id`, then a page's `url`, over the array index so keys
+// survive reordering.
 const nodeKey = (node: PageTreeNode): string =>
   node.$id ?? ("url" in node ? node.url : nameKey(node));
 

apps/web/components/nav-buttons.tsx

@@ -2,7 +2,6 @@ import Link from "next/link";
 
 import { cn } from "@/lib/utils";
 
-// The outlined buttons. Docs, the filled one, has its own classes below.
 const OutlinedNavButton = ({
   destination,
   href,

apps/web/components/sections/terminal-demo.tsx

@@ -15,7 +15,6 @@ const COMMAND = "docker-doctor .";
 const TOTAL_TICKS = 210;
 const TICK_MS = 100;
 
-// Calls tick every TICK_MS milliseconds. Returns the cleanup that stops it.
 const startTicking = (tick: () => void): (() => void) => {
   const timer = setInterval(tick, TICK_MS);
 

apps/web/lib/css-variables.d.ts

@@ -1,7 +1,6 @@
 import "react";
 
 declare module "react" {
-  // The CSS custom properties the website's style objects set.
   interface CSSProperties {
     "--beam-delay"?: string;
     "--beam-end"?: string;

apps/web/lib/leaderboard.ts

@@ -36,7 +36,6 @@ interface ResultsBody {
   schemaVersion?: unknown;
 }
 
-// Any JSON object can be read field by field. The fields are checked below.
 const isResultsBody = (value: unknown): value is ResultsBody =>
   typeof value === "object" && value !== null;
 

apps/web/lib/source.ts

@@ -1,7 +1,6 @@
 import { docs } from "collections/server";
 import { loader } from "fumadocs-core/source";
 
-// See https://fumadocs.dev/docs/headless/source-api for more info
 export const source = loader({
   baseUrl: "/docs",
   source: docs.toFumadocsSource(),

apps/web/lib/text.ts

@@ -1,4 +1,2 @@
-// True for a string with at least one character, which is what a truthiness
-// test on a string that may be missing checked.
 export const hasText = (value: string | null | undefined): value is string =>
   value !== undefined && value !== null && value !== "";

apps/web/scripts/optimize-icons.ts

@@ -7,7 +7,6 @@ import type { Config } from "svgo";
 const ICONS_DIR = path.resolve(import.meta.dirname, "../components/icons");
 
 // React camelCase SVG attributes → standard SVG hyphenated names
-// Only those that differ and could reference IDs are important.
 const REACT_SVG_ATTR_MAP = new Map([
   ["clipPath", "clip-path"],
   ["clipRule", "clip-rule"],

apps/web/source.config.ts

@@ -11,20 +11,17 @@ interface MarkdownNode {
   type?: unknown;
 }
 
-// Every object in a remark tree is a node. Its fields are checked where they
-// are read.
 const isMarkdownNode = (value: unknown): value is MarkdownNode =>
   typeof value === "object" && value !== null;
 
 const isString = (value: unknown): value is string => typeof value === "string";
 
 const VALID_LANG = /^[a-zA-Z][a-zA-Z0-9+#-]*$/u;
 
-// Some docs use non-standard fenced code labels like
-// `\`\`\`384:401:path/to/file.ts` (line range + file path instead of a
-// language). Shiki rejects those. Normalize anything that isn't a plain
-// language identifier to `text`, preserving the original label as fence
-// meta so it still renders above the block.
+// Shiki rejects a fence label that is not a language, such as
+// `\`\`\`384:401:path/to/file.ts` (a line range and a file path). Normalize
+// anything that isn't a plain language identifier to `text`, preserving the
+// original label as fence meta so it still renders above the block.
 const normalizeCodeLang = (node: MarkdownNode): void => {
   if (
     node.type === "code" &&

packages/videos/remotion.config.ts

@@ -1,10 +1,3 @@
-/**
- * Note: When using the Node.JS APIs, the config file
- * doesn't apply. Instead, pass options directly to the APIs.
- *
- * All configuration options: https://remotion.dev/docs/config
- */
-
 import fs from "node:fs";
 import path from "node:path";
 
@@ -28,8 +21,6 @@ interface WebpackRule {
   use?: unknown;
 }
 
-// A rule or a loader entry is any object. The fields are checked where they
-// are read.
 const isWebpackRule = (rule: unknown): rule is WebpackRule =>
   typeof rule === "object" && rule !== null;
 

packages/videos/src/compose-agents-composition.tsx

@@ -15,8 +15,8 @@ import { FONT_VARS, SANS } from "./fonts";
 
 // The v0.5.0 release video, styled after basement.studio: paper-white stage,
 // heavy Geist stacked caps slamming in on hard cuts, marquee
-// strips top and bottom, film grain, one brand-blue accent. No fades anywhere —
-// every scene change is a cut, every reveal is a clip-mask slam.
+// strips top and bottom, film grain, one brand-blue accent. Every scene
+// change is a hard cut.
 
 const MONO = "var(--font-geist-mono), ui-monospace, monospace";
 
@@ -28,8 +28,6 @@ const BRAND = "#2b7fff";
 const FAINT = "rgba(17,17,16,0.38)";
 const HAIRLINE = "rgba(17,17,16,0.14)";
 
-// ─── Texture ────────────────────────────────────────────────────────────────
-
 // Film grain: SVG turbulence re-seeded every other frame so the noise
 // crawls like scanned film instead of sitting frozen on the frame.
 const Grain = () => {
@@ -54,8 +52,6 @@ const Grain = () => {
   );
 };
 
-// ─── Marquee ────────────────────────────────────────────────────────────────
-
 // Two identical halves shifted by their own width: translating by
 // `-(t mod 50%)` loops seamlessly without measuring pixels.
 const Marquee = ({
@@ -103,8 +99,6 @@ const Marquee = ({
   );
 };
 
-// ─── Type ───────────────────────────────────────────────────────────────────
-
 // Cap a display line's font size so it bleeds close to the frame edge but
 // never clips: Geist bold caps average ~0.62em per character.
 const SAFE_W = 1150;
@@ -203,8 +197,6 @@ const Centered = ({ children }: { readonly children: ReactNode }) => (
   </AbsoluteFill>
 );
 
-// ─── Scene 1 · Title ────────────────────────────────────────────────────────
-
 const TITLE_DURATION = 80;
 
 const SceneTitle = () => (
@@ -215,8 +207,6 @@ const SceneTitle = () => (
   </Centered>
 );
 
-// ─── Scene 2 · Theme ────────────────────────────────────────────────────────
-
 const THEME_DURATION = 70;
 
 const SceneTheme = () => (
@@ -231,8 +221,6 @@ const SceneTheme = () => (
   </Centered>
 );
 
-// ─── Scene 3 · Rule counter ─────────────────────────────────────────────────
-
 const COUNT_DURATION = 60;
 
 const SceneCount = () => {
@@ -265,8 +253,6 @@ const SceneCount = () => {
   );
 };
 
-// ─── Scene 4 · Feature slams ────────────────────────────────────────────────
-
 const FEATURES: { title: string; caption: string }[] = [
   {
     caption: "privileged mode / docker.sock mounts / plaintext secrets",
@@ -338,8 +324,6 @@ const SceneFeatures = () => (
   </>
 );
 
-// ─── Scene 5 · CTA ──────────────────────────────────────────────────────────
-
 const CTA_DURATION = 100;
 const OUT_DURATION = 80;
 
@@ -376,8 +360,6 @@ const SceneOut = () => (
   </Centered>
 );
 
-// ─── Composition ────────────────────────────────────────────────────────────
-
 export const FPS = 30;
 export const WIDTH = 1920;
 export const HEIGHT = 1080;
@@ -388,9 +370,7 @@ const FEATURES_END = COUNT_END + FEATURES_DURATION;
 const CTA_END = FEATURES_END + CTA_DURATION;
 export const DURATION = CTA_END + OUT_DURATION;
 
-// ─── Sound ──────────────────────────────────────────────────────────────────
-
-// A composed music bed plus two accents (scripts/make-sfx.py), in the
+// A composed music bed plus three accents (scripts/make-sfx.ts), in the
 // product-launch style of ElevenLabs' videos: 22.5 s of minimal electronic
 // in D minor at 96 BPM under the whole video, a soft sub thump on each
 // scene cut, a rising pluck per counter increment, and a tiny key tick per
@@ -559,7 +539,7 @@ export const ComposeAgents = () => {
             <SceneOut />
           </Sequence>
 
-          {/* Chrome that rides above every scene: marquees, crosshairs. */}
+          {/* Chrome that rides above every scene: the marquees. */}
           <div style={{ left: 0, position: "absolute", right: 0, top: 0 }}>
             <Marquee phrase={MARQUEE} />
           </div>

packages/videos/src/composition.tsx

@@ -65,7 +65,6 @@ const CenteredLine = ({
   </AbsoluteFill>
 );
 
-// ─── Scene 1 · The setup ────────────────────────────────────────────────────
 // Two centered lines blur in — the second trails the first by 0.25s (8f
 // @30fps) so the question lands as a beat, not a single flash.
 const SceneTagline = () => (
@@ -81,7 +80,6 @@ const SceneTagline = () => (
   </>
 );
 
-// ─── Scene 3 · The question ─────────────────────────────────────────────────
 // The pivot between the two terminals, in the tagline's two-line rhythm.
 const QUESTION_DURATION = 80;
 
@@ -98,7 +96,6 @@ const SceneQuestion = () => (
   </>
 );
 
-// ─── Scene 5 · The feature run ──────────────────────────────────────────────
 const SNAPS = [
   "30 rules. Zero setup.",
   "Root users. Mutable tags.",
@@ -139,7 +136,6 @@ const SceneFeatures = () => (
   </>
 );
 
-// ─── Scene 6 · The close ────────────────────────────────────────────────────
 const SceneCta = () => (
   // Transparent so the backdrop carries through, with the caret running out
   // to the final frame.

packages/videos/src/index.css

@@ -1,10 +1,9 @@
 @import "tailwindcss";
 
 /*
- * Design tokens mirror apps/web/app/globals.css (the `.dark` theme) so the
- * video renders in the exact same visual language as the marketing site:
- * shadcn neutral palette (oklch, chroma 0) + Geist / Instrument Serif fonts.
- * The video is always dark, so the dark values are baked straight in.
+ * Design tokens mirror apps/web/app/globals.css so the video renders in the
+ * same visual language as the marketing site: shadcn neutral palette (oklch,
+ * chroma 0) + Geist / Instrument Serif fonts.
  */
 @theme {
   --radius: 0.625rem;

packages/videos/src/launch-composition.tsx

@@ -49,7 +49,6 @@ const Positioned = ({
   </div>
 );
 
-// ─── Scene 1 · The hook ─────────────────────────────────────────────────────
 // The post's opening question. SoftBlurIn needs ~45 frames to land a
 // 17-character line, so the scene is sized to the last line's arrival plus a
 // one-second hold.
@@ -74,7 +73,6 @@ const SceneHook = () => (
   </>
 );
 
-// ─── Scene 3 · The close ────────────────────────────────────────────────────
 // The command on a pill, large enough to read on a phone — it already typed
 // out in the terminal, so this is the thing to copy, not the reveal.
 const CTA_DURATION = 66;

packages/videos/src/sandbox-composition.tsx

@@ -43,7 +43,6 @@ const Positioned = ({
   </div>
 );
 
-// ─── Scene 1 · The setup ────────────────────────────────────────────────────
 // The post's hook, in the launch video's rhythm: one size, one color, and the
 // timing alone carries the beat — a smaller, dimmer last line would read as a
 // subtitle when it is the actual question.
@@ -67,7 +66,6 @@ const SceneHook = () => (
   </>
 );
 
-// ─── Scene 4 · The payoff ───────────────────────────────────────────────────
 // SoftBlurIn spends ~27 frames per character plus a frame of stagger each, so
 // a 20-character line is not fully on screen for ~47 frames. Every text scene
 // below is sized to that arrival plus a two-second hold; at the old durations
@@ -91,7 +89,6 @@ const ScenePayoff = () => (
   </>
 );
 
-// ─── Scene 5 · The close ────────────────────────────────────────────────────
 // The command on a pill, at a size that survives a phone screen — it already
 // typed out legibly in scene 2, so this is a reminder, not the reveal.
 const CTA_DURATION = 112;