sigrank 0.18.5 → 1.0.1

package/tools/compare-operators.mjs

@@ -0,0 +1,80 @@
+/**
+ * tools/compare-operators.mjs — compare_operators tool.
+ */
+
+import { COMPARE_OPERATORS_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { _behavioralFraming, _classMeaning, _competitiveLayer } from "./_framing.mjs";
+import { LEADERBOARD_METRIC } from "../lib/constants.mjs";
+
+export const TOOL_DEF = {
+  name: "compare_operators",
+  description:
+    "Compares two operators side-by-side with a behavioral verdict. Fetches both profiles from the board and returns their yield, leverage, velocity, class, and rank side-by-side, plus a verdict explaining who is more efficient and why in power-user language. Use this when users ask 'compare operator X vs Y' or 'who is more efficient' or 'how do two AI users compare'. Intent: COMPARE_OPERATORS.",
+  annotations: { title: "Compare two operators", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {
+      codename_a: {
+        type: "string",
+        description:
+          "First operator's codename from the SigRank leaderboard. Case-insensitive.",
+      },
+      codename_b: {
+        type: "string",
+        description:
+          "Second operator's codename from the SigRank leaderboard. Case-insensitive.",
+      },
+    },
+    required: ["codename_a", "codename_b"],
+    description:
+      "Requires both codenames. Both must exist on the board.",
+  },
+  outputSchema: COMPARE_OPERATORS_OUTPUT,
+};
+
+export async function handleCompareOperators(args, ctx) {
+  const nameA = String(args?.codename_a || "").trim();
+  const nameB = String(args?.codename_b || "").trim();
+  if (!nameA || !nameB)
+    throw new Error(
+      "compare_operators requires both `codename_a` and `codename_b`.",
+    );
+
+  const [opA, opB, board] = await Promise.all([
+    ctx.fetchJson(`/api/v1/operators/${encodeURIComponent(nameA)}`),
+    ctx.fetchJson(`/api/v1/operators/${encodeURIComponent(nameB)}`),
+    ctx.fetchJson(`/api/v1/leaderboard?metric=${LEADERBOARD_METRIC}`),
+  ]);
+
+  const yieldA = opA.yield_ || 0;
+  const yieldB = opB.yield_ || 0;
+  const delta = yieldA - yieldB;
+
+  const winner = yieldA > yieldB ? opA : opB;
+  const loser = yieldA > yieldB ? opB : opA;
+  const verdict = `${winner.codename} is more token-efficient (${winner.yield_?.toLocaleString?.() || winner.yield_} vs ${loser.yield_?.toLocaleString?.() || loser.yield_} Υ). ${_behavioralFraming(winner)} ${loser.codename} ${_classMeaning(loser.class).toLowerCase()}`;
+
+  return {
+    operator_a: {
+      codename: opA.codename,
+      yield_: opA.yield_,
+      leverage: opA.leverage,
+      velocity: opA.velocity,
+      class: opA.class,
+      rank: opA.rank,
+      competitive: _competitiveLayer(opA, board),
+    },
+    operator_b: {
+      codename: opB.codename,
+      yield_: opB.yield_,
+      leverage: opB.leverage,
+      velocity: opB.velocity,
+      class: opB.class,
+      rank: opB.rank,
+      competitive: _competitiveLayer(opB, board),
+    },
+    verdict,
+    yield_delta: delta,
+    cta: "Compare me to others",
+  };
+}

package/tools/compare-self.mjs

@@ -0,0 +1,124 @@
+/**
+ * tools/compare-self.mjs — compare_self tool.
+ */
+
+import { cascade, parsePillars } from "../analytics/cascade.mjs";
+import { COMPARE_SELF_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { MAX_INPUT, withParseWarnings } from "./_helpers.mjs";
+import { LEADERBOARD_METRIC } from "../lib/constants.mjs";
+import {
+  _powerUserAssessment,
+  _classMeaning,
+  _improvementSuggestion,
+  _competitiveLayer,
+  _competitiveSummary,
+  FALLBACK_CLASS,
+} from "./_framing.mjs";
+
+export const TOOL_DEF = {
+  name: "compare_self",
+  description:
+    "Compares an operator's metrics against board averages and power-user archetypes, returning a behavioral assessment. Accepts either a codename (fetches from the board) or raw token pillars (computes locally). Returns: your yield/leverage/velocity/class/rank, a power-user assessment mapping your class tier to AI power-user language, comparison vs board averages (your percentile), and one actionable suggestion to improve. Use this when users ask 'how do I measure up to other AI users?' or 'am I a power user?' or 'compare me to others'. Intent: COMPARE_SELF.",
+  annotations: { title: "Compare self to board", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {
+      codename: {
+        type: "string",
+        description:
+          "Your codename on the SigRank leaderboard. If provided, fetches your live profile from the board. Case-insensitive.",
+      },
+      text: {
+        type: "string",
+        description:
+          'Alternative: raw token pillars to score locally (ccusage JSON or "input output cacheCreate cacheRead"). Use this if you are not on the board yet but want to see how you would compare.',
+      },
+    },
+    description:
+      "Provide either `codename` (to fetch from the board) or `text` (to score locally). At least one is required.",
+  },
+  outputSchema: COMPARE_SELF_OUTPUT,
+};
+
+export async function handleCompareSelf(args, ctx) {
+  const codename = String(args?.codename || "").trim();
+  const text = String(args?.text || "").trim();
+
+  if (!codename && !text)
+    throw new Error(
+      "compare_self requires either `codename` (to fetch from the board) or `text` (raw token pillars to score locally).",
+    );
+
+  let yourMetrics;
+  if (codename) {
+    yourMetrics = await ctx.fetchJson(
+      `/api/v1/operators/${encodeURIComponent(codename)}`,
+    );
+  } else {
+    if (text.length > MAX_INPUT) {
+      return {
+        error: "input_too_large",
+        detail: `text exceeds ${MAX_INPUT} chars.`,
+      };
+    }
+    const pillars = parsePillars(text);
+    const c = withParseWarnings(pillars, cascade(pillars));
+    yourMetrics = {
+      codename: "you (local)",
+      yield_: c.yield,
+      leverage: c.leverage,
+      velocity: c.velocity,
+      class: c.class,
+      rank: null,
+    };
+  }
+
+  // Fetch board for comparison
+  const board = await ctx.fetchJson(`/api/v1/leaderboard?metric=${LEADERBOARD_METRIC}`);
+  const allOps = board.operators || board || [];
+  const yields = allOps.map((o) => o.yield_ || 0).sort((a, b) => a - b);
+  const avgYield = yields.length
+    ? yields.reduce((s, y) => s + y, 0) / yields.length
+    : 0;
+  const yourYield = yourMetrics.yield_ || 0;
+  const percentile = yields.length
+    ? Math.round(
+        (yields.filter((y) => y < yourYield).length / yields.length) * 100,
+      )
+    : 0;
+
+  const klass = yourMetrics.class || FALLBACK_CLASS;
+  const powerUserAssessment = _powerUserAssessment(klass, yourMetrics);
+  const classMeaning = _classMeaning(klass);
+
+  const yieldVsAvg = yields.length
+    ? yourYield > avgYield
+      ? `${(yourYield / avgYield).toFixed(1)}× the board average`
+      : `${((yourYield / avgYield) * 100).toFixed(0)}% of the board average`
+    : "board has no other operators";
+
+  const suggestion = _improvementSuggestion(klass, yourMetrics);
+
+  // Competitive layer per SHARED_DESIGN_DECISIONS.md §3/§4/§5
+  const competitive = _competitiveLayer(yourMetrics, board);
+  const competitiveSummary = _competitiveSummary(yourMetrics, board);
+
+  return {
+    your_metrics: yourMetrics,
+    power_user_assessment: powerUserAssessment,
+    comparison: {
+      your_yield_vs_avg: yieldVsAvg,
+      your_class_meaning: classMeaning,
+      percentile,
+      rank: competitive.rank,
+      total_operators: competitive.total_operators,
+      class_tier: competitive.class_tier,
+      delta_from_average: competitive.delta_from_average,
+      delta_from_top: competitive.delta_from_top,
+    },
+    competitive_summary: competitiveSummary,
+    shareable_url: competitive.shareable_url,
+    suggestion,
+    cta: "See where I stand",
+  };
+}

package/tools/describe-power-user.mjs

@@ -0,0 +1,78 @@
+/**
+ * tools/describe-power-user.mjs — describe_power_user tool.
+ */
+
+import { ANNOTATIONS, CLASS_ENUM } from "./_schemas.mjs";
+import { CLASS_TIERS, UNCLASSED } from "../analytics/cascade.mjs";
+import { DEFAULT_API_BASE } from "./_helpers.mjs";
+
+export const TOOL_DEF = {
+  name: "describe_power_user",
+  description:
+    "Returns an explanatory description of what makes an AI power user, anchored in SigRank's metrics and operator classes. Explains the yield metric, leverage, velocity, and how the 8 experience tiers (ARCH+ / ARCH / POWER / BASE / SEEKER / REFINER / BEARER / IGNITER, each with 3 sub-stages I/II/III, plus UNCLASSED for no-data) map to power-user behavior patterns. Use this when users ask 'what is an AI power user?' or 'what makes a good AI user?' or 'describe advanced AI user behavior'. Intent: DESCRIBE_POWER_USER (Informational).",
+  annotations: { title: "Describe power user", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint },
+  inputSchema: {
+    type: "object",
+    properties: {},
+    description:
+      "This tool takes no parameters. It returns a static explanatory response about AI power users.",
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      description: { type: "string", description: "What is an AI power user" },
+      metrics_explained: {
+        type: "object",
+        description: "How SigRank metrics map to power-user behavior",
+        properties: {
+          yield_: { type: "string", description: "What yield measures in power-user terms" },
+          leverage: { type: "string", description: "What leverage means for power users" },
+          velocity: { type: "string", description: "What velocity means for power users" },
+        },
+      },
+      class_tiers: {
+        type: "array",
+        description: "Operator class tiers and their power-user meaning",
+        items: {
+          type: "object",
+          properties: {
+            class: { type: "string", enum: CLASS_ENUM },
+            meaning: { type: "string" },
+          },
+        },
+      },
+      link: { type: "string", description: "URL to learn more" },
+    },
+  },
+};
+
+export async function handleDescribePowerUser() {
+  return {
+    description:
+      "An AI power user isn't someone who sends the most tokens — it's someone who compounds signal. " +
+      "Power users build workflows where cached context does the heavy lifting, fresh input stays lean, " +
+      "and output per session is high. SigRank quantifies this with the yield metric (Υ = cache_read × output / input²).",
+    metrics_explained: {
+      yield_: "Yield (Υ) measures how well you compound signal, not how much you burn. High yield = your cached context is doing work for you.",
+      leverage: "Leverage (Cr/I) measures how much you reuse prior work vs starting fresh. High leverage = you're building on cached results, not re-explaining everything.",
+      velocity: "Velocity (O/I) measures how much output you get per token spent. High velocity = you're productive, not just active.",
+    },
+    // The 8 base tiers + UNCLASSED, in descending cut order (matches
+    // analytics/cascade.mjs CLASS_TIERS). Each tier has 3 sub-stages (I/II/III)
+    // — 24 stages total. TRANSMITTER is a peak badge, not a class.
+    class_tiers: [
+      { class: "ARCH+", sub_stages: ["ARCH+ I", "ARCH+ II", "ARCH+ III"], meaning: "Deepest field experience — volume that became architecture. The AI power user archetype." },
+      { class: "ARCH", sub_stages: ["ARCH I", "ARCH II", "ARCH III"], meaning: "System builder — sustained volume, coherent output, heavy cache reuse." },
+      { class: "POWER", sub_stages: ["POWER I", "POWER II", "POWER III"], meaning: "Above the center — volume compounding, building momentum." },
+      { class: "BASE", sub_stages: ["BASE I", "BASE II", "BASE III"], meaning: "The center of the field — the average operator's experience. Building momentum." },
+      { class: "SEEKER", sub_stages: ["SEEKER I", "SEEKER II", "SEEKER III"], meaning: "Approaching the center — experience accumulating, reuse patterns forming." },
+      { class: "REFINER", sub_stages: ["REFINER I", "REFINER II", "REFINER III"], meaning: "Practicing with purpose — early sustained volume, refining context reuse." },
+      { class: "BEARER", sub_stages: ["BEARER I", "BEARER II", "BEARER III"], meaning: "Quiet accumulation — the first real volume. Session continuity starting." },
+      { class: "IGNITER", sub_stages: ["IGNITER I", "IGNITER II", "IGNITER III"], meaning: "Entry — dormant potential. First sessions, minimal accumulated volume." },
+      { class: UNCLASSED, sub_stages: null, meaning: "No cascade data yet — run sessions and re-rank to see your tier." },
+    ],
+    link: "https://signalaf.com/score — check your class tier and yield",
+    shareable_url: `${DEFAULT_API_BASE}/score`,
+    cta: "Learn the scoring",
+  };
+}

package/tools/diagnose-cascade.mjs

@@ -0,0 +1,192 @@
+/**
+ * tools/diagnose-cascade.mjs — diagnose_cascade tool.
+ */
+
+import { cascade, parsePillars } from "../analytics/cascade.mjs";
+import { DIAGNOSE_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { MAX_INPUT, withParseWarnings } from "./_helpers.mjs";
+
+export const TOOL_DEF = {
+  name: "diagnose_cascade",
+  description:
+    "Analyzes your token cascade and diagnoses where you're leaking efficiency. Takes your 4 pillars (input/output/cacheCreate/cacheRead) and produces a ranked list of efficiency leaks with severity (critical/warning/info), findings, and recommendations. Checks: cache leverage (are you rereading what you wrote?), velocity (are you generating enough output per input?), SNR (is your signal drowning in noise?), cache creation ratio (are you over-committing?), input bloat (is fresh input too high?), and 10xDEV (is the full cascade compounding?). Each finding includes an estimated Υ impact. Pure local math — no network, no submission. Use this BEFORE simulate_change to understand what's wrong, then use simulate_change to test fixes. Accepts the same input formats as rank_paste (JSON or 4 whitespace numbers).",
+  annotations: {
+    title: "Diagnose cascade breakdown",
+    ...ANNOTATIONS.readOnlyHint,
+    ...ANNOTATIONS.idempotentHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      text: {
+        type: "string",
+        description:
+          'Token pillars — ccusage JSON or "input output cacheCreate cacheRead" (same format as rank_paste).',
+      },
+    },
+    required: ["text"],
+  },
+  outputSchema: DIAGNOSE_OUTPUT,
+};
+
+export async function handleDiagnoseCascade(args) {
+  if (!args?.text)
+    throw new Error(
+      "diagnose_cascade requires a non-empty `text` argument (token pillars).",
+    );
+  if (typeof args.text === "string" && args.text.length > MAX_INPUT) {
+    return {
+      status: "error",
+      reason: "input_too_large",
+      detail: `text exceeds ${MAX_INPUT} chars.`,
+    };
+  }
+
+  const p = parsePillars(args.text);
+  const result = withParseWarnings(p, cascade(p));
+  const { input: i, output: o, cacheCreate: cw, cacheRead: cr } = p;
+  const diagnosis = [];
+
+  // Cache leverage check — the #1 cascade efficiency signal
+  const leverage = result.leverage;
+  if (leverage !== null) {
+    if (leverage < 10) {
+      diagnosis.push({
+        metric: "cache_leverage",
+        severity: "critical",
+        finding: `Cache leverage is ${leverage}× — you're reading only ${leverage}× your fresh input from cache. Top-tier operators hit 200×+.`,
+        recommendation:
+          "Increase context reuse: load prior session context, use longer conversation threads, reference earlier outputs.",
+        estimated_yield_impact: `+${Math.round((1 - leverage / 50) * 100)}% Υ potential`,
+      });
+    } else if (leverage < 50) {
+      diagnosis.push({
+        metric: "cache_leverage",
+        severity: "warning",
+        finding: `Cache leverage is ${leverage}× — decent but below the ARCH+ threshold (~100×+).`,
+        recommendation:
+          "Push cache reads higher by reusing prior context more aggressively.",
+        estimated_yield_impact: `+${Math.round((1 - leverage / 100) * 50)}% Υ potential`,
+      });
+    }
+  }
+
+  // Velocity check — output per input
+  const velocity = result.velocity;
+  if (velocity !== null) {
+    if (velocity < 0.5) {
+      diagnosis.push({
+        metric: "velocity",
+        severity: "critical",
+        finding: `Velocity is ${velocity} — generating only ${velocity}× your input as output. You're reading more than you produce.`,
+        recommendation:
+          "Increase output: ask the agent to generate more code/text per turn, reduce over-reading.",
+        estimated_yield_impact: `+${Math.round((0.5 - velocity) * 100)}% Υ per 0.1 velocity gain`,
+      });
+    } else if (velocity < 1.0) {
+      diagnosis.push({
+        metric: "velocity",
+        severity: "warning",
+        finding: `Velocity is ${velocity} — below 1.0 (output < input). Healthy operators hit 1.5×+.`,
+        recommendation:
+          "Generate more output per input token — larger edits, more complete responses.",
+        estimated_yield_impact: `+${Math.round((1 - velocity) * 30)}% Υ potential`,
+      });
+    }
+  }
+
+  // SNR check — signal-to-noise
+  const snr = result.snr;
+  if (snr !== null && snr < 0.3) {
+    diagnosis.push({
+      metric: "snr",
+      severity: "warning",
+      finding: `SNR is ${snr} — less than 30% of your token flow is output. Input is dominating.`,
+      recommendation:
+        "Reduce fresh input (reuse context) or increase output generation.",
+      estimated_yield_impact:
+        "Indirect — improves both velocity and leverage",
+    });
+  }
+
+  // Cache creation ratio — are you over-committing?
+  if (cw > 0 && o > 0) {
+    const commitRatio = cw / o;
+    if (commitRatio > 20) {
+      diagnosis.push({
+        metric: "cache_creation",
+        severity: "info",
+        finding: `Cache creation is ${commitRatio.toFixed(1)}× your output — high commitment. This is fine if you're rereading it (check leverage), but wasteful if not.`,
+        recommendation:
+          "Ensure you're rereading committed context. If leverage is low, you're writing cache you never read.",
+        estimated_yield_impact: "Cost reduction, not Υ directly",
+      });
+    }
+  }
+
+  // Input bloat — is fresh input too high relative to total?
+  const total = i + o + cw + cr;
+  if (total > 0) {
+    const inputPct = (i / total) * 100;
+    if (inputPct > 10) {
+      diagnosis.push({
+        metric: "input_bloat",
+        severity: "warning",
+        finding: `Fresh input is ${inputPct.toFixed(1)}% of your total token flow — high. Efficient operators keep input under 1% by leaning on cache.`,
+        recommendation:
+          "Reduce fresh input by reusing prior context instead of re-pasting it.",
+        estimated_yield_impact: `+${Math.round((inputPct - 1) * 5)}% Υ potential`,
+      });
+    }
+  }
+
+  // 10xDEV check — is the full cascade compounding?
+  if (result.dev10x === null && cw === 0) {
+    diagnosis.push({
+      metric: "10xdev",
+      severity: "critical",
+      finding:
+        "No cache creation — the cascade cannot compound. You're operating in a non-compounding mode (like ChatGPT without prompt caching).",
+      recommendation:
+        "Switch to a platform with prompt caching (Claude Code) or enable caching if available.",
+      estimated_yield_impact: "Enables the full cascade — potentially 10×+ Υ",
+    });
+  } else if (result.dev10x !== null && result.dev10x < 1.0) {
+    diagnosis.push({
+      metric: "10xdev",
+      severity: "info",
+      finding: `10xDEV is ${result.dev10x} — below 1.0 (BASE threshold). The cascade is compounding but not strongly.`,
+      recommendation:
+        "Improve both leverage AND velocity — 10xDEV = log10(transmission × commitment × reuse).",
+      estimated_yield_impact: "Class tier improvement",
+    });
+  }
+
+  // Sort by severity (critical > warning > info)
+  const sevOrder = { critical: 0, warning: 1, info: 2 };
+  diagnosis.sort((a, b) => sevOrder[a.severity] - sevOrder[b.severity]);
+
+  const healthScore = diagnosis.filter(
+    (d) => d.severity === "critical",
+  ).length;
+  const summary =
+    healthScore === 0
+      ? `Cascade is healthy — Υ ${result.yield}, class ${result.class}. ${diagnosis.length} minor optimizations available.`
+      : `Cascade has ${healthScore} critical leak${healthScore > 1 ? "s" : ""} — Υ ${result.yield}, class ${result.class}. Fix the critical items first.`;
+
+  return {
+    pillars: p,
+    cascade: {
+      yield_: result.yield,
+      snr: result.snr,
+      leverage: result.leverage,
+      velocity: result.velocity,
+      tenx_dev: result.dev10x,
+      class: result.class,
+      warnings: result.warnings,
+    },
+    diagnosis,
+    summary,
+  };
+}

package/tools/discover-peers.mjs

@@ -0,0 +1,198 @@
+/**
+ * tools/discover-peers.mjs — discover_peers tool.
+ *
+ * Finds mentors, peers, and complementary operators for YOUR operator on the
+ * SigRank leaderboard. Uses the enrolled device identity (ensureIdentity) so
+ * the operator's agent doesn't need to pass a codename — it knows who you are.
+ *
+ * This is the "make connections" piece of the agent workflow loop:
+ *   enroll → submit_verified → discover_peers → self_improve → submit again
+ *
+ * Fetches the operator's profile + the full leaderboard from signalaf.com's
+ * public API, then runs pure client-side peer-matching logic:
+ *   - Mentors: 1-2 class tiers above, ranked by cascade shape similarity
+ *   - Peers: same class tier, ranked by yield proximity
+ *   - Complementary: operators whose strength maps to your weakness
+ *
+ * For each mentor, computes the pillar delta — the specific token difference
+ * that explains the yield gap (e.g. "12× your cache reads").
+ */
+
+import { ensureIdentity } from "../identity/keystore.mjs";
+import { ANNOTATIONS } from "./_schemas.mjs";
+import { DEFAULT_API_BASE } from "./_helpers.mjs";
+import {
+  findMentors,
+  findPeers,
+  findComplementary,
+  peerSummary,
+  tierRank,
+} from "./_peer-matching.mjs";
+import { LEADERBOARD_METRIC } from "../lib/constants.mjs";
+
+export const TOOL_DEF = {
+  name: "discover_peers",
+  description:
+    "Discovers mentors, peers, and complementary operators for YOUR operator on the SigRank leaderboard. Uses your enrolled device identity — no codename needed. Finds operators you should learn from: (1) Mentors — 1-2 class tiers above you with similar cascade shapes, including the specific pillar delta that explains the yield gap (e.g. '12× your cache reads'). (2) Peers — same class tier, ranked by yield proximity. (3) Complementary — operators whose strength is your weakness. Use this after submit_verified to find who to learn from, then chain into self_improve with the mentor's pillar deltas as context. Requires enrollment (npx sigrank-mcp enroll). Intent: DISCOVER_PEERS.",
+  annotations: {
+    title: "Discover peers and mentors",
+    ...ANNOTATIONS.readOnlyHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      platform: {
+        type: "string",
+        description:
+          "Filter peers by platform (default: your operator's primary platform). Use 'all' to search across all platforms.",
+      },
+      n: {
+        type: "integer",
+        description:
+          "Number of operators to return per category (default: 5, max: 20).",
+        minimum: 1,
+        maximum: 20,
+      },
+    },
+    description:
+      "Optional: platform filter and result count. Uses your enrolled identity to determine your operator.",
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      your_profile: {
+        type: "object",
+        description: "Your operator's current profile on the board",
+        properties: {
+          codename: { type: "string" },
+          class_tier: { type: "string" },
+          platform: { type: "string" },
+          yield_: { type: "number" },
+          leverage: { type: "number" },
+          velocity: { type: "number" },
+          rank: { type: "integer" },
+        },
+      },
+      mentors: {
+        type: "array",
+        description:
+          "Operators 1-2 class tiers above you with similar cascade shapes, including pillar deltas",
+      },
+      peers: {
+        type: "array",
+        description: "Operators in your class tier, ranked by yield proximity",
+      },
+      complementary: {
+        type: "array",
+        description: "Operators whose strength maps to your weakness",
+      },
+      summary: { type: "string", description: "One-line summary of findings" },
+      cta: { type: "string" },
+    },
+  },
+};
+
+export async function handleDiscoverPeers(args, ctx) {
+  const id = ctx.opts.identity || ensureIdentity();
+  if (!id.codename) {
+    return {
+      status: "not_enrolled",
+      detail:
+        "Run `npx sigrank-mcp enroll` to bind this device first, then submit_verified to appear on the board.",
+    };
+  }
+
+  const apiBase = ctx.apiBase || DEFAULT_API_BASE;
+  const n = Math.min(20, Math.max(1, args?.n ?? 5));
+  const platformFilter = args?.platform === "all" ? null : args?.platform;
+
+  // Fetch the operator's profile and the full leaderboard in parallel.
+  const [profile, board] = await Promise.all([
+    ctx.fetchJson(`/api/v1/operators/${encodeURIComponent(id.codename)}`),
+    ctx.fetchJson(`/api/v1/leaderboard?metric=${LEADERBOARD_METRIC}&limit=2000`),
+  ]);
+
+  // Find the operator's entry in the board (has raw token pillars + class_tier).
+  const entries = board.entries || board.operators || board || [];
+  const boardEntry = entries.find(
+    (op) => op.codename?.toLowerCase() === id.codename?.toLowerCase(),
+  );
+
+  if (!boardEntry) {
+    return {
+      status: "not_on_board",
+      codename: id.codename,
+      detail:
+        "You're enrolled but not on the leaderboard yet. Run submit_verified to publish your snapshots.",
+      profile,
+    };
+  }
+
+  // Merge profile + board entry (board entry has raw pillars, profile has
+  // per-window breakdowns). Use board entry as the primary source since it
+  // has the fields peer-matching needs.
+  const operator = {
+    ...boardEntry,
+    ...profile,
+    // Ensure board entry fields take precedence for peer-matching
+    class_tier: boardEntry.class_tier || boardEntry.class || profile.class_tier,
+    yield_: boardEntry.yield_ ?? profile.yield_,
+    leverage: boardEntry.leverage ?? profile.leverage,
+    velocity: boardEntry.velocity ?? profile.velocity,
+    snr: boardEntry.snr ?? profile.snr,
+    platform: boardEntry.platform || profile.platform,
+  };
+
+  const myTier = tierRank(operator.class_tier);
+  if (myTier < 0) {
+    // UNCLASSED — no class to match on. Return complementary only.
+    const complementary = findComplementary(operator, entries, { n, apiBase, platform: platformFilter });
+    return {
+      your_profile: {
+        codename: operator.codename,
+        class_tier: operator.class_tier,
+        platform: operator.platform,
+        yield_: operator.yield_,
+        leverage: operator.leverage,
+        velocity: operator.velocity,
+        rank: operator.rank,
+      },
+      mentors: [],
+      peers: [],
+      complementary,
+      summary: `You're UNCLASSED — no class tier to match peers on. ${complementary.length} complementary operators found based on cascade dimensions. Submit more snapshots to get classified.`,
+      cta: "Submit snapshots",
+    };
+  }
+
+  const opts = { n, apiBase, platform: platformFilter };
+  const mentors = findMentors(operator, entries, opts);
+  const peers = findPeers(operator, entries, opts);
+  const complementary = findComplementary(operator, entries, opts);
+
+  // Add shareable URLs to mentors
+  const mentorsWithUrls = mentors.map((m) => ({
+    ...m,
+    shareable_url: `${apiBase}/operator/${encodeURIComponent(m.codename)}`,
+  }));
+
+  const summary = peerSummary(operator, mentors, peers, complementary);
+
+  return {
+    your_profile: {
+      codename: operator.codename,
+      class_tier: operator.class_tier,
+      platform: operator.platform,
+      yield_: operator.yield_,
+      leverage: operator.leverage,
+      velocity: operator.velocity,
+      rank: operator.rank,
+    },
+    mentors: mentorsWithUrls,
+    peers,
+    complementary,
+    summary,
+    cta: "Study their cascade",
+  };
+}