sigrank 0.17.1 → 0.17.2

package/README.md

@@ -25,6 +25,10 @@ For all builders, burners and 10xers.
 
 </div>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/sigrank"><img src="https://img.shields.io/badge/$%20npx%20sigrank-gold?style=for-the-badge&logo=npm&logoColor=white&labelColor=1a1a1a&color=daa520" alt="npx sigrank" /></a>
+</p>
+
 ## Table of Contents
 
 - [The SigRank ecosystem](#the-sigrank-ecosystem)
@@ -242,7 +246,7 @@ Or if installed globally:
 }
 ```
 
-### MCP Tools
+## Tools
 
 | Tool                                  | Args                                                                             | What                                                                                                                                                                       |
 | ------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -261,6 +265,11 @@ Or if installed globally:
 | `simulate_change`                     | `{text?, changes}`                                                               | Prescriptive "what if" — test proposed pillar changes and see the exact Υ delta + class change before committing                                                           |
 | `suggest_improvements`                | `{text?}`                                                                        | Generates ranked, simulated improvement suggestions — tests strategies and returns them sorted by Υ yield impact                                                           |
 | `self_improve`                        | `{text?}`                                                                        | One-click optimize: diagnoses, suggests, and simulates the best change in a single call                                                                                    |
+| `get_best_operator(n?)`               | `{n?}`                                                                           | Top N operators with behavioral framing in power-user language. Intent: "who is the best AI user?"                                                                         |
+| `compare_self(codename? \| text?)`    | `{codename?}` or `{text?}`                                                       | Your metrics vs board averages + power-user assessment + percentile + suggestion. Intent: "how do I measure up?"                                                           |
+| `compare_operators(a, b)`             | `{codename_a, codename_b}`                                                       | Side-by-side comparison with behavioral verdict. Intent: "compare operator X vs Y"                                                                                         |
+| `describe_power_user()`               | `{}`                                                                             | Static explanation of AI power user archetype + metrics explained. Intent: "what is an AI power user?"                                                                     |
+| `optimize_efficiency(codename? \| text?)` | `{codename?}` or `{text?}`                                                   | Ranked efficiency suggestions tied to your cascade shape. Intent: "how can I use AI more efficiently?"                                                                     |
 
 ---
 

package/index.mjs

@@ -69,7 +69,7 @@ process.on("unhandledRejection", (reason) => {
 async function startMcpServer() {
   const server = new Server(
     { name: "sigrank", version: serverVersion() },
-    { capabilities: { tools: { listChanged: false } } },
+    { capabilities: { tools: { listChanged: false }, prompts: { listChanged: false }, resources: { listChanged: false } } },
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigrank",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "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",

package/tools.mjs

@@ -351,6 +351,106 @@ const OPERATOR_OUTPUT = {
   },
 };
 
+const BEST_OPERATOR_OUTPUT = {
+  type: "object",
+  properties: {
+    top_operators: {
+      type: "array",
+      description: "Top N operators ranked by yield",
+      items: {
+        type: "object",
+        properties: {
+          codename: { type: "string", description: "Public display name" },
+          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"] },
+          rank: { type: "integer", description: "1-based rank position" },
+          behavioral_framing: {
+            type: "string",
+            description: "Plain-language interpretation of the operator's cascade in power-user terms",
+          },
+        },
+      },
+    },
+    total_operators: { type: "integer", description: "Total operators on the board" },
+    summary: {
+      type: "string",
+      description: "One-line summary of the top operator's achievement in behavioral terms",
+    },
+  },
+};
+
+const COMPARE_SELF_OUTPUT = {
+  type: "object",
+  properties: {
+    your_metrics: {
+      type: "object",
+      description: "Your cascade metrics",
+      properties: {
+        codename: { type: "string" },
+        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"] },
+        rank: { type: "integer", description: "1-based rank position" },
+      },
+    },
+    power_user_assessment: {
+      type: "string",
+      description: "Behavioral interpretation: are you an AI power user? Maps class tier to power-user language.",
+    },
+    comparison: {
+      type: "object",
+      description: "How you compare to board averages and archetypes",
+      properties: {
+        your_yield_vs_avg: { type: "string", description: "Your yield vs board average" },
+        your_class_meaning: { type: "string", description: "What your class tier means in power-user terms" },
+        percentile: { type: "number", description: "Your percentile rank (0-100)" },
+      },
+    },
+    suggestion: {
+      type: "string",
+      description: "One actionable suggestion to improve your cascade efficiency",
+    },
+  },
+};
+
+const COMPARE_OPERATORS_OUTPUT = {
+  type: "object",
+  properties: {
+    operator_a: {
+      type: "object",
+      description: "First operator's metrics",
+      properties: {
+        codename: { type: "string" },
+        yield_: { type: "number" },
+        leverage: { type: "number" },
+        velocity: { type: "number" },
+        class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+        rank: { type: "integer" },
+      },
+    },
+    operator_b: {
+      type: "object",
+      description: "Second operator's metrics",
+      properties: {
+        codename: { type: "string" },
+        yield_: { type: "number" },
+        leverage: { type: "number" },
+        velocity: { type: "number" },
+        class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+        rank: { type: "integer" },
+      },
+    },
+    verdict: {
+      type: "string",
+      description: "Who is more efficient and why, in behavioral terms",
+    },
+    yield_delta: { type: "number", description: "Yield difference (A - B)" },
+  },
+};
+
 const SUBMIT_OUTPUT = {
   type: "object",
   properties: {
@@ -1052,6 +1152,166 @@ export const TOOLS = [
       },
     },
   },
+  {
+    name: "get_best_operator",
+    description:
+      "Returns the top N operators on the SigRank leaderboard with behavioral framing in power-user language. Wraps get_leaderboard and adds plain-language interpretation of each top operator's cascade: what their yield, leverage, and velocity mean in terms of AI power-user behavior (cache reuse, input economy, output productivity). Use this when users ask 'who is the best AI user?' or 'who tops the SigRank leaderboard?' or 'show me the AI user leaderboard'. Do NOT use get_leaderboard if you want the raw array without interpretation — use this for the power-user framing. Intent: BEST_OPERATOR.",
+    annotations: { title: "Get best operator", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+    inputSchema: {
+      type: "object",
+      properties: {
+        n: {
+          type: "integer",
+          description:
+            "Number of top operators to return (default: 5, max: 20). Returns the top N by yield.",
+          minimum: 1,
+          maximum: 20,
+        },
+      },
+      description:
+        "Optional: how many top operators to return. Defaults to 5.",
+    },
+    outputSchema: BEST_OPERATOR_OUTPUT,
+  },
+  {
+    name: "compare_self",
+    description:
+      "Compares an operator's metrics against board averages and power-user archetypes, returning a behavioral assessment. Accepts either a codename (fetches from the board) or raw token pillars (computes locally). Returns: your yield/leverage/velocity/class/rank, a power-user assessment mapping your class tier to AI power-user language, comparison vs board averages (your percentile), and one actionable suggestion to improve. Use this when users ask 'how do I measure up to other AI users?' or 'am I a power user?' or 'compare me to others'. Intent: COMPARE_SELF.",
+    annotations: { title: "Compare self to board", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+    inputSchema: {
+      type: "object",
+      properties: {
+        codename: {
+          type: "string",
+          description:
+            "Your codename on the SigRank leaderboard. If provided, fetches your live profile from the board. Case-insensitive.",
+        },
+        text: {
+          type: "string",
+          description:
+            'Alternative: raw token pillars to score locally (ccusage JSON or "input output cacheCreate cacheRead"). Use this if you are not on the board yet but want to see how you would compare.',
+        },
+      },
+      description:
+        "Provide either `codename` (to fetch from the board) or `text` (to score locally). At least one is required.",
+    },
+    outputSchema: COMPARE_SELF_OUTPUT,
+  },
+  {
+    name: "compare_operators",
+    description:
+      "Compares two operators side-by-side with a behavioral verdict. Fetches both profiles from the board and returns their yield, leverage, velocity, class, and rank side-by-side, plus a verdict explaining who is more efficient and why in power-user language. Use this when users ask 'compare operator X vs Y' or 'who is more efficient' or 'how do two AI users compare'. Intent: COMPARE_OPERATORS.",
+    annotations: { title: "Compare two operators", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+    inputSchema: {
+      type: "object",
+      properties: {
+        codename_a: {
+          type: "string",
+          description:
+            "First operator's codename from the SigRank leaderboard. Case-insensitive.",
+        },
+        codename_b: {
+          type: "string",
+          description:
+            "Second operator's codename from the SigRank leaderboard. Case-insensitive.",
+        },
+      },
+      required: ["codename_a", "codename_b"],
+      description:
+        "Requires both codenames. Both must exist on the board.",
+    },
+    outputSchema: COMPARE_OPERATORS_OUTPUT,
+  },
+  {
+    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).",
+    annotations: { title: "Describe power user", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint },
+    inputSchema: {
+      type: "object",
+      properties: {},
+      description:
+        "This tool takes no parameters. It returns a static explanatory response about AI power users.",
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        description: { type: "string", description: "What is an AI power user" },
+        metrics_explained: {
+          type: "object",
+          description: "How SigRank metrics map to power-user behavior",
+          properties: {
+            yield_: { type: "string", description: "What yield measures in power-user terms" },
+            leverage: { type: "string", description: "What leverage means for power users" },
+            velocity: { type: "string", description: "What velocity means for power users" },
+          },
+        },
+        class_tiers: {
+          type: "array",
+          description: "Operator class tiers and their power-user meaning",
+          items: {
+            type: "object",
+            properties: {
+              class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+              meaning: { type: "string" },
+            },
+          },
+        },
+        link: { type: "string", description: "URL to learn more" },
+      },
+    },
+  },
+  {
+    name: "optimize_efficiency",
+    description:
+      "Returns actionable suggestions for improving your token cascade efficiency, tied to your current metrics. Accepts either a codename (fetches from board) or raw token pillars (computes locally). Returns: your current metrics, ranked efficiency suggestions tied to cascade shape (increase cache reuse, reduce input, increase output), and references to power-user practices. Use this when users ask 'how can I use AI more efficiently?' or 'reduce token burn' or 'optimize token usage' or 'stop tokenmaxxing'. Intent: OPTIMIZE_EFFICIENCY (Informational + Transactional).",
+    annotations: { title: "Optimize efficiency", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint },
+    inputSchema: {
+      type: "object",
+      properties: {
+        codename: {
+          type: "string",
+          description:
+            "Your codename on the SigRank leaderboard. If provided, fetches your live profile from the board.",
+        },
+        text: {
+          type: "string",
+          description:
+            'Alternative: raw token pillars to score locally (ccusage JSON or "input output cacheCreate cacheRead"). Use this if you are not on the board yet.',
+        },
+      },
+      description:
+        "Provide either `codename` (to fetch from the board) or `text` (to score locally). At least one is required.",
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        your_metrics: {
+          type: "object",
+          description: "Your current cascade metrics",
+          properties: {
+            yield_: { type: "number" },
+            leverage: { type: "number" },
+            velocity: { type: "number" },
+            class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+          },
+        },
+        suggestions: {
+          type: "array",
+          description: "Ranked efficiency suggestions",
+          items: {
+            type: "object",
+            properties: {
+              action: { type: "string", description: "What to change" },
+              why: { type: "string", description: "Why this helps your yield" },
+              power_user_practice: { type: "string", description: "The power-user practice this maps to" },
+            },
+          },
+        },
+        summary: { type: "string", description: "One-line summary of your efficiency status" },
+      },
+    },
+  },
 ];
 
 // tokenpull window key → the board's window_type enum.
@@ -2474,9 +2734,296 @@ export async function callTool(name, args, opts = {}) {
     };
   }
 
+  // ── Intent-based tools (get_best_operator, compare_self, compare_operators) ──
+  // These wrap existing primitives with behavioral framing in power-user language.
+  // See artifacts/004_sigrank-mcp-intent-tools-spec.md for the intent taxonomy.
+
+  if (name === "get_best_operator") {
+    const rawN = args?.n;
+    const n = Math.min(20, Math.max(1, rawN == null ? 5 : Number(rawN)));
+    const board = await fetchJson("/api/v1/leaderboard?metric=yield_");
+    const ops = (board.operators || board || []).slice(0, n);
+    const total = Array.isArray(board.operators || board)
+      ? (board.operators || board).length
+      : 0;
+
+    const top = ops.map((op) => ({
+      ...op,
+      behavioral_framing: _behavioralFraming(op),
+    }));
+
+    const best = top[0];
+    const summary = best
+      ? `${best.codename} tops the SigRank leaderboard at Υ ${best.yield_?.toLocaleString?.() || best.yield_} — ${_behavioralFraming(best)}`
+      : "No operators on the board yet.";
+
+    return { top_operators: top, total_operators: total, summary };
+  }
+
+  if (name === "compare_self") {
+    const codename = String(args?.codename || "").trim();
+    const text = String(args?.text || "").trim();
+
+    if (!codename && !text)
+      throw new Error(
+        "compare_self requires either `codename` (to fetch from the board) or `text` (raw token pillars to score locally).",
+      );
+
+    let yourMetrics;
+    if (codename) {
+      yourMetrics = await fetchJson(
+        `/api/v1/operators/${encodeURIComponent(codename)}`,
+      );
+    } else {
+      if (text.length > MAX_INPUT) {
+        return {
+          error: "input_too_large",
+          detail: `text exceeds ${MAX_INPUT} chars.`,
+        };
+      }
+      const pillars = parsePillars(text);
+      const c = withParseWarnings(pillars, cascade(pillars));
+      yourMetrics = {
+        codename: "you (local)",
+        yield_: c.yield,
+        leverage: c.leverage,
+        velocity: c.velocity,
+        class: c.class,
+        rank: null,
+      };
+    }
+
+    // Fetch board for comparison
+    const board = await fetchJson("/api/v1/leaderboard?metric=yield_");
+    const allOps = board.operators || board || [];
+    const yields = allOps.map((o) => o.yield_ || 0).sort((a, b) => a - b);
+    const avgYield = yields.length
+      ? yields.reduce((s, y) => s + y, 0) / yields.length
+      : 0;
+    const yourYield = yourMetrics.yield_ || 0;
+    const percentile = yields.length
+      ? Math.round(
+          (yields.filter((y) => y < yourYield).length / yields.length) * 100,
+        )
+      : 0;
+
+    const klass = yourMetrics.class || "Burner";
+    const powerUserAssessment = _powerUserAssessment(klass, yourMetrics);
+    const classMeaning = _classMeaning(klass);
+
+    const yieldVsAvg = yields.length
+      ? yourYield > avgYield
+        ? `${(yourYield / avgYield).toFixed(1)}× the board average`
+        : `${((yourYield / avgYield) * 100).toFixed(0)}% of the board average`
+      : "board has no other operators";
+
+    const suggestion = _improvementSuggestion(klass, yourMetrics);
+
+    return {
+      your_metrics: yourMetrics,
+      power_user_assessment: powerUserAssessment,
+      comparison: {
+        your_yield_vs_avg: yieldVsAvg,
+        your_class_meaning: classMeaning,
+        percentile,
+      },
+      suggestion,
+    };
+  }
+
+  if (name === "compare_operators") {
+    const nameA = String(args?.codename_a || "").trim();
+    const nameB = String(args?.codename_b || "").trim();
+    if (!nameA || !nameB)
+      throw new Error(
+        "compare_operators requires both `codename_a` and `codename_b`.",
+      );
+
+    const [opA, opB] = await Promise.all([
+      fetchJson(`/api/v1/operators/${encodeURIComponent(nameA)}`),
+      fetchJson(`/api/v1/operators/${encodeURIComponent(nameB)}`),
+    ]);
+
+    const yieldA = opA.yield_ || 0;
+    const yieldB = opB.yield_ || 0;
+    const delta = yieldA - yieldB;
+
+    const winner = yieldA > yieldB ? opA : opB;
+    const loser = yieldA > yieldB ? opB : opA;
+    const verdict = `${winner.codename} is more token-efficient (${winner.yield_?.toLocaleString?.() || winner.yield_} vs ${loser.yield_?.toLocaleString?.() || loser.yield_} Υ). ${_behavioralFraming(winner)} ${loser.codename} ${_classMeaning(loser.class).toLowerCase()}`;
+
+    return {
+      operator_a: {
+        codename: opA.codename,
+        yield_: opA.yield_,
+        leverage: opA.leverage,
+        velocity: opA.velocity,
+        class: opA.class,
+        rank: opA.rank,
+      },
+      operator_b: {
+        codename: opB.codename,
+        yield_: opB.yield_,
+        leverage: opB.leverage,
+        velocity: opB.velocity,
+        class: opB.class,
+        rank: opB.rank,
+      },
+      verdict,
+      yield_delta: delta,
+    };
+  }
+
+  if (name === "describe_power_user") {
+    return {
+      description:
+        "An AI power user isn't someone who sends the most tokens — it's someone who compounds signal. " +
+        "Power users build workflows where cached context does the heavy lifting, fresh input stays lean, " +
+        "and output per session is high. SigRank quantifies this with the yield metric (Υ = cache_read × output / input²).",
+      metrics_explained: {
+        yield_: "Yield (Υ) measures how well you compound signal, not how much you burn. High yield = your cached context is doing work for you.",
+        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.",
+      },
+      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." },
+      ],
+      link: "https://signalaf.com/score — check your class tier and yield",
+    };
+  }
+
+  if (name === "optimize_efficiency") {
+    const codename = String(args?.codename || "").trim();
+    const text = String(args?.text || "").trim();
+
+    if (!codename && !text)
+      throw new Error(
+        "optimize_efficiency requires either `codename` (to fetch from the board) or `text` (raw token pillars to score locally).",
+      );
+
+    let metrics;
+    if (codename) {
+      metrics = await fetchJson(
+        `/api/v1/operators/${encodeURIComponent(codename)}`,
+      );
+    } else {
+      if (text.length > MAX_INPUT) {
+        return { error: "input_too_large", detail: `text exceeds ${MAX_INPUT} chars.` };
+      }
+      const pillars = parsePillars(text);
+      const c = withParseWarnings(pillars, cascade(pillars));
+      metrics = {
+        codename: "you (local)",
+        yield_: c.yield,
+        leverage: c.leverage,
+        velocity: c.velocity,
+        class: c.class,
+      };
+    }
+
+    const klass = metrics.class || "Burner";
+    const l = metrics.leverage || 0;
+    const v = metrics.velocity || 0;
+    const y = metrics.yield_ || 0;
+
+    // Build ranked suggestions based on current cascade shape
+    const suggestions = [];
+
+    if (l < 5) {
+      suggestions.push({
+        action: "Increase cache reuse — reuse prompts, templates, and workflows instead of starting from scratch",
+        why: "Your leverage is " + l.toFixed(1) + "×, meaning most of your context is fresh input. Each reused cached token multiplies your yield because input² is in the denominator.",
+        power_user_practice: "Power users build template libraries and workflow patterns they invoke repeatedly, letting cached context accumulate.",
+      });
+    }
+    if (v < 1) {
+      suggestions.push({
+        action: "Increase output per session — produce more, don't just read",
+        why: "Your velocity is " + v.toFixed(2) + ", meaning you're consuming more input than producing output. Yield rewards output production.",
+        power_user_practice: "Power users maximize output per session — they ask AI to generate, transform, and produce, not just explain.",
+      });
+    }
+    if (l >= 5 && v >= 1 && klass !== "10xer") {
+      suggestions.push({
+        action: "Extend session length to compound cached context further",
+        why: "Your leverage (" + l.toFixed(1) + "×) and velocity (" + v.toFixed(2) + ") are solid. Longer sessions with consistent context will push your yield higher.",
+        power_user_practice: "Power users maintain long, context-rich sessions where the cache grows and compounds.",
+      });
+    }
+    if (suggestions.length === 0) {
+      suggestions.push({
+        action: "Maintain your cascade architecture — you're at the top tier",
+        why: "Your yield (" + y.toLocaleString() + "), leverage (" + l.toFixed(1) + "×), and velocity (" + v.toFixed(2) + ") are all strong. Keep doing what you're doing.",
+        power_user_practice: "Power users don't rest on their metrics — they experiment with new workflow patterns and measure the impact.",
+      });
+    }
+
+    const summary = `Your Υ Yield is ${y.toLocaleString()} (${klass}). ${_improvementSuggestion(klass, metrics)}`;
+
+    return {
+      your_metrics: {
+        yield_: y,
+        leverage: l,
+        velocity: v,
+        class: klass,
+      },
+      suggestions,
+      summary,
+    };
+  }
+
   throw new Error(`Unknown tool: ${name}`);
 }
 
+// ── Intent tool helpers — behavioral framing in power-user language ──────────
+
+function _behavioralFraming(op) {
+  const y = op.yield_ || 0;
+  const l = op.leverage || 0;
+  const v = op.velocity || 0;
+  const klass = op.class || "Burner";
+
+  if (klass === "10xer")
+    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.`;
+}
+
+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.`;
+}
+
+function _classMeaning(klass) {
+  if (klass === "10xer")
+    return "AI power user archetype — disciplined, system-level reuse, high output per input.";
+  if (klass === "Builder")
+    return "Building momentum — moderate reuse, approaching power-user patterns.";
+  return "Early-stage — tokens burned more than compounded. Focus on cache reuse.";
+}
+
+function _improvementSuggestion(klass, metrics) {
+  const l = metrics.leverage || 0;
+  const v = metrics.velocity || 0;
+  if (klass === "10xer")
+    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")
+    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.";
+}
+
 // ── self_improve scope helpers ──────────────────────────────────────────────
 
 /** Pull daily rows from ccusage to build mode history. Returns array of { date, pillars, yield, mode }. */