sigrank 0.0.181 → 0.0.182

package/tools/_framing.mjs

@@ -3,9 +3,54 @@
  *
  * Power-user language + competitive layer shared by get_best_operator,
  * compare_self, compare_operators, and optimize_efficiency.
+ *
+ * Class-tier language is keyed off the canonical 8-tier dev10x taxonomy
+ * (analytics/cascade.mjs CLASS_TIERS) + UNCLASSED. A prior version branched
+ * on the legacy 3-tier Burner/Builder/10xer names, which the cascade
+ * classifier never emits — every operator was falling through to the
+ * "Burner" branch and getting "you are not yet a power user" framing
+ * regardless of their actual tier. The framing now groups the 8 tiers into
+ * power-user bands (apex / high / mid / early / entry / no-data) and writes
+ * one message per band.
  */
 
 import { DEFAULT_API_BASE } from "./_helpers.mjs";
+import { CLASS_TIERS, UNCLASSED } from "../analytics/cascade.mjs";
+
+/**
+ * Map a class tier to a power-user band. The 8 dev10x tiers collapse into 5
+ * behavioral bands + UNCLASSED so the framing stays short without writing 8
+ * bespoke messages. Band order matches CLASS_TIERS cut order (descending).
+ *
+ *   TRANSMITTER           → apex    (the rare closed-loop operator)
+ *   ARCH+, ARCH           → high    (power-user archetype)
+ *   POWER, BASE           → mid     (building momentum)
+ *   SEEKER, REFINER       → early   (compounding, not yet compounding well)
+ *   IGNITER               → entry   (tokens burned, not compounded)
+ *   UNCLASSED / unknown   → nodata
+ */
+const BAND = {
+  TRANSMITTER: "apex",
+  "ARCH+": "high",
+  ARCH: "high",
+  POWER: "mid",
+  BASE: "mid",
+  SEEKER: "early",
+  REFINER: "early",
+  IGNITER: "entry",
+  [UNCLASSED]: "nodata",
+};
+
+/** Default fallback when a metrics object carries no class — UNCLASSED, not
+ *  the legacy "Burner". Callers that did `metrics.class || "Burner"` were
+ *  silently relabeling every no-data operator as the bottom legacy tier. */
+export const FALLBACK_CLASS = UNCLASSED;
+
+/** Map a class tier to its power-user band. Exported so tool handlers can
+ *  branch on band without re-deriving the tier→band mapping. */
+export function bandOf(klass) {
+  return BAND[klass] ?? "nodata";
+}
 
 /**
  * Competitive layer for tool responses per SHARED_DESIGN_DECISIONS.md §3/§4/§5.
@@ -57,7 +102,7 @@ export function _competitiveLayer(op, board) {
     rank,
     total_operators: total,
     percentile,
-    class_tier: op.class || "Burner",
+    class_tier: op.class || FALLBACK_CLASS,
     delta_from_average: deltaFromAvg,
     delta_from_top: deltaFromTop,
     shareable_url: shareableUrl,
@@ -97,43 +142,75 @@ export function _behavioralFraming(op) {
   const y = op.yield_ || 0;
   const l = op.leverage || 0;
   const v = op.velocity || 0;
-  const klass = op.class || "Burner";
+  const klass = op.class || FALLBACK_CLASS;
+  const band = bandOf(klass);
 
-  if (klass === "10xer")
+  if (band === "apex")
+    return `Closed-loop operator: ${l.toFixed(1)}× leverage over fresh input with ${v.toFixed(2)} output velocity. Both axes held at once — the rare apex profile the leverage/velocity tradeoff says shouldn't exist.`;
+  if (band === "high")
     return `Disciplined, system-level reuse: ${l.toFixed(1)}× leverage means heavy cache reuse over fresh input, ${v.toFixed(2)} velocity means more output per token spent. This is the AI power-user archetype.`;
-  if (klass === "Builder")
-    return `Building cascade momentum: moderate cache reuse (${l.toFixed(1)}× leverage) with ${v.toFixed(2)} output velocity. Approaching power-user patterns — increase cache reuse to push into 10xer territory.`;
-  return `Early-stage cascade: ${v.toFixed(2)} output velocity with ${l.toFixed(1)}× leverage. Tokens are being burned more than compounded. Focus on reusing prior context (templates, prompts, workflows) to build leverage.`;
+  if (band === "mid")
+    return `Building cascade momentum: moderate cache reuse (${l.toFixed(1)}× leverage) with ${v.toFixed(2)} output velocity. Approaching power-user patterns — increase cache reuse to push into the ARCH band.`;
+  if (band === "early")
+    return `Compounding, not yet compounding well: ${v.toFixed(2)} output velocity with ${l.toFixed(1)}× leverage. Cache reuse is starting but input still dominates. Reuse prior context (templates, prompts, workflows) to build leverage.`;
+  if (band === "entry")
+    return `Early-stage cascade: ${v.toFixed(2)} output velocity with ${l.toFixed(1)}× leverage. Tokens are being burned more than compounded. Focus on reusing prior context (templates, prompts, workflows) to build leverage.`;
+  return `No cascade data yet — run a few sessions and re-rank to see your tier. Yield is computed from four token pillars (input, output, cacheCreate, cacheRead).`;
 }
 
 export function _powerUserAssessment(klass, metrics) {
   const l = metrics.leverage || 0;
   const v = metrics.velocity || 0;
-  if (klass === "10xer")
-    return `You are an AI power user. Your SigRank class (10xer) indicates you reuse prior work heavily (${l.toFixed(1)}× leverage), get more out of each token (${v.toFixed(2)} velocity), and keep input lean. This is consistent with AI power-user behavior: iterative, efficient, multi-use patterns.`;
-  if (klass === "Builder")
-    return `You are becoming an AI power user. Your Builder class shows growing cache reuse (${l.toFixed(1)}× leverage) and ${v.toFixed(2)} output velocity. You're building the habits — increase context reuse to push into 10xer territory.`;
-  return `You are not yet an AI power user. Your Burner class means tokens are being spent without compounding. The power-user shift: reuse prior context (prompts, templates, cached results) instead of starting fresh each time. Your leverage (${l.toFixed(1)}×) is the key metric to improve.`;
+  const band = bandOf(klass);
+
+  if (band === "apex")
+    return `You are an apex AI power user. Your SigRank class (${klass}) indicates you reuse prior work heavily (${l.toFixed(1)}× leverage), get more out of each token (${v.toFixed(2)} velocity), and keep input lean — both leverage and velocity held at once.`;
+  if (band === "high")
+    return `You are an AI power user. Your SigRank class (${klass}) indicates you reuse prior work heavily (${l.toFixed(1)}× leverage), get more out of each token (${v.toFixed(2)} velocity), and keep input lean. This is consistent with AI power-user behavior: iterative, efficient, multi-use patterns.`;
+  if (band === "mid")
+    return `You are becoming an AI power user. Your ${klass} class shows growing cache reuse (${l.toFixed(1)}× leverage) and ${v.toFixed(2)} output velocity. You're building the habits — increase context reuse to push into the ARCH band.`;
+  if (band === "early")
+    return `You are starting to compound. Your ${klass} class shows ${l.toFixed(1)}× leverage and ${v.toFixed(2)} velocity — cache reuse is beginning but input still dominates. The power-user shift: reuse prior context instead of starting fresh each time.`;
+  if (band === "entry")
+    return `You are not yet an AI power user. Your ${klass} class means tokens are being spent without compounding. The power-user shift: reuse prior context (prompts, templates, cached results) instead of starting fresh each time. Your leverage (${l.toFixed(1)}×) is the key metric to improve.`;
+  return `No cascade data yet — your tier is ${UNCLASSED}. Run a few sessions, re-rank, and the assessment will reflect your actual leverage and velocity.`;
 }
 
 export function _classMeaning(klass) {
-  if (klass === "10xer")
+  const band = bandOf(klass);
+  if (band === "apex")
+    return "Apex power user — both leverage and velocity held at once. The rare closed-loop operator.";
+  if (band === "high")
     return "AI power user archetype — disciplined, system-level reuse, high output per input.";
-  if (klass === "Builder")
+  if (band === "mid")
     return "Building momentum — moderate reuse, approaching power-user patterns.";
-  return "Early-stage — tokens burned more than compounded. Focus on cache reuse.";
+  if (band === "early")
+    return "Compounding, not yet compounding well — cache reuse starting, input still dominates.";
+  if (band === "entry")
+    return "Early-stage — tokens burned more than compounded. Focus on cache reuse.";
+  return "No data — run sessions and re-rank to see your tier.";
 }
 
 export function _improvementSuggestion(klass, metrics) {
   const l = metrics.leverage || 0;
   const v = metrics.velocity || 0;
-  if (klass === "10xer")
+  const band = bandOf(klass);
+
+  if (band === "apex")
+    return v < 1
+      ? "Your leverage is exceptional but velocity is under 1.0 — you're reading more cache than producing output. Push for more output per session."
+      : "You're at the apex. Maintain your cache architecture and experiment with longer sessions to compound yield further.";
+  if (band === "high")
     return v < 1
       ? "Your leverage is excellent but velocity is under 1.0 — you're reading more cache than producing output. Push for more output per session."
       : "You're at the top tier. Maintain your cache architecture and experiment with longer sessions to compound yield further.";
-  if (klass === "Builder")
+  if (band === "mid")
     return l < 5
       ? "Increase cache reuse: reuse prompts, templates, and workflows instead of starting from scratch. Each reused token multiplies your yield."
       : "Your leverage is solid. Focus on output velocity — produce more per session to push your yield up.";
-  return "Start by reusing prior context. Instead of fresh prompts each time, build on cached results. Even a 2× increase in cache_read will dramatically improve your yield because input² is in the denominator.";
+  if (band === "early")
+    return "Start by reusing prior context. Instead of fresh prompts each time, build on cached results. Even a 2× increase in cache_read will dramatically improve your yield because input² is in the denominator.";
+  if (band === "entry")
+    return "Start by reusing prior context. Instead of fresh prompts each time, build on cached results. Even a 2× increase in cache_read will dramatically improve your yield because input² is in the denominator.";
+  return "No cascade data yet. Run a few sessions so the four token pillars are populated, then re-rank for an actionable suggestion.";
 }

package/tools/_helpers.mjs

@@ -8,10 +8,10 @@
 
 import { createHash } from "node:crypto";
 import { execFile, execFileSync } from "node:child_process";
-import { readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { pkgVersion } from "../lib/pkg-version.mjs";
 import {
   tokenpull as pullLocal,
   tokenpullCodex as pullCodex,
@@ -67,16 +67,11 @@ export function execFileAsync(cmd, args, timeoutMs) {
   });
 }
 
-/** Resolve this package's version for the User-Agent stamp (best-effort). */
+/** Resolve this package's version for the User-Agent stamp (best-effort).
+ *  Thin wrapper over the shared lib/pkg-version.mjs helper so there is exactly
+ *  one version-resolution implementation in the repo. */
 export function agentVersionStamp() {
-  try {
-    const pkg = JSON.parse(
-      readFileSync(new URL("../package.json", import.meta.url), "utf-8"),
-    );
-    return pkg.version;
-  } catch {
-    return "unknown";
-  }
+  return pkgVersion();
 }
 
 /**

package/tools/_schemas.mjs

@@ -2,6 +2,8 @@
  * tools/_schemas.mjs — MCP tool annotation + input/output schema objects.
  */
 
