sigrank 0.18.5 → 1.0.1

package/tools/enroll.mjs

@@ -0,0 +1,119 @@
+/**
+ * tools/enroll.mjs — enroll tool.
+ */
+
+import os from "node:os";
+import { ensureIdentity, recordEnrollment } from "../identity/keystore.mjs";
+import { ENROLL_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { TERMS_VERSION, PRIVACY_VERSION } from "../lib/constants.mjs";
+
+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,59 @@
+/**
+ * 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";
+import { LEADERBOARD_METRIC } from "../lib/constants.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=${LEADERBOARD_METRIC}`);
+  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,27 @@
+/**
+ * tools/get-leaderboard.mjs — get_leaderboard tool.
+ */
+
+import { LEADERBOARD_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { LEADERBOARD_METRIC } from "../lib/constants.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 (one of 24 experience stages: 8 tiers × 3 sub-stages, e.g. ARCH+ I, REFINER II, IGNITER III), 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: LEADERBOARD_METRIC });
+  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 (one of 24 experience stages: 8 tiers × 3 sub-stages, e.g. ARCH+ I, REFINER II, IGNITER III), 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)}`);
+}

package/tools/index.mjs

@@ -0,0 +1,229 @@
+/**
+ * tools/index.mjs — the SigRank MCP tool table + dispatcher, transport-free so it can be
+ * unit-tested without spawning the stdio server.
+ *
+ * Imports individual tool modules from ./ and re-exports the TOOLS array + callTool
+ * dispatcher. Backward-compatible root import via ../tools.mjs (shim).
+ */
+
+import { ALL_PLATFORMS } from "../adapters/index.mjs";
+import { execFileAsync } from "./_helpers.mjs";
+import { buildFetch, DEFAULT_API_BASE, DEFAULT_FETCH_TIMEOUT } from "./_helpers.mjs";
+import {
+  TOKSCALE_CLIENT_MAP,
+  TOKSCALE_BLIND_PLATFORMS,
+} from "../lib/constants.mjs";
+
+import { TOOL_DEF as rankPasteTool, handleRankPaste } from "./rank-paste.mjs";
+import { TOOL_DEF as getLeaderboardTool, handleGetLeaderboard } from "./get-leaderboard.mjs";
+import { TOOL_DEF as getOperatorTool, handleGetOperator } from "./get-operator.mjs";
+import { TOOL_DEF as submitPasteTool, handleSubmitPaste } from "./submit-paste.mjs";
+import { TOOL_DEF as tokenpullTool, handleTokenpull } from "./tokenpull.mjs";
+import { TOOL_DEF as tokenpullSubmitTool, handleTokenpullSubmit } from "./tokenpull-submit.mjs";
+import { TOOL_DEF as rankWindowsTool, handleRankWindows } from "./rank-windows.mjs";
+import { TOOL_DEF as watchTokenpullTool, handleWatchTokenpull } from "./watch-tokenpull.mjs";
+import { TOOL_DEF as tokenpullCompareTool, handleTokenpullCompare } from "./tokenpull-compare.mjs";
+import { TOOL_DEF as enrollTool, handleEnroll } from "./enroll.mjs";
+import { TOOL_DEF as submitVerifiedTool, handleSubmitVerified } from "./submit-verified.mjs";
+import { TOOL_DEF as simulateChangeTool, handleSimulateChange } from "./simulate-change.mjs";
+import { TOOL_DEF as diagnoseCascadeTool, handleDiagnoseCascade } from "./diagnose-cascade.mjs";
+import { TOOL_DEF as suggestImprovementsTool, handleSuggestImprovements } from "./suggest-improvements.mjs";
+import { TOOL_DEF as selfImproveTool, handleSelfImprove } from "./self-improve.mjs";
+import { TOOL_DEF as discoverPeersTool, handleDiscoverPeers } from "./discover-peers.mjs";
+// NOTE: get_best_operator, compare_self, compare_operators, describe_power_user,
+// and optimize_efficiency were moved to bestuser-router-mcp (the marketing layer).
+// They are duplicated there with richer params (metric sorting, platform filters,
+// local text scoring). sigrank-mcp stays focused on local pulling + scoring +
+// submission + tokscale analytics.
+import { TOOL_DEF as tokscaleBreakdownTool, handleTokscaleBreakdown } from "./tokscale-breakdown.mjs";
+import { TOOL_DEF as tokscaleMarketShareTool, handleTokscaleMarketShare } from "./tokscale-market-share.mjs";
+import { TOOL_DEF as tokscaleDeveloperProfileTool, handleTokscaleDeveloperProfile } from "./tokscale-developer-profile.mjs";
+import { TOOL_DEF as tokscaleModelTrendsTool, handleTokscaleModelTrends } from "./tokscale-model-trends.mjs";
+import { TOOL_DEF as tokscaleCostAnalysisTool, handleTokscaleCostAnalysis } from "./tokscale-cost-analysis.mjs";
+import { TOOL_DEF as tokscaleDeviceProfileTool, handleTokscaleDeviceProfile } from "./tokscale-device-profile.mjs";
+import { TOOL_DEF as tokscaleMcpUsageTool, handleTokscaleMcpUsage } from "./tokscale-mcp-usage.mjs";
+import { TOOL_DEF as tokscaleCompetitiveIntelTool, handleTokscaleCompetitiveIntel } from "./tokscale-competitive-intel.mjs";
+
+export { DEFAULT_API_BASE, DEFAULT_FETCH_TIMEOUT };
+
+export const TOOLS = [
+  rankPasteTool,
+  getLeaderboardTool,
+  getOperatorTool,
+  submitPasteTool,
+  tokenpullTool,
+  tokenpullSubmitTool,
+  rankWindowsTool,
+  watchTokenpullTool,
+  tokenpullCompareTool,
+  enrollTool,
+  submitVerifiedTool,
+  simulateChangeTool,
+  diagnoseCascadeTool,
+  suggestImprovementsTool,
+  selfImproveTool,
+  discoverPeersTool,
+  // get_best_operator, compare_self, compare_operators, describe_power_user,
+  // optimize_efficiency → moved to bestuser-router-mcp
+  tokscaleBreakdownTool,
+  tokscaleMarketShareTool,
+  tokscaleDeveloperProfileTool,
+  tokscaleModelTrendsTool,
+  tokscaleCostAnalysisTool,
+  tokscaleDeviceProfileTool,
+  tokscaleMcpUsageTool,
+  tokscaleCompetitiveIntelTool,
+];
+
+// TOKSCALE_CLIENT_MAP is imported from lib/constants.mjs (single source of
+// truth — was duplicated in tools/tokscale-breakdown.mjs and
+// tokscale_analytics.mjs, and the copies had started to drift).
+
+/** Run `tokscale models --json` and return the list of our platform names. */
+async function _tokscaleDetectClients() {
+  const raw = await execFileAsync("tokscale", ["models", "--json"], 60000);
+  const data = JSON.parse(raw);
+  const entries = Array.isArray(data?.entries)
+    ? data.entries
+    : Array.isArray(data)
+      ? data
+      : [];
+  if (!entries.length) return [];
+  const clients = new Set();
+  for (const e of entries) {
+    if (!e || !e.client) continue;
+    if (e.model === "<synthetic>" || e.model === "unknown") continue;
+    const input = Number(e.input) || 0;
+    const output = Number(e.output) || 0;
+    if (input + output === 0) continue;
+    const platform = TOKSCALE_CLIENT_MAP[e.client];
+    if (platform === null) continue; // synthetic → skip
+    clients.add(platform || "other");
+  }
+  return [...clients];
+}
+
+/** Detection targets = what tokscale saw ∪ the platforms tokscale is blind to.
+ *  Without the union, an operator with GBs of oh-my-pi telemetry gets no omp row
+ *  on any machine where tokscale succeeds, because tokscale never names that
+ *  client. Pure + exported so the union is unit-testable without shelling out. */
+export function withTokscaleBlind(detected) {
+  return [...new Set([...(detected || []), ...TOKSCALE_BLIND_PLATFORMS])];
+}
+
+/** Pull a specific set of platforms in parallel, filter to active ones.
+ *  opts.callTool overrides the per-platform pull for tests (same opts-injection
+ *  convention as opts.adapter in pullByPlatform) so the target-set logic is
+ *  assertable without a real filesystem scan. */
+async function _pullExplicit(platforms, opts = {}) {
+  const pull = opts.callTool || callTool;
+  const settled = await Promise.allSettled(
+    platforms.map((p) => pull("tokenpull", { platform: p }, opts)),
+  );
+  const active = settled
+    .filter((r) => r.status === "fulfilled" && r.value)
+    .map((r) => r.value)
+    .filter((d) =>
+      (d.windows || []).some(
+        (w) => (w.pillars?.input ?? 0) + (w.pillars?.output ?? 0) > 0,
+      ),
+    );
+  const rank = (p) =>
+    p === "claude" ? -2 : p === "codex" ? -1 : ALL_PLATFORMS.indexOf(p);
+  active.sort((a, b) => rank(a.platform) - rank(b.platform));
+  return active;
+}
+
+// ── Shared active-platform loader ───────────────────────────────────────────
+// THE single data path for "show my cascade across platforms" — used by `me`,
+// `watch`, and the TUI Dashboard so they can't drift apart again. Pulls each
+// target platform via the tokenpull tool (enriched: pillars + cascade + card),
+// keeps only platforms with real local data, and sorts claude → codex → rest.
+// Pass `platforms` to scope it (e.g. ['claude'] for a fast first paint).
+export async function pullActivePlatforms({ platforms } = {}, opts = {}) {
+  // If the caller specified explicit platforms, use those.
+  if (platforms && platforms.length) {
+    return _pullExplicit(platforms, opts);
+  }
+  // Auto-detect: run tokscale once to discover all active clients, then pull
+  // only those (plus the tokscale-blind platforms). This is much faster than trying
+  // all adapters (most fail silently on a machine that doesn't have that tool).
+  //
+  // Flow: tokscale surfaces ALL clients → map to our platform names →
+  // ccusage is primary for Claude (more accurate) → other platforms use
+  // their adapters. Anything in tokscale NOT in ccusage gets included.
+  // opts.detectClients overrides the tokscale probe for tests (no shelling out).
+  const detect = opts.detectClients || _tokscaleDetectClients;
+  const detected = await detect().catch(() => null);
+  if (detected && detected.length > 0) {
+    return _pullExplicit(withTokscaleBlind(detected), opts);
+  }
+  // Fallback: tokscale not installed or failed → try all adapters (old behavior)
+  return _pullExplicit(ALL_PLATFORMS, opts);
+}
+
+export async function callTool(name, args, opts = {}) {
+  const { apiBase, doFetch, fetchJson } = buildFetch(opts);
+  const ctx = {
+    apiBase,
+    doFetch,
+    fetchJson,
+    opts,
+    callTool: (n, a) => callTool(n, a, opts),
+  };
+
+  switch (name) {
+    case "rank_paste":
+      return handleRankPaste(args);
+    case "get_leaderboard":
+      return handleGetLeaderboard(args, ctx);
+    case "get_operator":
+      return handleGetOperator(args, ctx);
+    case "submit_paste":
+      return handleSubmitPaste(args, ctx);
+    case "tokenpull":
+      return handleTokenpull(args, ctx);
+    case "tokenpull_submit":
+      return handleTokenpullSubmit(args, ctx);
+    case "rank_windows":
+      return handleRankWindows(args);
+    case "watch_tokenpull":
+      return handleWatchTokenpull(args, ctx);
+    case "tokenpull_compare":
+      return handleTokenpullCompare(args, ctx);
+    case "enroll":
+      return handleEnroll(args, ctx);
+    case "submit_verified":
+      return handleSubmitVerified(args, ctx);
+    case "simulate_change":
+      return handleSimulateChange(args);
+    case "diagnose_cascade":
+      return handleDiagnoseCascade(args);
+    case "suggest_improvements":
+      return handleSuggestImprovements(args);
+    case "self_improve":
+      return handleSelfImprove(args, ctx);
+    case "discover_peers":
+      return handleDiscoverPeers(args, ctx);
+    // get_best_operator, compare_self, compare_operators, describe_power_user,
+    // optimize_efficiency → moved to bestuser-router-mcp
+    case "tokscale_breakdown":
+      return handleTokscaleBreakdown(args);
+    case "tokscale_market_share":
+      return handleTokscaleMarketShare();
+    case "tokscale_developer_profile":
+      return handleTokscaleDeveloperProfile();
+    case "tokscale_model_trends":
+      return handleTokscaleModelTrends();
+    case "tokscale_cost_analysis":
+      return handleTokscaleCostAnalysis();
+    case "tokscale_device_profile":
+      return handleTokscaleDeviceProfile();
+    case "tokscale_mcp_usage":
+      return handleTokscaleMcpUsage();
+    case "tokscale_competitive_intel":
+      return handleTokscaleCompetitiveIntel(args);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}

package/tools/optimize-efficiency.mjs

@@ -0,0 +1,170 @@
+/**
+ * tools/optimize-efficiency.mjs — optimize_efficiency tool.
+ */
+
+import { cascade, parsePillars } from "../analytics/cascade.mjs";
+import { ANNOTATIONS, CLASS_ENUM } from "./_schemas.mjs";
+import { MAX_INPUT, withParseWarnings } from "./_helpers.mjs";
+import { LEADERBOARD_METRIC } from "../lib/constants.mjs";
+import {
+  _improvementSuggestion,
+  _competitiveLayer,
+  _competitiveSummary,
+  FALLBACK_CLASS,
+  bandOf,
+} from "./_framing.mjs";
+
+export const TOOL_DEF = {
+  name: "optimize_efficiency",
+  description:
+    "Returns actionable suggestions for improving your token cascade efficiency, tied to your current metrics. Accepts either a codename (fetches from board) or raw token pillars (computes locally). Returns: your current metrics, ranked efficiency suggestions tied to cascade shape (increase cache reuse, reduce input, increase output), and references to power-user practices. Use this when users ask 'how can I use AI more efficiently?' or 'reduce token burn' or 'optimize token usage' or 'stop tokenmaxxing'. Intent: OPTIMIZE_EFFICIENCY (Informational + Transactional).",
+  annotations: { title: "Optimize efficiency", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint },
+  inputSchema: {
+    type: "object",
+    properties: {
+      codename: {
+        type: "string",
+        description:
+          "Your codename on the SigRank leaderboard. If provided, fetches your live profile from the board.",
+      },
+      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.',
+      },
+    },
+    description:
+      "Provide either `codename` (to fetch from the board) or `text` (to score locally). At least one is required.",
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      your_metrics: {
+        type: "object",
+        description: "Your current cascade metrics",
+        properties: {
+          yield_: { type: "number" },
+          leverage: { type: "number" },
+          velocity: { type: "number" },
+          class: { type: "string", enum: CLASS_ENUM },
+        },
+      },
+      suggestions: {
+        type: "array",
+        description: "Ranked efficiency suggestions",
+        items: {
+          type: "object",
+          properties: {
+            action: { type: "string", description: "What to change" },
+            why: { type: "string", description: "Why this helps your yield" },
+            power_user_practice: { type: "string", description: "The power-user practice this maps to" },
+          },
+        },
+      },
+      summary: { type: "string", description: "One-line summary of your efficiency status" },
+    },
+  },
+};
+
+export async function handleOptimizeEfficiency(args, ctx) {
+  const codename = String(args?.codename || "").trim();
+  const text = String(args?.text || "").trim();
+
+  if (!codename && !text)
+    throw new Error(
+      "optimize_efficiency requires either `codename` (to fetch from the board) or `text` (raw token pillars to score locally).",
+    );
+
+  let metrics;
+  if (codename) {
+    metrics = 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));
+    metrics = {
+      codename: "you (local)",
+      yield_: c.yield,
+      leverage: c.leverage,
+      velocity: c.velocity,
+      class: c.class,
+    };
+  }
+
+  const klass = metrics.class || FALLBACK_CLASS;
+  const l = metrics.leverage || 0;
+  const v = metrics.velocity || 0;
+  const y = metrics.yield_ || 0;
+
+  // Build ranked suggestions based on current cascade shape
+  const suggestions = [];
+
+  if (l < 5) {
+    suggestions.push({
+      action: "Increase cache reuse — reuse prompts, templates, and workflows instead of starting from scratch",
+      why: "Your leverage is " + l.toFixed(1) + "×, meaning most of your context is fresh input. Each reused cached token multiplies your yield because input² is in the denominator.",
+      power_user_practice: "Power users build template libraries and workflow patterns they invoke repeatedly, letting cached context accumulate.",
+    });
+  }
+  if (v < 1) {
+    suggestions.push({
+      action: "Increase output per session — produce more, don't just read",
+      why: "Your velocity is " + v.toFixed(2) + ", meaning you're consuming more input than producing output. Yield rewards output production.",
+      power_user_practice: "Power users maximize output per session — they ask AI to generate, transform, and produce, not just explain.",
+    });
+  }
+  // Top-band tiers (apex/high) already have leverage + velocity — the
+  // "extend session" suggestion is for mid/early/entry operators whose
+  // leverage and velocity are both solid but not yet at the top. The legacy
+  // `klass !== "10xer"` guard never matched because the classifier emits the
+  // 8-tier dev10x names, not "10xer" — so this branch fired for EVERY
+  // operator including top-tier ones. Now keyed off the canonical bands.
+  const TOP_BANDS = new Set(["apex", "high"]);
+  if (l >= 5 && v >= 1 && !TOP_BANDS.has(bandOf(klass))) {
+    suggestions.push({
+      action: "Extend session length to compound cached context further",
+      why: "Your leverage (" + l.toFixed(1) + "×) and velocity (" + v.toFixed(2) + ") are solid. Longer sessions with consistent context will push your yield higher.",
+      power_user_practice: "Power users maintain long, context-rich sessions where the cache grows and compounds.",
+    });
+  }
+  if (suggestions.length === 0) {
+    suggestions.push({
+      action: "Maintain your cascade architecture — you're at the top tier",
+      why: "Your yield (" + y.toLocaleString() + "), leverage (" + l.toFixed(1) + "×), and velocity (" + v.toFixed(2) + ") are all strong. Keep doing what you're doing.",
+      power_user_practice: "Power users don't rest on their metrics — they experiment with new workflow patterns and measure the impact.",
+    });
+  }
+
+  const summary = `Your Υ Yield is ${y.toLocaleString()} (${klass}). ${_improvementSuggestion(klass, metrics)}`;
+
+  // Competitive layer per SHARED_DESIGN_DECISIONS.md §3/§4/§5
+  const board = await ctx.fetchJson(`/api/v1/leaderboard?metric=${LEADERBOARD_METRIC}`);
+  const competitive = _competitiveLayer(metrics, board);
+  const competitiveSummary = _competitiveSummary(metrics, board);
+
+  return {
+    your_metrics: {
+      yield_: y,
+      leverage: l,
+      velocity: v,
+      class: klass,
+    },
+    competitive: {
+      rank: competitive.rank,
+      total_operators: competitive.total_operators,
+      percentile: competitive.percentile,
+      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,
+    suggestions,
+    summary,
+    cta: "Improve my score",
+  };
+}