sigrank 0.15.4 → 0.16.0

package/tools.mjs

@@ -8,7 +8,8 @@
  * narration card in ./narrate.mjs. Token-only, no transcript content.
  */
 
-import { cascade, parsePillars } from './cascade.mjs'
+import { cascade, parsePillars, detectMode, qualityScore, MODE_EXPECTED_YIELD } from './cascade.mjs'
+import { computeBadges } from './badges.mjs'
 import { narrate } from './narrate.mjs'
 import { tokenpull as pullLocal, tokenpullCodex as pullCodex, tokenpullAny } from './tokenpull.mjs'
 import { ALL_PLATFORMS } from './adapters.mjs'
@@ -165,11 +166,221 @@ export const DEFAULT_FETCH_TIMEOUT = Number(process.env.SIGRANK_FETCH_TIMEOUT) |
  *  past this is malformed or abusive — reject cleanly before parsing/POSTing (E2 hardening). */
 const MAX_INPUT = 1_000_000
 
+// ── Smithery quality: output schemas + annotations ──────────────────────────
+// MCP tool annotations hint to clients about side-effects, read-only status, etc.
+const ANNOTATIONS = {
+  readOnlyHint: { readOnlyHint: true },
+  destructiveHint: { destructiveHint: false },
+  idempotentHint: { idempotentHint: true },
+  openWorldHint: { openWorldHint: false },
+}
+
+// Common output schema for cascade results (rank_paste, simulate_change, etc.)
+const CASCADE_OUTPUT = {
+  type: 'object',
+  properties: {
+    yield_: { type: 'number', description: 'Υ Yield — the headline efficiency metric (Cache Reads × Output / Input²)' },
+    snr: { type: 'number', description: 'Signal-to-noise ratio' },
+    leverage: { type: 'number', 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' },
+    class: { type: 'string', enum: ['Burner', 'Builder', '10xer'], description: 'Operator class tier' },
+    card: { type: 'string', description: 'Deterministic prose summary of the cascade result' },
+    warnings: { type: 'array', items: { type: 'string' }, description: 'Parse or data warnings if any' },
+  },
+  required: ['yield_', 'class'],
+}
+
+const LEADERBOARD_OUTPUT = {
+  type: 'object',
+  properties: {
+    operators: {
+  type: 'array',
+  description: 'Array of ranked operators sorted 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' },
+    },
+  },
+    },
+  },
+}
+
+const OPERATOR_OUTPUT = {
+  type: 'object',
+  properties: {
+    codename: { type: 'string', description: 'Operator 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' },
+    windows: {
+      type: 'array',
+      description: 'Per-window breakdowns (7d, 30d, 90d, all-time)',
+      items: {
+        type: 'object',
+        properties: {
+          window: { type: 'string', enum: ['7d', '30d', '90d', 'all_time'] },
+          pillars: {
+            type: 'object',
+            properties: {
+              input: { type: 'integer' },
+              output: { type: 'integer' },
+              cacheCreate: { type: 'integer' },
+              cacheRead: { type: 'integer' },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+
+const SUBMIT_OUTPUT = {
+  type: 'object',
+  properties: {
+    status: { type: 'string', enum: ['ok', 'error', 'skipped'], description: 'Submission status' },
+    preview: CASCADE_OUTPUT,
+    server_response: { type: 'object', description: 'Server-side response including new rank if accepted' },
+    reason: { type: 'string', description: 'Error or skip reason if status is not ok' },
+  },
+}
+
+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,
+        },
+      },
+    },
+  },
+}
+
+const ENROLL_OUTPUT = {
+  type: 'object',
+  properties: {
+    status: { type: 'string', enum: ['enrolled', 'error'], description: 'Enrollment result' },
+    codename: { type: 'string', description: 'Operator codename if enrolled' },
+    operator_id: { type: 'string', description: 'Operator ID if enrolled' },
+    device_id: { type: 'string', description: 'Local device ID' },
+    trust_status: { type: 'string', description: 'Trust level of the device' },
+    reason: { type: 'string', description: 'Error reason if status is error' },
+  },
+}
+
+const COMPARE_OUTPUT = {
+  type: 'object',
+  properties: {
+    platform: { type: 'string' },
+    sources: {
+      type: 'array',
+      description: 'Side-by-side comparison of each token source',
+      items: {
+        type: 'object',
+        properties: {
+          source: { type: 'string', description: 'Source name (tokenpull, ccusage, token-dash, tokscale)' },
+          pillars: { type: 'object' },
+          cascade: CASCADE_OUTPUT,
+          delta_pct: { type: 'object', description: 'Delta % vs tokenpull baseline' },
+        },
+      },
+    },
+  },
+}
+
+const SIMULATE_OUTPUT = {
+  type: 'object',
+  properties: {
+    current: CASCADE_OUTPUT,
+    simulated: CASCADE_OUTPUT,
+    yield_delta: { type: 'number', description: 'Υ Yield change (simulated - current)' },
+    class_change: { type: 'string', description: 'Class tier change description' },
+    metric_diffs: { type: 'object', description: 'Per-metric before/after diffs' },
+  },
+}
+
+const DIAGNOSE_OUTPUT = {
+  type: 'object',
+  properties: {
+    pillars: { type: 'object', description: 'The 4 raw token pillars' },
+    cascade: CASCADE_OUTPUT,
+    diagnosis: {
+      type: 'array',
+      description: 'Ranked list of efficiency leaks found, worst first',
+      items: {
+        type: 'object',
+        properties: {
+          metric: { type: 'string', description: 'Which metric is underperforming' },
+          severity: { type: 'string', enum: ['critical', 'warning', 'info'], description: 'How bad the leak is' },
+          finding: { type: 'string', description: 'What the analysis found' },
+          recommendation: { type: 'string', description: 'What to do about it' },
+          estimated_yield_impact: { type: 'string', description: 'Estimated Υ improvement if fixed' },
+        },
+      },
+    },
+    summary: { type: 'string', description: 'One-line summary of the operator\'s cascade health' },
+  },
+}
+
+const SUGGEST_OUTPUT = {
+  type: 'object',
+  properties: {
+    suggestions: {
+      type: 'array',
+      description: 'Ranked recommendations, highest Υ impact first',
+      items: {
+        type: 'object',
+        properties: {
+          rank: { type: 'number', description: '1-based rank by Υ impact' },
+          action: { type: 'string', description: 'What to change' },
+          pillar: { type: 'string', description: 'Which pillar to adjust' },
+          delta: { type: 'string', description: 'How much to change it' },
+          simulated_yield: { type: 'number', description: 'Projected Υ after the change' },
+          yield_delta: { type: 'number', description: 'Υ change vs current' },
+          class_after: { type: 'string', description: 'Projected class after the change' },
+          rationale: { type: 'string', description: 'Why this helps' },
+        },
+      },
+    },
+    current_yield: { type: 'number', description: 'Current Υ before any changes' },
+    current_class: { type: 'string', description: 'Current class tier' },
+    best_single_change: { type: 'string', description: 'The single highest-impact change' },
+  },
+}
+
 export const TOOLS = [
   {
     name: 'rank_paste',
     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: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.destructiveHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: 'object',
       properties: {
@@ -181,21 +392,25 @@ export const TOOLS = [
       required: ['text'],
       description: 'Requires the token counts as a string. No other parameters are accepted.',
     },
+    outputSchema: CASCADE_OUTPUT,
   },
   {
     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 },
     inputSchema: {
       type: 'object',
       properties: {},
       description: 'This tool takes no parameters. It always fetches the full public leaderboard.',
     },
+    outputSchema: LEADERBOARD_OUTPUT,
   },
   {
     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 },
     inputSchema: {
       type: 'object',
       properties: {
@@ -207,11 +422,13 @@ export const TOOLS = [
       required: ['codename'],
       description: 'Requires the operator\'s codename. No other parameters are accepted.',
     },
+    outputSchema: OPERATOR_OUTPUT,
   },
   {
     name: 'submit_paste',
     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: { ...ANNOTATIONS.destructiveHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: 'object',
       properties: {
@@ -227,11 +444,13 @@ export const TOOLS = [
       required: ['text'],
       description: 'Requires token counts (text). Codename is optional but required for board submission — omit it for preview-only mode.',
     },
+    outputSchema: SUBMIT_OUTPUT,
   },
   {
     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 },
     inputSchema: {
       type: 'object',
       properties: {
@@ -242,11 +461,13 @@ export const TOOLS = [
         },
       },
     },
+    outputSchema: TOKENPULL_OUTPUT,
   },
   {
     name: 'tokenpull_submit',
     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: { ...ANNOTATIONS.destructiveHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: 'object',
       properties: {
@@ -266,11 +487,13 @@ export const TOOLS = [
         },
       },
     },
+    outputSchema: SUBMIT_OUTPUT,
   },
   {
     name: 'rank_windows',
     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: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: 'object',
       properties: {
@@ -283,11 +506,28 @@ export const TOOLS = [
       // at least one window paste is required (runtime check backs this up)
       anyOf: [{ required: ['7d'] }, { required: ['30d'] }, { required: ['90d'] }, { required: ['all'] }],
     },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        windows: {
+          type: 'array',
+          description: 'Cascade results per window',
+          items: {
+            type: 'object',
+            properties: {
+              window: { type: 'string', enum: ['7d', '30d', '90d', 'all'] },
+              ...CASCADE_OUTPUT.properties,
+            },
+          },
+        },
+      },
+    },
   },
   {
     name: 'watch_tokenpull',
     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: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: 'object',
       properties: {
@@ -297,11 +537,13 @@ export const TOOLS = [
         submit:      { type: 'boolean', description: 'auto-submit the watched window to the board as a VERIFIED operator each poll (requires `enroll`; default false = preview only)' },
       },
     },
+    outputSchema: TOKENPULL_OUTPUT,
   },
   {
     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 },
     inputSchema: {
       type: 'object',
       properties: {
@@ -312,11 +554,13 @@ export const TOOLS = [
         },
       },
     },
+    outputSchema: COMPARE_OUTPUT,
   },
   {
     name: 'enroll',
     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: { ...ANNOTATIONS.destructiveHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: 'object',
       properties: {
@@ -325,11 +569,13 @@ export const TOOLS = [
       },
       required: ['code'],
     },
+    outputSchema: ENROLL_OUTPUT,
   },
   {
     name: 'submit_verified',
     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: { ...ANNOTATIONS.destructiveHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: 'object',
       properties: {
@@ -338,11 +584,13 @@ export const TOOLS = [
         dry_run: { type: 'boolean', description: 'build + sign but do NOT publish — returns the exact payload that would be POSTed (token counts only), so you can inspect before submitting' },
       },
     },
+    outputSchema: SUBMIT_OUTPUT,
   },
   {
     name: 'simulate_change',
     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: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
     inputSchema: {
       type: 'object',
       properties: {
@@ -363,6 +611,84 @@ export const TOOLS = [
       },
       required: ['text', 'changes'],
     },
+    outputSchema: SIMULATE_OUTPUT,
+  },
+  {
+    name: 'diagnose_cascade',
+    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: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: {
+          type: 'string',
+          description: 'Token pillars — ccusage JSON or "input output cacheCreate cacheRead" (same format as rank_paste).',
+        },
+      },
+      required: ['text'],
+    },
+    outputSchema: DIAGNOSE_OUTPUT,
+  },
+  {
+    name: 'suggest_improvements',
+    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: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: {
+          type: 'string',
+          description: 'Token pillars — ccusage JSON or "input output cacheCreate cacheRead" (same format as rank_paste).',
+        },
+      },
+      required: ['text'],
+    },
+    outputSchema: SUGGEST_OUTPUT,
+  },
+  {
+    name: 'self_improve',
+    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: { ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint, ...ANNOTATIONS.openWorldHint },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: {
+          type: 'string',
+          description: 'Optional: token pillars — ccusage JSON or "input output cacheCreate cacheRead". If omitted, runs tokenpull to get current pillars from local logs.',
+        },
+        window: {
+          type: 'string',
+          enum: ['7d', '30d', '90d', 'all'],
+          description: 'Which time window to pull when running tokenpull (default: 30d). Ignored if `text` is provided.',
+        },
+        scope: {
+          type: 'string',
+          enum: ['daily', 'weekly', 'trend'],
+          description: 'Analysis scope: "daily" (default — current behavior + mode detection), "weekly" (compound daily rows into weekly snapshots + report artifact with badges), "trend" (30d/90d trajectory + phase patterns). Daily modes never leave the machine — only weekly distribution goes in submitted reports.',
+        },
+      },
+    },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        pillars: { type: 'object', description: 'The 4 raw token pillars used' },
+        current_cascade: CASCADE_OUTPUT,
+        diagnosis: { type: 'array', description: 'Efficiency leaks found (from diagnose_cascade)' },
+        suggestions: { type: 'array', description: 'Ranked improvements (from suggest_improvements)' },
+        best_simulation: { type: 'object', description: 'Simulated result of the top suggestion' },
+        cycle_summary: { type: 'string', description: 'One-line summary of the full cycle' },
+        // Scope-specific fields
+        mode: { type: 'object', description: 'Detected mode { mode, confidence } — present when scope is daily/weekly/trend' },
+        quality_score: { type: 'number', description: 'Yield relative to mode expectation (daily scope)' },
+        assessment: { type: 'string', description: 'One-line assessment for daily scope' },
+        advice: { type: 'string', description: 'Advice for next session (daily scope)' },
+        report: { type: 'object', description: 'Weekly report artifact (weekly scope)' },
+        trend: { type: 'object', description: 'Trend analysis (trend scope)' },
+      },
+    },
   },
 ]
 
