sigrank 0.0.177 → 0.0.179

package/tools/compare-self.mjs

@@ -0,0 +1,122 @@
+/**
+ * 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 {
+  _powerUserAssessment,
+  _classMeaning,
+  _improvementSuggestion,
+  _competitiveLayer,
+  _competitiveSummary,
+} 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=yield_");
+  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 || "Burner";
+  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,68 @@
+/**
+ * tools/describe-power-user.mjs — describe_power_user tool.
+ */
+
+import { ANNOTATIONS } from "./_schemas.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 class tiers (Burner/Builder/10xer) 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: ["Burner", "Builder", "10xer"] },
+            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.",
+    },
+    class_tiers: [
+      { class: "10xer", meaning: "AI power user archetype — disciplined, system-level reuse, high output per input. Leverage > 10×, high velocity." },
+      { class: "Builder", meaning: "Building momentum — moderate cache reuse, approaching power-user patterns. Growing leverage and velocity." },
+      { class: "Burner", meaning: "Early-stage — tokens burned more than compounded. Low leverage, low velocity. The shift: reuse prior context." },
+    ],
+    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. TRANSMITTER-class 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/enroll.mjs

@@ -0,0 +1,121 @@
+/**
+ * tools/enroll.mjs — enroll tool.
+ */
+
+import os from "node:os";
+import { ensureIdentity, recordEnrollment } from "../identity/keystore.mjs";
+import { ENROLL_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+
+const TERMS_VERSION = "2026-07-21";
+const PRIVACY_VERSION = "2026-07-21";
+
+export const TOOL_DEF = {
+  name: "enroll",
+  description:
+    'Bind THIS device to your SigRank operator so your signed token runs cascade to the live board. Paste the key from signalaf.com → Settings → "New key" (or "Generate connect code"). On first run it generates + stores a local ed25519 keypair (~/.sigrank-mcp/identity.json); only the PUBLIC key is ever sent. By enrolling you agree to the SignalAF Terms of Service (signalaf.com/terms) and Privacy Policy (signalaf.com/privacy). Need a new key? Click "New key" at signalaf.com → Settings, then paste it here.',
+  annotations: {
+    title: "Enroll device identity",
+    ...ANNOTATIONS.destructiveHint,
+    ...ANNOTATIONS.idempotentHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      code: {
+        type: "string",
+        description:
+          "the key / connect code (SIGR-XXXXX-XXXXX-XXXXX) from Settings → New key (or Generate connect code)",
+      },
+      device_label: {
+        type: "string",
+        description:
+          "optional label for this device (default: hostname · agent version)",
+      },
+    },
+    required: ["code"],
+  },
+  outputSchema: ENROLL_OUTPUT,
+};
+
+export async function handleEnroll(args, ctx) {
+  // Redeem a web connect code → bind this device. Generates/loads the local keypair;
+  // sends ONLY the public key. operator binding happens server-side from the code row.
+  const code = String(args?.code || "").trim();
+  if (!code)
+    throw new Error(
+      "enroll requires a `code` — paste your connect code from signalaf.com → Settings → Connect a device.",
+    );
+  const id = ctx.opts.identity || ensureIdentity();
+  const deviceLabel = String(
+    args?.device_label || `${os.hostname()} · ${id.agent_version}`,
+  ).slice(0, 120);
+  const res = await ctx.doFetch(`${ctx.apiBase}/api/v1/devices/enroll`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json",
+    },
+    body: JSON.stringify({
+      code,
+      device_id: id.device_id,
+      public_key: id.public_key,
+      device_label: deviceLabel,
+      agent_version: id.agent_version,
+      consent_acknowledged: true,
+      terms_version: TERMS_VERSION,
+      privacy_version: PRIVACY_VERSION,
+    }),
+  });
+  let ack;
+  try {
+    ack = await res.json();
+  } catch {
+    ack = {};
+  }
+  if (res.status === 201 && ack.status === "enrolled") {
+    // Persist the binding locally (skipped when a test injects opts.identity → no keystore write).
+    if (!ctx.opts.identity)
+      recordEnrollment({
+        codename: ack.codename,
+        operator_id: ack.operator_id,
+      });
+    return {
+      status: "enrolled",
+      codename: ack.codename ?? null,
+      operator_id: ack.operator_id ?? null,
+      device_id: id.device_id,
+      trust_status: ack.trust_status ?? "trusted",
+    };
+  }
+  // Recovery: if the server says device_already_enrolled but includes the
+  // codename/operator_id, the device IS bound server-side — record it locally
+  // and return enrolled instead of erroring. This handles the case where the
+  // local binding was lost (partial write, version transition) but the device
+  // is still enrolled server-side.
+  if (
+    ack.reason === "device_already_enrolled" &&
+    ack.codename &&
+    ack.operator_id
+  ) {
+    if (!ctx.opts.identity)
+      recordEnrollment({
+        codename: ack.codename,
+        operator_id: ack.operator_id,
+      });
+    return {
+      status: "enrolled",
+      codename: ack.codename,
+      operator_id: ack.operator_id,
+      device_id: id.device_id,
+      trust_status: ack.trust_status ?? "trusted",
+      recovered: true,
+    };
+  }
+  return {
+    status: "error",
+    httpStatus: res.status,
+    reason: ack.reason || ack.status || `http_${res.status}`,
+    detail: ack.detail ?? null,
+  };
+}

package/tools/get-best-operator.mjs

