sigrank 0.0.229 → 0.0.231

package/MCP_SERVER_DESCRIPTION.md

@@ -1,6 +1,6 @@
 # SigRank MCP Server
 
-> Operator leaderboard measuring users, not models — 15 tools, TUI, signed submit, privacy-first.
+> Operator leaderboard measuring users, not models — 24 tools, TUI, signed submit, privacy-first.
 
 SigRank is the first leaderboard that ranks **AI operators** — the humans — by token cascade efficiency, not the models. The yield metric (Υ = cache_read × output / input²) turns raw token telemetry into a competitive ranking on [signalaf.com](https://signalaf.com).
 
@@ -64,41 +64,72 @@ npx sigrank diagnose            # Diagnose cascade inefficiencies
 npx sigrank improve             # Get improvement suggestions
 ```
 
-## The 20 MCP Tools
+## The 24 MCP Tools
 
-### Read-only (no auth required)
+### Read-only — pure math (no auth, no filesystem)
 
 | # | Tool | What it does |
 |---|------|-------------|
 | 1 | `rank_paste` | Paste token counts, get projected SigRank rank instantly. Computes the full yield cascade locally (Υ, SNR, Leverage, Velocity, 10xDEV, class tier). No network calls. |
-| 2 | `get_leaderboard` | Fetch the live public leaderboard from signalaf.com. Returns all ranked operators sorted by yield, with codename, Υ, leverage, velocity, class, and rank position. |
-| 3 | `get_operator` | Get any operator's full profile by codename. Returns detailed metrics + per-window breakdowns (7d/30d/90d/all-time) with the four token pillars per window. |
-| 4 | `tokenpull` | Pull your LOCAL token usage from session logs and rank it across all four windows — zero paste. Reads token counts, not message content. Numbers stay on your machine. |
-| 5 | `rank_windows` | Rank all four time windows (7d/30d/90d/all-time) in one call from a dashboard paste. Paste the full table from ccusage, tokscale, or Claude Max dashboard. |
-| 6 | `tokenpull_compare` | Pull token usage from ALL four local sources in parallel (JSONL canon, ccusage CLI, token-dashboard SQLite, tokscale) and compare side-by-side with delta % vs baseline. |
-| 7 | `simulate_change` | "What if I changed my token mix?" — takes your current pillars + proposed changes, runs the cascade on both, returns exact Υ delta, class change, and per-metric diffs. Pure local math. |
-| 8 | `diagnose_cascade` | Analyzes your token cascade and diagnoses where you're leaking efficiency. Returns ranked list of leaks with severity, findings, recommendations, and estimated Υ impact per fix. |
-| 9 | `suggest_improvements` | Generates ranked, simulated improvement suggestions. Tests multiple strategies (increase cache reads, reduce input, increase output, optimize cache creation), simulates each, returns ranked by Υ impact. |
-| 10 | `self_improve` | One-click optimize — runs the full cycle in one call: tokenpull → diagnose → suggest → simulate. Returns diagnosis + suggestions + simulated impact of the best change. Supports scope modes (daily/weekly/trend). |
-| 11 | `watch_tokenpull` | One poll per call — pulls local token logs and returns current cascade for the watched window. Re-call at your desired cadence to monitor. With `submit:true`, signs + publishes (rate-limited to once per 5 min). |
-| 12 | `get_best_operator` | Top N operators with behavioral framing in power-user language. **Intent:** "who is the best AI user?" / "show me the AI user leaderboard". Wraps `get_leaderboard` with plain-language interpretation of each operator's cascade. |
-| 13 | `compare_self` | Your metrics vs board averages + power-user assessment + percentile + actionable suggestion. **Intent:** "how do I measure up to other AI users?" / "am I a power user?" Accepts codename (from board) or raw token pillars (local). |
-| 14 | `compare_operators` | Side-by-side comparison of two operators with behavioral verdict. **Intent:** "compare operator X vs Y" / "who is more efficient". Returns both operators' metrics + verdict in power-user language. |
-| 15 | `describe_power_user` | Static explanation of what makes an AI power user, with metrics explained and class tier meanings. **Intent:** "what is an AI power user?" / "what makes a good AI user?" |
-| 16 | `optimize_efficiency` | Ranked efficiency suggestions tied to your current cascade shape. **Intent:** "how can I use AI more efficiently?" / "reduce token burn" / "stop tokenmaxxing". Accepts codename or raw token pillars. |
-
-### Write (submit to board)
+| 2 | `rank_windows` | Rank all four time windows (7d/30d/90d/all-time) in one call from a dashboard paste. Paste the full table from ccusage, tokscale, or Claude Max dashboard. |
+| 3 | `simulate_change` | "What if I changed my token mix?" — takes your current pillars + proposed changes, runs the cascade on both, returns exact Υ delta, class change, and per-metric diffs. Pure local math. |
+| 4 | `diagnose_cascade` | Analyzes your token cascade and diagnoses where you're leaking efficiency. Returns ranked list of leaks with severity, findings, recommendations, and estimated Υ impact per fix. |
+| 5 | `suggest_improvements` | Generates ranked, simulated improvement suggestions. Tests multiple strategies (increase cache reads, reduce input, increase output, optimize cache creation), simulates each, returns ranked by Υ impact. |
+| 6 | `self_improve` | One-click optimize — runs the full cycle in one call: tokenpull → diagnose → suggest → simulate. Returns diagnosis + suggestions + simulated impact of the best change. Supports scope modes (daily/weekly/trend). |
+
+### Read-only — calls signalaf.com API (no auth)
+
+| # | Tool | What it does |
+|---|------|-------------|
+| 7 | `get_leaderboard` | Fetch the live public leaderboard from signalaf.com. Returns all ranked operators sorted by yield, with codename, Υ, leverage, velocity, class, and rank position. |
+| 8 | `get_operator` | Get any operator's full profile by codename. Returns detailed metrics + per-window breakdowns (7d/30d/90d/all-time) with the four token pillars per window. |
+| 9 | `discover_peers` | Find mentors, peers, and complementary operators for your operator on the leaderboard. |
+
+### Read-only — local filesystem (no auth, no network)
+
+| # | Tool | What it does |
+|---|------|-------------|
+| 10 | `tokenpull` | Pull your LOCAL token usage from session logs and rank it across all four windows — zero paste. Reads token counts, not message content. Numbers stay on your machine. 17 platform adapters. |
+| 11 | `tokenpull_compare` | Pull token usage from ALL four local sources in parallel (JSONL canon, ccusage CLI, token-dashboard SQLite, tokscale) and compare side-by-side with delta % vs baseline. |
+| 12 | `watch_tokenpull` | One poll per call — pulls local token logs and returns current cascade for the watched window. Re-call at your desired cadence to monitor. With `submit:true`, signs + publishes (rate-limited to once per 5 min). |
+
+### Write — submit to board (needs enrolled identity)
+
+| # | Tool | What it does |
+|---|------|-------------|
+| 13 | `submit_paste` | Ranks a paste of token counts AND publishes to the live board in one call. Computes local preview, then submits to server for authoritative scoring. Returns both local + server results. |
+| 14 | `tokenpull_submit` | Pull your LOCAL token usage AND publish to the board in one call — the zero-paste flow. Reads pillars per window, computes cascade, submits each window server-side. Token-only, no prompt content. |
+| 15 | `submit_verified` | Publish your LOCAL token runs as a VERIFIED operator — the enrolled, signed path. Reads pillars, builds Schema 1.0 snapshot, ed25519-signs with your device key, POSTs to board. Requires `enroll` first. |
+| 16 | `enroll` | Bind THIS device to your SigRank operator. Paste the key from signalaf.com → Settings → "New key". Generates + stores a local ed25519 keypair. Only the PUBLIC key is ever sent. |
+
+### Tokscale analytics — local tokscale data (no auth, no network)
 
 | # | Tool | What it does |
 |---|------|-------------|
-| 17 | `submit_paste` | Ranks a paste of token counts AND publishes to the live board in one call. Computes local preview, then submits to server for authoritative scoring. Returns both local + server results. |
-| 18 | `tokenpull_submit` | Pull your LOCAL token usage AND publish to the board in one call — the zero-paste flow. Reads pillars per window, computes cascade, submits each window server-side. Token-only, no prompt content. |
-| 19 | `submit_verified` | Publish your LOCAL token runs as a VERIFIED operator — the enrolled, signed path. Reads pillars, builds Schema 1.0 snapshot, ed25519-signs with your device key, POSTs to board. Requires `enroll` first. |
-| 20 | `enroll` | Bind THIS device to your SigRank operator. Paste the key from signalaf.com → Settings → "New key". Generates + stores a local ed25519 keypair. Only the PUBLIC key is ever sent. |
+| 17 | `tokscale_breakdown` | Per-model token breakdown across platforms (models under threshold → "other"). |
+| 18 | `tokscale_market_share` | AI tool market share: each tool's % of tokens/cost/messages, ranked. From local tokscale data. |
+| 19 | `tokscale_developer_profile` | Per-developer usage profile across all detected tools: model mix, pillars, sessions, workspaces. Paths redacted. |
+| 20 | `tokscale_model_trends` | Model adoption over time: per-model first/last seen, active days, month-by-month adoption curve. |
+| 21 | `tokscale_cost_analysis` | Cost per developer per model: cost_per_million_tokens, cost_per_message, share_cost, client rollup. |
+| 22 | `tokscale_device_profile` | Device fingerprinting: installed tools, session counts, active days, day-of-week distribution, concurrency. Paths redacted. |
+| 23 | `tokscale_mcp_usage` | MCP server usage: detected servers, detection window, active days. |
+| 24 | `tokscale_competitive_intel` | Competitive intelligence for any AI tool: rank, model mix, cost efficiency, share vs all competitors. |
+
+### Moved to bestuser-router-mcp (5 intent tools)
+
+The following 5 tools were moved to [bestuser-router-mcp](https://github.com/SunrisesIllNeverSee/bestuser-router-mcp) to keep sigrank-mcp focused as a measurement instrument. They are available as a separate npm package (`npx bestuser-router-mcp`):
+
+| Tool | Intent | Trigger |
+|------|--------|---------|
+| `get_best_operator` | BEST_OPERATOR | "who is the best AI user?" |
+| `compare_self` | COMPARE_SELF | "how do I measure up?" |
+| `compare_operators` | COMPARE_OPERATORS | "compare X vs Y" |
+| `describe_power_user` | DESCRIBE_POWER_USER | "what is a power user?" |
+| `optimize_efficiency` | OPTIMIZE_EFFICIENCY | "how can I use AI more efficiently?" |
 
 ## Intent Taxonomy
 
-The intent-based tools (12-16) are designed to map natural-language queries to the right MCP call. Calling agents and LLMs can use these intent mappings to route user questions:
+The intent-based tools (in bestuser-router-mcp) are designed to map natural-language queries to the right MCP call. Calling agents and LLMs can use these intent mappings to route user questions:
 
 | Intent | Trigger phrases | Tool |
 |--------|----------------|------|
@@ -129,7 +160,7 @@ The intent-based tools (12-16) are designed to map natural-language queries to t
 | Transport | stdio |
 | Platform | Cross-platform (Node.js) |
 | Language | JavaScript |
-| Tools | 20 |
+| Tools | 24 |
 | Auth | None for reads; Supabase anon key for submits |
 | Category | Developer Tools |
 

package/analytics/cascade.mjs

@@ -1,10 +1,25 @@
 /**
- * cascade.mjs — pure SigRank yield cascade (no deps, no transport).
- * Mirrors sigrank-app/lib/ingest/bridge.ts computeCascadeMetrics() so rank_paste
- * reproduces the canonical MO§ES Υ 18436.98 from its 4 raw token pillars.
- * Paper-and-pencil math, open by design; proprietary threshold cuts stay server-side.
+ * cascade.mjs — SigRank yield cascade facade.
  *
- * Degenerate-input policy (hardened):
+ * The canonical cascade math (Υ Yield, SNR, Leverage, Velocity, 10xDEV, and the
+ * 24-stage RS05 class taxonomy) now lives in the `@sigrank/cascade` package.
+ * This file re-exports the canonical functions and adds local-only helpers that
+ * are presentation/MCP-specific and intentionally NOT part of the canonical
+ * math package:
+ *   - CLASS_TIERS, SIGNAL_CLASSES, UNCLASSED  (display taxonomy)
+ *   - tierOf(), stageOf()                      (display helpers)
+ *   - detectMode(), MODE_EXPECTED_YIELD, qualityScore()  (mode/quality layer)
+ *   - parsePillars()                           (text → 4 pillars extractor)
+ *
+ * The cascade() wrapper preserves the object-signature
+ * ({ input, output, cacheCreate, cacheRead }) used throughout this repo and
+ * re-attaches the `mode` field (detectMode) that the canonical package
+ * intentionally omits (mode is a presentation-layer concern, not canonical
+ * math).
+ *
+ * Canonical reference: MO§ES Υ 18436.98 from (1251211, 11296121, 128196310, 2555179769).
+ *
+ * Degenerate-input policy (inherited from the canonical package):
  *   - Any pillar that collapses a denominator (i=0, o=0, cw=0, cr=0) returns null for
  *     the affected metrics rather than Infinity/NaN.
  *   - A `warnings[]` array is attached when any metric is null so callers can surface the
@@ -13,76 +28,64 @@
  *     Callers that require a fully-formed result should check `warnings.length === 0`.
  */
 
-export const round = (n, d) =>
-  Number.isFinite(n) ? Number(n.toFixed(d)) : null;
-
-/** The four raw token pillars → the cascade. */
-export function cascade({ input, output, cacheCreate, cacheRead }) {
-  const i = Number(input),
-    o = Number(output),
-    cw = Number(cacheCreate),
-    cr = Number(cacheRead);
-  const total = i + o + cw + cr;
-  const warnings = [];
-
-  // SNR: undefined when both i and o are 0 (empty session)
-  const snrDenom = i + o;
-  const snr = snrDenom > 0 ? o / snrDenom : null;
-  if (snr === null) warnings.push("snr_undefined: input+output=0");
-
-  // velocity: undefined when i=0 (no fresh input — pure cache-only session)
-  const velocity = i > 0 ? o / i : null;
-  if (velocity === null) warnings.push("velocity_undefined: input=0");
-
-  // leverage: undefined when i=0
-  const leverage = i > 0 ? cr / i : null;
-  if (leverage === null) warnings.push("leverage_undefined: input=0");
-
-  // Υ = leverage × velocity = (Cr·O)/I² — null when either component is null
-  const yield_ =
-    leverage !== null && velocity !== null ? leverage * velocity : null;
-  if (yield_ === null && !warnings.some((w) => w.startsWith("yield")))
-    warnings.push("yield_undefined: requires input>0");
+// ─── Canonical math (from @sigrank/cascade) ─────────────────────────────────
+import {
+  cascade as cascadeCanonical,
+  round,
+  classify,
+  RS05_CLASS_THRESHOLDS,
+  fieldStats,
+  percentileOf,
+  rankOf,
+  operatorSignature,
+  evaluateOperator,
+} from "@sigrank/cascade";
 
-  // dev10x = log10(Cr/I) — collapses when cw=0 (no cache commits) or i=0 or cr=0.
-  // narrate.mjs already has a nonCompounding branch for this case; we return null
-  // explicitly so the branch triggers correctly (vs -Infinity on log10(0)).
-  let dev10x = null;
-  if (i > 0 && o > 0 && cw > 0 && cr > 0) {
-    dev10x = Math.log10((o / i) * (cw / o) * (cr / cw)); // = log10(Cr/I)
-  } else {
-    warnings.push("dev10x_undefined: requires all four pillars > 0");
-  }
+// Re-export the canonical functions so existing import paths keep working.
+export {
+  round,
+  classify,
+  RS05_CLASS_THRESHOLDS,
+  fieldStats,
+  percentileOf,
+  rankOf,
+  operatorSignature,
+  evaluateOperator,
+};
 
-  const result = {
-    pillars: { input: i, output: o, cacheCreate: cw, cacheRead: cr, total },
-    yield: round(yield_, 2),
-    snr: round(snr, 4),
-    leverage: round(leverage, 1),
-    velocity: round(velocity, 3),
-    dev10x: round(dev10x, 2),
-    class: classify(total),
-    mode: detectMode({ input: i, output: o, cacheCreate: cw, cacheRead: cr }),
-  };
-  if (warnings.length > 0) result.warnings = warnings;
+/**
+ * The four raw token pillars → the cascade.
+ *
+ * Object-signature wrapper around the canonical `@sigrank/cascade` cascade()
+ * (which takes positional args). Re-attaches the `mode` field via detectMode()
+ * so the 20+ call sites in this repo that read `result.mode` keep working.
+ */
+export function cascade({ input, output, cacheCreate, cacheRead }) {
+  const result = cascadeCanonical(input, output, cacheCreate, cacheRead);
+  // Re-attach mode — the canonical package intentionally omits it (mode is a
+  // presentation-layer concern, not canonical math).
+  result.mode = detectMode({ input, output, cacheCreate, cacheRead });
   return result;
 }
 
+// ─── Local-only display taxonomy (not in @sigrank/cascade) ───────────────────
+
 /**
  * CLASS_TIERS — the 8 base tier names (K.01–K.08) for display: glyph, color,
  * meaning. SINGLE SOURCE OF TRUTH for tier-level display info.
  *
  * The permanent class is an EXPERIENCE ladder keyed on TOTAL TOKENS. Each tier
  * has 3 sub-stages (I/II/III) — 24 stages total. The 24 thresholds live in
- * RS05_CLASS_THRESHOLDS below. classify() returns the full sub-stage string
- * (e.g. "REFINER II"). Use tierOf() to extract the base tier name.
+ * RS05_CLASS_THRESHOLDS (re-exported from @sigrank/cascade above). classify()
+ * returns the full sub-stage string (e.g. "REFINER II"). Use tierOf() to
+ * extract the base tier name.
  *
  * TRANSMITTER is NOT on this ladder — it is a temporary peak badge (RS.08).
  * The client does not evaluate the badge (owner is still calibrating it);
  * the server does it on read.
  *
- * Mirrors the server's canon-ids.ts CLASS_TIERS (display) + ruleset.ts
- * RS05_CLASS_THRESHOLDS (thresholds). Order is descending (ARCH+ → IGNITER).
+ * Mirrors the server's canon-ids.ts CLASS_TIERS (display). Order is descending
+ * (ARCH+ → IGNITER).
  */
 export const CLASS_TIERS = [
   "ARCH+",
@@ -112,42 +115,6 @@ export const SIGNAL_CLASSES = [
   "IGNITER I", "IGNITER II", "IGNITER III",
 ];
 
-/**
- * RS05_CLASS_THRESHOLDS — 24 total-token breakpoints (8 tiers × 3 sub-stages).
- * Mirrors the server's lib/analytics/ruleset.ts RS05_CLASS_THRESHOLDS exactly.
- * Calibrated from the HCM cut (1,626 operators) using target distribution
- * (Option C): IGNITER 10%, BEARER 12.5%, REFINER 15%, SEEKER 22.5%, BASE 20%,
- * POWER 15%, ARCH 5%, ARCH+ 0% (aspirational). Each tier split into 3
- * equal-population sub-stages. Update this one constant to stay in parity
- * when the owner tweaks server-side.
- */
-export const RS05_CLASS_THRESHOLDS = [
-  { class: "ARCH+ I", totalMin: 7068201104627 },
-  { class: "ARCH+ II", totalMin: 3000000000000 },
-  { class: "ARCH+ III", totalMin: 1000000000000 },
-  { class: "ARCH I", totalMin: 186207267611 },
-  { class: "ARCH II", totalMin: 98543134083 },
-  { class: "ARCH III", totalMin: 68766193943 },
-  { class: "POWER I", totalMin: 39958782379 },
-  { class: "POWER II", totalMin: 26955905621 },
-  { class: "POWER III", totalMin: 19141226889 },
-  { class: "BASE I", totalMin: 13960345961 },
-  { class: "BASE II", totalMin: 10189224970 },
-  { class: "BASE III", totalMin: 7747041813 },
-  { class: "SEEKER I", totalMin: 5446673659 },
-  { class: "SEEKER II", totalMin: 4014577247 },
-  { class: "SEEKER III", totalMin: 2961798768 },
-  { class: "REFINER I", totalMin: 2358346840 },
-  { class: "REFINER II", totalMin: 1845750357 },
-  { class: "REFINER III", totalMin: 1334876308 },
-  { class: "BEARER I", totalMin: 984078167 },
-  { class: "BEARER II", totalMin: 714619043 },
-  { class: "BEARER III", totalMin: 431702990 },
-  { class: "IGNITER I", totalMin: 216393332 },
-  { class: "IGNITER II", totalMin: 88999166 },
-  { class: "IGNITER III", totalMin: 0 },
-];
-
 /** The degenerate-case class returned when totalTokens is null/undefined
  *  (all-zero / empty session). Distinct from IGNITER III (which is a real
  *  low-experience tier) so callers can tell "no data" from "bottom tier". */
@@ -174,17 +141,7 @@ export function stageOf(cls) {
   return stage === "I" || stage === "II" || stage === "III" ? stage : null;
 }
 
-/** Classify an operator's experience stage from total tokens (input + output +
- *  cacheCreate + cacheRead). Descending first-match-wins scan over
- *  RS05_CLASS_THRESHOLDS — mirrors the server's assignClass(totalTokens).
- *  Returns a full sub-stage string (e.g. "REFINER II") or UNCLASSED. */
-export function classify(totalTokens) {
-  if (totalTokens == null || !Number.isFinite(totalTokens)) return UNCLASSED;
-  for (const t of RS05_CLASS_THRESHOLDS) {
-    if (totalTokens >= t.totalMin) return t.class;
-  }
-  return "IGNITER III";
-}
+// ─── Mode / quality layer (not in @sigrank/cascade) ──────────────────────────
 
 /**
  * detectMode — classify an operator's current working mode from 4 token pillars.
@@ -262,6 +219,8 @@ export function qualityScore(actualYield, mode) {
   return actualYield / expected;
 }
 
+// ─── Text parsing (not in @sigrank/cascade) ──────────────────────────────────
+
 /**
  * Extract the 4 pillars from pasted text: JSON object OR 4 whitespace numbers.
  *

package/manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json",
   "manifest_version": "0.4",
   "name": "sigrank",
-  "version": "0.0.228",
+  "version": "0.0.230",
   "description": "Ranks AI coding operators by token cascade efficiency (Yield = cache_read \u00d7 output / input\u00b2). 23 tools for yield calculation, local token usage pulls, signed submission, and tokscale-powered analytics (market share, developer profiles, model trends, cost analysis, device profiles, MCP usage, competitive intelligence). Privacy-first: runs locally, only four token counts leave the machine.",
   "author": {
     "name": "SunrisesIllNeverSee",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigrank",
-  "version": "0.0.229",
+  "version": "0.0.231",
   "author": "SunrisesIllNeverSee (https://github.com/SunrisesIllNeverSee)",
   "description": "SigRank MCP server — AI operator evaluation and token cascade efficiency tools. The yield cascade + live leaderboard as MCP tools any agent can call.",
   "mcpName": "io.github.SunrisesIllNeverSee/sigrank-mcp",
@@ -82,6 +82,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "@sigrank/cascade": "^0.1.1",
     "ccusage": "^20.0.19",
     "tokscale": "^4.7.0"
   },