refactor: improve code documentation and remove unnecessary comments

- Enhanced documentation across various files, providing clearer explanations of functions and types.
- Removed redundant comment blocks that did not add value or clarity to the code.
- Updated comments to reflect the purpose and functionality of specific code sections, improving maintainability.
- Ensured consistency in comment style and formatting throughout the codebase.

Author: nicklaunches

CLAUDE.md

@@ -49,11 +49,12 @@ const SECTIONS = [
     { href: "#errors", label: "Errors" },
 ] as const;
 
-// ---------------------------------------------------------------------------
-// Install snippets. Kept in step with `install-tabs.tsx` by hand: that
-// component is the hero, this is the reference, and both get copied verbatim.
-// ---------------------------------------------------------------------------
-
+/**
+ * One agent's install snippet.
+ *
+ * Kept in step with `install-tabs.tsx` by hand: that component is the hero, this
+ * is the reference, and both get copied verbatim.
+ */
 type InstallDef = {
     id: string;
     label: string;
@@ -133,10 +134,7 @@ bearer_token_env_var = "BUILDERS_BACKLINKS_TOKEN"`,
     },
 ];
 
-// ---------------------------------------------------------------------------
-// Tool reference. Transcribed from registerTools() in src/lib/mcp/tools.ts.
-// ---------------------------------------------------------------------------
-
+/** One argument in the tool reference below, transcribed from `registerTools()` in `src/lib/mcp/tools.ts`. */
 type ToolArg = {
     name: string;
     /** The schema, written the way a caller has to satisfy it. */
@@ -345,13 +343,16 @@ const WRITE_TOOLS: readonly ToolDef[] = [
     },
 ];
 
-// ---------------------------------------------------------------------------
-// The worked example. The most valuable block on the page, so it is a real
-// sequence with real argument names, not a shape.
-// ---------------------------------------------------------------------------
-
+/** One beat of the worked example. */
 type Step = { n: string; title: string; body: string; call: string; result?: string };
 
+/**
+ * The worked example, and the most valuable block on the page.
+ *
+ * A real sequence with real argument names rather than a shape: readers paste
+ * from here, so a placeholder would be the page lying about the product.
+ */
+
 const WALKTHROUGH: readonly Step[] = [
     {
         n: "01",
@@ -425,10 +426,6 @@ const WALKTHROUGH: readonly Step[] = [
     },
 ];
 
-// ---------------------------------------------------------------------------
-// Rendering
-// ---------------------------------------------------------------------------
-
 const PILL = "rounded-full border px-2 py-0.5 font-mono text-[10.5px] tracking-[0.1em] whitespace-nowrap uppercase";
 const PILL_ACCENT = `${PILL} border-accent/40 bg-accent-soft text-accent`;
 const PILL_MUTED = `${PILL} border-line text-muted`;

next-app/src/app/(site)/docs/mcp/page.tsx

@@ -80,7 +80,6 @@ export async function GET(request: Request) {
 
     const now = new Date();
 
-    // ---------------------------------------------------------------------
     // Expire stale matches first.
     //
     // `expiresAt` was written on every match from the day matching shipped and
@@ -95,7 +94,6 @@ export async function GET(request: Request) {
     // partners with a live match, and lets the digest reach the member again.
     // `declined` and `placed` are terminal and deliberately excluded: a placed
     // match has real links behind it and must never be reopened by a clock.
-    // ---------------------------------------------------------------------
     // Returns both site ids and the state it expired FROM, because expiry used
     // to be silent: a member watched a partner disappear off the dashboard with
     // no message before it or after. The prior state decides the wording, since a
@@ -141,7 +139,6 @@ export async function GET(request: Request) {
         }
     }
 
-    // ---------------------------------------------------------------------
     // Re-pair the idle pool.
     //
     // Approval used to be the only thing that ever called `autoPair`, which
@@ -161,7 +158,6 @@ export async function GET(request: Request) {
     // one this site already has a match row with. Sites already holding an open
     // match are excluded before that, so the pass is idempotent over an
     // unchanged pool.
-    // ---------------------------------------------------------------------
     const dryRun = new URL(request.url).searchParams.get("dry") === "1";
 
     const idle = await db()
@@ -282,7 +278,6 @@ export async function GET(request: Request) {
         console.log(`recheck: re-pair batch was full at ${PAIR_BATCH}, more idle sites remain for tomorrow`);
     }
 
-    // ---------------------------------------------------------------------
     // Nudge agreed matches where a link is still missing.
     //
     // Nothing used to be sent between `match-agreed` and expiry, and the weekly
@@ -293,7 +288,6 @@ export async function GET(request: Request) {
     // Only the side that owes something is mailed. `lastNudgedAt` is the
     // high-water mark that stops a nightly pass from mailing nightly; with the
     // two windows below it lands on roughly day 3 and day 10 of an agreed match.
-    // ---------------------------------------------------------------------
     let nudged = 0;
     if (!dryRun) {
         try {

next-app/src/app/api/cron/recheck/route.ts

@@ -157,9 +157,13 @@ const handler = createMcpHandler(createServer, {
     onerror: (err) => console.error("mcp transport error", err),
 });
 
-// Every method goes to the same handler: POST carries the JSON-RPC exchange,
-// GET opens a subscription stream, DELETE and OPTIONS are answered by the
-// transport itself. Next needs each one exported by name to route it here.
+/**
+ * The one handler behind all four HTTP methods.
+ *
+ * POST carries the JSON-RPC exchange, GET opens a subscription stream, and
+ * DELETE and OPTIONS are answered by the transport itself. Next needs each one
+ * exported by name to route it here.
+ */
 const serve = (request: Request): Promise<Response> => handler.fetch(request);
 
 export { serve as GET, serve as POST, serve as DELETE, serve as OPTIONS };

next-app/src/app/api/mcp/route.ts

@@ -26,16 +26,19 @@ import { getSessionMember } from "@/lib/session";
  * `revalidatePath` anywhere. The client holds enough state to update itself.
  */
 
-// ---------------------------------------------------------------------------
-// Accept or decline
-// ---------------------------------------------------------------------------
-
 export type RespondState =
     | { status: "idle" }
     | { status: "signed_out" }
     | { status: "error"; matchId: string; message: string }
     | { status: "done"; matchId: string; accepted: boolean; revealed: boolean };
 
+/**
+ * Accepts or declines a proposed match.
+ *
+ * `revealed` comes back on the done arm because accepting is only half of a
+ * reveal: identities appear when BOTH sides have accepted, so the client cannot
+ * infer it from its own click.
+ */
 export async function respondToMatchAction(_previous: RespondState, formData: FormData): Promise<RespondState> {
     const member = await getSessionMember();
     if (!member) return { status: "signed_out" };
@@ -59,10 +62,6 @@ export async function respondToMatchAction(_previous: RespondState, formData: Fo
     }
 }
 
-// ---------------------------------------------------------------------------
-// Link brief
-// ---------------------------------------------------------------------------
-
 export type BriefState =
     | { status: "idle" }
     | { status: "signed_out" }
@@ -102,10 +101,6 @@ export async function getLinkBriefAction(_previous: BriefState, formData: FormDa
     }
 }
 
-// ---------------------------------------------------------------------------
-// Mark placed
-// ---------------------------------------------------------------------------
-
 export type PlaceState =
     | { status: "idle" }
     | { status: "signed_out" }

next-app/src/app/app/actions.ts

@@ -93,10 +93,7 @@ export function KeyPanel({ initial }: KeyPanelProps) {
     );
 }
 
-// ---------------------------------------------------------------------------
-// No key yet
-// ---------------------------------------------------------------------------
-
+/** The state before a member has any key: what one is for, and the button that mints it. */
 function Generate({ formAction, pending }: { formAction: () => void; pending: boolean }) {
     return (
         <section aria-labelledby="generate-heading" className="border-line bg-surface rounded-sm border p-6 sm:p-8">
@@ -140,10 +137,12 @@ function Generate({ formAction, pending }: { formAction: () => void; pending: bo
     );
 }
 
-// ---------------------------------------------------------------------------
-// One-time reveal
-// ---------------------------------------------------------------------------
-
+/**
+ * The one screen the plaintext key is ever readable on.
+ *
+ * Only a hash is stored, so there is no second chance and the warning is a
+ * `role="alert"` that cannot be scrolled past.
+ */
 function Reveal({ state, onDismiss }: { state: Extract<IssueKeyState, { status: "issued" }>; onDismiss: () => void }) {
     const command = claudeCommand(state.plaintext);
     const cursor = cursorConfig(state.plaintext);
@@ -258,10 +257,7 @@ function Snippet({
     );
 }
 
-// ---------------------------------------------------------------------------
-// Key already exists
-// ---------------------------------------------------------------------------
-
+/** The returning state: when the key was issued and last used, and a confirmed regenerate. */
 function ExistingKey({
     issuedAt,
     lastUsedAt,

next-app/src/app/app/key/key-panel.tsx

@@ -35,11 +35,7 @@ import { getSessionMember } from "@/lib/session";
  * server never fetched, while the tool analyzes every single one.
  */
 
-// ---------------------------------------------------------------------------
-// Step one: draft
-// ---------------------------------------------------------------------------
-
-/** Everything the confirmation screen needs, plus the signature tying DR to this server. */
+/** Step one. Everything the confirmation screen needs, plus the signature tying DR to this server. */
 export type DraftPayload = {
     domain: string;
     /** Final URL after redirects. This, not the typed one, is what gets listed. */
@@ -124,10 +120,7 @@ function explainAnalyzeFailure(err: unknown): string {
     return "Something went wrong on our side. Nothing was changed. Try again in a moment.";
 }
 
-// ---------------------------------------------------------------------------
-// Step two: commit
-// ---------------------------------------------------------------------------
-
+/** Step two. What the confirmation screen shows once the listing is written. */
 export type CommitState =
     | { status: "idle" }
     | { status: "signed_out" }

next-app/src/app/submit/actions.ts

@@ -329,10 +329,14 @@ export function ReviewForm({ draft, onStartOver }: ReviewFormProps) {
 
 const SIGNED_OUT = "Your session expired before we could save this. Sign in again and resubmit, nothing was written.";
 
-// One icon, not two. This used to celebrate with a PartyPopper when the submit
-// call came back already matched, which cannot happen any more: nothing is
-// matched until review clears the listing. The celebration belongs on whatever
-// surface tells a member they have a match, not on the one that says "received".
+/**
+ * The "received, pending review" confirmation.
+ *
+ * One icon, not two. This used to celebrate with a PartyPopper when the submit
+ * call came back already matched, which cannot happen any more: nothing is
+ * matched until review clears the listing. The celebration belongs on whatever
+ * surface tells a member they have a match, not on the one that says "received".
+ */
 function SubmittedPanel({ state }: { state: Extract<CommitState, { status: "done" }> }) {
     return (
         <section className="border-accent/35 bg-accent-soft rounded-sm border p-6 sm:p-8" aria-live="polite">

next-app/src/app/submit/review-form.tsx

@@ -44,10 +44,7 @@ import { type TabItem, TabList, panelId, tabId } from "@/components/web/tab-list
 
 const MCP_URL = "https://builders-backlinks.com/api/mcp";
 
-// ---------------------------------------------------------------------------
-// Install snippets
-// ---------------------------------------------------------------------------
-
+/** The agents an install snippet exists for. */
 type ClientId = "claude" | "cursor" | "codex" | "gemini";
 
 type ClientDef = {
@@ -138,10 +135,7 @@ const CLIENT_TABS: readonly TabItem<ClientId>[] = CLIENTS.map((client) => ({
     label: client.label,
 }));
 
-// ---------------------------------------------------------------------------
-// Transcripts
-// ---------------------------------------------------------------------------
-
+/** How one span of transcript text is coloured. Maps to the `--term-*` custom properties. */
 type Tone = "plain" | "dim" | "bright" | "prompt" | "tool" | "key" | "ok" | "add" | "mask" | "warn";
 
 type Segment = { text: string; tone?: Tone };
@@ -304,10 +298,6 @@ const VIEW_CAPTION: Record<ViewId, string> = {
     place: "This is the step every other exchange leaves to you, and the step where most trades die.",
 };
 
-// ---------------------------------------------------------------------------
-// Remembering whether the demo is collapsed
-// ---------------------------------------------------------------------------
-
 /**
  * Where the collapsed/expanded choice is kept.
  *
@@ -365,10 +355,7 @@ function writeDemoPreference(open: boolean): void {
     }
 }
 
-// ---------------------------------------------------------------------------
-// Rendering
-// ---------------------------------------------------------------------------
-
+/** Renders one transcript as terminal lines, tone by tone. */
 function TranscriptBody({ lines }: { lines: readonly Line[] }) {
     return (
         <pre className="min-w-max font-mono text-[12px] leading-[1.75] sm:text-[12.5px]">

next-app/src/components/web/install-tabs.tsx

@@ -14,12 +14,8 @@
 import type { Category } from "@/lib/categories";
 import type { Placement, PlacementOffer } from "@/lib/exchange";
 
-// ---------------------------------------------------------------------------
-// src/lib/analyze  ->  analyzeSite()
-// ---------------------------------------------------------------------------
-
 /**
- * Everything derived from a URL at submit time.
+ * Everything derived from a URL at submit time. Produced by `analyzeSite()` in `src/lib/analyze`.
  *
  * `description` must be identity-scrubbed: it is shown to potential partners
  * before either side knows who the other is, so it has to say what the site
@@ -103,12 +99,9 @@ export function analyzeFailureHint(code: AnalyzeErrorCode): string {
 
 export type AnalyzeSite = (rawUrl: string) => Promise<SiteAnalysis>;
 
-// ---------------------------------------------------------------------------
-// src/lib/verify  ->  verifyLink()
-// ---------------------------------------------------------------------------
-
 /**
- * Result of crawling one page looking for a link to one domain.
+ * Result of crawling one page looking for a link to one domain. Produced by `verifyLink()` in
+ * `src/lib/verify`.
  *
  * POLICY REMINDER: this classifies, it does not judge. A `footer` placement or
  * a `nofollow` rel is reported plainly to both parties and still counts as a
@@ -146,11 +139,10 @@ export type VerifyLink = (input: {
     detectSitewide?: boolean;
 }) => Promise<LinkVerification>;
 
-// ---------------------------------------------------------------------------
-// src/lib/matching  ->  scoreCandidate() / findBestPartner()
-// ---------------------------------------------------------------------------
-
-/** The subset of a site the matching engine needs. Keeps it testable without Mongo. */
+/**
+ * The subset of a site `scoreCandidate()` and `findBestPartner()` in `src/lib/matching` need.
+ * Deliberately a plain object, so the matcher stays testable without a database.
+ */
 export type MatchableSite = {
     id: string;
     ownerId: string;
@@ -202,13 +194,12 @@ export type FindBestPartner = (
     ctx: ScoreContext,
 ) => { candidate: MatchableSite; score: ScoreBreakdown } | null;
 
-// ---------------------------------------------------------------------------
-// Shared view models returned to MCP tools and web routes
-// ---------------------------------------------------------------------------
-
 /**
  * A site's give/get standing, counted from the links that are live right now.
  *
+ * First of the shared view models: everything from here down is returned to MCP
+ * tools and web routes alike, which is what stops the two surfaces drifting.
+ *
  * Every view that shows these numbers takes them as a value rather than reading
  * them off a site row, because they are not a property of the site: they are a
  * `COUNT` over `exchange_links`, resolved by `services/standing.ts`.