From 7adf944e4c79d570883fd7f8437c70870df3b959 Mon Sep 17 00:00:00 2001
From: Phanuella <phanuella81@gmail.com>
Date: Thu, 22 Oct 2026 09:19:37 +0100
Subject: [PATCH 1/4] feat: delegate accountability score in directory and
 voter-history views (#685)

---
 docs/delegate-accountability.md             | 36 ++++++++++
 src/app/governance/delegates/page.tsx       |  6 +-
 src/app/governance/voter/[address]/page.tsx |  9 ++-
 src/components/AccountabilityBadge.tsx      | 23 +++++++
 src/lib/delegateAccountability.test.ts      | 66 ++++++++++++++++++
 src/lib/delegateAccountability.ts           | 75 +++++++++++++++++++++
 6 files changed, 213 insertions(+), 2 deletions(-)
 create mode 100644 docs/delegate-accountability.md
 create mode 100644 src/components/AccountabilityBadge.tsx
 create mode 100644 src/lib/delegateAccountability.test.ts
 create mode 100644 src/lib/delegateAccountability.ts

diff --git a/docs/delegate-accountability.md b/docs/delegate-accountability.md
new file mode 100644
index 00000000..1ff3bea6
--- /dev/null
+++ b/docs/delegate-accountability.md
@@ -0,0 +1,36 @@
+# Delegate accountability score
+
+The accountability score is a single 0-100 signal shown as a badge in the delegate directory
+(`/governance/delegates`) and the voter-history page header (`/governance/voter/[address]`). It sits
+alongside the raw `participationRate` and `proposalsVoted` stats and does not replace them. It is
+informational only and must never gate an on-chain action.
+
+Implementation: `src/lib/delegateAccountability.ts` (`computeAccountabilityScore`), a pure function
+with no fetching.
+
+## Formula
+
+Three components, each in the range 0-1:
+
+| Component      | Weight | Definition |
+| -------------- | ------ | ---------- |
+| Participation  | 0.5    | The delegate's `participationRate`. |
+| Activity       | 0.3    | Mean recency weight of the delegate's votes, where a vote of age `d` days weighs `0.5^(d / 90)` (90-day half-life). |
+| Alignment      | 0.2    | Share of votes (with a known outcome) that match the winning choice. |
+
+`score = round(100 * sum(weight_i * value_i) / sum(weight_i))`
+
+Components that cannot be computed are dropped and the remaining weights are renormalised:
+
+- No per-proposal vote history: only participation is used (the directory currently has no history).
+- No votes with a known majority outcome: alignment is skipped.
+
+## Insufficient history
+
+If `max(vote history length, proposalsVoted) < 3`, no number is shown. The badge reads
+"Insufficient history" so new delegates are neither flattered nor penalised.
+
+## Limitations
+
+Majority alignment is a descriptive signal, not a judgement: voting with a minority is legitimate.
+It carries the lowest weight for that reason.
diff --git a/src/app/governance/delegates/page.tsx b/src/app/governance/delegates/page.tsx
index 76a1db7c..18962756 100644
--- a/src/app/governance/delegates/page.tsx
+++ b/src/app/governance/delegates/page.tsx
@@ -6,6 +6,7 @@ import { useDelegation } from '@/hooks/useDelegation';
 import { sanitizeText } from '@/lib/textSafety';
 import { isSameStellarAddress, isValidStellarAddress } from '@/lib/stellarAddress';
 import { secureLogger } from '@/lib/secureLogging';
+import { AccountabilityBadge } from '@/components/AccountabilityBadge';
 
 interface DelegateProfile {
   address: string;
@@ -231,7 +232,10 @@ export default function DelegatesPage() {
             <li key={d.address} className="rounded-lg border p-4">
               <div className="flex flex-wrap items-center justify-between gap-2">
                 <div>
-                  <p className="font-medium">{sanitizeText(d.name)}</p>
+                  <p className="flex flex-wrap items-center gap-2 font-medium">
+                    {sanitizeText(d.name)}
+                    <AccountabilityBadge profile={d} />
+                  </p>
                   <p className="font-mono text-xs break-all text-muted-foreground">{d.address}</p>
                 </div>
                 <button
diff --git a/src/app/governance/voter/[address]/page.tsx b/src/app/governance/voter/[address]/page.tsx
index 8d39374d..43674c67 100644
--- a/src/app/governance/voter/[address]/page.tsx
+++ b/src/app/governance/voter/[address]/page.tsx
@@ -4,6 +4,7 @@ import { notFound } from 'next/navigation';
 import { StrKey } from '@stellar/stellar-sdk';
 import { governanceStore } from '@/lib/governanceStore';
 import { sanitizeText } from '@/lib/textSafety';
+import { AccountabilityBadge } from '@/components/AccountabilityBadge';
 
 const WINDOWS = [30, 90, 365] as const;
 const PAGE_SIZE = 20;
@@ -82,7 +83,13 @@ export default async function VoterHistoryPage({ params, searchParams }: VoterPa
       </nav>
 
       <header className="mb-6">
-        <h1 className="text-2xl font-semibold">Voter history</h1>
+        <h1 className="flex flex-wrap items-center gap-3 text-2xl font-semibold">
+          Voter history
+          <AccountabilityBadge
+            profile={{ participationRate, proposalsVoted: totalVotes }}
+            voteHistory={votes}
+          />
+        </h1>
         <p className="mt-1 break-all font-mono text-sm text-muted-foreground">{address}</p>
       </header>
 
diff --git a/src/components/AccountabilityBadge.tsx b/src/components/AccountabilityBadge.tsx
new file mode 100644
index 00000000..6955838b
--- /dev/null
+++ b/src/components/AccountabilityBadge.tsx
@@ -0,0 +1,23 @@
+import { computeAccountabilityScore, type AccountabilityProfile, type VoteHistoryEntry } from '@/lib/delegateAccountability';
+
+interface AccountabilityBadgeProps {
+  profile: AccountabilityProfile;
+  voteHistory?: readonly VoteHistoryEntry[];
+}
+
+export function AccountabilityBadge({ profile, voteHistory }: AccountabilityBadgeProps) {
+  const result = computeAccountabilityScore(profile, voteHistory);
+  const label =
+    result.status === 'scored'
+      ? `Accountability score: ${result.score} out of 100`
+      : 'Accountability score: insufficient history';
+  return (
+    <span
+      aria-label={label}
+      title="Combines participation, recent activity and majority alignment. See docs/delegate-accountability.md."
+      className="inline-block rounded-full border border-border px-2 py-0.5 text-xs font-medium"
+    >
+      {result.status === 'scored' ? `Accountability ${result.score}/100` : 'Insufficient history'}
+    </span>
+  );
+}
diff --git a/src/lib/delegateAccountability.test.ts b/src/lib/delegateAccountability.test.ts
new file mode 100644
index 00000000..821eff0d
--- /dev/null
+++ b/src/lib/delegateAccountability.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { computeAccountabilityScore, type VoteHistoryEntry } from './delegateAccountability';
+
+const NOW = Date.UTC(2026, 0, 1);
+const daysAgo = (d: number) => NOW - d * 24 * 60 * 60 * 1000;
+
+function history(count: number, opts: { age?: number; aligned?: boolean } = {}): VoteHistoryEntry[] {
+  return Array.from({ length: count }, (_, i) => ({
+    timestamp: daysAgo(opts.age ?? i),
+    choice: 'for',
+    majorityChoice: opts.aligned === false ? 'against' : 'for',
+  }));
+}
+
+describe('computeAccountabilityScore', () => {
+  it('scores near 100 for perfect, recent, majority-aligned attendance', () => {
+    const result = computeAccountabilityScore(
+      { participationRate: 1, proposalsVoted: 10 },
+      history(10, { age: 0 }),
+      NOW,
+    );
+    expect(result).toEqual({ status: 'scored', score: 100 });
+  });
+
+  it('scores lower for sporadic, stale voting', () => {
+    const result = computeAccountabilityScore(
+      { participationRate: 0.2, proposalsVoted: 4 },
+      history(4, { age: 400 }),
+      NOW,
+    );
+    expect(result.status).toBe('scored');
+    if (result.status === 'scored') expect(result.score).toBeLessThan(50);
+  });
+
+  it('lowers the score for always-minority voting', () => {
+    const profile = { participationRate: 1, proposalsVoted: 10 };
+    const aligned = computeAccountabilityScore(profile, history(10, { age: 0 }), NOW);
+    const minority = computeAccountabilityScore(profile, history(10, { age: 0, aligned: false }), NOW);
+    expect(aligned).toEqual({ status: 'scored', score: 100 });
+    expect(minority).toEqual({ status: 'scored', score: 80 });
+  });
+
+  it('reports insufficient history for brand-new delegates', () => {
+    expect(computeAccountabilityScore({ participationRate: 1, proposalsVoted: 0 }, [], NOW)).toEqual({
+      status: 'insufficient',
+      sampleSize: 0,
+    });
+    expect(
+      computeAccountabilityScore({ participationRate: 1, proposalsVoted: 2 }, history(2), NOW).status,
+    ).toBe('insufficient');
+  });
+
+  it('falls back to participation alone when no vote history is available', () => {
+    expect(computeAccountabilityScore({ participationRate: 0.9, proposalsVoted: 50 }, [], NOW)).toEqual({
+      status: 'scored',
+      score: 90,
+    });
+  });
+
+  it('ignores alignment when majority outcomes are unknown', () => {
+    const votes = history(5, { age: 0 }).map(({ timestamp, choice }) => ({ timestamp, choice }));
+    expect(
+      computeAccountabilityScore({ participationRate: 1, proposalsVoted: 5 }, votes, NOW),
+    ).toEqual({ status: 'scored', score: 100 });
+  });
+});
diff --git a/src/lib/delegateAccountability.ts b/src/lib/delegateAccountability.ts
new file mode 100644
index 00000000..581c9e7d
--- /dev/null
+++ b/src/lib/delegateAccountability.ts
@@ -0,0 +1,75 @@
+/**
+ * Delegate accountability score (0-100). Pure and independent of fetching so
+ * it can be audited and tested against fixtures. Formula: docs/delegate-accountability.md.
+ */
+
+export const MIN_HISTORY_FOR_SCORE = 3;
+export const RECENCY_HALF_LIFE_DAYS = 90;
+
+export const ACCOUNTABILITY_WEIGHTS = {
+  participation: 0.5,
+  activity: 0.3,
+  alignment: 0.2,
+} as const;
+
+export interface AccountabilityProfile {
+  /** Fraction of eligible proposals voted on, 0-1. */
+  participationRate: number;
+  proposalsVoted: number;
+}
+
+export interface VoteHistoryEntry {
+  timestamp: string | number | Date;
+  choice: string;
+  /** Winning choice of the proposal, when known. */
+  majorityChoice?: string | null;
+}
+
+export type AccountabilityScore =
+  | { status: 'scored'; score: number }
+  | { status: 'insufficient'; sampleSize: number };
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function clamp01(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}
+
+export function computeAccountabilityScore(
+  profile: AccountabilityProfile,
+  voteHistory: readonly VoteHistoryEntry[] = [],
+  now: number = Date.now(),
+): AccountabilityScore {
+  const sampleSize = Math.max(voteHistory.length, profile.proposalsVoted);
+  if (sampleSize < MIN_HISTORY_FOR_SCORE) {
+    return { status: 'insufficient', sampleSize };
+  }
+
+  const parts: { value: number; weight: number }[] = [
+    { value: clamp01(profile.participationRate), weight: ACCOUNTABILITY_WEIGHTS.participation },
+  ];
+
+  if (voteHistory.length > 0) {
+    const recency = voteHistory.map((vote) => {
+      const time = new Date(vote.timestamp).getTime();
+      if (Number.isNaN(time)) return 0;
+      const ageDays = Math.max(0, (now - time) / DAY_MS);
+      return Math.pow(0.5, ageDays / RECENCY_HALF_LIFE_DAYS);
+    });
+    parts.push({
+      value: recency.reduce((sum, r) => sum + r, 0) / recency.length,
+      weight: ACCOUNTABILITY_WEIGHTS.activity,
+    });
+
+    const known = voteHistory.filter((vote) => vote.majorityChoice);
+    if (known.length > 0) {
+      const aligned = known.filter((vote) => vote.choice === vote.majorityChoice).length;
+      parts.push({ value: aligned / known.length, weight: ACCOUNTABILITY_WEIGHTS.alignment });
+    }
+  }
+
+  const totalWeight = parts.reduce((sum, p) => sum + p.weight, 0);
+  const weighted = parts.reduce((sum, p) => sum + p.value * p.weight, 0) / totalWeight;
+  return { status: 'scored', score: Math.round(weighted * 100) };
+}

From 80a4b1cd46759d86b02582b4ec36f68bce4e484d Mon Sep 17 00:00:00 2001
From: Phanuella <phanuella81@gmail.com>
Date: Thu, 22 Oct 2026 09:19:43 +0100
Subject: [PATCH 2/4] docs: resolve conduct-contact placeholder in
 CONTRIBUTING.md (#686)

---
 CODE_OF_CONDUCT.md | 2 +-
 CONTRIBUTING.md    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 9c466f88..59c2462a 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-[TODO: maintainer email] or conduct@vortexprotocol.io.
+conduct@vortexprotocol.io.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 52d8dc74..11fb4e35 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,4 +16,4 @@ All contributors and maintainers are expected to adhere to our [Code of Conduct]
 
 ## Reporting Conduct Issues
 
-If you experience or witness unacceptable behavior, please contact the maintainers at `conduct@vortexprotocol.io` or `[TODO: maintainer email]`.
+If you experience or witness unacceptable behavior, please contact the maintainers at `conduct@vortexprotocol.io`, the single conduct-reporting channel (also listed in the [Code of Conduct](./CODE_OF_CONDUCT.md)).

From 160bcb96d65884e23d1c6c76442a0fb0e753f442 Mon Sep 17 00:00:00 2001
From: Phanuella <phanuella81@gmail.com>
Date: Thu, 22 Oct 2026 09:20:13 +0100
Subject: [PATCH 3/4] feat: persist contributors Wave Tracker filters in the
 URL (#687)

---
 .../ContributorsPageClient.test.tsx           | 46 ++++++++++++-
 .../contributors/ContributorsPageClient.tsx   | 65 ++++++++++++++++---
 2 files changed, 100 insertions(+), 11 deletions(-)

diff --git a/src/app/contributors/ContributorsPageClient.test.tsx b/src/app/contributors/ContributorsPageClient.test.tsx
index fdf0458e..71657f13 100644
--- a/src/app/contributors/ContributorsPageClient.test.tsx
+++ b/src/app/contributors/ContributorsPageClient.test.tsx
@@ -1,10 +1,18 @@
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { render, screen, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { parseIssuesMarkdown } from "@/lib/issuesParser";
 
 vi.mock("@/components/Nav", () => ({ Nav: () => <nav /> }));
 
+const replaceMock = vi.fn();
+let currentParams = new URLSearchParams();
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({ replace: replaceMock }),
+  usePathname: () => "/contributors",
+  useSearchParams: () => currentParams,
+}));
+
 import ContributorsPageClient from "./ContributorsPageClient";
 
 const metrics = parseIssuesMarkdown(`
@@ -28,3 +36,39 @@ describe("ContributorsPageClient good-first-issue filter", () => {
     expect(screen.queryByText("Solver Performance Graph")).not.toBeInTheDocument();
   });
 });
+
+describe("ContributorsPageClient URL-persisted filters", () => {
+  beforeEach(() => {
+    replaceMock.mockClear();
+    currentParams = new URLSearchParams();
+  });
+
+  it("writes filter changes to the URL without scrolling", async () => {
+    const user = userEvent.setup();
+    render(<ContributorsPageClient metrics={metrics} />);
+
+    await user.click(screen.getByLabelText("Good first issues only"));
+    expect(replaceMock).toHaveBeenLastCalledWith("/contributors?goodFirstOnly=1", { scroll: false });
+
+    await user.click(screen.getByLabelText("Good first issues only"));
+    expect(replaceMock).toHaveBeenLastCalledWith("/contributors", { scroll: false });
+  });
+
+  it("pre-populates the controls from query params", () => {
+    currentParams = new URLSearchParams("goodFirstOnly=1&complexity=Trivial&q=uptime");
+    render(<ContributorsPageClient metrics={metrics} />);
+
+    expect(screen.getByLabelText("Good first issues only")).toBeChecked();
+    expect(screen.getByDisplayValue("uptime")).toBeInTheDocument();
+    expect(screen.getByText("Active Solver Uptime Indicator")).toBeInTheDocument();
+    expect(screen.queryByText("Solver Performance Graph")).not.toBeInTheDocument();
+  });
+
+  it("falls back to defaults for invalid query params", () => {
+    currentParams = new URLSearchParams("status=Bogus&complexity=Huge&category=Nope");
+    render(<ContributorsPageClient metrics={metrics} />);
+
+    expect(screen.getByText("Active Solver Uptime Indicator")).toBeInTheDocument();
+    expect(screen.getByText("Solver Performance Graph")).toBeInTheDocument();
+  });
+});
diff --git a/src/app/contributors/ContributorsPageClient.tsx b/src/app/contributors/ContributorsPageClient.tsx
index ee195424..841e18f7 100644
--- a/src/app/contributors/ContributorsPageClient.tsx
+++ b/src/app/contributors/ContributorsPageClient.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import { useState } from "react";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
 import { Nav } from "@/components/Nav";
 import type { ComplexityTier, IssueStatus, WaveMetrics } from "@/lib/issuesParser";
 import { useTranslation } from "@/lib/i18n/I18nProvider";
@@ -22,6 +23,11 @@ const TIER_LABEL_KEY: Record<ComplexityTier, MessageKey> = {
   High: "wave.tier.high",
 };
 
+const COMPLEXITY_VALUES: readonly string[] = ["Trivial", "Medium", "High"];
+const STATUS_VALUES: readonly string[] = ["Completed", "In Progress", "Open"];
+
+type FilterParam = "category" | "complexity" | "status" | "q" | "goodFirstOnly";
+
 function truncateAddress(addr: string): string {
   if (!addr || addr.length < 10) return addr;
   return `${addr.slice(0, 4)}...${addr.slice(-4)}`;
@@ -29,11 +35,35 @@ function truncateAddress(addr: string): string {
 
 export default function ContributorsPageClient({ metrics }: { metrics: WaveMetrics }) {
   const { t } = useTranslation();
-  const [selectedCategory, setSelectedCategory] = useState<string>("all");
-  const [selectedComplexity, setSelectedComplexity] = useState<string>("all");
-  const [selectedStatus, setSelectedStatus] = useState<string>("all");
-  const [searchQuery, setSearchQuery] = useState<string>("");
-  const [goodFirstOnly, setGoodFirstOnly] = useState(false);
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  // Initial filter state comes from the URL; unknown values fall back to "all".
+  const pick = (name: FilterParam, allowed: readonly string[]): string => {
+    const value = searchParams?.get(name);
+    return value && allowed.includes(value) ? value : "all";
+  };
+  const [selectedCategory, setSelectedCategory] = useState<string>(() =>
+    pick("category", metrics.categories.map((c) => c.category)),
+  );
+  const [selectedComplexity, setSelectedComplexity] = useState<string>(() =>
+    pick("complexity", COMPLEXITY_VALUES),
+  );
+  const [selectedStatus, setSelectedStatus] = useState<string>(() => pick("status", STATUS_VALUES));
+  const [searchQuery, setSearchQuery] = useState<string>(() => searchParams?.get("q") ?? "");
+  const [goodFirstOnly, setGoodFirstOnly] = useState(() => searchParams?.get("goodFirstOnly") === "1");
+
+  const syncUrl = (name: FilterParam, value: string) => {
+    const next = new URLSearchParams(searchParams?.toString() ?? "");
+    if (value === "" || value === "all" || (name === "goodFirstOnly" && value !== "1")) {
+      next.delete(name);
+    } else {
+      next.set(name, value);
+    }
+    const query = next.toString();
+    router.replace(query ? `${pathname}?${query}` : pathname, { scroll: false });
+  };
 
   const filteredIssues = metrics.issues.filter((issue) => {
     if (selectedCategory !== "all" && issue.category !== selectedCategory) return false;
@@ -241,13 +271,19 @@ export default function ContributorsPageClient({ metrics }: { metrics: WaveMetri
                 type="text"
                 placeholder={t("wave.issues.search")}
                 value={searchQuery}
-                onChange={(e) => setSearchQuery(e.target.value)}
+                onChange={(e) => {
+                  setSearchQuery(e.target.value);
+                  syncUrl("q", e.target.value);
+                }}
                 className="bg-vx-surface border border-vx-border rounded-lg px-3 py-2 text-xs text-vx-text placeholder-vx-dim focus:outline-none focus:border-vx-sage/50"
               />
 
               <select
                 value={selectedCategory}
-                onChange={(e) => setSelectedCategory(e.target.value)}
+                onChange={(e) => {
+                  setSelectedCategory(e.target.value);
+                  syncUrl("category", e.target.value);
+                }}
                 className="bg-vx-surface border border-vx-border rounded-lg px-3 py-2 text-xs text-vx-text focus:outline-none focus:border-vx-sage/50"
               >
                 <option value="all">{t("wave.issues.allCategories")}</option>
@@ -260,7 +296,10 @@ export default function ContributorsPageClient({ metrics }: { metrics: WaveMetri
 
               <select
                 value={selectedComplexity}
-                onChange={(e) => setSelectedComplexity(e.target.value)}
+                onChange={(e) => {
+                  setSelectedComplexity(e.target.value);
+                  syncUrl("complexity", e.target.value);
+                }}
                 className="bg-vx-surface border border-vx-border rounded-lg px-3 py-2 text-xs text-vx-text focus:outline-none focus:border-vx-sage/50"
               >
                 <option value="all">{t("wave.issues.allComplexities")}</option>
@@ -271,7 +310,10 @@ export default function ContributorsPageClient({ metrics }: { metrics: WaveMetri
 
               <select
                 value={selectedStatus}
-                onChange={(e) => setSelectedStatus(e.target.value)}
+                onChange={(e) => {
+                  setSelectedStatus(e.target.value);
+                  syncUrl("status", e.target.value);
+                }}
                 className="bg-vx-surface border border-vx-border rounded-lg px-3 py-2 text-xs text-vx-text focus:outline-none focus:border-vx-sage/50"
               >
                 <option value="all">{t("wave.issues.allStatuses")}</option>
@@ -284,7 +326,10 @@ export default function ContributorsPageClient({ metrics }: { metrics: WaveMetri
                 <input
                   type="checkbox"
                   checked={goodFirstOnly}
-                  onChange={(e) => setGoodFirstOnly(e.target.checked)}
+                  onChange={(e) => {
+                    setGoodFirstOnly(e.target.checked);
+                    syncUrl("goodFirstOnly", e.target.checked ? "1" : "");
+                  }}
                   className="accent-vx-sage focus:outline-none focus-visible:ring-2 focus-visible:ring-vx-sage"
                 />
                 Good first issues only

From 62fae3f8dda7122e6f459300df0d509a427d9f3c Mon Sep 17 00:00:00 2001
From: Phanuella <phanuella81@gmail.com>
Date: Thu, 22 Oct 2026 09:20:30 +0100
Subject: [PATCH 4/4] feat: good first issue mentor pairing on the contributors
 page (#688)

---
 CONTRIBUTING.md                                  | 10 ++++++++++
 issues.md                                        |  3 +++
 .../contributors/ContributorsPageClient.test.tsx | 16 ++++++++++++++++
 src/app/contributors/ContributorsPageClient.tsx  | 10 ++++++++++
 src/lib/issuesParser.test.ts                     | 16 ++++++++++++++++
 src/lib/issuesParser.ts                          |  7 +++++++
 6 files changed, 62 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 11fb4e35..ae14bc29 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -14,6 +14,16 @@ All contributors and maintainers are expected to adhere to our [Code of Conduct]
 4. **Browser storage**: Never touch `localStorage`/`sessionStorage` directly; register the key in `STORAGE_KEYS` and use the `storage` facade in `src/lib/storage.ts` (lint-enforced).
 5. **Submit PR**: Open a pull request detailing your changes and referencing the closed issue (`Closes #N`).
 
+## Good First Issue Mentors
+
+A maintainer can opt a good-first issue into having a mentor by adding `Mentor: <github-handle>` to its entry in `issues.md`, next to `Good first issue: yes`:
+
+```
+- #14 Swap Sound Effects (Complexity: Trivial, Points: 50, Status: Open, Contributor: None, Good first issue: yes, Mentor: octocat)
+```
+
+The Wave Tracker then shows an "Ask @handle about this one" link to that person's GitHub profile on the issue's card. Mentoring is optional and informal: the mentor agrees to answer questions about that specific issue (scope, where to look in the code, review expectations) on a best-effort basis. They are not expected to write the change, and the link is not an in-app chat or scheduling system. Only add a mentor who has agreed to it, and remove the field if they can no longer help. The handle is not validated against GitHub when `issues.md` is parsed.
+
 ## Reporting Conduct Issues
 
 If you experience or witness unacceptable behavior, please contact the maintainers at `conduct@vortexprotocol.io`, the single conduct-reporting channel (also listed in the [Code of Conduct](./CODE_OF_CONDUCT.md)).
diff --git a/issues.md b/issues.md
index 76509b9e..b1197410 100644
--- a/issues.md
+++ b/issues.md
@@ -23,6 +23,9 @@ contributors dashboard). An issue is only labelled when it meets **all** of:
    WebSocket live-data layering.
 4. **Bounded** — the expected result is concrete and easy to verify.
 
+A labelled issue may optionally name a mentor with `Mentor: <github-handle>` in its
+entry; see "Good First Issue Mentors" in `CONTRIBUTING.md`.
+
 When in doubt, an issue stays unlabelled: complexity tier alone isn't the test
 (some Trivial issues touch the signing path, and nothing here is labelled just
 to fill a quota).
diff --git a/src/app/contributors/ContributorsPageClient.test.tsx b/src/app/contributors/ContributorsPageClient.test.tsx
index 71657f13..2fa63597 100644
--- a/src/app/contributors/ContributorsPageClient.test.tsx
+++ b/src/app/contributors/ContributorsPageClient.test.tsx
@@ -72,3 +72,19 @@ describe("ContributorsPageClient URL-persisted filters", () => {
     expect(screen.getByText("Solver Performance Graph")).toBeInTheDocument();
   });
 });
+
+describe("ContributorsPageClient mentor affordance", () => {
+  it("links to the mentor's GitHub profile only when a mentor is set", () => {
+    currentParams = new URLSearchParams();
+    const mentored = parseIssuesMarkdown(`
+## Solver Network
+- #28 Mentored Issue (Complexity: Trivial, Points: 50, Status: Open, Contributor: None, Good first issue: yes, Mentor: octocat)
+- #29 Plain Issue (Complexity: Trivial, Points: 50, Status: Open, Contributor: None, Good first issue: yes)
+`);
+    render(<ContributorsPageClient metrics={mentored} />);
+
+    const link = screen.getByRole("link", { name: "Ask @octocat about this one" });
+    expect(link).toHaveAttribute("href", "https://github.com/octocat");
+    expect(screen.getAllByRole("link", { name: /Ask @/ })).toHaveLength(1);
+  });
+});
diff --git a/src/app/contributors/ContributorsPageClient.tsx b/src/app/contributors/ContributorsPageClient.tsx
index 841e18f7..c1d2a292 100644
--- a/src/app/contributors/ContributorsPageClient.tsx
+++ b/src/app/contributors/ContributorsPageClient.tsx
@@ -364,6 +364,16 @@ export default function ContributorsPageClient({ metrics }: { metrics: WaveMetri
                           Good first issue
                         </span>
                       )}
+                      {issue.goodFirstIssue && issue.mentor && (
+                        <a
+                          href={`https://github.com/${encodeURIComponent(issue.mentor)}`}
+                          target="_blank"
+                          rel="noopener noreferrer"
+                          className="ml-2 text-[10px] font-normal text-vx-sage underline focus:outline-none focus-visible:ring-2 focus-visible:ring-vx-sage"
+                        >
+                          Ask @{issue.mentor} about this one
+                        </a>
+                      )}
                     </td>
                     <td className="px-5 py-3.5 text-vx-muted">{issue.category}</td>
                     <td className="px-5 py-3.5">
diff --git a/src/lib/issuesParser.test.ts b/src/lib/issuesParser.test.ts
index a0b7026f..20080885 100644
--- a/src/lib/issuesParser.test.ts
+++ b/src/lib/issuesParser.test.ts
@@ -19,6 +19,22 @@ describe("parseIssuesMarkdown good-first-issue annotation", () => {
     expect(issues[0]).toMatchObject({ complexity: "Trivial", status: "Open", contributor: null });
   });
 
+  it("reads an optional `Mentor:` handle", () => {
+    const { issues } = parseIssuesMarkdown(`
+## Core Swap UI
+- #1 Mentored (Complexity: Trivial, Points: 50, Status: Open, Contributor: None, Good first issue: yes, Mentor: @octocat)
+- #2 Bare handle (Complexity: Trivial, Points: 50, Status: Open, Contributor: None, Good first issue: yes, Mentor: some-user)
+- #3 No mentor (Complexity: Trivial, Points: 50, Status: Open, Contributor: None, Good first issue: yes)
+- #4 Mentor none (Complexity: Trivial, Points: 50, Status: Open, Contributor: None, Mentor: None)
+`);
+    expect(issues.map((i) => [i.id, i.mentor])).toEqual([
+      [1, "octocat"],
+      [2, "some-user"],
+      [3, null],
+      [4, null],
+    ]);
+  });
+
   it("flags exactly the curated issues in issues.md, all of them open", () => {
     const markdown = readFileSync(path.resolve(__dirname, "../../issues.md"), "utf8");
     const { issues } = parseIssuesMarkdown(markdown);
diff --git a/src/lib/issuesParser.ts b/src/lib/issuesParser.ts
index 5ab94b70..5f6e62a0 100644
--- a/src/lib/issuesParser.ts
+++ b/src/lib/issuesParser.ts
@@ -11,6 +11,8 @@ export type WaveIssue = {
   contributor: string | null;
   /** Curated onboarding signal from `Good first issue: yes` in issues.md. */
   goodFirstIssue: boolean;
+  /** Optional GitHub handle (no leading `@`) from `Mentor: handle` in issues.md. */
+  mentor: string | null;
 };
 
 export type CategorySummary = {
@@ -100,6 +102,7 @@ export function parseIssuesMarkdown(markdown: string): WaveMetrics {
         let status: IssueStatus = "Open";
         let contributor: string | null = null;
         let goodFirstIssue = false;
+        let mentor: string | null = null;
 
         for (const part of detailsParts) {
           const [key, val] = part.split(":").map((s) => s?.trim());
@@ -124,6 +127,9 @@ export function parseIssuesMarkdown(markdown: string): WaveMetrics {
             }
           } else if (keyLower === "good first issue") {
             goodFirstIssue = val.toLowerCase() === "yes";
+          } else if (keyLower === "mentor") {
+            const handle = val.replace(/^@/, "");
+            if (handle && handle !== "None") mentor = handle;
           }
         }
 
@@ -136,6 +142,7 @@ export function parseIssuesMarkdown(markdown: string): WaveMetrics {
           status,
           contributor,
           goodFirstIssue,
+          mentor,
         });
       } catch {
         // Graceful error handling for unexpected lines