@@ -521,7 +847,8 @@ export async function callTool(name, args, opts = {}) {
           msgs += w.messages || 0
         }
         if (sum.input + sum.output + sum.cacheCreate + sum.cacheRead <= 0) continue // skip empty window
-        const r = await submitSignedWindow(wk, sum, msgs, id, { apiBase, fetchImpl: doFetch, platform: 'multi', now: opts.now, dryRun: !!args?.dry_run })
+        const report = _computeReportBlock(sum)
+        const r = await submitSignedWindow(wk, sum, msgs, id, { apiBase, fetchImpl: doFetch, platform: 'multi', now: opts.now, dryRun: !!args?.dry_run, report })
         out.push({ window: wk, pillars: sum, ...r })
       }
       return { platform: 'multi', codename: id.codename, operator_id: id.operator_id, sources: detected.map((d) => d.platform), windows: out }
@@ -531,12 +858,16 @@ export async function callTool(name, args, opts = {}) {
     const targets = args?.window ? pulled.windows.filter((w) => w.window === args.window) : pulled.windows
     const out = []
     for (const w of targets) {
+      // Compute the cascade report block (mode + badges + health) for this window.
+      // Pure math, computed locally, submitted alongside the 4 token pillars.
+      const report = _computeReportBlock(w.pillars)
       const r = await submitSignedWindow(w.window, w.pillars, w.messages, id, {
         apiBase,
         fetchImpl: doFetch,
         platform: pulled.platform,
         now: opts.now,
         dryRun: !!args?.dry_run,
+        report,
       })
       out.push({ window: w.window, pillars: w.pillars, ...r })
     }
@@ -898,5 +1229,742 @@ export async function callTool(name, args, opts = {}) {
     }
   }
 
