sigrank 0.16.1 → 0.17.1

package/README.md

@@ -1,8 +1,8 @@
 # SigRank MCP
 
 > **🏆 SigRank is live: [signalaf.com](https://signalaf.com)** — the leaderboard for how
-> efficiently you use AI, not how much. See your projected rank in 60 seconds at
-> [signalaf.com/score](https://signalaf.com/score). _Token counts only. Never your prompts._
+> efficiently you use AI, not how much. Run `npx sigrank` to see your cascade now.
+> _Token counts only. Never your prompts._
 
 <div align="center">
 
@@ -21,12 +21,13 @@ For all builders, burners and 10xers.
 [![platform](https://img.shields.io/badge/platform-node-grey.svg?style=flat-square)](https://nodejs.org)
 [![live](https://img.shields.io/badge/board-signalaf.com-gold.svg?style=flat-square)](https://signalaf.com)
 [![SunrisesIllNeverSee/sigrank-mcp MCP server](https://glama.ai/mcp/servers/SunrisesIllNeverSee/sigrank-mcp/badges/score.svg)](https://glama.ai/mcp/servers/SunrisesIllNeverSee/sigrank-mcp)
-[![Smithery](https://smithery.ai/badge/burnmydays/sigrank-mcp)](https://smithery.ai/servers/burnmydays/sigrank-mcp)
+[![Smithery](https://smithery.ai/badge/burnmydays/sigrank)](https://smithery.ai/servers/burnmydays/sigrank)
 
 </div>
 
 ## Table of Contents
 
+- [The SigRank ecosystem](#the-sigrank-ecosystem)
 - [Quickstart](#quickstart--3-steps-to-the-board)
 - [Install from GitHub](#install-from-github)
 - [Install via Smithery](#install-via-smithery)
@@ -51,6 +52,16 @@ For all builders, burners and 10xers.
 
 ---
 
+## The SigRank ecosystem
+
+| Repo | What it is | Install |
+|------|-----------|---------|
+| **[sigrank-mcp](https://github.com/SunrisesIllNeverSee/sigrank-mcp)** (this repo) | The instrument — extracts 4 token pillars, computes the cascade, submits to the leaderboard. MCP server + TUI dashboard. | `npx sigrank` |
+| **[sigrank-app](https://github.com/SunrisesIllNeverSee/sigrank-app)** | The leaderboard — signalaf.com. Privacy-preserving operator profiles, class tiers, board rankings. | [signalaf.com](https://signalaf.com) |
+| **[signaf](https://github.com/SunrisesIllNeverSee/signa)** | The coach — reads your session logs, builds a taste profile, measures ASI, coaches you on token efficiency. | `npx @burnmydays/signaf` |
+| **[sigrank-vscode](https://github.com/SunrisesIllNeverSee/sigrank-vscode)** | The IDE extension — see your cascade metrics inline in VS Code. | `code --install-extension sigrank.sigrank` |
+| **[fundscore](https://github.com/SunrisesIllNeverSee/fundscore)** | The repo scorer — investor-readiness scoring for GitHub repos. CLI + MCP server. | `npx fundscore` |
+
 ## Quickstart — 3 steps to the board
 
 ```bash
@@ -95,14 +106,14 @@ sigrank
 **Repo:** [`SunrisesIllNeverSee/sigrank-mcp`](https://github.com/SunrisesIllNeverSee/sigrank-mcp)
 **Site:** [signalaf.com](https://signalaf.com)
 **npm:** [sigrank](https://www.npmjs.com/package/sigrank)
-**Smithery:** [smithery.ai/servers/burnmydays/sigrank-mcp](https://smithery.ai/servers/burnmydays/sigrank-mcp)
+**Smithery:** [smithery.ai/servers/burnmydays/sigrank](https://smithery.ai/servers/burnmydays/sigrank)
 **Glama:** [glama.ai/mcp/servers/SunrisesIllNeverSee/sigrank-mcp](https://glama.ai/mcp/servers/SunrisesIllNeverSee/sigrank-mcp)
 
 ---
 
 ## Install via Smithery
 
-SigRank is available on [Smithery](https://smithery.ai/servers/burnmydays/sigrank-mcp) as a stdio MCP bundle — one-click install for Claude Desktop, Cursor, and other MCP clients.
+SigRank is available on [Smithery](https://smithery.ai/servers/burnmydays/sigrank) as a stdio MCP bundle — one-click install for Claude Desktop, Cursor, and other MCP clients.
 
 ### Smithery CLI
 
@@ -111,7 +122,7 @@ SigRank is available on [Smithery](https://smithery.ai/servers/burnmydays/sigran
 npm install -g smithery
 
 # Connect to SigRank (downloads the MCPB bundle locally)
-smithery mcp add burnmydays/sigrank-mcp --id sigrank
+smithery mcp add burnmydays/sigrank --id sigrank
 
 # List available tools
 smithery tool list sigrank
@@ -123,7 +134,7 @@ smithery tool call sigrank rank_paste '{"text": "1000000 500000 50000 800000"}'
 
 ### Claude Desktop (via Smithery)
 
-1. Go to [smithery.ai/servers/burnmydays/sigrank-mcp](https://smithery.ai/servers/burnmydays/sigrank-mcp)
+1. Go to [smithery.ai/servers/burnmydays/sigrank](https://smithery.ai/servers/burnmydays/sigrank)
 2. Click **Install**
 3. Smithery handles the rest — no manual config editing
 
@@ -132,7 +143,7 @@ smithery tool call sigrank rank_paste '{"text": "1000000 500000 50000 800000"}'
 ## Commands
 
 ```
-⊙ SigRank CLI  v0.16.0
+⊙ SigRank CLI  v0.17.0
 
 Default (no args)
   sigrank              unified dashboard: cascade + token pillars + board

package/index.mjs

@@ -28,6 +28,8 @@ import {
   ListToolsRequestSchema,
   ListPromptsRequestSchema,
   GetPromptRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
   McpError,
   ErrorCode,
 } from "@modelcontextprotocol/sdk/types.js";
@@ -67,7 +69,7 @@ process.on("unhandledRejection", (reason) => {
 async function startMcpServer() {
   const server = new Server(
     { name: "sigrank", version: serverVersion() },
-    { capabilities: { tools: {}, prompts: {} } },
+    { capabilities: { tools: { listChanged: false } } },
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS,
@@ -172,6 +174,202 @@ async function startMcpServer() {
     throw new McpError(ErrorCode.InvalidParams, `Unknown prompt: ${name}`);
   });
 
+  // --- Resources: static context agents can read without calling a tool ---
+  const RESOURCES = [
+    {
+      uri: "sigrank://scoring-formula",
+      name: "SigRank Scoring Formula",
+      description:
+        "The yield cascade formula and all derived metrics: Υ (Yield = Cache Reads × Output / Input²), SNR (signal-to-noise), Leverage (Cr/I), Velocity (O/I), 10xDEV score, and class tier thresholds (Burner / Builder / 10xer).",
+      mimeType: "text/markdown",
+    },
+    {
+      uri: "sigrank://class-tiers",
+      name: "Class Tier Definitions",
+      description:
+        "Definitions and thresholds for the three SigRank operator classes: Burner (raw volume), Builder (balanced efficiency), and 10xer (cascade-optimized). Includes the yield ranges that define each tier.",
+      mimeType: "text/markdown",
+    },
+    {
+      uri: "sigrank://install-guide",
+      name: "Quick Start Guide",
+      description:
+        "Step-by-step install and first submission: npx sigrank → enroll → submit. Covers ccusage/tokscale/tokendash bundled deps, privacy model (token counts only, never prompts), and dry-run workflow.",
+      mimeType: "text/markdown",
+    },
+    {
+      uri: "sigrank://privacy-model",
+      name: "Privacy Model",
+      description:
+        "How SigRank protects user privacy: runs locally, only four token counts (input, output, cacheCreate, cacheRead) leave the machine, ed25519-signed submissions, no prompt content ever transmitted.",
+      mimeType: "text/markdown",
+    },
+  ];
+
+  const RESOURCE_CONTENT = {
+    "sigrank://scoring-formula": `# SigRank Scoring Formula
+
+## Yield (Υ) — the headline metric
+
+\`\`\`
+Υ = Cache Reads × Output / Input²
+\`\`\`
+
+Yield rewards operators who maximize output while minimizing input — and who build cache to amortize that input across sessions. A high yield means you're getting more done with less, efficiently.
+
+## Derived Metrics
+
+| Metric | Formula | Meaning |
+|--------|---------|---------|
+| **SNR** | Output / (Input + CacheCreate) | Signal-to-noise: how much of your token spend is productive output vs. overhead |
+| **Leverage** | Cache Reads / Input | How well you reuse cached context — higher = better cache utilization |
+| **Velocity** | Output / Input | Raw output efficiency — how much output you generate per token of input |
+| **10xDEV** | Composite score | Weighted blend of yield, leverage, and velocity for cross-platform comparison |
+
+## Class Tier Thresholds
+
+| Tier | Yield Range | Profile |
+|------|-------------|---------|
+| **Burner** | Υ < 1.0 | Raw volume — high input, low cache reuse, brute-force output |
+| **Builder** | 1.0 ≤ Υ < 10.0 | Balanced — moderate cache, decent output efficiency |
+| **10xer** | Υ ≥ 10.0 | Cascade-optimized — high cache reads, minimal input, efficient output |
+
+The formula is deterministic and computed locally. No network calls needed for scoring.
+`,
+
+    "sigrank://class-tiers": `# SigRank Class Tiers
+
+Every operator is classified into one of three tiers based on their Yield (Υ = Cache Reads × Output / Input²).
+
+## Burner (Υ < 1.0)
+- **Profile:** Raw volume operators. High input tokens, low cache reuse.
+- **Behavior:** Brute-force — lots of context fed in, relatively little output back.
+- **Typical:** New AI users, verbose prompters, no session continuity.
+- **Fix:** Build cache across sessions. Stop re-explaining context. Use --continue.
+
+## Builder (1.0 ≤ Υ < 10.0)
+- **Profile:** Balanced operators. Moderate cache, decent output efficiency.
+- **Behavior:** Productive — reasonable input-to-output ratio, some cache leverage.
+- **Typical:** Experienced AI coders who use CLAUDE.md, project context, and session continuity.
+- **Fix:** Increase cache reads by reusing sessions. Reduce input by trimming unnecessary context.
+
+## 10xer (Υ ≥ 10.0)
+- **Profile:** Cascade-optimized operators. High cache reads, minimal input, efficient output.
+- **Behavior:** Surgical — minimal new input, maximum cache reuse, high-yield output.
+- **Typical:** Power users with long-running sessions, tight context windows, and aggressive cache strategies.
+- **Maintain:** Keep cache hit rate high. Avoid context bloat. Monitor with watch_tokenpull.
+
+Tiers are recalculated on every submission. Your tier can change between windows (7d, 30d, 90d, all-time).
+`,
+
+    "sigrank://install-guide": `# SigRank Quick Start
+
+## Install
+
+\`\`\`bash
+npx sigrank
+\`\`\`
+
+No global install needed. The MCP server starts automatically when an AI client (Claude, Cursor, Cline) connects.
+
+## First Submission
+
+1. **Enroll** — register your operator codename:
+   \`\`\`bash
+   npx sigrank enroll
+   \`\`\`
+
+2. **Pull + Submit** — scan your local AI session logs and publish:
+   \`\`\`bash
+   npx sigrank submit
+   \`\`\`
+
+3. **Dry Run** — see exactly what would be sent before publishing:
+   \`\`\`bash
+   npx sigrank submit --dry-run
+   \`\`\`
+
+## Token Pull Sources (bundled)
+
+SigRank bundles three token readers as dependencies:
+- **ccusage** — Claude Code session logs
+- **tokscale** — multi-platform token telemetry
+- **tokendash** — dashboard + TUI for token usage
+
+No separate install needed. All three are called automatically by the tokenpull tools.
+
+## MCP Client Setup
+
+Add to your MCP client config:
+\`\`\`json
+{
+  "mcpServers": {
+    "sigrank": {
+      "command": "npx",
+      "args": ["sigrank"]
+    }
+  }
+}
+\`\`\`
+
+## Live Board
+
+Visit https://signalaf.com to see the global leaderboard.
+`,
+
+    "sigrank://privacy-model": `# SigRank Privacy Model
+
+## What leaves your machine
+
+**Only four numbers per submission:**
+- Input tokens
+- Output tokens
+- Cache create tokens
+- Cache read tokens
+
+**That's it.** No prompts, no code, no file contents, no conversation text.
+
+## How it works
+
+1. **Local-first:** All token pulling happens on your machine. SigRank reads session logs from ~/.claude, ~/.codex, ~/.local/share/amp, etc.
+2. **Token counts only:** The MCP tools extract integer counts from log metadata. The actual content of your conversations is never read, parsed, or transmitted.
+3. **Signed submission:** Submissions are ed25519-signed. The board verifies authenticity without seeing your data.
+4. **No auth required:** No API keys, no OAuth, no account needed to read the leaderboard. Enrollment only requires a codename.
+
+## What SigRank can NOT see
+
+- Your prompts or messages
+- Your code or file contents
+- Your tool calls or their results
+- Which AI platform you use (beyond token counts)
+- Your identity (only your chosen codename)
+
+## Verification
+
+The submit_verified tool uses ed25519 signing. The board's source_attestations table records the signature for audit. You can verify your own submissions via get_operator.
+`,
+  };
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: RESOURCES,
+  }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+    const uri = req.params.uri;
+    const content = RESOURCE_CONTENT[uri];
+    if (!content) {
+      throw new McpError(ErrorCode.InvalidParams, `Unknown resource: ${uri}`);
+    }
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/markdown",
+          text: content,
+        },
+      ],
+    };
+  });
+
   await server.connect(new StdioServerTransport());
 }
 

package/package.json

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

package/tools.mjs

@@ -553,6 +553,7 @@ export const TOOLS = [
     description:
       'Computes the SigRank yield cascade from a paste of token counts. Parses the input, runs the full cascade math locally (no network calls), and returns: Υ Yield (the headline efficiency metric, Υ = Cache Reads × Output / Input²), SNR (signal-to-noise ratio), Leverage ratio (Cr/I = cache reads divided by input), Velocity (O/I = output divided by input), 10xDEV score, operator class tier (Burner / Builder / 10xer), and a deterministic prose "card" summarizing the result in plain English. Accepts two input formats: (1) JSON object {"input":N,"output":N,"cacheCreate":N,"cacheRead":N} or (2) four whitespace-separated numbers in order: input output cacheCreate cacheRead. Returns an error if the input is malformed or has negative values. Use this for a quick one-off ranking without submitting to the board. Do NOT use this to submit your score — use submit_paste instead, which both ranks and publishes. Do NOT use this if you want to rank all four time windows at once — use rank_windows for that. After calling this, use submit_paste to publish the result if you want to appear on the leaderboard.',
     annotations: {
+      title: "Rank a paste",
       ...ANNOTATIONS.readOnlyHint,
       ...ANNOTATIONS.destructiveHint,
       ...ANNOTATIONS.idempotentHint,
@@ -577,7 +578,7 @@ export const TOOLS = [
     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.",
-    annotations: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+    annotations: { title: "Get leaderboard", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: "object",
       properties: {},
@@ -590,7 +591,7 @@ export const TOOLS = [
     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.",
-    annotations: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+    annotations: { title: "Get operator profile", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: "object",
       properties: {
@@ -611,6 +612,7 @@ export const TOOLS = [
     description:
       "Ranks a paste of token counts AND publishes it to the live SigRank board at signalaf.com in one call. First computes the cascade locally for an instant preview (yield, leverage, velocity, class, card), then submits the raw paste to the board's web-paste endpoint, which re-parses and re-scores it server-side. The server score is authoritative — it may differ from the local preview if the board applies additional validation. Returns both the local preview and the server response (including the operator's new rank if accepted). A codename is required to publish — omit it for a local preview only (no board submission). Token-only, no auth required. Use this when you have token counts from ccusage or a dashboard and want to both see your score and publish it. Do NOT use this if you want to pull your local usage automatically — use tokenpull_submit for the zero-paste flow. Do NOT use this for multi-window dashboard pastes — use rank_windows to rank them first, then submit each window. After calling this, use get_operator with your codename to verify your submission appeared on the board.",
     annotations: {
+      title: "Submit paste to board",
       ...ANNOTATIONS.destructiveHint,
       ...ANNOTATIONS.idempotentHint,
       ...ANNOTATIONS.openWorldHint,
@@ -639,7 +641,7 @@ export const TOOLS = [
     name: "tokenpull",
     description:
       "Pull your LOCAL token usage from the platform's session logs and rank it across the four windows (7d/30d/90d/all-time) with the cascade — zero paste. Token-only: reads usage counts not message content. The numbers stay on your machine unless you submit them. Some platforms may have partial data (estimated=true when cacheCreate isn't available) or a dataGap note when the log format doesn't expose raw token counts.",
-    annotations: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+    annotations: { title: "Pull local token usage", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: "object",
       properties: {
@@ -657,6 +659,7 @@ export const TOOLS = [
     description:
       "Pull your LOCAL token usage from session logs AND publish it to the SigRank board in one call — the zero-paste flow. Reads the four canonical pillars (input, output, cacheCreate, cacheRead) per window from your local logs, computes the cascade, and submits each window to the board where it is re-scored server-side and tagged with the source platform. Requires a codename to publish; omit for a local preview only. Token-only — no prompt content is read or transmitted.",
     annotations: {
+      title: "Pull and submit tokens",
       ...ANNOTATIONS.destructiveHint,
       ...ANNOTATIONS.idempotentHint,
       ...ANNOTATIONS.openWorldHint,
@@ -689,6 +692,7 @@ export const TOOLS = [
     description:
       "Rank all four time windows (7d/30d/90d/all-time) in one call from a dashboard paste — paste the full table from ccusage, tokscale, or the Claude Max usage dashboard and get the cascade (Υ, SNR, Leverage, Velocity, 10xDEV, class, card) for each window. Each window is parsed and scored independently. Named keys required (input/output/cacheCreate/cacheRead); positional order is NOT safe here (dashboards list cache_read before cache_create — see WINDOWED_PROFILES gotcha). Omit windows you don't have — partial input is allowed (1–4 windows). Does NOT submit to the board; use tokenpull_submit for zero-paste publishing.",
     annotations: {
+      title: "Rank all time windows",
       ...ANNOTATIONS.readOnlyHint,
       ...ANNOTATIONS.idempotentHint,
       ...ANNOTATIONS.openWorldHint,
@@ -759,6 +763,7 @@ export const TOOLS = [
     description:
       "One poll per call: pulls your local token logs and returns the current cascade for the watched window — the tool never blocks or loops. Re-call at your desired cadence to watch for changes (interval_s is advisory only and echoed back as poll_interval_s). With submit:true (and an enrolled device) each call may also sign + publish the watched window to the board, rate-limited to once per 5 min per platform+window; default is preview-only (no submit).",
     annotations: {
+      title: "Watch token pull",
       ...ANNOTATIONS.idempotentHint,
       ...ANNOTATIONS.openWorldHint,
     },
@@ -794,7 +799,7 @@ export const TOOLS = [
     name: "tokenpull_compare",
     description:
       "Pull token usage from ALL four local sources in parallel — tokenpull (JSONL canon), ccusage CLI, token-dashboard SQLite, and tokscale report — and return them side-by-side with delta % vs tokenpull as the baseline. Also computes the cascade (Υ, SNR, Leverage, class) for each source so you can see how each verifier scores. Useful for validating your numbers before submitting, or understanding discrepancies between tools. Claude only for token-dash; codex and others use tokenpull + ccusage + tokscale. Token-only, on-device.",
-    annotations: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+    annotations: { title: "Compare token sources", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: "object",
       properties: {
@@ -813,6 +818,7 @@ export const TOOLS = [
     description:
       'Bind THIS device to your SigRank operator so your signed token runs cascade to the live board. Paste the key from signalaf.com → Settings → "New key" (or "Generate connect code"). On first run it generates + stores a local ed25519 keypair (~/.sigrank-mcp/identity.json); only the PUBLIC key is ever sent. Need a new key? Click "New key" at signalaf.com → Settings, then paste it here.',
     annotations: {
+      title: "Enroll device identity",
       ...ANNOTATIONS.destructiveHint,
       ...ANNOTATIONS.idempotentHint,
       ...ANNOTATIONS.openWorldHint,
@@ -840,6 +846,7 @@ export const TOOLS = [
     description:
       "Publish your LOCAL token runs to the SigRank board as a VERIFIED operator — the enrolled, signed path. Reads your pillars (tokenpull), builds the canonical Schema 1.0 snapshot per window, ed25519-signs it with your device key, and POSTs to /api/v1/snapshots. Requires `npx sigrank-mcp enroll` first (a bound device). Only signed submissions from a trusted device rank on the board. Token-only; the private key never leaves your machine. Pass dry_run:true to inspect the exact signed payload without publishing.",
     annotations: {
+      title: "Submit verified score",
       ...ANNOTATIONS.destructiveHint,
       ...ANNOTATIONS.idempotentHint,
       ...ANNOTATIONS.openWorldHint,
@@ -872,6 +879,7 @@ export const TOOLS = [
     description:
       "The first PRESCRIPTIVE SigRank tool — 'what if I changed my token mix?' Takes your current 4 pillars (input/output/cacheCreate/cacheRead) and one or more proposed changes, runs the canonical cascade on BOTH the current and simulated values, and returns the exact Υ Yield delta, class change, and per-metric diffs. This is the 'show me the payoff before I do the work' primitive: no network, no submission, pure local math. Use it to answer 'would increasing my cache-read by 50k tokens actually move my class?' before you change your workflow. Accepts the current pillars as JSON or 4 numbers (same as rank_paste) plus a `changes` object with any of the 4 pillar names mapped to new absolute values OR relative deltas (e.g. {cacheRead: '+50000'} or {input: 800000}).",
     annotations: {
+      title: "Simulate metric change",
       ...ANNOTATIONS.readOnlyHint,
       ...ANNOTATIONS.idempotentHint,
       ...ANNOTATIONS.openWorldHint,
@@ -921,6 +929,7 @@ export const TOOLS = [
     description:
       "Analyzes your token cascade and diagnoses where you're leaking efficiency. Takes your 4 pillars (input/output/cacheCreate/cacheRead) and produces a ranked list of efficiency leaks with severity (critical/warning/info), findings, and recommendations. Checks: cache leverage (are you rereading what you wrote?), velocity (are you generating enough output per input?), SNR (is your signal drowning in noise?), cache creation ratio (are you over-committing?), input bloat (is fresh input too high?), and 10xDEV (is the full cascade compounding?). Each finding includes an estimated Υ impact. Pure local math — no network, no submission. Use this BEFORE simulate_change to understand what's wrong, then use simulate_change to test fixes. Accepts the same input formats as rank_paste (JSON or 4 whitespace numbers).",
     annotations: {
+      title: "Diagnose cascade breakdown",
       ...ANNOTATIONS.readOnlyHint,
       ...ANNOTATIONS.idempotentHint,
       ...ANNOTATIONS.openWorldHint,
@@ -943,6 +952,7 @@ export const TOOLS = [
     description:
       "Generates ranked, simulated improvement suggestions for your token cascade. Takes your 4 pillars, tests multiple improvement strategies (increase cache reads, reduce fresh input, increase output, optimize cache creation), simulates each with the canonical cascade engine, and returns them ranked by Υ yield impact. Each suggestion includes: the action, which pillar to change, how much to change it, the projected Υ after the change, the yield delta, the projected class tier, and a rationale. Also returns the single highest-impact change (best_single_change). Pure local math — no network, no submission. Use this after diagnose_cascade to get actionable next steps, then use simulate_change to fine-tune before committing. Accepts the same input formats as rank_paste.",
     annotations: {
+      title: "Suggest improvements",
       ...ANNOTATIONS.readOnlyHint,
       ...ANNOTATIONS.idempotentHint,
       ...ANNOTATIONS.openWorldHint,
@@ -965,6 +975,7 @@ export const TOOLS = [
     description:
       "Runs the full self-improvement cycle in one call: (1) gets your current token pillars — either from the provided text or by running tokenpull on your local logs, (2) diagnoses where you're leaking efficiency (diagnose_cascade), (3) generates ranked improvement suggestions (suggest_improvements), (4) simulates the top suggestion (simulate_change), and (5) returns the complete cycle: diagnosis + suggestions + the simulated impact of the best change. This is the 'one-click optimize' tool — call it at the end of a session to see what to improve next time. If you provide pillars in `text`, it skips the tokenpull step. If you omit `text`, it runs tokenpull first (requires local ccusage logs). Pure local math — no network, no submission. The `scope` parameter adds mode detection (BUILD/EDIT/DEBUG/MAINTAIN/IDLE) and scoped analysis: 'daily' (default — current behavior + mode), 'weekly' (compound into weekly snapshots + report artifact), 'trend' (30d/90d trajectory analysis).",
     annotations: {
+      title: "Self-improve plan",
       ...ANNOTATIONS.readOnlyHint,
       ...ANNOTATIONS.idempotentHint,
       ...ANNOTATIONS.openWorldHint,