sigrank 0.0.176 → 0.0.178

package/README.md

@@ -66,10 +66,17 @@ For all builders, burners and 10xers.
 | **[sigrank-vscode](https://github.com/SunrisesIllNeverSee/sigrank-vscode)** | The IDE extension — see your cascade metrics inline in VS Code. | `code --install-extension sigrank.sigrank` |
 | **[fundscore](https://github.com/SunrisesIllNeverSee/fundscore)** | The repo scorer — investor-readiness scoring for GitHub repos. CLI + MCP server. | `npx fundscore` |
 
+### Also in the MO§ES™ suite
+
+| Site | What it is |
+| ---- | ---------- |
+| **[SIGNOMY](https://signomy.xyz)** | Governed AI agent marketplace where ranked agents form teams, fill slots, run missions, and earn revenue under constitutional protocol. Agents are free. Operators pay. |
+| **[MO§ES](https://mos2es.com)** | The governance framework that underpins SigRank, SIGNOMY, and all governed agent operations. Structural accountability for agentic systems. |
+
 ## Quickstart — 3 steps to the board
 
 ```bash
-# 1. Install (pulls ccusage + tokscale + tokendash automatically — no separate installs)
+# 1. Install (pulls ccusage + tokscale automatically — no separate installs)
 npm install -g sigrank
 
 # 2. Sign in (paste a connect code from signalaf.com → Settings → New key)
@@ -147,7 +154,7 @@ smithery tool call sigrank rank_paste '{"text": "1000000 500000 50000 800000"}'
 ## Commands
 
 ```
-⊙ SigRank CLI  v0.0.176
+⊙ SigRank CLI  v0.0.177
 
 Default (no args)
   sigrank              unified dashboard: cascade + token pillars + board
@@ -296,10 +303,10 @@ The dashboard pulls from multiple sources and shows them side-by-side for verifi
 | ----------------- | ------------------------------------------------------------------------------ | --------------------- |
 | `tokenpull`       | On-device JSONL scanner (canon source)                                         | claude, codex, amp, … |
 | `ccusage`         | `ccusage <platform> daily --json` CLI (bundled)                                | claude, codex         |
-| `token-dashboard` | `~/.claude/token-dashboard.db` SQLite (bundled)                                | claude only           |
+| `token-dashboard` | `~/.claude/token-dashboard.db` SQLite ([Nate's](https://github.com/nateherkai/token-dashboard)) | claude only           |
 | `tokscale`        | `tokscale models --json` CLI (bundled, falls back to `~/tokscale_report.json`) | claude, codex         |
 
-**Codex input is estimated** — Codex logs don't expose true input tokens directly. The formula:
+**Non-Claude input is estimated** — most non-Claude systems (Codex, Devin, etc.) combine user input + cache write into a single `input_tokens` field, so true fresh input must be derived. The ruleset (applies to ALL non-Claude systems):
 
 ```
 input       = output × ioRatio         (ioRatio derived from Claude ratio, else 2.0)
@@ -307,6 +314,10 @@ cacheCreate = uncached − input         (uncached = input_tokens − cached_inp
 cacheRead   = exact (from logs)
 ```
 
+- **Beta** = operator's Claude input/output ratio (if Claude data available)
+- **Alpha** = 2.0 default (when no Claude data)
+- Owner-stated average: 7:1:2 (cache:input:output) → input/output ≈ 0.5
+
 Verifier numbers (ccusage/tokscale for codex) show **raw uncached input** (`input_tokens − cached`) — a different field than the estimated input above. The discrepancy is expected and explained inline in the dashboard.
 
 ---
@@ -319,6 +330,7 @@ All adapters are token-only (no message content, no cost fields, no credentials)
 | ------------------ | ---------------------------------------------- | --------------------------------------------------------------- |
 | Claude Code        | ✅ `~/.claude/projects`                        | Native; dedup by `(session_id, message_id)`; subagents included |
 | Codex              | ✅ `~/.codex/sessions`                         | Estimated input via `io_ratio`; verified vs ccusage             |
+| Devin CLI          | ✅ `~/.local/share/devin/cli/sessions.db`      | Estimated input via `io_ratio`; SQLite; same split as Codex     |
 | Amp                | ✅ `~/.local/share/amp/threads`                | Full 4-pillar; per-message                                      |
 | Kimi               | ✅ `~/.kimi/sessions`                          | Full 4-pillar; `StatusUpdate` lines only                        |
 | pi-agent           | ✅ `~/.pi/agent/sessions`                      | Full 4-pillar; per-message JSONL                                |

package/adapters.mjs

@@ -15,6 +15,14 @@
  *   messages(root): async generator → { id?, sid?, ts, input, output, cacheCreate, cacheRead, file }
  *
  * SigRank-specific mapping rules (applied consistently across all adapters):
+ *   - Claude = parsed natively (4 pillars exact, no conversion)
+ *   - Non-Claude systems = combined input → split via ioRatio:
+ *       input = floor(output × ioRatio)     // Beta from Claude, else Alpha 2.0
+ *       cacheCreate = max(0, uncached − input)
+ *       cacheRead = exact
+ *     (Adapters that yield {ts, output, cacheRead, uncached} via records() go through
+ *      tokenpullCodex(); adapters that yield native 4-pillar via messages() go through
+ *      tokenpull() directly. The split happens at the tokenpullAny() routing layer.)
  *   - Reasoning / thinking tokens → folded into `output` (they are output-side spend)
  *   - No cache-creation data available → cacheCreate: 0 + adapter sets `estimated: true`
  *   - Cost fields (USD) → NEVER used or forwarded (SigRank scores cost efficiency from
@@ -97,10 +105,11 @@ function* parseJsonl(text, filePath) {
 /** Run sqlite3 -json and return parsed rows, or [] on error/unavailability.
  *  execFile with an args array — no shell, so dbPath/sql need no quoting/escaping
  *  (matches the execFile hardening used in tools.mjs / tokenpull.mjs). */
-async function sqliteJson(dbPath, sql) {
+async function sqliteJson(dbPath, sql, timeoutMs = 10_000) {
   try {
     const { stdout } = await execFileP("sqlite3", ["-json", dbPath, sql], {
-      timeout: 10_000,
+      timeout: timeoutMs,
+      maxBuffer: 256 * 1024 * 1024, // 256MB — Devin's sessions.db yields ~15MB JSON
     });
     return JSON.parse(stdout || "[]");
   } catch {
@@ -729,6 +738,110 @@ export const hermesAdapter = {
   },
 };
 
+// ── 14. Devin CLI ────────────────────────────────────────────────────────────
+// SQLite: ~/.local/share/devin/cli/sessions.db
+// Same combined-input problem as Codex: input_tokens INCLUDES cache write, so we
+// yield { ts, output, cacheRead, uncached } and let tokenpullCodex() do the
+// ioRatio split (input = output × ioRatio, cacheCreate = uncached − input).
+// ioRatio comes from Claude (Beta) or the 7:1:2 average (Alpha = 0.5).
+export const devinAdapter = {
+  platform: "devin",
+  defaultRoot: () => join(homedir(), ".local", "share", "devin", "cli"),
+  async *records(root) {
+    for (const r of roots("DEVIN_HOME", root)) {
+      const dbPath = join(r, "sessions.db");
+      const rows = await sqliteJson(
+        dbPath,
+        `SELECT row_id, session_id,
+                json_extract(chat_message, '$.metadata.metrics.input_tokens') as input_tokens,
+                json_extract(chat_message, '$.metadata.metrics.output_tokens') as output_tokens,
+                json_extract(chat_message, '$.metadata.metrics.cache_read_tokens') as cache_read_tokens,
+                json_extract(chat_message, '$.metadata.created_at') as created_at
+         FROM message_nodes
+         WHERE json_extract(chat_message, '$.role') = 'assistant'
+           AND json_extract(chat_message, '$.metadata.metrics.input_tokens') IS NOT NULL
+         ORDER BY created_at`,
+        60_000,
+      );
+      for (const row of rows) {
+        const inputIncl = Number(row.input_tokens || 0);
+        const cached = Number(row.cache_read_tokens || 0);
+        const output = Number(row.output_tokens || 0);
+        if (inputIncl + output + cached === 0) continue;
+        yield {
+          ts: row.created_at || null,
+          output,
+          cacheRead: cached,
+          uncached: Math.max(0, inputIncl - cached),
+          file: dbPath,
+        };
+      }
+    }
+  },
+};
+
+// ── 15. Other (user-supplied JSON) ───────────────────────────────────────────
+// For platforms/models not yet on the adapter list. The user writes a JSON file
+// with the 4 pillars per window and points SIGRANK_OTHER_PATH at it. This lets
+// anyone with a new tool submit without needing a custom adapter.
+//
+// JSON format (all fields optional, missing windows are skipped):
+// {
+//   "platform": "my-tool",           // optional, defaults to "other"
+//   "windows": {
+//     "all":  { "input": 1000, "output": 2000, "cacheCreate": 500, "cacheRead": 8000 },
+//     "30d":  { "input":  500, "output": 1000, "cacheCreate": 200, "cacheRead": 4000 },
+//     "7d":   { "input":  100, "output":  200, "cacheCreate":  50, "cacheRead":  800 }
+//   }
+// }
+//
+// The adapter yields one "message" per window with the summed pillars. Since
+// there's no per-message timestamp, all data lands in the "all" window only
+// (same as null-timestamp records in other adapters).
+export const otherAdapter = {
+  platform: "other",
+  defaultRoot: () => process.env.SIGRANK_OTHER_PATH || "",
+  async *messages(root) {
+    const filePath = root || process.env.SIGRANK_OTHER_PATH;
+    if (!filePath) {
+      throw new Error(
+        "other adapter: set SIGRANK_OTHER_PATH to a JSON file with your token pillars. " +
+          'Format: { "windows": { "all": { "input": N, "output": N, "cacheCreate": N, "cacheRead": N } } }',
+      );
+    }
+    let text;
+    try {
+      text = await readFile(filePath, "utf8");
+    } catch {
+      throw new Error(`other adapter: cannot read ${filePath} — check SIGRANK_OTHER_PATH`);
+    }
+    let data;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      throw new Error(`other adapter: invalid JSON in ${filePath}`);
+    }
+    const windows = data.windows || {};
+    for (const [win, pillars] of Object.entries(windows)) {
+      const input = Number(pillars.input || 0);
+      const output = Number(pillars.output || 0);
+      const cacheCreate = Number(pillars.cacheCreate || pillars.cache_create || 0);
+      const cacheRead = Number(pillars.cacheRead || pillars.cache_read || 0);
+      if (input + output + cacheCreate + cacheRead === 0) continue;
+      yield {
+        id: `other:${win}`,
+        sid: `other-${win}`,
+        ts: null, // no timestamp → lands in "all" window only
+        input,
+        output,
+        cacheCreate,
+        cacheRead,
+        file: filePath,
+      };
+    }
+  },
+};
+
 // ── Registry ──────────────────────────────────────────────────────────────────
 /** All non-Claude, non-Codex adapters keyed by platform ID. */
 export const ADAPTERS = {
@@ -745,6 +858,8 @@ export const ADAPTERS = {
   goose: gooseAdapter,
   kilo: kiloAdapter,
   hermes: hermesAdapter,
+  devin: devinAdapter,
+  other: otherAdapter,
 };
 
 export const ALL_PLATFORMS = Object.keys(ADAPTERS).concat(["claude", "codex"]);

package/cli.mjs

@@ -236,7 +236,10 @@ async function fetchBoard(window = "30d") {
   const res = await fetch(
     `${DEFAULT_API_BASE}/api/v1/leaderboard?window=${window}&metric=yield_`,
     {
-      headers: { accept: "application/json" },
+      headers: {
+        accept: "application/json",
+        "user-agent": `node/${process.version} sigrank-mcp/cli`,
+      },
     },
   );
   if (!res.ok) throw new Error(`Board API → HTTP ${res.status}`);
@@ -491,7 +494,7 @@ function appPillars() {
 async function tokenDashPillars() {
   const dbPath = path.join(os.homedir(), ".claude", "token-dashboard.db");
   if (!existsSync(dbPath)) return null;
-  // Read directly with sqlite3 — no python script needed (bundled dep).
+  // Read directly with sqlite3 — DB created by Nate's token-dashboard (github.com/nateherkai/token-dashboard).
   // Windowed queries using sqlite3's datetime() function.
   const cf =
     "(model LIKE '%claude%' OR model LIKE '%fable%' OR model LIKE '%sonnet%' OR model LIKE '%opus%' OR model LIKE '%haiku%')";
@@ -934,6 +937,7 @@ async function runWatch({
 const ALL_PLATFORMS = [
   "claude",
   "codex",
+  "devin",
   "amp",
   "gemini",
   "kimi",
@@ -944,8 +948,10 @@ const ALL_PLATFORMS = [
   "droid",
   "codebuff",
   "copilot",
+  "opencode",
   "openclaw",
   "pi",
+  "other",
 ];
 
 async function runSigRank() {
@@ -1472,6 +1478,7 @@ async function runSigRank() {
                       headers: {
                         "content-type": "application/json",
                         accept: "application/json",
+                        "user-agent": `node/${process.version} sigrank-mcp/cli`,
                       },
                       body: JSON.stringify({
                         codename,

package/index.mjs

@@ -194,7 +194,7 @@ async function startMcpServer() {
       uri: "sigrank://install-guide",
       name: "Quick Start Guide",
       description:
-        "Step-by-step install and first submission: npx sigrank → enroll → submit. Covers ccusage/tokscale/tokendash bundled deps, privacy model (token counts only, never prompts), and dry-run workflow.",
+        "Step-by-step install and first submission: npx sigrank → enroll → submit. Covers ccusage/tokscale bundled deps + token-dashboard (Nate's, github.com/nateherkai/token-dashboard), privacy model (token counts only, never prompts), and dry-run workflow.",
       mimeType: "text/markdown",
     },
     {
@@ -289,14 +289,20 @@ No global install needed. The MCP server starts automatically when an AI client
    npx sigrank submit --dry-run
    \`\`\`
 
-## Token Pull Sources (bundled)
+## Token Pull Sources
 
-SigRank bundles three token readers as dependencies:
+SigRank bundles two token readers as npm dependencies:
 - **ccusage** — Claude Code session logs
 - **tokscale** — multi-platform token telemetry
-- **tokendash** — dashboard + TUI for token usage
 
-No separate install needed. All three are called automatically by the tokenpull tools.
+A third source, **token-dashboard**, is read from \`~/.claude/token-dashboard.db\` (SQLite).
+That DB is created by [Nate's token-dashboard](https://github.com/nateherkai/token-dashboard) (Python):
+\`\`\`bash
+git clone https://github.com/nateherkai/token-dashboard.git
+cd token-dashboard
+python3 cli.py dashboard
+\`\`\`
+Run the scan once to create the DB; SigRank reads it directly via sqlite3 after that.
 
 ## MCP Client Setup
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigrank",
-  "version": "0.0.176",
+  "version": "0.0.178",
   "author": "SunrisesIllNeverSee (https://github.com/SunrisesIllNeverSee)",
   "description": "SigRank MCP server — the yield cascade + live leaderboard as MCP tools any agent can call",
   "mcpName": "io.github.SunrisesIllNeverSee/sigrank-mcp",
@@ -24,7 +24,8 @@
   },
   "scripts": {
     "start": "node index.mjs",
-    "test": "node test.mjs && node sign.test.mjs && node --test __tests__/cascade.test.mjs __tests__/badges.test.mjs"
+    "test": "node test.mjs && node sign.test.mjs && node --test __tests__/cascade.test.mjs __tests__/badges.test.mjs",
+    "sync:platforms": "node scripts/sync-platforms.mjs"
   },
   "files": [
     "index.mjs",
@@ -64,8 +65,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@zhangferry-dev/tokendash": "^1.7.5",
-    "ccusage": "^20.0.14",
-    "tokscale": "^4.0.4"
+    "ccusage": "^20.0.17",
+    "tokscale": "^4.5.2"
   }
 }

package/submit.mjs

@@ -11,9 +11,22 @@
 
 import { snapshotHash, signPayload } from "./sign.mjs";
 import { preflight } from "./preflight.mjs";
+import { readFileSync } from "node:fs";
 
 const WINDOW_TYPE = { "7d": "7d", "30d": "30d", "90d": "90d", all: "all_time" };
 const WINDOW_SPAN_DAYS = { "7d": 7, "30d": 30, "90d": 90, all_time: 3650 };
+
+/** Resolve this package's version for the User-Agent stamp (best-effort). */
+function _pkgVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL("./package.json", import.meta.url), "utf-8"),
+    );
+    return pkg.version;
+  } catch {
+    return "unknown";
+  }
+}
 const PLATFORM_ENUM = new Set([
   "claude",
   "chatgpt",
@@ -181,8 +194,13 @@ export async function submitSignedWindow(
     ((url, init = {}) => {
       const ctrl = new AbortController();
       const timer = setTimeout(() => ctrl.abort(), 15_000);
+      const headers = {
+        "user-agent": `node/${process.version} sigrank-mcp/${_pkgVersion()}`,
+        ...(init.headers || {}),
+      };
       return fetch(url, {
         ...init,
+        headers,
         signal: init.signal || ctrl.signal,
       }).finally(() => clearTimeout(timer));
     });

package/tokenpull.mjs

@@ -343,7 +343,7 @@ export async function tokenpullCodex({
   });
 
   return {
-    platform: "codex",
+    platform: adapter.platform || "codex",
     root: r,
     generatedAt: new Date(nowMs).toISOString(),
     files: files.size,
@@ -367,13 +367,12 @@ export async function tokenpullCodex({
 export async function tokenpullAny(platform, opts = {}) {
   if (!platform || platform === "claude")
     return tokenpull({ adapter: claudeAdapter, ...opts });
-  if (platform === "codex") {
-    // Auto-derive io_ratio from the operator's Claude data when not explicitly provided.
+  // Codex + Devin: both combine input + cache write in input_tokens, so both go
+  // through tokenpullCodex() which splits via ioRatio (Beta from Claude, Alpha 2.0).
+  if (platform === "codex" || platform === "devin") {
     let ioRatio = opts.ioRatio || 2.0;
     if (!opts.ioRatio) {
       try {
-        // Forward root/now from opts so the Beta-ratio derivation is testable
-        // (without this, it always reads the real ~/.claude and can't be injected).
         const c = await tokenpull({
           adapter: claudeAdapter,
           root: opts.root,
@@ -386,15 +385,8 @@ export async function tokenpullAny(platform, opts = {}) {
         /* no Claude data → Alpha 2.0 */
       }
     }
-    return tokenpullCodex({ ioRatio, ...opts });
-  }
-  // Cloud agents (Devin, etc.) run server-side — no local JSONL to read
-  const CLOUD_AGENTS = { devin: "Cognition/Devin" };
-  if (platform in CLOUD_AGENTS) {
-    throw new Error(
-      `"${platform}" (${CLOUD_AGENTS[platform]}) runs in the cloud — sessions are not written to local JSONL files. ` +
-        `There is no local data source to read. If ${CLOUD_AGENTS[platform]} exposes a usage API in future, an adapter can be added.`,
-    );
+    const adapter = platform === "codex" ? codexAdapter : ADAPTERS.devin;
+    return tokenpullCodex({ adapter, ioRatio, ...opts });
   }
   const adapter = ADAPTERS[platform];
   if (!adapter)
@@ -486,7 +478,7 @@ async function _freshTokendash(platform = "claude") {
   if (platform !== "claude") return null;
   const dbPath = join(homedir(), ".claude", "token-dashboard.db");
   // Read the token-dashboard DB directly with sqlite3 (no external python scan
-  // needed — the DB is created by the tokendash dashboard, now bundled as a dep).
+  // needed — the DB is created by Nate's token-dashboard, github.com/nateherkai/token-dashboard).
   // all-time only; the db doesn't expose windowing here.
   if (!existsSync(dbPath)) return null;
   try {

package/tools.mjs

@@ -26,7 +26,7 @@ import { ALL_PLATFORMS } from "./adapters.mjs";
 import { ensureIdentity, recordEnrollment } from "./keystore.mjs";
 import { submitSignedWindow } from "./submit.mjs";
 import { createHash } from "node:crypto";
-import { execFile } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -256,6 +256,56 @@ export const DEFAULT_FETCH_TIMEOUT =
  *  past this is malformed or abusive — reject cleanly before parsing/POSTing (E2 hardening). */
 const MAX_INPUT = 1_000_000;
 
+/** Resolve this package's version for the User-Agent stamp (best-effort). */
+function agentVersionStamp() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL("./package.json", import.meta.url), "utf-8"),
+    );
+    return pkg.version;
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * curl-based fetch fallback for when Node's fetch is blocked by Vercel's bot
+ * protection (TLS fingerprinting). Returns a Response-like object with .ok,
+ * .status, .json(), .text(). Uses execFileSync for synchronous curl execution.
+ */
+function curlFetch(url, init = {}, timeoutMs = 10_000) {
+  const args = ["-s", "-S", "-w", "\n__HTTP_STATUS__%{http_code}", "--max-time", String(Math.ceil(timeoutMs / 1000))];
+  if (init.method) args.push("-X", init.method);
+  const headers = init.headers || {};
+  for (const [k, v] of Object.entries(headers)) {
+    args.push("-H", `${k}: ${v}`);
+  }
+  if (init.body) {
+    args.push("-d", init.body);
+  }
+  args.push(url);
+  let stdout;
+  try {
+    stdout = execFileSync("curl", args, {
+      encoding: "utf-8",
+      maxBuffer: 10 * 1024 * 1024,
+      timeout: timeoutMs + 2000,
+    });
+  } catch (e) {
+    throw new Error(`curl transport failed: ${e.message}`);
+  }
+  // Parse the status code from the trailer
+  const statusMatch = stdout.match(/__HTTP_STATUS__(\d+)$/);
+  const status = statusMatch ? parseInt(statusMatch[1], 10) : 0;
+  const bodyText = statusMatch ? stdout.slice(0, statusMatch.index) : stdout;
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => { try { return JSON.parse(bodyText); } catch { return {}; } },
+    text: async () => bodyText,
+  };
+}
+
 // ── Smithery quality: output schemas + annotations ──────────────────────────
 // MCP tool annotations hint to clients about side-effects, read-only status, etc.
 const ANNOTATIONS = {
@@ -747,8 +797,8 @@ export const TOOLS = [
       properties: {
         platform: {
           type: "string",
-          enum: ALL_PLATFORMS,
-          description: `source platform (default: claude). Supported: ${ALL_PLATFORMS.join(", ")}. codex is estimated via io_ratio. Some platforms need setup (e.g. copilot requires COPILOT_OTEL_ENABLED=true).`,
+          enum: [...ALL_PLATFORMS, "multi"],
+          description: `source platform (default: claude). Supported: ${ALL_PLATFORMS.join(", ")}, multi. 'multi' = combined cascade summed across all locally-detected platforms (needs 2+ active). 'devin' reads from ~/.local/share/devin/cli/sessions.db (SQLite, all windows). 'codex' is estimated via io_ratio. 'other' reads from a user-supplied JSON file (set SIGRANK_OTHER_PATH). Some platforms need setup (e.g. copilot requires COPILOT_OTEL_ENABLED=true).`,
         },
       },
     },
@@ -780,8 +830,8 @@ export const TOOLS = [
         },
         platform: {
           type: "string",
-          enum: ALL_PLATFORMS,
-          description: `Source platform to pull from (default: claude). Supported: ${ALL_PLATFORMS.join(", ")}. Each platform reads its own session logs locally.`,
+          enum: [...ALL_PLATFORMS, "multi"],
+          description: `Source platform to pull from (default: claude). Supported: ${ALL_PLATFORMS.join(", ")}, multi. 'multi' = combined cascade summed across all locally-detected platforms (needs 2+ active). 'devin' reads from ~/.local/share/devin/cli/sessions.db (SQLite, all windows). 'other' reads from a user-supplied JSON file (set SIGRANK_OTHER_PATH). Each platform reads its own session logs locally.`,
         },
       },
     },
@@ -1312,6 +1362,36 @@ export const TOOLS = [
       },
     },
   },
+  {
+    name: "tokscale_breakdown",
+    description:
+      "Show a per-model breakdown of your token usage across all platforms detected by tokscale. Models under the threshold (default 1%) are lumped into 'other' to keep the display clean. Useful for seeing which models you actually use per platform (e.g. claude-opus-4-8 76%, claude-sonnet-4-6 11%, other 0.3%). Returns { platform: [{ model, input, output, cacheRead, cacheCreate, pct }] }.",
+    annotations: {
+      title: "Model breakdown",
+      ...ANNOTATIONS.readOnlyHint,
+      ...ANNOTATIONS.openWorldHint,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        threshold: {
+          type: "number",
+          description:
+            "Models below this fraction of their platform's total tokens are lumped into 'other'. Default 0.01 (1%). Set 0 to see every model.",
+          default: 0.01,
+        },
+      },
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        platforms: {
+          type: "object",
+          description: "Map of platform name → array of { model, input, output, cacheRead, cacheCreate, pct }",
+        },
+      },
+    },
+  },
 ];
 
 // tokenpull window key → the board's window_type enum.
@@ -1333,9 +1413,191 @@ const _lastWatchSubmitAt = new Map();
 // 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 = {}) {
-  const targets = platforms && platforms.length ? platforms : ALL_PLATFORMS;
+  // 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. This is much faster than trying all 17 adapters (most fail
+  // silently on a machine that doesn't have that tool installed).
+  //
+  // 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.
+  const detected = await _tokscaleDetectClients().catch(() => null);
+  if (detected && detected.length > 0) {
+    return _pullExplicit(detected, opts);
+  }
+  // Fallback: tokscale not installed or failed → try all adapters (old behavior)
+  return _pullExplicit(ALL_PLATFORMS, opts);
+}
+
+/** 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 [];
+  // Complete tokscale client → our platform name mapping.
+  // Tokscale supports 40 clients (as of v3.1.0). We have native adapters for 16;
+  // the rest map to "other" (user-supplied JSON via SIGRANK_OTHER_PATH).
+  // Source: https://github.com/junhoyeo/tokscale
+  const TOKSCALE_CLIENT_MAP = {
+    // Native adapters
+    claude: "claude",
+    codex: "codex",
+    "devin-cli": "devin",
+    "devin-desktop": "devin",
+    gemini: "gemini",
+    amp: "amp",
+    kimi: "kimi",
+    qwen: "qwen",
+    goose: "goose",
+    kilo: "kilo",
+    kilocode: "kilo",
+    hermes: "hermes",
+    droid: "droid",
+    codebuff: "codebuff",
+    copilot: "copilot",
+    opencode: "opencode",
+    openclaw: "openclaw",
+    pi: "pi",
+    // No native adapter yet → "other"
+    cursor: "other",
+    roocode: "other",
+    mux: "other",
+    crush: "other",
+    antigravity: "other",
+    "antigravity-cli": "other",
+    zed: "other",
+    kiro: "other",
+    trae: "other",
+    warp: "other",
+    cline: "other",
+    gjc: "other",
+    grok: "other",
+    jcode: "other",
+    commandcode: "other",
+    micode: "other",
+    junie: "other",
+    zcode: "other",
+    opencodereview: "other",
+    codebuddy: "other",
+    workbuddy: "other",
+    // synthetic = re-attributed from other sources, skip
+    synthetic: null,
+  };
+  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];
+}
+
+/**
+ * Run `tokscale models --json` and return a model-level breakdown per platform.
+ * Models under `threshold` (default 1%) of their platform's total are lumped
+ * into "other" to keep the display clean.
+ *
+ * Returns: { platform: [{ model, input, output, cacheRead, cacheCreate, pct }] }
+ */
+export async function tokscaleModelBreakdown(threshold = 0.01) {
+  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 TOKSCALE_CLIENT_MAP = {
+    claude: "claude", codex: "codex", "devin-cli": "devin",
+    "devin-desktop": "devin", gemini: "gemini", amp: "amp",
+    kimi: "kimi", qwen: "qwen", goose: "goose", kilo: "kilo",
+    kilocode: "kilo", hermes: "hermes", droid: "droid",
+    codebuff: "codebuff", copilot: "copilot", opencode: "opencode",
+    openclaw: "openclaw", pi: "pi",
+    cursor: "other", roocode: "other", mux: "other", crush: "other",
+    antigravity: "other", "antigravity-cli": "other", zed: "other",
+    kiro: "other", trae: "other", warp: "other", cline: "other",
+    gjc: "other", grok: "other", jcode: "other", commandcode: "other",
+    micode: "other", junie: "other", zcode: "other",
+    opencodereview: "other", codebuddy: "other", workbuddy: "other",
+    synthetic: null,
+  };
+
+  // Group entries by our platform name
+  const byPlatform = {};
+  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;
+    const p = platform || "other";
+    if (!byPlatform[p]) byPlatform[p] = [];
+    byPlatform[p].push({
+      model: e.model,
+      input,
+      output,
+      cacheRead: Number(e.cacheRead) || 0,
+      cacheCreate: Number(e.cacheWrite) || 0,
+    });
+  }
+
+  // For each platform: sort by total tokens desc, lump small models into "other"
+  const result = {};
+  for (const [platform, models] of Object.entries(byPlatform)) {
+    const total = models.reduce(
+      (s, m) => s + m.input + m.output + m.cacheRead + m.cacheCreate,
+      0,
+    );
+    if (total === 0) continue;
+    const sorted = models.sort(
+      (a, b) =>
+        b.input + b.output + b.cacheRead + b.cacheCreate -
+        (a.input + a.output + a.cacheRead + a.cacheCreate),
+    );
+    const big = [];
+    const small = { model: "other", input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };
+    for (const m of sorted) {
+      const t = m.input + m.output + m.cacheRead + m.cacheCreate;
+      if (t / total < threshold) {
+        small.input += m.input;
+        small.output += m.output;
+        small.cacheRead += m.cacheRead;
+        small.cacheCreate += m.cacheCreate;
+      } else {
+        big.push({ ...m, pct: t / total });
+      }
+    }
+    if (small.input + small.output + small.cacheRead + small.cacheCreate > 0) {
+      const t = small.input + small.output + small.cacheRead + small.cacheCreate;
+      big.push({ ...small, pct: t / total });
+    }
+    result[platform] = big;
+  }
+  return result;
+}
+
+/** Pull a specific set of platforms in parallel, filter to active ones. */
+async function _pullExplicit(platforms, opts = {}) {
   const settled = await Promise.allSettled(
-    targets.map((p) => callTool("tokenpull", { platform: p }, opts)),
+    platforms.map((p) => callTool("tokenpull", { platform: p }, opts)),
   );
   const active = settled
     .filter((r) => r.status === "fulfilled" && r.value)
@@ -1357,13 +1619,45 @@ export async function callTool(name, args, opts = {}) {
   const rawFetch = opts.fetchImpl || fetch;
 
   // Wrap every fetch with an AbortController timeout so a hung network call never
-  // blocks the MCP client indefinitely.
-  const doFetch = (url, init = {}) => {
+  // blocks the MCP client indefinitely. Vercel's bot protection (security
+  // checkpoint) blocks Node's fetch via TLS fingerprinting — no UA fix helps.
+  // When fetch gets a 403 Vercel challenge, fall back to curl (which passes).
+  const doFetch = async (url, init = {}) => {
     const ac = new AbortController();
     const timer = setTimeout(() => ac.abort(), timeoutMs);
-    return rawFetch(url, { ...init, signal: ac.signal }).finally(() =>
-      clearTimeout(timer),
-    );
+    const headers = {
+      "user-agent": `node/${process.version} sigrank-mcp/${agentVersionStamp()}`,
+      ...(init.headers || {}),
+    };
+    try {
+      const res = await rawFetch(url, { ...init, headers, signal: ac.signal });
+      // Detect Vercel security checkpoint (403 + HTML body, not JSON)
+      if (res.status === 403) {
+        const text = await res.text();
+        if (text.includes("Vercel Security Checkpoint") || text.includes("x-vercel-challenge")) {
+          // Fall back to curl transport
+          return curlFetch(url, init, timeoutMs);
+        }
+        // Real 403 from the API — return a mock response object
+        return {
+          ok: false,
+          status: 403,
+          json: async () => { try { return JSON.parse(text); } catch { return {}; } },
+          text: async () => text,
+        };
+      }
+      return res;
+    } catch (e) {
+      if (e.name === "AbortError") throw e;
+      // Network error — try curl as fallback
+      try {
+        return await curlFetch(url, init, timeoutMs);
+      } catch {
+        throw e;
+      }
+    } finally {
+      clearTimeout(timer);
+    }
   };
 
   const fetchJson = async (path) => {
@@ -1405,8 +1699,12 @@ export async function callTool(name, args, opts = {}) {
     const c = withParseWarnings(pillars, cascade(pillars));
     return { ...c, card: narrate(c) };
   }
-  if (name === "get_leaderboard")
-    return fetchJson("/api/v1/leaderboard?metric=yield_");
+  if (name === "get_leaderboard") {
+    const params = new URLSearchParams({ metric: "yield_" });
+    if (args?.limit) params.set("limit", String(args.limit));
+    if (args?.window) params.set("window", args.window);
+    return fetchJson(`/api/v1/leaderboard?${params}`);
+  }
   if (name === "get_operator") {
     const codename = String(args?.codename || "").trim();
     if (!codename)
@@ -1677,6 +1975,67 @@ export async function callTool(name, args, opts = {}) {
   if (name === "tokenpull") {
     // Local read → 4 windows of pillars → cascade each. Token-only, on-device.
     const platform = args?.platform || "claude";
+
+    // MULTI: sum every locally-detected platform's pillars per window. Same logic as
+    // submit_verified's multi flow — Devin (cloud, via tokscale) is included.
+    if (platform === "multi") {
+      const detected = [];
+      for (const p of ALL_PLATFORMS) {
+        const r = await pullByPlatform(p, opts).catch(() => null);
+        const live =
+          r &&
+          (r.windows || []).some(
+            (w) =>
+              w.pillars.input +
+                w.pillars.output +
+                w.pillars.cacheCreate +
+                w.pillars.cacheRead >
+              0,
+          );
+        if (live) detected.push(r);
+      }
+      if (detected.length < 2) {
+        return {
+          platform: "multi",
+          status: "skipped",
+          reason: "need_2_platforms",
+          detail: `multi needs 2+ active platforms; found ${detected.length} (${detected.map((d) => d.platform).join(", ") || "none"}).`,
+          windows: [],
+        };
+      }
+      const winKeys = ["7d", "30d", "90d", "all"];
+      const windows = [];
+      for (const wk of winKeys) {
+        const sum = { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 };
+        let msgs = 0;
+        for (const d of detected) {
+          const w = (d.windows || []).find((x) => x.window === wk);
+          if (!w) continue;
+          sum.input += w.pillars.input || 0;
+          sum.output += w.pillars.output || 0;
+          sum.cacheCreate += w.pillars.cacheCreate || 0;
+          sum.cacheRead += w.pillars.cacheRead || 0;
+          msgs += w.messages || 0;
+        }
+        if (sum.input + sum.output + sum.cacheCreate + sum.cacheRead <= 0)
+          continue;
+        const c = cascade(sum);
+        windows.push({
+          window: wk,
+          messages: msgs,
+          pillars: sum,
+          cascade: c,
+          card: narrate(c, `${wk} multi`),
+        });
+      }
+      return {
+        platform: "multi",
+        estimated: true,
+        sources: detected.map((d) => d.platform),
+        windows,
+      };
+    }
+
     const pulled = await pullByPlatform(platform, opts);
     const windows = pulled.windows.map((w) => {
       const c = cascade(w.pillars);
@@ -1704,7 +2063,111 @@ export async function callTool(name, args, opts = {}) {
     // (server re-scores). The board stays platform-agnostic via the 4 pillars; the
     // source platform rides along as a tag. Conversion already happened in the adapter.
     const codename = String(args?.codename || "").trim();
-    const pulled = await pullByPlatform(args?.platform || "claude", opts);
+    const platform = args?.platform || "claude";
+
+    // MULTI: same combined cross-platform cascade as submit_verified. Includes Devin
+    // (cloud, via tokscale). Aggregate every locally-detected platform's pillars per
+    // window and publish as platform='multi'.
+    if (platform === "multi") {
+      const detected = [];
+      for (const p of ALL_PLATFORMS) {
+        const r = await pullByPlatform(p, opts).catch(() => null);
+        const live =
+          r &&
+          (r.windows || []).some(
+            (w) =>
+              w.pillars.input +
+                w.pillars.output +
+                w.pillars.cacheCreate +
+                w.pillars.cacheRead >
+              0,
+          );
+        if (live) detected.push(r);
+      }
+      if (detected.length < 2) {
+        return {
+          platform: "multi",
+          codename: codename || undefined,
+          status: "skipped",
+          reason: "need_2_platforms",
+          detail: `multi needs 2+ active platforms; found ${detected.length} (${detected.map((d) => d.platform).join(", ") || "none"}).`,
+          windows: [],
+        };
+      }
+      const winKeys = args?.window ? [args.window] : ["7d", "30d", "90d", "all"];
+      const out = [];
+      for (const wk of winKeys) {
+        const sum = { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 };
+        let msgs = 0;
+        for (const d of detected) {
+          const w = (d.windows || []).find((x) => x.window === wk);
+          if (!w) continue;
+          sum.input += w.pillars.input || 0;
+          sum.output += w.pillars.output || 0;
+          sum.cacheCreate += w.pillars.cacheCreate || 0;
+          sum.cacheRead += w.pillars.cacheRead || 0;
+          msgs += w.messages || 0;
+        }
+        if (sum.input + sum.output + sum.cacheCreate + sum.cacheRead <= 0)
+          continue;
+        const c = cascade(sum);
+        const card = narrate(c, `${wk} multi`);
+        if (!codename) {
+          out.push({
+            window: wk,
+            pillars: sum,
+            cascade: c,
+            card,
+            submission: { status: "not_submitted", reason: "codename_required" },
+          });
+          continue;
+        }
+        const rawPaste = `${sum.input} ${sum.output} ${sum.cacheCreate} ${sum.cacheRead}`;
+        const windowType = WINDOW_TYPE[wk] || wk;
+        const stamp = uploadStamp({
+          codename,
+          window: windowType,
+          pillars: sum,
+          platform: "multi",
+        });
+        const res = await doFetch(`${apiBase}/api/v1/ingest-paste`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            accept: "application/json",
+          },
+          body: JSON.stringify({
+            codename,
+            raw_paste: rawPaste,
+            window_type: windowType,
+            telemetry: { platform: { primary: "multi" } },
+            ...stamp,
+          }),
+        });
+        let ack;
+        try {
+          ack = await res.json();
+        } catch {
+          ack = { status: "parse_error", httpStatus: res.status };
+        }
+        const ranked = ack?.ranked ?? ack?.accepted ?? false;
+        out.push({
+          window: wk,
+          pillars: sum,
+          cascade: c,
+          card,
+          submission: { ...stamp, httpStatus: res.status, ranked, ...ack },
+        });
+      }
+      return {
+        platform: "multi",
+        codename: codename || undefined,
+        sources: detected.map((d) => d.platform),
+        windows: out,
+      };
+    }
+
+    const pulled = await pullByPlatform(platform, opts);
     const targets = args?.window
       ? pulled.windows.filter((w) => w.window === args.window)
       : pulled.windows;
@@ -2774,6 +3237,7 @@ export async function callTool(name, args, opts = {}) {
     const top = ops.map((op) => ({
       ...op,
       behavioral_framing: _behavioralFraming(op),
+      competitive: _competitiveLayer(op, board),
     }));
 
     const best = top[0];
@@ -2781,7 +3245,13 @@ export async function callTool(name, args, opts = {}) {
       ? `${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 };
+    return {
+      top_operators: top,
+      total_operators: total,
+      summary,
+      cta: "Check my rank",
+      shareable_url: best ? `${DEFAULT_API_BASE}/operator/${encodeURIComponent(best.codename)}` : null,
+    };
   }
 
   if (name === "compare_self") {
@@ -2843,6 +3313,10 @@ export async function callTool(name, args, opts = {}) {
 
     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,
@@ -2850,8 +3324,16 @@ export async function callTool(name, args, opts = {}) {
         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",
     };
   }
 
@@ -2863,9 +3345,10 @@ export async function callTool(name, args, opts = {}) {
         "compare_operators requires both `codename_a` and `codename_b`.",
       );
 
-    const [opA, opB] = await Promise.all([
+    const [opA, opB, board] = await Promise.all([
       fetchJson(`/api/v1/operators/${encodeURIComponent(nameA)}`),
       fetchJson(`/api/v1/operators/${encodeURIComponent(nameB)}`),
+      fetchJson("/api/v1/leaderboard?metric=yield_"),
     ]);
 
     const yieldA = opA.yield_ || 0;
@@ -2884,6 +3367,7 @@ export async function callTool(name, args, opts = {}) {
         velocity: opA.velocity,
         class: opA.class,
         rank: opA.rank,
+        competitive: _competitiveLayer(opA, board),
       },
       operator_b: {
         codename: opB.codename,
@@ -2892,9 +3376,11 @@ export async function callTool(name, args, opts = {}) {
         velocity: opB.velocity,
         class: opB.class,
         rank: opB.rank,
+        competitive: _competitiveLayer(opB, board),
       },
       verdict,
       yield_delta: delta,
+      cta: "Compare me to others",
     };
   }
 
@@ -2915,6 +3401,8 @@ export async function callTool(name, args, opts = {}) {
         { 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",
     };
   }
 
@@ -2986,6 +3474,11 @@ export async function callTool(name, args, opts = {}) {
 
     const summary = `Your Υ Yield is ${y.toLocaleString()} (${klass}). ${_improvementSuggestion(klass, metrics)}`;
 
+    // Competitive layer per SHARED_DESIGN_DECISIONS.md §3/§4/§5
+    const board = await fetchJson("/api/v1/leaderboard?metric=yield_");
+    const competitive = _competitiveLayer(metrics, board);
+    const competitiveSummary = _competitiveSummary(metrics, board);
+
     return {
       your_metrics: {
         yield_: y,
@@ -2993,16 +3486,117 @@ export async function callTool(name, args, opts = {}) {
         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",
     };
   }
 
+  if (name === "tokscale_breakdown") {
+    const threshold = Number(args?.threshold ?? 0.01);
+    const platforms = await tokscaleModelBreakdown(threshold);
+    return { platforms };
+  }
+
   throw new Error(`Unknown tool: ${name}`);
 }
 
 // ── Intent tool helpers — behavioral framing in power-user language ──────────
 
+/**
+ * Competitive layer for tool responses per SHARED_DESIGN_DECISIONS.md §3/§4/§5.
+ * Every tool response that includes operator data must show:
+ *   rank, percentile, class_tier, delta_from_average, delta_from_top, shareable_url
+ * Response style: factual + competitive ("You rank #12 of 47 operators...")
+ */
+function _competitiveLayer(op, board) {
+  const allOps = Array.isArray(board?.operators || board) ? (board.operators || board) : [];
+  const yields = allOps.map((o) => o.yield_ || 0).sort((a, b) => a - b);
+  const yourYield = op.yield_ || 0;
+  const total = allOps.length;
+
+  // Rank: find operator's position (1-based)
+  let rank = op.rank || null;
+  if (!rank && total > 0) {
+    const sorted = [...allOps].sort((a, b) => (b.yield_ || 0) - (a.yield_ || 0));
+    const idx = sorted.findIndex((o) => o.codename === op.codename);
+    rank = idx >= 0 ? idx + 1 : null;
+  }
+
+  // Percentile: % of operators with yield below this operator
+  const percentile = total > 0
+    ? Math.round((yields.filter((y) => y < yourYield).length / total) * 100)
+    : 0;
+
+  // Delta from average
+  const avgYield = total > 0 ? yields.reduce((s, y) => s + y, 0) / total : 0;
+  const deltaFromAvg = avgYield > 0
+    ? { absolute: Math.round(yourYield - avgYield),
+        percent: Math.round(((yourYield - avgYield) / avgYield) * 100) }
+    : { absolute: 0, percent: 0 };
+
+  // Delta from top operator
+  const topYield = total > 0 ? Math.max(...yields) : 0;
+  const deltaFromTop = topYield > 0
+    ? { absolute: Math.round(topYield - yourYield),
+        percent: Math.round(((topYield - yourYield) / topYield) * 100) }
+    : { absolute: 0, percent: 0 };
+
+  // Shareable URL
+  const shareableUrl = op.codename && op.codename !== "you (local)"
+    ? `${DEFAULT_API_BASE}/operator/${encodeURIComponent(op.codename)}`
+    : null;
+
+  return {
+    rank,
+    total_operators: total,
+    percentile,
+    class_tier: op.class || "Burner",
+    delta_from_average: deltaFromAvg,
+    delta_from_top: deltaFromTop,
+    shareable_url: shareableUrl,
+  };
+}
+
+/** Factual + competitive summary line per SHARED_DESIGN_DECISIONS.md §4 */
+function _competitiveSummary(op, board) {
+  const cl = _competitiveLayer(op, board);
+  const parts = [];
+
+  if (cl.rank && cl.total_operators > 0) {
+    parts.push(`You rank #${cl.rank} of ${cl.total_operators} operators.`);
+  }
+
+  const topOp = (board?.operators || board || []).reduce(
+    (best, o) => ((o.yield_ || 0) > (best?.yield_ || 0) ? o : best),
+    null,
+  );
+  if (topOp && topOp.codename) {
+    parts.push(`Top operator is ${topOp.codename} with Υ ${(topOp.yield_ || 0).toLocaleString()}.`);
+  }
+
+  if (cl.delta_from_average.percent !== 0) {
+    const dir = cl.delta_from_average.percent > 0 ? "above" : "below";
+    parts.push(`You're ${Math.abs(cl.delta_from_average.percent)}% ${dir} average.`);
+  }
+
+  if (cl.delta_from_top.percent > 0) {
+    parts.push(`${cl.delta_from_top.percent}% below top.`);
+  }
+
+  return parts.join(" ");
+}
+
 function _behavioralFraming(op) {
   const y = op.yield_ || 0;
   const l = op.leverage || 0;