+  if (name === 'diagnose_cascade') {
+    if (!args?.text) throw new Error('diagnose_cascade requires a non-empty `text` argument (token pillars).')
+    if (typeof args.text === 'string' && args.text.length > MAX_INPUT) {
+      return { status: 'error', reason: 'input_too_large', detail: `text exceeds ${MAX_INPUT} chars.` }
+    }
+
+    const p = parsePillars(args.text)
+    const result = withParseWarnings(p, cascade(p))
+    const { input: i, output: o, cacheCreate: cw, cacheRead: cr } = p
+    const diagnosis = []
+
+    // Cache leverage check — the #1 cascade efficiency signal
+    const leverage = result.leverage
+    if (leverage !== null) {
+      if (leverage < 10) {
+        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×+.`,
+          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`,
+        })
+      } else if (leverage < 50) {
+        diagnosis.push({
+          metric: 'cache_leverage',
+          severity: 'warning',
+          finding: `Cache leverage is ${leverage}× — decent but below the ARCH+ threshold (~100×+).`,
+          recommendation: 'Push cache reads higher by reusing prior context more aggressively.',
+          estimated_yield_impact: `+${Math.round((1 - leverage / 100) * 50)}% Υ potential`,
+        })
+      }
+    }
+
+    // Velocity check — output per input
+    const velocity = result.velocity
+    if (velocity !== null) {
+      if (velocity < 0.5) {
+        diagnosis.push({
+          metric: 'velocity',
+          severity: 'critical',
+          finding: `Velocity is ${velocity} — generating only ${velocity}× your input as output. You're reading more than you produce.`,
+          recommendation: 'Increase output: ask the agent to generate more code/text per turn, reduce over-reading.',
+          estimated_yield_impact: `+${Math.round((0.5 - velocity) * 100)}% Υ per 0.1 velocity gain`,
+        })
+      } else if (velocity < 1.0) {
+        diagnosis.push({
+          metric: 'velocity',
+          severity: 'warning',
+          finding: `Velocity is ${velocity} — below 1.0 (output < input). Healthy operators hit 1.5×+.`,
+          recommendation: 'Generate more output per input token — larger edits, more complete responses.',
+          estimated_yield_impact: `+${Math.round((1 - velocity) * 30)}% Υ potential`,
+        })
+      }
+    }
+
+    // SNR check — signal-to-noise
+    const snr = result.snr
+    if (snr !== null && snr < 0.3) {
+      diagnosis.push({
+        metric: 'snr',
+        severity: 'warning',
+        finding: `SNR is ${snr} — less than 30% of your token flow is output. Input is dominating.`,
+        recommendation: 'Reduce fresh input (reuse context) or increase output generation.',
+        estimated_yield_impact: 'Indirect — improves both velocity and leverage',
+      })
+    }
+
+    // Cache creation ratio — are you over-committing?
+    if (cw > 0 && o > 0) {
+      const commitRatio = cw / o
+      if (commitRatio > 20) {
+        diagnosis.push({
+          metric: 'cache_creation',
+          severity: 'info',
+          finding: `Cache creation is ${commitRatio.toFixed(1)}× your output — high commitment. This is fine if you're rereading it (check leverage), but wasteful if not.`,
+          recommendation: "Ensure you're rereading committed context. If leverage is low, you're writing cache you never read.",
+          estimated_yield_impact: 'Cost reduction, not Υ directly',
+        })
+      }
+    }
+
+    // Input bloat — is fresh input too high relative to total?
+    const total = i + o + cw + cr
+    if (total > 0) {
+      const inputPct = (i / total) * 100
+      if (inputPct > 10) {
+        diagnosis.push({
+          metric: 'input_bloat',
+          severity: 'warning',
+          finding: `Fresh input is ${inputPct.toFixed(1)}% of your total token flow — high. Efficient operators keep input under 1% by leaning on cache.`,
+          recommendation: 'Reduce fresh input by reusing prior context instead of re-pasting it.',
+          estimated_yield_impact: `+${Math.round((inputPct - 1) * 5)}% Υ potential`,
+        })
+      }
+    }
+
+    // 10xDEV check — is the full cascade compounding?
+    if (result.dev10x === null && cw === 0) {
+      diagnosis.push({
+        metric: '10xdev',
+        severity: 'critical',
+        finding: "No cache creation — the cascade cannot compound. You're operating in a non-compounding mode (like ChatGPT without prompt caching).",
+        recommendation: 'Switch to a platform with prompt caching (Claude Code) or enable caching if available.',
+        estimated_yield_impact: 'Enables the full cascade — potentially 10×+ Υ',
+      })
+    } else if (result.dev10x !== null && result.dev10x < 1.0) {
+      diagnosis.push({
+        metric: '10xdev',
+        severity: 'info',
+        finding: `10xDEV is ${result.dev10x} — below 1.0 (BASE threshold). The cascade is compounding but not strongly.`,
+        recommendation: 'Improve both leverage AND velocity — 10xDEV = log10(transmission × commitment × reuse).',
+        estimated_yield_impact: 'Class tier improvement',
+      })
+    }
+
+    // Sort by severity (critical > warning > info)
+    const sevOrder = { critical: 0, warning: 1, info: 2 }
+    diagnosis.sort((a, b) => sevOrder[a.severity] - sevOrder[b.severity])
+
+    const healthScore = diagnosis.filter((d) => d.severity === 'critical').length
+    const summary = healthScore === 0
+      ? `Cascade is healthy — Υ ${result.yield}, class ${result.class}. ${diagnosis.length} minor optimizations available.`
+      : `Cascade has ${healthScore} critical leak${healthScore > 1 ? 's' : ''} — Υ ${result.yield}, class ${result.class}. Fix the critical items first.`
+
+    return {
+      pillars: p,
+      cascade: {
+        yield_: result.yield,
+        snr: result.snr,
+        leverage: result.leverage,
+        velocity: result.velocity,
+        tenx_dev: result.dev10x,
+        class: result.class,
+        warnings: result.warnings,
+      },
+      diagnosis,
+      summary,
+    }
+  }
+
+  if (name === 'suggest_improvements') {
+    if (!args?.text) throw new Error('suggest_improvements requires a non-empty `text` argument (token pillars).')
+    if (typeof args.text === 'string' && args.text.length > MAX_INPUT) {
+      return { status: 'error', reason: 'input_too_large', detail: `text exceeds ${MAX_INPUT} chars.` }
+    }
+
+    const p = parsePillars(args.text)
+    const current = withParseWarnings(p, cascade(p))
+    const { input: i, output: o, cacheCreate: cw, cacheRead: cr } = p
+
+    // Generate candidate improvements, simulate each, rank by Υ impact
+    const candidates = []
+
+    // Strategy 1: Increase cache reads (the #1 lever)
+    const crBoosts = cr > 0 ? [1.5, 2, 3, 5] : []
+    for (const mult of crBoosts) {
+      const sim = cascade({ ...p, cacheRead: Math.round(cr * mult) })
+      if (sim.yield !== null) {
+        candidates.push({
+          action: `Increase cache reads by ${Math.round((mult - 1) * 100)}%`,
+          pillar: 'cacheRead',
+          delta: `+${Math.round(cr * (mult - 1)).toLocaleString()}`,
+          simulated_yield: sim.yield,
+          yield_delta: Number((sim.yield - (current.yield ?? 0)).toFixed(2)),
+          class_after: sim.class,
+          rationale: 'Cache reads are the strongest Υ multiplier. More reuse = higher leverage = higher yield.',
+        })
+      }
+    }
+    // For zero-cache operators, suggest enabling caching with a starter amount
+    if (cr === 0 && cw === 0) {
+      const starterAmounts = [Math.round(i * 10), Math.round(i * 50), Math.round(i * 100)]
+      for (const amt of starterAmounts) {
+        const sim = cascade({ ...p, cacheCreate: Math.round(amt * 0.5), cacheRead: amt })
+        if (sim.yield !== null && sim.yield > 0) {
+          candidates.push({
+            action: `Enable caching with ${amt.toLocaleString()} cache reads`,
+            pillar: 'cacheRead',
+            delta: `+${amt.toLocaleString()}`,
+            simulated_yield: sim.yield,
+            yield_delta: Number((sim.yield - (current.yield ?? 0)).toFixed(2)),
+            class_after: sim.class,
+            rationale: 'You have no cache — enabling it unlocks the cascade. Start by reusing prior context.',
+          })
+        }
+      }
+    }
+
+    // Strategy 2: Reduce fresh input (Υ = Cr·O/I² — input is squared in the denominator)
+    const inputReductions = [0.9, 0.75, 0.5]
+    for (const mult of inputReductions) {
+      const newInput = Math.round(i * mult)
+      if (newInput < 1) continue
+      const sim = cascade({ ...p, input: newInput })
+      if (sim.yield !== null) {
+        candidates.push({
+          action: `Reduce fresh input by ${Math.round((1 - mult) * 100)}%`,
+          pillar: 'input',
+          delta: `-${Math.round(i * (1 - mult)).toLocaleString()}`,
+          simulated_yield: sim.yield,
+          yield_delta: Number((sim.yield - (current.yield ?? 0)).toFixed(2)),
+          class_after: sim.class,
+          rationale: 'Input is squared in the Υ denominator (Υ = Cr·O/I²). Reducing input has a quadratic payoff.',
+        })
+      }
+    }
+
+    // Strategy 3: Increase output
+    const outputBoosts = [1.25, 1.5, 2]
+    for (const mult of outputBoosts) {
+      const sim = cascade({ ...p, output: Math.round(o * mult) })
+      if (sim.yield !== null) {
+        candidates.push({
+          action: `Increase output by ${Math.round((mult - 1) * 100)}%`,
+          pillar: 'output',
+          delta: `+${Math.round(o * (mult - 1)).toLocaleString()}`,
+          simulated_yield: sim.yield,
+          yield_delta: Number((sim.yield - (current.yield ?? 0)).toFixed(2)),
+          class_after: sim.class,
+          rationale: 'Output is a linear multiplier in Υ. More output per session = higher yield.',
+        })
+      }
+    }
+
+    // Strategy 4: Optimize cache creation (reduce if over-committing)
+    if (cw > o * 10) {
+      const sim = cascade({ ...p, cacheCreate: Math.round(o * 5) })
+      if (sim.yield !== null) {
+        candidates.push({
+          action: 'Reduce cache creation to 5× output',
+          pillar: 'cacheCreate',
+          delta: `-${Math.round(cw - o * 5).toLocaleString()}`,
+          simulated_yield: sim.yield,
+          yield_delta: Number((sim.yield - (current.yield ?? 0)).toFixed(2)),
+          class_after: sim.class,
+          rationale: 'You\'re over-committing cache (cw >> output). Trimming to a healthy ratio reduces cost without hurting yield.',
+        })
+      }
+    }
+
+    // Sort by yield_delta descending, take top 8
+    candidates.sort((a, b) => b.yield_delta - a.yield_delta)
+    const top = candidates.slice(0, 8).map((c, idx) => ({ rank: idx + 1, ...c }))
+
+    const best = top[0]
+    return {
+      suggestions: top,
+      current_yield: current.yield,
+      current_class: current.class,
+      best_single_change: best
+        ? `${best.action} (Υ ${current.yield} → ${best.simulated_yield}, +${best.yield_delta} yield, class ${best.class_after})`
+        : 'No improvements found — your cascade is already optimized.',
+    }
+  }
+
+  if (name === 'self_improve') {
+    // The full self-improvement cycle: pull → diagnose → suggest → simulate.
+    // If text is provided, use it as pillars. If not, run tokenpull first.
+    let pillars
+    let pulledFrom = 'provided'
+
+    if (args?.text) {
+      if (typeof args.text === 'string' && args.text.length > MAX_INPUT) {
+        return { status: 'error', reason: 'input_too_large', detail: `text exceeds ${MAX_INPUT} chars.` }
+      }
+      pillars = parsePillars(args.text)
+    } else {
+      // Run tokenpull to get current pillars from local logs
+      const windowType = args?.window || '30d'
+      try {
+        const pullResult = await callTool('tokenpull', { window: windowType }, opts)
+        if (pullResult?.status === 'error' || !pullResult?.windows?.length) {
+          return {
+            status: 'error',
+            reason: 'tokenpull_failed',
+            detail: 'Could not pull pillars from local logs. Provide pillars via `text` argument instead.',
+            pull_result: pullResult,
+          }
+        }
+        // Use the first window's pillars
+        const w = pullResult.windows[0]
+        pillars = w.pillars
+        pulledFrom = `tokenpull ${w.window || windowType}`
+      } catch (e) {
+        return {
+          status: 'error',
+          reason: 'tokenpull_error',
+          detail: String(e.message || e),
+          hint: 'Provide pillars via `text` argument instead.',
+        }
+      }
+    }
+
+    const currentResult = withParseWarnings(pillars, cascade(pillars))
+    const { input: i, output: o, cacheCreate: cw, cacheRead: cr } = pillars
+
+    // ── Step 1: Diagnose ──────────────────────────────────────────────
+    const diagnosis = []
+    const leverage = currentResult.leverage
+    if (leverage !== null && leverage < 10) {
+      diagnosis.push({
+        metric: 'cache_leverage', severity: 'critical',
+        finding: `Cache leverage is ${leverage}× — TRANSMITTER-class operators hit 200×+.`,
+        recommendation: 'Increase context reuse: load prior session context, use longer threads.',
+      })
+    } else if (leverage !== null && leverage < 50) {
+      diagnosis.push({
+        metric: 'cache_leverage', severity: 'warning',
+        finding: `Cache leverage is ${leverage}× — below ARCH+ threshold (~100×+).`,
+        recommendation: 'Push cache reads higher by reusing prior context.',
+      })
+    }
+
+    const velocity = currentResult.velocity
+    if (velocity !== null && velocity < 0.5) {
+      diagnosis.push({
+        metric: 'velocity', severity: 'critical',
+        finding: `Velocity is ${velocity} — generating only ${velocity}× input as output.`,
+        recommendation: 'Increase output per turn, reduce over-reading.',
+      })
+    } else if (velocity !== null && velocity < 1.0) {
+      diagnosis.push({
+        metric: 'velocity', severity: 'warning',
+        finding: `Velocity is ${velocity} — below 1.0. Healthy operators hit 1.5×+.`,
+        recommendation: 'Generate more output per input token.',
+      })
+    }
+
+    if (currentResult.dev10x === null && cw === 0) {
+      diagnosis.push({
+        metric: '10xdev', severity: 'critical',
+        finding: 'No cache creation — cascade cannot compound.',
+        recommendation: 'Switch to a platform with prompt caching (Claude Code).',
+      })
+    }
+
+    const total = i + o + cw + cr
+    if (total > 0 && (i / total) * 100 > 10) {
+      diagnosis.push({
+        metric: 'input_bloat', severity: 'warning',
+        finding: `Fresh input is ${((i / total) * 100).toFixed(1)}% of total flow — efficient operators keep it under 1%.`,
+        recommendation: 'Reduce fresh input by reusing prior context.',
+      })
+    }
+
+    // ── Step 2: Suggest (generate + simulate candidates) ──────────────
+    const candidates = []
+    // If cacheRead is 0, suggest absolute amounts instead of percentage boosts
+    const crBoosts = cr > 0 ? [1.5, 2, 3, 5] : []
+    for (const mult of crBoosts) {
+      const sim = cascade({ ...pillars, cacheRead: Math.round(cr * mult) })
+      if (sim.yield !== null) candidates.push({
+        action: `Increase cache reads by ${Math.round((mult - 1) * 100)}%`,
+        pillar: 'cacheRead', delta: `+${Math.round(cr * (mult - 1)).toLocaleString()}`,
+        simulated_yield: sim.yield, yield_delta: Number((sim.yield - (currentResult.yield ?? 0)).toFixed(2)),
+        class_after: sim.class, rationale: 'Cache reads are the strongest Υ multiplier.',
+      })
+    }
+    // For zero-cache operators, suggest enabling caching with a starter amount
+    if (cr === 0 && cw === 0) {
+      const starterAmounts = [Math.round(i * 10), Math.round(i * 50), Math.round(i * 100)]
+      for (const amt of starterAmounts) {
+        const sim = cascade({ ...pillars, cacheCreate: Math.round(amt * 0.5), cacheRead: amt })
+        if (sim.yield !== null && sim.yield > 0) candidates.push({
+          action: `Enable caching with ${amt.toLocaleString()} cache reads`,
+          pillar: 'cacheRead', delta: `+${amt.toLocaleString()}`,
+          simulated_yield: sim.yield, yield_delta: Number((sim.yield - (currentResult.yield ?? 0)).toFixed(2)),
+          class_after: sim.class, rationale: 'You have no cache — enabling it unlocks the cascade. Start by reusing prior context.',
+        })
+      }
+    }
+    for (const mult of [0.9, 0.75, 0.5]) {
+      const newInput = Math.round(i * mult)
+      if (newInput < 1) continue
+      const sim = cascade({ ...pillars, input: newInput })
+      if (sim.yield !== null) candidates.push({
+        action: `Reduce fresh input by ${Math.round((1 - mult) * 100)}%`,
+        pillar: 'input', delta: `-${Math.round(i * (1 - mult)).toLocaleString()}`,
+        simulated_yield: sim.yield, yield_delta: Number((sim.yield - (currentResult.yield ?? 0)).toFixed(2)),
+        class_after: sim.class, rationale: 'Input is squared in Υ denominator — quadratic payoff.',
+      })
+    }
+    for (const mult of [1.25, 1.5, 2]) {
+      const sim = cascade({ ...pillars, output: Math.round(o * mult) })
+      if (sim.yield !== null) candidates.push({
+        action: `Increase output by ${Math.round((mult - 1) * 100)}%`,
+        pillar: 'output', delta: `+${Math.round(o * (mult - 1)).toLocaleString()}`,
+        simulated_yield: sim.yield, yield_delta: Number((sim.yield - (currentResult.yield ?? 0)).toFixed(2)),
+        class_after: sim.class, rationale: 'Output is a linear multiplier in Υ.',
+      })
+    }
+    candidates.sort((a, b) => b.yield_delta - a.yield_delta)
+    const suggestions = candidates.slice(0, 8).map((c, idx) => ({ rank: idx + 1, ...c }))
+
+    // ── Step 3: Simulate the top suggestion ───────────────────────────
+    const best = suggestions[0]
+    let bestSimulation = null
+    if (best) {
+      const simPillars = { ...pillars }
+      const delta = parseInt(best.delta.replace(/[+\-,]/g, ''), 10)
+      if (best.pillar === 'cacheRead') simPillars.cacheRead = cr + delta
+      else if (best.pillar === 'input') simPillars.input = Math.max(i - delta, 1)
+      else if (best.pillar === 'output') simPillars.output = o + delta
+      const simResult = cascade(simPillars)
+      bestSimulation = {
+        action: best.action,
+        current_yield: currentResult.yield,
+        simulated_yield: simResult.yield,
+        yield_delta: best.yield_delta,
+        current_class: currentResult.class,
+        simulated_class: simResult.class,
+        class_changed: currentResult.class !== simResult.class,
+      }
+    }
+
+    // ── Step 4: Cycle summary ─────────────────────────────────────────
+    const criticalCount = diagnosis.filter((d) => d.severity === 'critical').length
+    const cycleSummary = best
+      ? `Pulled from ${pulledFrom}. Υ ${currentResult.yield} (${currentResult.class}). ${criticalCount} critical, ${diagnosis.length - criticalCount} other findings. Best: ${best.action} → Υ ${best.simulated_yield} (+${best.yield_delta}).`
+      : `Pulled from ${pulledFrom}. Υ ${currentResult.yield} (${currentResult.class}). ${diagnosis.length} findings. No improvements suggested — cascade is optimized.`
+
+    // ── Step 5: Scope-specific analysis ───────────────────────────────
+    const scope = args?.scope || 'daily'
+    const modeInfo = currentResult.mode // { mode, confidence }
+    const scopeResult = {}
+
+    if (scope === 'daily') {
+      // Daily: mode + quality score + assessment + advice
+      const qs = qualityScore(currentResult.yield ?? 0, modeInfo.mode)
+      const expected = MODE_EXPECTED_YIELD[modeInfo.mode] ?? 0
+      const assessment = _dailyAssessment(modeInfo.mode, currentResult.yield, qs, expected)
+      const advice = _dailyAdvice(modeInfo.mode, currentResult.yield, qs)
+      scopeResult.mode = modeInfo
+      scopeResult.quality_score = Math.round(qs * 100) / 100
+      scopeResult.assessment = assessment
+      scopeResult.advice = advice
+    }
+
+    if (scope === 'weekly' || scope === 'trend') {
+      // Pull daily rows from ccusage to build weekly snapshots
+      const dailyRows = await _pullDailyRows(opts)
+      const weeklySnapshots = _compoundWeekly(dailyRows)
+      const modeDistribution = _modeDistribution(weeklySnapshots)
+      const modeWeightedYield = _modeWeightedYield(weeklySnapshots)
+
+      // Compute badges
+      const historyForBadges = weeklySnapshots.map(w => ({
+        date: w.weekStart,
+        mode: w.mode,
+        yield: w.yield,
+        pillars: w.pillars,
+      }))
+      const badges = computeBadges({
+        pillars,
+        cascade: currentResult,
+        history: historyForBadges,
+        isVerified: false, // set by submit_verified
+        rank: null, // server-side
+      })
+
+      if (scope === 'weekly') {
+        scopeResult.mode = modeInfo
+        // Strip dailyModes from weekly_snapshots — privacy boundary (daily modes never leave the machine)
+        const safeSnapshots = weeklySnapshots.map(({ dailyModes, ...rest }) => rest)
+        scopeResult.report = {
+          current_mode: modeInfo.mode,
+          mode_confidence: modeInfo.confidence,
+          mode_distribution: modeDistribution,
+          mode_weighted_yield: modeWeightedYield,
+          peak_yield: _peakYield(weeklySnapshots),
+          health_score: _healthScore(weeklySnapshots, modeWeightedYield),
+          weekly_snapshots: safeSnapshots,
+          badges,
+        }
+      }
+
+      if (scope === 'trend') {
+        const yield7d = _yieldForDays(weeklySnapshots, 7)
+        const yield30d = _yieldForDays(weeklySnapshots, 30)
+        const yield90d = _yieldForDays(weeklySnapshots, 90)
+        const trajectory = _trajectory(yield7d, yield30d, yield90d)
+        scopeResult.mode = modeInfo
+        scopeResult.trend = {
+          yield_7d: yield7d,
+          yield_30d: yield30d,
+          yield_90d: yield90d,
+          trajectory,
+          mode_distribution: modeDistribution,
+          phase_pattern: _phasePattern(weeklySnapshots),
+        }
+      }
+    }
+
+    return {
+      pillars,
+      current_cascade: {
+        yield_: currentResult.yield,
+        snr: currentResult.snr,
+        leverage: currentResult.leverage,
+        velocity: currentResult.velocity,
+        tenx_dev: currentResult.dev10x,
+        class: currentResult.class,
+        mode: modeInfo,
+        warnings: currentResult.warnings,
+      },
+      diagnosis,
+      suggestions,
+      best_simulation: bestSimulation,
+      cycle_summary: cycleSummary,
+      ...scopeResult,
+    }
+  }
+
   throw new Error(`Unknown tool: ${name}`)
 }