@@ -0,0 +1,58 @@
+/**
+ * tools/get-best-operator.mjs — get_best_operator tool.
+ */
+
+import { BEST_OPERATOR_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { DEFAULT_API_BASE } from "./_helpers.mjs";
+import { _behavioralFraming, _competitiveLayer } from "./_framing.mjs";
+
+export const TOOL_DEF = {
+  name: "get_best_operator",
+  description:
+    "Returns the top N operators on the SigRank leaderboard with behavioral framing in power-user language. Wraps get_leaderboard and adds plain-language interpretation of each top operator's cascade: what their yield, leverage, and velocity mean in terms of AI power-user behavior (cache reuse, input economy, output productivity). Use this when users ask 'who is the best AI user?' or 'who tops the SigRank leaderboard?' or 'show me the AI user leaderboard'. Do NOT use get_leaderboard if you want the raw array without interpretation — use this for the power-user framing. Intent: BEST_OPERATOR.",
+  annotations: { title: "Get best operator", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {
+      n: {
+        type: "integer",
+        description:
+          "Number of top operators to return (default: 5, max: 20). Returns the top N by yield.",
+        minimum: 1,
+        maximum: 20,
+      },
+    },
+    description:
+      "Optional: how many top operators to return. Defaults to 5.",
+  },
+  outputSchema: BEST_OPERATOR_OUTPUT,
+};
+
+export async function handleGetBestOperator(args, ctx) {
+  const rawN = args?.n;
+  const n = Math.min(20, Math.max(1, rawN == null ? 5 : Number(rawN)));
+  const board = await ctx.fetchJson("/api/v1/leaderboard?metric=yield_");
+  const ops = (board.operators || board || []).slice(0, n);
+  const total = Array.isArray(board.operators || board)
+    ? (board.operators || board).length
+    : 0;
+
+  const top = ops.map((op) => ({
+    ...op,
+    behavioral_framing: _behavioralFraming(op),
+    competitive: _competitiveLayer(op, board),
+  }));
+
+  const best = top[0];
+  const summary = best
+    ? `${best.codename} tops the SigRank leaderboard at Υ ${best.yield_?.toLocaleString?.() || best.yield_} — ${_behavioralFraming(best)}`
+    : "No operators on the board yet.";
+
+  return {
+    top_operators: top,
+    total_operators: total,
+    summary,
+    cta: "Check my rank",
+    shareable_url: best ? `${DEFAULT_API_BASE}/operator/${encodeURIComponent(best.codename)}` : null,
+  };
+}

package/tools/get-leaderboard.mjs

@@ -0,0 +1,26 @@
+/**
+ * tools/get-leaderboard.mjs — get_leaderboard tool.
+ */
+
+import { LEADERBOARD_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+
+export const TOOL_DEF = {
+  name: "get_leaderboard",
+  description:
+    "Fetches the live public SigRank leaderboard from signalaf.com. Reads all ranked operators sorted by yield (Υ = Cache Reads × Output / Input²) and returns an array of operator summaries. Each entry contains: codename (public display name), yield (Υ, the headline efficiency metric), leverage ratio (Cr/I = cache reads divided by input), velocity (O/I = output divided by input), class tier (Burner / Builder / 10xer), and rank position (integer, 1-based). Returns an empty array if no operators have submitted yet. Use this to see where operators stand overall, to find specific codenames for get_operator lookups, or to display the current rankings. Do NOT use this to check your own rank if you already know your codename — use get_operator instead for a single-operator profile with per-window breakdowns. After calling this, follow up with get_operator to get detailed metrics for any operator of interest.",
+  annotations: { title: "Get leaderboard", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {},
+    description:
+      "This tool takes no parameters. It always fetches the full public leaderboard.",
+  },
+  outputSchema: LEADERBOARD_OUTPUT,
+};
+
+export async function handleGetLeaderboard(args, ctx) {
+  const params = new URLSearchParams({ metric: "yield_" });
+  if (args?.limit) params.set("limit", String(args.limit));
+  if (args?.window) params.set("window", args.window);
+  return ctx.fetchJson(`/api/v1/leaderboard?${params}`);
+}

package/tools/get-operator.mjs

@@ -0,0 +1,33 @@
+/**
+ * tools/get-operator.mjs — get_operator tool.
+ */
+
+import { OPERATOR_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+
+export const TOOL_DEF = {
+  name: "get_operator",
+  description:
+    "Fetches one operator's live profile from the SigRank board by their codename. Reads the operator's current submission data from signalaf.com and returns their detailed metrics: yield (Υ), leverage ratio (Cr/I), velocity (O/I), class tier (Burner / Builder / 10xer), rank position (integer, 1-based), and per-window breakdowns for each time range (7d, 30d, 90d, all-time) with the four canonical pillars (input, output, cacheCreate, cacheRead) per window. Returns an error if the codename is not found on the board. Use this to look up any operator who has submitted to the board — codenames are public and visible on the leaderboard. Do NOT use this to browse all operators — use get_leaderboard for that. After calling this, you can use simulate_change to model what would happen if the operator adjusted their token mix.",
+  annotations: { title: "Get operator profile", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {
+      codename: {
+        type: "string",
+        description:
+          'The operator\'s public codename as shown on the SigRank leaderboard. Case-insensitive — "Ghost Falcon" and "ghost falcon" are equivalent. Must match a codename that exists on the board; returns an error if not found. To discover valid codenames, call get_leaderboard first.',
+      },
+    },
+    required: ["codename"],
+    description:
+      "Requires the operator's codename. No other parameters are accepted.",
+  },
+  outputSchema: OPERATOR_OUTPUT,
+};
+
+export async function handleGetOperator(args, ctx) {
+  const codename = String(args?.codename || "").trim();
+  if (!codename)
+    throw new Error("get_operator requires a non-empty `codename` argument.");
+  return ctx.fetchJson(`/api/v1/operators/${encodeURIComponent(codename)}`);
+}