+import { CLASS_TIERS, UNCLASSED } from "../analytics/cascade.mjs";
+
 // Smithery quality: output schemas + annotations
 // MCP tool annotations hint to clients about side-effects, read-only status, etc.
 export const ANNOTATIONS = {
@@ -11,11 +13,25 @@ export const ANNOTATIONS = {
   openWorldHint: { openWorldHint: false },
 };
 
+// The canonical class-tier enum, single-sourced from analytics/cascade.mjs.
+// Every output schema that exposes a `class` field uses this so the enum can
+// never drift between tools (the old schemas each inlined ["Burner","Builder",
+// "10xer"] — a 3-tier legacy that didn't match the 8-tier dev10x classifier
+// the cascade actually emits). UNCLASSED is included for the degenerate
+// no-data case. Exported so tool files that declare their own output schema
+// (optimize-efficiency.mjs, describe-power-user.mjs) import the same enum
+// instead of re-inlining a stale tier list.
+export const CLASS_ENUM = [...CLASS_TIERS, UNCLASSED];
+
 // Common output schema for cascade results (rank_paste, simulate_change, etc.)
+// Field names match the actual cascade() output in analytics/cascade.mjs:
+//   `yield` (not `yield_` — `yield_` was a schema-only alias that didn't match
+//   the real payload), `dev10x` (not `tenx_dev`), `class`, `snr`, `leverage`,
+//   `velocity`, `pillars`, `mode`, `warnings`, plus the tool-added `card`.
 export const CASCADE_OUTPUT = {
   type: "object",
   properties: {
-    yield_: {
+    yield: {
       type: "number",
       description:
         "Υ Yield — the headline efficiency metric (Cache Reads × Output / Input²)",
@@ -26,11 +42,19 @@ export const CASCADE_OUTPUT = {
       description: "Cr/I — cache reads divided by input",
     },
     velocity: { type: "number", description: "O/I — output divided by input" },
-    tenx_dev: { type: "number", description: "10xDEV score" },
+    dev10x: { type: "number", description: "10xDEV score (log10 of the cascade product)" },
     class: {
       type: "string",
-      enum: ["Burner", "Builder", "10xer"],
-      description: "Operator class tier",
+      enum: CLASS_ENUM,
+      description: "Operator class tier (dev10x taxonomy)",
+    },
+    mode: {
+      type: "object",
+      description: "Detected working mode (BUILD/EDIT/DEBUG/MAINTAIN/IDLE) + confidence",
+    },
+    pillars: {
+      type: "object",
+      description: "The four raw token pillars the cascade was computed from",
     },
     card: {
       type: "string",
@@ -42,7 +66,7 @@ export const CASCADE_OUTPUT = {
       description: "Parse or data warnings if any",
     },
   },
-  required: ["yield_", "class"],
+  required: ["yield", "class"],
 };
 
 export const LEADERBOARD_OUTPUT = {
@@ -58,7 +82,7 @@ export const LEADERBOARD_OUTPUT = {
           yield_: { type: "number", description: "Υ Yield metric" },
           leverage: { type: "number", description: "Cr/I ratio" },
           velocity: { type: "number", description: "O/I ratio" },
-          class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+          class: { type: "string", enum: CLASS_ENUM },
           rank: { type: "integer", description: "1-based rank position" },
         },
       },
@@ -73,7 +97,7 @@ export const OPERATOR_OUTPUT = {
     yield_: { type: "number", description: "Υ Yield metric" },
     leverage: { type: "number", description: "Cr/I ratio" },
     velocity: { type: "number", description: "O/I ratio" },
-    class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+    class: { type: "string", enum: CLASS_ENUM },
     rank: { type: "integer", description: "1-based rank position" },
     windows: {
       type: "array",
@@ -110,7 +134,7 @@ export const BEST_OPERATOR_OUTPUT = {
           yield_: { type: "number", description: "Υ Yield metric" },
           leverage: { type: "number", description: "Cr/I ratio" },
           velocity: { type: "number", description: "O/I ratio" },
-          class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+          class: { type: "string", enum: CLASS_ENUM },
           rank: { type: "integer", description: "1-based rank position" },
           behavioral_framing: {
             type: "string",
@@ -138,7 +162,7 @@ export const COMPARE_SELF_OUTPUT = {
         yield_: { type: "number", description: "Υ Yield metric" },
         leverage: { type: "number", description: "Cr/I ratio" },
         velocity: { type: "number", description: "O/I ratio" },
-        class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+        class: { type: "string", enum: CLASS_ENUM },
         rank: { type: "integer", description: "1-based rank position" },
       },
     },
@@ -173,7 +197,7 @@ export const COMPARE_OPERATORS_OUTPUT = {
         yield_: { type: "number" },
         leverage: { type: "number" },
         velocity: { type: "number" },
-        class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+        class: { type: "string", enum: CLASS_ENUM },
         rank: { type: "integer" },
       },
     },
@@ -185,7 +209,7 @@ export const COMPARE_OPERATORS_OUTPUT = {
         yield_: { type: "number" },
         leverage: { type: "number" },
         velocity: { type: "number" },
-        class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+        class: { type: "string", enum: CLASS_ENUM },
         rank: { type: "integer" },
       },
     },
@@ -221,35 +245,41 @@ export const TOKENPULL_OUTPUT = {
   type: "object",
   properties: {
     platform: { type: "string", description: "Source platform name" },
-    generatedAt: { type: "string", description: "ISO timestamp of the pull" },
-    windows: {
-      type: "array",
-      description: "Per-window token usage + cascade results",
-      items: {
-        type: "object",
-        properties: {
-          window: { type: "string", enum: ["7d", "30d", "90d", "all"] },
-          pillars: {
-            type: "object",
-            properties: {
-              input: { type: "integer" },
-              output: { type: "integer" },
-              cacheCreate: { type: "integer" },
-              cacheRead: { type: "integer" },
-            },
-          },
-          messages: {
-            type: "integer",
-            description: "Number of messages in window",
-          },
-          estimated: {
-            type: "boolean",
-            description: "True if cacheCreate was estimated",
-          },
-          cascade: CASCADE_OUTPUT,
-        },
+    window: {
+      type: "string",
+      enum: ["7d", "30d", "90d", "all"],
+      description: "The watched window (watch_tokenpull watches one window per call)",
+    },
+    pillars: {
+      type: "object",
+      description: "The four raw token pillars for the watched window",
+      properties: {
+        input: { type: "integer" },
+        output: { type: "integer" },
+        cacheCreate: { type: "integer" },
+        cacheRead: { type: "integer" },
       },
     },
+    messages: {
+      type: "integer",
+      description: "Number of messages in the watched window",
+    },
+    cascade: CASCADE_OUTPUT,
+    card: { type: "string", description: "Deterministic prose summary" },
+    generatedAt: { type: "string", description: "ISO timestamp of the pull" },
+    poll_interval_s: {
+      type: "number",
+      description: "Advisory poll cadence echoed back (does not make the call block)",
+    },
+    auth_submit: {
+      type: ["object", "null"],
+      description:
+        "Present only when submit:true. One of: {status:'received'|'cooldown'|'not_enrolled'|'error', ...}. Null when submit is false (preview only).",
+    },
+    note: {
+      type: "string",
+      description: "Reminder that one snapshot is returned per call — re-call to detect changes.",
+    },
   },
 };
 

package/tools/compare-operators.mjs

@@ -4,6 +4,7 @@
 
 import { COMPARE_OPERATORS_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
 import { _behavioralFraming, _classMeaning, _competitiveLayer } from "./_framing.mjs";
+import { LEADERBOARD_METRIC } from "../lib/constants.mjs";
 
 export const TOOL_DEF = {
   name: "compare_operators",
@@ -42,7 +43,7 @@ export async function handleCompareOperators(args, ctx) {
   const [opA, opB, board] = await Promise.all([
     ctx.fetchJson(`/api/v1/operators/${encodeURIComponent(nameA)}`),
     ctx.fetchJson(`/api/v1/operators/${encodeURIComponent(nameB)}`),
-    ctx.fetchJson("/api/v1/leaderboard?metric=yield_"),
+    ctx.fetchJson(`/api/v1/leaderboard?metric=${LEADERBOARD_METRIC}`),
   ]);
 
   const yieldA = opA.yield_ || 0;

package/tools/compare-self.mjs

@@ -5,12 +5,14 @@
 import { cascade, parsePillars } from "../analytics/cascade.mjs";
 import { COMPARE_SELF_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
 import { MAX_INPUT, withParseWarnings } from "./_helpers.mjs";
+import { LEADERBOARD_METRIC } from "../lib/constants.mjs";
 import {
   _powerUserAssessment,
   _classMeaning,
   _improvementSuggestion,
   _competitiveLayer,
   _competitiveSummary,
+  FALLBACK_CLASS,
 } from "./_framing.mjs";
 
 export const TOOL_DEF = {
@@ -72,7 +74,7 @@ export async function handleCompareSelf(args, ctx) {
   }
 
   // Fetch board for comparison
-  const board = await ctx.fetchJson("/api/v1/leaderboard?metric=yield_");
+  const board = await ctx.fetchJson(`/api/v1/leaderboard?metric=${LEADERBOARD_METRIC}`);
   const allOps = board.operators || board || [];
   const yields = allOps.map((o) => o.yield_ || 0).sort((a, b) => a - b);
   const avgYield = yields.length
@@ -85,7 +87,7 @@ export async function handleCompareSelf(args, ctx) {
       )
     : 0;
 
-  const klass = yourMetrics.class || "Burner";
+  const klass = yourMetrics.class || FALLBACK_CLASS;
   const powerUserAssessment = _powerUserAssessment(klass, yourMetrics);
   const classMeaning = _classMeaning(klass);
 

package/tools/describe-power-user.mjs

@@ -2,13 +2,14 @@
  * tools/describe-power-user.mjs — describe_power_user tool.
  */
 
-import { ANNOTATIONS } from "./_schemas.mjs";
+import { ANNOTATIONS, CLASS_ENUM } from "./_schemas.mjs";
+import { CLASS_TIERS, UNCLASSED } from "../analytics/cascade.mjs";
 import { DEFAULT_API_BASE } from "./_helpers.mjs";
 
 export const TOOL_DEF = {
   name: "describe_power_user",
   description:
-    "Returns an explanatory description of what makes an AI power user, anchored in SigRank's metrics and operator classes. Explains the yield metric, leverage, velocity, and how class tiers (Burner/Builder/10xer) map to power-user behavior patterns. Use this when users ask 'what is an AI power user?' or 'what makes a good AI user?' or 'describe advanced AI user behavior'. Intent: DESCRIBE_POWER_USER (Informational).",
+    "Returns an explanatory description of what makes an AI power user, anchored in SigRank's metrics and operator classes. Explains the yield metric, leverage, velocity, and how the 8 class tiers (TRANSMITTER / ARCH+ / ARCH / POWER / BASE / SEEKER / REFINER / IGNITER, plus UNCLASSED for no-data) map to power-user behavior patterns. Use this when users ask 'what is an AI power user?' or 'what makes a good AI user?' or 'describe advanced AI user behavior'. Intent: DESCRIBE_POWER_USER (Informational).",
   annotations: { title: "Describe power user", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint },
   inputSchema: {
     type: "object",
@@ -35,7 +36,7 @@ export const TOOL_DEF = {
         items: {
           type: "object",
           properties: {
-            class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+            class: { type: "string", enum: CLASS_ENUM },
             meaning: { type: "string" },
           },
         },
@@ -56,10 +57,20 @@ export async function handleDescribePowerUser() {
       leverage: "Leverage (Cr/I) measures how much you reuse prior work vs starting fresh. High leverage = you're building on cached results, not re-explaining everything.",
       velocity: "Velocity (O/I) measures how much output you get per token spent. High velocity = you're productive, not just active.",
     },
+    // The 8-tier dev10x taxonomy + UNCLASSED, in descending cut order
+    // (matches analytics/cascade.mjs CLASS_TIERS). Each tier carries a
+    // one-line power-user meaning. The legacy 3-tier Burner/Builder/10xer
+    // list is retired — the classifier never emitted those names.
     class_tiers: [
-      { class: "10xer", meaning: "AI power user archetype — disciplined, system-level reuse, high output per input. Leverage > 10×, high velocity." },
-      { class: "Builder", meaning: "Building momentum — moderate cache reuse, approaching power-user patterns. Growing leverage and velocity." },
-      { class: "Burner", meaning: "Early-stage — tokens burned more than compounded. Low leverage, low velocity. The shift: reuse prior context." },
+      { class: "TRANSMITTER", meaning: "Apex power user — both leverage and velocity held at once. The rare closed-loop operator." },
+      { class: "ARCH+", meaning: "AI power user archetype — disciplined, system-level reuse, high output per input." },
+      { class: "ARCH", meaning: "Power user — heavy cache reuse and strong output velocity." },
+      { class: "POWER", meaning: "Building momentum — moderate-to-high cache reuse, approaching the ARCH band." },
+      { class: "BASE", meaning: "Building momentum — cache reuse starting, velocity solid. Increase reuse to climb." },
+      { class: "SEEKER", meaning: "Compounding, not yet compounding well — cache reuse beginning but input still dominates." },
+      { class: "REFINER", meaning: "Early compounding — low leverage, refining context reuse habits." },
+      { class: "IGNITER", meaning: "Entry — tokens burned more than compounded. The shift: reuse prior context." },
+      { class: UNCLASSED, meaning: "No cascade data yet — run sessions and re-rank to see your tier." },
     ],
     link: "https://signalaf.com/score — check your class tier and yield",
     shareable_url: `${DEFAULT_API_BASE}/score`,

package/tools/enroll.mjs

@@ -5,9 +5,7 @@
 import os from "node:os";
 import { ensureIdentity, recordEnrollment } from "../identity/keystore.mjs";
 import { ENROLL_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
-
-const TERMS_VERSION = "2026-07-21";
-const PRIVACY_VERSION = "2026-07-21";
+import { TERMS_VERSION, PRIVACY_VERSION } from "../lib/constants.mjs";
 
 export const TOOL_DEF = {
   name: "enroll",

package/tools/get-best-operator.mjs

@@ -5,6 +5,7 @@
 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",
@@ -31,7 +32,7 @@ export const TOOL_DEF = {
 export async function handleGetBestOperator(args, ctx) {
   const rawN = args?.n;
   const n = Math.min(20, Math.max(1, rawN == null ? 5 : Number(rawN)));
-  const board = await ctx.fetchJson("/api/v1/leaderboard?metric=yield_");
+  const 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

package/tools/get-leaderboard.mjs

@@ -3,11 +3,12 @@
  */
 
 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 (Burner / Builder / 10xer), and rank position (integer, 1-based). Returns an empty array if no operators have submitted yet. Use this to see where operators stand overall, to find specific codenames for get_operator lookups, or to display the current rankings. Do NOT use this to check your own rank if you already know your codename — use get_operator instead for a single-operator profile with per-window breakdowns. After calling this, follow up with get_operator to get detailed metrics for any operator of interest.",
+    "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 the 8 dev10x tiers: TRANSMITTER / ARCH+ / ARCH / POWER / BASE / SEEKER / REFINER / IGNITER), 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",
@@ -19,7 +20,7 @@ export const TOOL_DEF = {
 };
 
 export async function handleGetLeaderboard(args, ctx) {
-  const params = new URLSearchParams({ metric: "yield_" });
+  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

@@ -7,7 +7,7 @@ import { OPERATOR_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
 export const TOOL_DEF = {
   name: "get_operator",
   description:
-    "Fetches one operator's live profile from the SigRank board by their codename. Reads the operator's current submission data from signalaf.com and returns their detailed metrics: yield (Υ), leverage ratio (Cr/I), velocity (O/I), class tier (Burner / Builder / 10xer), rank position (integer, 1-based), and per-window breakdowns for each time range (7d, 30d, 90d, all-time) with the four canonical pillars (input, output, cacheCreate, cacheRead) per window. Returns an error if the codename is not found on the board. Use this to look up any operator who has submitted to the board — codenames are public and visible on the leaderboard. Do NOT use this to browse all operators — use get_leaderboard for that. After calling this, you can use simulate_change to model what would happen if the operator adjusted their token mix.",
+    "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 the 8 dev10x tiers: TRANSMITTER / ARCH+ / ARCH / POWER / BASE / SEEKER / REFINER / IGNITER), 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",

package/tools/index.mjs

@@ -9,6 +9,7 @@
 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 } from "../lib/constants.mjs";
 
 import { TOOL_DEF as rankPasteTool, handleRankPaste } from "./rank-paste.mjs";
 import { TOOL_DEF as getLeaderboardTool, handleGetLeaderboard } from "./get-leaderboard.mjs";
@@ -69,48 +70,9 @@ export const TOOLS = [
   tokscaleCompetitiveIntelTool,
 ];
 
-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,
-};
+// 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() {