+
+// ── self_improve scope helpers ──────────────────────────────────────────────
+
+/** Pull daily rows from ccusage to build mode history. Returns array of { date, pillars, yield, mode }. */
+async function _pullDailyRows(opts = {}) {
+  try {
+    const raw = await execFileAsync('ccusage', ['claude', 'daily', '--json'], 15000)
+    const rows = JSON.parse(raw)?.daily ?? JSON.parse(raw)
+    if (!Array.isArray(rows)) return []
+    return rows.map(r => {
+      const pillars = {
+        input: r.inputTokens ?? r.input_tokens ?? 0,
+        output: r.outputTokens ?? r.output_tokens ?? 0,
+        cacheCreate: r.cacheCreationTokens ?? r.cache_create_tokens ?? 0,
+        cacheRead: r.cacheReadTokens ?? r.cache_read_tokens ?? 0,
+      }
+      const cas = cascade(pillars)
+      const mode = detectMode(pillars)
+      return {
+        date: r.date ?? r.day ?? null,
+        pillars,
+        yield: cas.yield ?? 0,
+        mode: mode.mode,
+        mode_confidence: mode.confidence,
+      }
+    }).filter(r => r.date)
+  } catch {
+    return []
+  }
+}
+
+/** Compound daily rows into weekly snapshots. Each week = 7 days, starting Monday. */
+function _compoundWeekly(dailyRows) {
+  if (!dailyRows || dailyRows.length === 0) return []
+  // Group by ISO week (week starts Monday)
+  const weeks = new Map()
+  for (const row of dailyRows) {
+    const d = new Date(row.date)
+    const day = d.getDay() || 7 // Sunday=0 → 7
+    const monday = new Date(d)
+    monday.setDate(d.getDate() - day + 1)
+    const weekKey = monday.toISOString().slice(0, 10)
+    if (!weeks.has(weekKey)) {
+      weeks.set(weekKey, { weekStart: weekKey, days: [] })
+    }
+    weeks.get(weekKey).days.push(row)
+  }
+  // Compound each week
+  return Array.from(weeks.values()).map(w => {
+    const pillars = w.days.reduce((acc, d) => ({
+      input: acc.input + d.pillars.input,
+      output: acc.output + d.pillars.output,
+      cacheCreate: acc.cacheCreate + d.pillars.cacheCreate,
+      cacheRead: acc.cacheRead + d.pillars.cacheRead,
+    }), { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 })
+    const cas = cascade(pillars)
+    const mode = detectMode(pillars)
+    return {
+      weekStart: w.weekStart,
+      pillars,
+      yield: cas.yield ?? 0,
+      mode: mode.mode,
+      mode_confidence: mode.confidence,
+      dayCount: w.days.length,
+      dailyModes: w.days.map(d => d.mode), // stays local — not in submitted report
+    }
+  }).sort((a, b) => a.weekStart.localeCompare(b.weekStart))
+}
+
+/** Compute mode distribution from weekly snapshots (weekly granularity = privacy boundary). */
+function _modeDistribution(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return {}
+  const counts = { BUILD: 0, EDIT: 0, DEBUG: 0, MAINTAIN: 0, IDLE: 0 }
+  for (const w of weeklySnapshots) {
+    counts[w.mode] = (counts[w.mode] || 0) + 1
+  }
+  const total = weeklySnapshots.length
+  const dist = {}
+  for (const [mode, count] of Object.entries(counts)) {
+    if (count > 0) dist[mode] = Math.round((count / total) * 100) / 100
+  }
+  return dist
+}
+
+/** Mode-weighted yield — average yield weighted by mode distribution. */
+function _modeWeightedYield(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0
+  const total = weeklySnapshots.length
+  const sum = weeklySnapshots.reduce((acc, w) => acc + (w.yield || 0), 0)
+  return Math.round(sum / total)
+}
+
+/** Peak yield across all weekly snapshots. */
+function _peakYield(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0
+  return Math.max(...weeklySnapshots.map(w => w.yield || 0))
+}
+
+/** Health score (0-100) — weighted composite of consistency, momentum, quality. */
+function _healthScore(weeklySnapshots, modeWeightedYield) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0
+  // Simplified Phase 1 formula:
+  //  40% — consistency (how often in MAINTAIN)
+  //  30% — momentum (recent yield vs older yield)
+  //  30% — quality (mode-weighted yield relative to MAINTAIN expected)
+  const dist = _modeDistribution(weeklySnapshots)
+  const maintainShare = dist.MAINTAIN || 0
+  const consistency = Math.min(maintainShare, 1) * 40
+
+  // Momentum: compare last 3 weeks to first 3 weeks
+  const recent = weeklySnapshots.slice(-3)
+  const older = weeklySnapshots.slice(0, 3)
+  const recentAvg = recent.reduce((a, w) => a + (w.yield || 0), 0) / (recent.length || 1)
+  const olderAvg = older.reduce((a, w) => a + (w.yield || 0), 0) / (older.length || 1)
+  const momentumRatio = olderAvg > 0 ? recentAvg / olderAvg : 1
+  const momentum = Math.min(momentumRatio, 2) / 2 * 30
+
+  // Quality: mode-weighted yield vs MAINTAIN expected (5000)
+  const quality = Math.min(modeWeightedYield / 5000, 1) * 30
+
+  return Math.round(consistency + momentum + quality)
+}
+
+/** Yield for the last N days (from weekly snapshots — approximates by summing recent weeks). */
+function _yieldForDays(weeklySnapshots, days) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0
+  const weeksNeeded = Math.ceil(days / 7)
+  const recent = weeklySnapshots.slice(-weeksNeeded)
+  if (recent.length === 0) return 0
+  const sum = recent.reduce((a, w) => a + (w.yield || 0), 0)
+  return Math.round(sum / recent.length) // average weekly yield
+}
+
+/** Trajectory description from 7d/30d/90d yields. */
+function _trajectory(y7, y30, y90) {
+  if (y90 === 0) return 'insufficient_data'
+  const r7v30 = y30 > 0 ? y7 / y30 : 1
+  const r30v90 = y90 > 0 ? y30 / y90 : 1
+  if (r7v30 > 1.2 && r30v90 > 1.0) return 'accelerating'
+  if (r7v30 > 1.2) return 'recent_surge'
+  if (r7v30 < 0.8 && r30v90 < 0.8) return 'declining'
+  if (r7v30 < 0.8) return 'recent_dip'
+  if (r30v90 > 1.1) return 'steady_growth'
+  return 'stable'
+}
+
+/** Phase pattern description from mode distribution over time. */
+function _phasePattern(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length < 2) return 'insufficient_data'
+  const modes = weeklySnapshots.map(w => w.mode)
+  const transitions = []
+  for (let i = 1; i < modes.length; i++) {
+    if (modes[i] !== modes[i - 1]) {
+      transitions.push(`${modes[i - 1]}→${modes[i]}`)
+    }
+  }
+  if (transitions.length === 0) return `consistent_${modes[0].toLowerCase()}`
+  // Check for smooth transitions (BUILD→MAINTAIN without DEBUG)
+  const smooth = transitions.every(t => !t.includes('DEBUG'))
+  if (smooth && transitions.some(t => t === 'BUILD→MAINTAIN')) return 'smooth_ramp'
+  if (transitions.filter(t => t.includes('DEBUG')).length > 2) return 'erratic'
+  return 'cyclical'
+}
+
+/** Daily assessment string. */
+function _dailyAssessment(mode, yieldVal, qualityScoreVal, expectedYield) {
+  const qsPct = Math.round(qualityScoreVal * 100)
+  if (mode === 'IDLE') return 'You\'re idle — no significant token activity today.'
+  if (mode === 'MAINTAIN') {
+    if (qualityScoreVal >= 0.5) return `You're in MAINTAIN mode. Yield ${yieldVal} is ${qsPct}% of MAINTAIN norm. The cascade is compounding.`
+    return `You're in MAINTAIN mode but yield ${yieldVal} is only ${qsPct}% of expected (${expectedYield}). You may be coasting — push for more output.`
+  }
+  if (mode === 'BUILD') {
+    if (qualityScoreVal >= 0.5) return `You're in BUILD mode. Yield ${yieldVal} is ${qsPct}% of BUILD norm. Greenfield work — expected to be low.`
+    return `You're in BUILD mode. Yield ${yieldVal} is ${qsPct}% of expected (${expectedYield}). Building is slow — keep going.`
+  }
+  if (mode === 'EDIT') {
+    if (qualityScoreVal >= 0.5) return `You're in EDIT mode. Yield ${yieldVal} is ${qsPct}% of EDIT norm. Fresh input but producing — good.`
+    return `You're in EDIT mode. Yield ${yieldVal} is ${qsPct}% of expected (${expectedYield}). Push for more output per input.`
+  }
+  if (mode === 'DEBUG') {
+    if (qualityScoreVal >= 0.5) return `You're in DEBUG mode. Yield ${yieldVal} is ${qsPct}% of DEBUG norm. Investigating — yield is expected to be low.`
+    return `You're in DEBUG mode. Yield ${yieldVal} is ${qsPct}% of expected (${expectedYield}). Debugging is slow — consider loading prior context.`
+  }
+  return `Mode: ${mode}. Yield: ${yieldVal}. Quality: ${qsPct}%.`
+}
+
+/** Daily advice string. */
+function _dailyAdvice(mode, yieldVal, qs) {
+  if (mode === 'MAINTAIN' && qs >= 0.5) return 'Keep the cascade going. Don\'t reset context — let it compound.'
+  if (mode === 'MAINTAIN') return 'You\'re in MAINTAIN but underperforming. Push the agent for more output per turn.'
+  if (mode === 'BUILD') return 'When you\'re done building, load prior context to transition to MAINTAIN. The cascade rewards reuse.'
+  if (mode === 'EDIT') return 'You\'re producing but using fresh input. Try to reuse prior context to boost leverage.'
+  if (mode === 'DEBUG') return 'When you\'re done debugging, load prior context to return to MAINTAIN. Don\'t let the debug phase drag on.'
+  if (mode === 'IDLE') return 'No activity detected. Start a session to build your cascade.'
+  return 'Keep working — the cascade will compound as you build context.'
+}
+
+/**
+ * Compute the cascade report block for a submission payload.
+ * Pure math — mode detection + badges + health score from the current pillars.
+ * The server stores this as-is (does NOT recompute modes).
+ * Weekly granularity is the privacy boundary — no daily modes in the report.
+ */
+function _computeReportBlock(pillars) {
+  const cas = cascade(pillars)
+  const modeInfo = detectMode(pillars)
+  const badges = computeBadges({
+    pillars,
+    cascade: cas,
+    history: [], // no history available at submit time — badges computed from current pillars only
+    isVerified: true, // submit_verified is the signed agent path
+    rank: null,
+  })
+  return {
+    current_mode: modeInfo.mode,
+    mode_confidence: modeInfo.confidence,
+    mode_distribution: { [modeInfo.mode]: 1.0 }, // single-window submission
+    mode_weighted_yield: cas.yield ?? 0,
+    peak_yield: cas.yield ?? 0,
+    health_score: _healthScore([{ mode: modeInfo.mode, yield: cas.yield ?? 0 }], cas.yield ?? 0),
+    badges,
+  }
+}