sigrank 0.0.181 → 0.0.183

package/tools/_framing.mjs

@@ -3,9 +3,55 @@
  *
  * 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, tierOf } from "../analytics/cascade.mjs";
+
+/**
+ * Map a class tier to a power-user band. The 8 experience 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).
+ *
+ *   ARCH+, ARCH           → high    (deep experience, power-user archetype)
+ *   POWER, BASE           → mid     (building momentum)
+ *   SEEKER, REFINER       → early   (accumulating volume, finding patterns)
+ *   BEARER, IGNITER       → entry   (first volume, or dormant)
+ *   UNCLASSED / unknown   → nodata
+ */
+const BAND = {
+  "ARCH+": "high",
+  ARCH: "high",
+  POWER: "mid",
+  BASE: "mid",
+  SEEKER: "early",
+  REFINER: "early",
+  BEARER: "entry",
+  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 (full sub-stage string or base tier) to its power-user
+ *  band. Exported so tool handlers can branch on band without re-deriving the
+ *  tier→band mapping. Uses tierOf() to extract the base tier from sub-stage
+ *  strings (e.g. "REFINER II" → "REFINER" → "early"). */
+export function bandOf(klass) {
+  return BAND[tierOf(klass)] ?? "nodata";
+}
 
 /**
  * Competitive layer for tool responses per SHARED_DESIGN_DECISIONS.md §3/§4/§5.
@@ -57,7 +103,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 +143,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 { SIGNAL_CLASSES, 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. SIGNAL_CLASSES is the 24 sub-stage names (8 tiers
+// × 3 sub-stages I/II/III) that classify() emits and the API returns.
+// 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 = [...SIGNAL_CLASSES, 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 experience tiers (ARCH+ / ARCH / POWER / BASE / SEEKER / REFINER / BEARER / IGNITER, each with 3 sub-stages I/II/III, 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,19 @@ 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 base tiers + UNCLASSED, in descending cut order (matches
+    // analytics/cascade.mjs CLASS_TIERS). Each tier has 3 sub-stages (I/II/III)
+    // — 24 stages total. TRANSMITTER is a peak badge, not a class.
     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: "ARCH+", sub_stages: ["ARCH+ I", "ARCH+ II", "ARCH+ III"], meaning: "Deepest field experience — volume that became architecture. The AI power user archetype." },
+      { class: "ARCH", sub_stages: ["ARCH I", "ARCH II", "ARCH III"], meaning: "System builder — sustained volume, coherent output, heavy cache reuse." },
+      { class: "POWER", sub_stages: ["POWER I", "POWER II", "POWER III"], meaning: "Above the center — volume compounding, building momentum." },
+      { class: "BASE", sub_stages: ["BASE I", "BASE II", "BASE III"], meaning: "The center of the field — the average operator's experience. Building momentum." },
+      { class: "SEEKER", sub_stages: ["SEEKER I", "SEEKER II", "SEEKER III"], meaning: "Approaching the center — experience accumulating, reuse patterns forming." },
+      { class: "REFINER", sub_stages: ["REFINER I", "REFINER II", "REFINER III"], meaning: "Practicing with purpose — early sustained volume, refining context reuse." },
+      { class: "BEARER", sub_stages: ["BEARER I", "BEARER II", "BEARER III"], meaning: "Quiet accumulation — the first real volume. Session continuity starting." },
+      { class: "IGNITER", sub_stages: ["IGNITER I", "IGNITER II", "IGNITER III"], meaning: "Entry — dormant potential. First sessions, minimal accumulated volume." },
+      { class: UNCLASSED, sub_stages: null, 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/diagnose-cascade.mjs

@@ -55,7 +55,7 @@ export async function handleDiagnoseCascade(args) {
       diagnosis.push({
         metric: "cache_leverage",
         severity: "critical",
-        finding: `Cache leverage is ${leverage}× — you're reading only ${leverage}× your fresh input from cache. TRANSMITTER-class operators hit 200×+.`,
+        finding: `Cache leverage is ${leverage}× — you're reading only ${leverage}× your fresh input from cache. Top-tier operators hit 200×+.`,
         recommendation:
           "Increase context reuse: load prior session context, use longer conversation threads, reference earlier outputs.",
         estimated_yield_impact: `+${Math.round((1 - leverage / 50) * 100)}% Υ potential`,

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 24 experience stages: 8 tiers × 3 sub-stages, e.g. ARCH+ I, REFINER II, IGNITER III), and rank position (integer, 1-based). Returns an empty array if no operators have submitted yet. Use this to see where operators stand overall, to find specific codenames for get_operator lookups, or to display the current rankings. Do NOT use this to check your own rank if you already know your codename — use get_operator instead for a single-operator profile with per-window breakdowns. After calling this, follow up with get_operator to get detailed metrics for any operator of interest.",
   annotations: { title: "Get leaderboard", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
   inputSchema: {
     type: "object",
@@ -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 24 experience stages: 8 tiers × 3 sub-stages, e.g. ARCH+ I, REFINER II, IGNITER III), rank position (integer, 1-based), and per-window breakdowns for each time range (7d, 30d, 90d, all-time) with the four canonical pillars (input, output, cacheCreate, cacheRead) per window. Returns an error if the codename is not found on the board. Use this to look up any operator who has submitted to the board — codenames are public and visible on the leaderboard. Do NOT use this to browse all operators — use get_leaderboard for that. After calling this, you can use simulate_change to model what would happen if the operator adjusted their token mix.",
   annotations: { title: "Get operator profile", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
   inputSchema: {
     type: "object",

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() {