fodda-mcp 1.30.0 → 1.32.0

package/dist/toolHandlers.js

@@ -10,15 +10,15 @@ import { z } from 'zod';
 import { GoogleGenAI } from '@google/genai';
 import axios from 'axios';
 import crypto from 'crypto';
-import { buildDynamicPromptSections, getDomainGraphIds, getGraphs, getLiveGraphs, buildDisplayName, getRelevantGraphs, getEnabledSkillConfigs, getSkillGraphs, getAnalysts } from './catalogCache.js';
+import { buildDynamicPromptSections, getDomainGraphIds, getGraphs, getLiveGraphs, buildDisplayName, getRelevantGraphs, getRelevantSources, getEnabledSkillConfigs, getSkillGraphs, getAnalysts } from './catalogCache.js';
 import { renderBrandWidget } from './brandTemplate.js';
 import { renderSearchWidget } from './searchTemplate.js';
 import { FODDA_COMPONENT_GUIDE, getShellTemplate } from './widgetShell.js';
 import { MCP_SERVER_VERSION } from './tools.js';
 import { buildSystemPrompt, BRAND_INTELLIGENCE_RENDERING_SPEC, FODDA_WIDGET_DESIGN_BRIEF } from './systemPrompt.js';
 import { computeLifecycle, computeMomentum, isFastMover, enrichEvidence, GRAPH_BADGES, getFoddaTheme, getSupplementalTheme } from './enrichment.js';
-import { handleAccessError, handleTrialCreditExhaustion } from './errorHandling.js';
-import { chargeQuery } from './pricingCache.js';
+import { handleAccessError, handleTrialCreditExhaustion, classifyAccessError } from './errorHandling.js';
+import { chargeQuery, getToolCostSummary } from './pricingCache.js';
 import { callOutputSkills, buildSkillInput, discoverSkillTools, executeSkillTool, mapSkillError } from './skillClient.js';
 import { createSessionTracker, postToSlack } from './sessionTracker.js';
 import { buildResearcherInstruction } from './agents/fodda-researcher/index.js';
@@ -53,13 +53,13 @@ function buildRenderInstructions(opts) {
     return instructions;
 }
 /**
- * Append a low-credit warning to the response data if tokens are running low.
+ * Append a low-credit warning to the response data if API calls are running low.
  * Utilizes new dynamic Stripe links and upsell data provided by the Fodda API.
  *
  * Also surfaces upstream X-Usage-* header warnings (approaching-limit, overage-active)
  * injected by foddaRequest() as _upstream_usage.
  */
-function appendUsageWarning(data, isTrial, userEmail) {
+function appendUsageWarning(data, userEmail) {
     // ── Upstream header-based warnings (X-Usage-Warning / X-Usage-Percent / X-Usage-Overage-Tokens) ──
     if (data?._upstream_usage) {
         const u = data._upstream_usage;
@@ -68,8 +68,8 @@ function appendUsageWarning(data, isTrial, userEmail) {
         }
         else if (u.warning === 'overage-active') {
             data._usage_status = u.overage_tokens
-                ? `📊 You're in overage — ${u.overage_tokens} additional token(s) used at $0.20/token this billing cycle.`
-                : `📊 Overage billing is active — additional queries are charged at $0.20/token.`;
+                ? `📊 You're in overage — ${u.overage_tokens} additional API call(s) used at $0.50/API call this billing cycle.`
+                : `📊 Overage billing is active — additional queries are charged at $0.50/API call.`;
         }
     }
     if (!data?.usage)
@@ -77,7 +77,7 @@ function appendUsageWarning(data, isTrial, userEmail) {
     const remaining = data.usage.remaining ?? data.usage.credits_remaining;
     if (remaining === undefined || remaining < 0)
         return;
-    const threshold = isTrial ? 10 : 15;
+    const threshold = 15;
     if (remaining >= threshold)
         return;
     const noun = remaining === 1 ? 'API call' : 'API calls';
@@ -89,10 +89,7 @@ function appendUsageWarning(data, isTrial, userEmail) {
     if (userEmail && userEmail.includes('@'))
         portalParams.set('email', userEmail);
     const portalUrl = `${API_BASE_URL.replace('api.', 'app.')}/portal?${portalParams.toString()}`;
-    if (isTrial) {
-        data._credit_warning = `\u26a0\ufe0f You have ${remaining} ${noun} remaining on your trial. Upgrade to the free Base plan (100 API calls/month) or a paid plan to continue.\n\n\ud83d\ude80 **[Upgrade Now \u2192](${portalUrl})**`;
-    }
-    else {
+    {
         let msg = `\u26a0\ufe0f You have ${remaining} ${noun} remaining this month.`;
         if (upsell) {
             msg += ` You can get 100 more API calls for $${upsell.price || '50'} right now: ${upsell.link || portalUrl}`;
@@ -172,7 +169,35 @@ function resolveUserId(sessionUserId, toolProvidedUid) {
 // ---------------------------------------------------------------------------
 const activeResearchJobs = new Map();
 const activeSupplementalJobs = new Map();
-export async function createServer(apiKey, userId, foddaRequest, waverunnerRequest, storeWidget, getServiceUrl, entryId = '') {
+export async function createServer(apiKey, userId, foddaRequest, waverunnerRequest, storeWidget, getServiceUrl, entryId = '', 
+// anonymous SPT session: token (settlement payer) + connect-time cap/prices (pre-run coverage)
+sptCtx) {
+    // ── SPT settlement helpers (inert for credit/API-key sessions: sptCtx is undefined) ──
+    // Pre-run guard: refuse a task BEFORE spending compute if this payment token can't cover it.
+    // Returns an error result to return immediately, or null to proceed.
+    const sptGuard = (queryTypeCode) => {
+        if (!sptCtx)
+            return null;
+        const priceUsd = sptCtx.prices[queryTypeCode];
+        if (priceUsd != null && sptCtx.maxAmountCents != null && priceUsd * 100 > sptCtx.maxAmountCents) {
+            return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'SPT_INSUFFICIENT', required_usd: priceUsd, message: `This task costs $${priceUsd.toFixed(2)}, above this payment token's limit.` }) }] };
+        }
+        return null;
+    };
+    // Settlement-as-gate: SPT sessions await the charge and WITHHOLD the result if it fails;
+    // credit sessions fire-and-forget (a missed meter only under-bills, never blocks delivery).
+    // Returns an error result to return instead of the payload, or null when it's safe to deliver.
+    const settleOrWithhold = async (params, label) => {
+        if (sptCtx) {
+            const r = await chargeQuery({ ...params, foddaRequest, spt: sptCtx.token });
+            if (!r.charged) {
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'SPT_SETTLEMENT_FAILED', message: r.error || 'Payment could not be completed; result withheld.' }) }] };
+            }
+            return null;
+        }
+        chargeQuery({ ...params, foddaRequest }).catch(e => console.error(`[${label}] chargeQuery failed:`, e.message));
+        return null;
+    };
     // Fetch account profile for persona-aware framing (best-effort)
     let accountProfile;
     let sessionDisabledGraphs = new Set();
@@ -233,10 +258,9 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
     catch (err) {
         console.error('[persona] Failed to fetch account profile — proceeding without persona framing');
     }
-    // sk_trial_ keys are retired. New individual trial accounts (planCode 13) use
-    // sk_live_ keys and are detected from API error responses via isIndividualTrial().
-    // isTrial is false at session init for all current account types.
-    const isTrial = false;
+    // Note: trial accounts are retired and handled entirely server-side by the API
+    // (rejected as no-longer-valid, or surfaced reactively via errorHandling.ts).
+    // No client-side trial state remains.
     const sessionTracker = createSessionTracker();
     // Fire-and-forget: log the user's query text to the Questions table.
     // Called at tool entry — BEFORE cache-eligible foddaRequest calls —
@@ -263,7 +287,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         name: 'fodda_mcp',
         version: MCP_SERVER_VERSION,
     }, {
-        instructions: buildSystemPrompt(accountProfile, skillPromptMeta, isTrial, entryId),
+        instructions: buildSystemPrompt(accountProfile, skillPromptMeta, entryId),
     });
     // Register empty capabilities and handlers to silence directory warnings
     server.server.registerCapabilities({
@@ -325,18 +349,6 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             const data = await foddaRequest('GET', '/v1/graphs', apiKey, userId);
             const account = data?._account;
             if (!account) {
-                if (isTrial) {
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: JSON.stringify({
-                                    plan: 'Trial',
-                                    note: 'You\'re on a trial — limited API calls across all expert graphs. I can set you up with a Free Base account (100 API calls/month) instantly — just give me your email.',
-                                    manage_url: 'https://app.fodda.ai',
-                                }, null, 2)
-                            }]
-                    };
-                }
                 return {
                     content: [{
                             type: 'text',
@@ -356,7 +368,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             if (typeof status.api_calls_remaining === 'number' && status.api_calls_remaining < 0) {
                 status.overage_active = true;
                 status.overage_tokens = Math.abs(status.api_calls_remaining);
-                status.overage_note = `You're ${Math.abs(status.api_calls_remaining)} token(s) over your monthly limit. Overage charges apply at $0.20/token.`;
+                status.overage_note = `You're ${Math.abs(status.api_calls_remaining)} API call(s) over your monthly limit. Overage charges apply at $0.50/API call.`;
             }
             if (account.tokens_used !== undefined)
                 status.api_calls_used = account.tokens_used;
@@ -389,6 +401,10 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 };
             }
             status.graphs_url = 'https://app.fodda.ai/graphs';
+            // Surface per-tool costs so the agent can explain spend before running queries
+            const costs = getToolCostSummary();
+            if (costs.length)
+                status.query_costs = costs;
             return {
                 content: [{
                         type: 'text',
@@ -423,7 +439,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             // Strip _account from list_graphs output (use get_my_account instead)
             if (data)
                 delete data._account;
-            if (account && !account.userContext && !isTrial) {
+            if (account && !account.userContext) {
                 const nudge = `\n\n---\n⚠️ NO RESEARCH PROFILE SET for this user.\nResponses will be generic until you capture their profile.\nThrough natural conversation, determine:\n- Their role and what they use Fodda for (pitches, ongoing research, client advisory)\n- What kind of evidence they value (commercial data vs. design inspiration)\n- Geographic focus (global, specific regions)\n- How results should be framed (executive brief vs. deep analysis)\nThen call update_user_profile. Write BEHAVIORAL INSTRUCTIONS, not a bio.\nFormat: one sentence of identity, then numbered directives that change how you respond.\nExample: "Agency strategist doing pitches. (1) Lead with landscape orientation. (2) Prioritize commercial evidence. (3) Time-scarce — strongest findings first."\n---`;
                 const jsonText = JSON.stringify(data, null, 2);
                 return { content: [{ type: 'text', text: jsonText + nudge }] };
@@ -453,7 +469,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         }
     });
     // --- search_graph ---
-    server.tool('search_graph', 'Search expert-curated knowledge graphs for trend clusters, signals, and consumer behavior evidence across retail, beauty, luxury, fashion, sport, consumer electronics, F&B, travel, and 30+ specialist domains. Returns structured trend data with cited evidence chains, source attribution, lifecycle signals (emerging/building/mature/fading), and momentum indicators — not generic web summaries. If graphId is omitted, searches ALL accessible graphs in parallel (recommended default). Use when the query involves market trends, competitor analysis, innovation signals, consumer behavior, cultural shifts, or any topic where curated expert intelligence outperforms web search.', {
+    server.tool('search_graph', 'Find trends, signals, and expert insights across 100+ curated knowledge graphs covering retail, beauty, tech, food, travel, sports, and 30+ specialist domains. Returns trend data with cited evidence, source attribution, and lifecycle stage (emerging/building/mature/fading) — not generic web summaries. If graphId is omitted, searches ALL accessible graphs in parallel (recommended default). Use for market trends, competitor analysis, innovation signals, consumer behavior, cultural shifts, or any topic where curated expert intelligence outperforms web search.', {
         graphId: z.string().optional().describe("Optional graph ID. If omitted, searches ALL accessible graphs. Examples: 'retail', 'tech', 'food', 'travel', 'beauty', 'sports', 'sic', 'pew', 'ce-design', 'ezra-eeman-wayfinder', 'dhl-ecommerce-trends-2026', 'automotive-color-trends', 'alyson-stevens-macro', 'generative-realities', 'pwc/sxsw-2026-key-insights', 'green-house/thrive-report', 'delta/the-connection-index'"),
         query: z.string().describe('The search query. Location terms are auto-detected and used to filter results geographically.'),
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.'),
@@ -483,6 +499,10 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 const results = await Promise.allSettled(graphsToSearch.map(g => foddaRequest('POST', `/v1/graphs/${encodeURIComponent(g.graph_id)}/search`, apiKey, resolveUserId(userId, uid), { ...body, limit: perGraphLimit })));
                 // Merge rows, deduplicate by trendId + near-duplicate name detection
                 const allRows = [];
+                // Capture any per-graph rejection caused by credit/quota exhaustion, so an
+                // out-of-credits state is surfaced explicitly instead of masquerading as an
+                // empty NO_MATCH coverage gap (the fan-out otherwise swallows rejections).
+                let creditRejection = null;
                 const seen = new Set();
                 const seenNames = []; // for near-duplicate check
                 const nameTokens = (name) => new Set(name.toLowerCase().replace(/[^a-z0-9\s]/g, '').split(/\s+/).filter(t => t.length > 2));
@@ -496,8 +516,12 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 };
                 for (let i = 0; i < results.length; i++) {
                     const r = results[i];
-                    if (r.status !== 'fulfilled')
+                    if (r.status !== 'fulfilled') {
+                        if (!creditRejection && classifyAccessError(r.reason) === 'credits') {
+                            creditRejection = r.reason;
+                        }
                         continue;
+                    }
                     const fulfilled = r;
                     const rows = Array.isArray(fulfilled.value) ? fulfilled.value : (fulfilled.value?.rows || []);
                     const graphMeta = relevantGraphs[i];
@@ -619,6 +643,14 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 })();
                 const finalRows = diversified.slice(0, effectiveLimit);
                 const actualSourceGraphs = [...new Set(finalRows.map((r) => r.graphId || r._use_this_graphId).filter(Boolean))];
+                // If the fan-out came back empty ONLY because credit/quota blocked the calls,
+                // surface that explicitly — never let it read as a "no coverage" gap.
+                if (allRows.length === 0 && creditRejection) {
+                    const trialResult = await handleTrialCreditExhaustion(creditRejection, apiKey, userId);
+                    if (trialResult)
+                        return trialResult;
+                    return await handleAccessError(creditRejection, 'search_graph');
+                }
                 data = { rows: finalRows, dataStatus: allRows.length > 0 ? 'ok' : 'NO_MATCH', _routed_graphs: actualSourceGraphs };
             }
             else {
@@ -797,7 +829,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 catch { /* Broadening failed silently */ }
             }
             // ── Low-credit warning for all users — utilizes dynamic Stripe links from API ──
-            appendUsageWarning(data, isTrial, resolveUserId(userId));
+            appendUsageWarning(data, resolveUserId(userId));
             // ── Supplemental data — macro context for all queries with results ──
             let supplemental = { google_trends: null, census_retail: null };
             const resultCount = (data?.rows || []).length;
@@ -872,7 +904,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 if (totalSize > 30000) {
                     console.error(`[search_graph] Payload too large (${(totalSize / 1024).toFixed(1)}KB) — skipping widget HTML, sending liteData JSON + design brief`);
                     // ── Query-level billing (large payload path) ──
-                    chargeQuery({ queryTypeCode: 'topic_research', apiKey, userId: resolveUserId(userId, uid), query, foddaRequest })
+                    chargeQuery({ queryTypeCode: 'topic_research', apiKey, userId: resolveUserId(userId, uid), query, foddaRequest, spt: sptCtx?.token })
                         .catch(e => console.error('[search_graph] chargeQuery failed:', e.message));
                     return { content: [
                             { type: 'text', text: jsonPayload },
@@ -892,7 +924,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                         })),
                     ] };
                 // ── Query-level billing (rich widget path) ──
-                chargeQuery({ queryTypeCode: 'topic_research', apiKey, userId: resolveUserId(userId, uid), query, foddaRequest })
+                chargeQuery({ queryTypeCode: 'topic_research', apiKey, userId: resolveUserId(userId, uid), query, foddaRequest, spt: sptCtx?.token })
                     .catch(e => console.error('[search_graph] chargeQuery failed:', e.message));
                 return widgetResponse;
             }
@@ -924,7 +956,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 return out;
             });
             // ── Query-level billing (fallback path) ──
-            chargeQuery({ queryTypeCode: 'topic_research', apiKey, userId: resolveUserId(userId, uid), query, foddaRequest })
+            chargeQuery({ queryTypeCode: 'topic_research', apiKey, userId: resolveUserId(userId, uid), query, foddaRequest, spt: sptCtx?.token })
                 .catch(e => console.error('[search_graph] chargeQuery failed:', e.message));
             return { content: [
                     { type: 'text', text: JSON.stringify(fallbackData, null, 2) },
@@ -949,16 +981,17 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 ] };
         }
         catch (err) {
-            // Trial-aware credit exhaustion handling
+            // Trial-aware credit exhaustion, then structured access/credit handling.
+            // (Routes credit errors through handleAccessError so payment details are
+            // returned as structured fields, not baked into a raw message string.)
             const trialResult = await handleTrialCreditExhaustion(err, apiKey, userId);
             if (trialResult)
                 return trialResult;
-            const msg = err.response?.data?.error?.message || err.response?.data?.message || err.message;
-            return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: msg }) }] };
+            return await handleAccessError(err, 'search_graph');
         }
     });
     // --- get_neighbors ---
-    server.tool('get_neighbors', 'Traverse graph relationships from a specific trend node to discover connected signals, brands, technologies, and locations. Returns structured relationship data that web search cannot provide — the curated editorial connections between trends. Use after search_graph to map the territory around a specific trend, find which brands are connected, or understand cross-domain links. Requires node_id from a prior search_graph result.', {
+    server.tool('get_neighbors', 'Discover what\'s connected to a specific trend — related brands, technologies, locations, and cross-domain links that search alone wouldn\'t surface. Returns curated editorial connections between trends that web search cannot provide. Use after search_graph to map the territory around a trend, find which brands are connected, or understand cross-domain relationships. Requires node_id from a prior search_graph result.', {
         graphId: z.string().describe(GRAPH_ID_DESC),
         seed_node_ids: z.array(z.string()).describe('Array of node IDs to start traversal from. MUST be actual node_id values from a prior search_graph result (e.g. ["2507.0"]). Node IDs are NOT sequential integers — do NOT guess or invent IDs like "1", "2", "3". Always call search_graph first to obtain valid IDs.'),
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.'),
@@ -978,7 +1011,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             if (direction)
                 body.direction = direction;
             let data = await foddaRequest('POST', `/v1/graphs/${encodeURIComponent(graphId)}/neighbors`, apiKey, resolveUserId(userId, uid), body);
-            appendUsageWarning(data, isTrial, resolveUserId(userId));
+            appendUsageWarning(data, resolveUserId(userId));
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (err) {
@@ -990,7 +1023,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         }
     });
     // --- get_evidence ---
-    server.tool('get_evidence', 'Retrieve curated source articles and structured evidence for a specific trend node — case studies, statistics, expert quotes, and analysis with full source attribution. Returns evidence that has been editorially selected and categorized, not raw web results. Each item includes sourceUrl, place, brandNames, publishedAt, category, and formatted_citation. Use after search_graph when you need the supporting proof behind a specific trend. This is a node lookup — not a text search tool.', {
+    server.tool('get_evidence', 'Get the source articles, case studies, and statistics behind a specific trend — with full citations and publisher attribution. Each item includes source URL, location, brand names, publication date, category, and a formatted citation. Use after search_graph when you need the supporting proof behind a trend. This is a direct lookup by trend ID — not a text search tool.', {
         graphId: z.string().describe(GRAPH_ID_DESC),
         for_node_id: z.string().describe("The node_id from a prior search_graph result (e.g. '2507.0'). MUST come from the search result's node_id field. Node IDs are NOT sequential integers — do NOT guess or invent IDs like '1', '2', '3'. Do NOT pass the trend name."),
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.'),
@@ -1005,7 +1038,10 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             // Enrich evidence with pre-formatted citations
             if (data?.evidence)
                 data.evidence = enrichEvidence(data.evidence);
-            appendUsageWarning(data, isTrial, resolveUserId(userId));
+            appendUsageWarning(data, resolveUserId(userId));
+            const withheld = await settleOrWithhold({ queryTypeCode: 'standalone_evidence', apiKey, userId: resolveUserId(userId, uid), query: for_node_id }, 'get_evidence');
+            if (withheld)
+                return withheld;
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (err) {
@@ -1017,7 +1053,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         }
     });
     // --- get_node ---
-    server.tool('get_node', 'Retrieve complete metadata for a specific trend node — full description, signal score, lifecycle, geographic scope, adjacent possibilities, and all properties. Use when you need the full detail on a single trend after search_graph returned a summary. Requires node_id from a prior search_graph result.', {
+    server.tool('get_node', 'Get the full profile of a specific trend — detailed description, lifecycle stage (emerging/building/mature), signal strength, geographic scope, and all properties. Use when you need deeper detail on a single trend after search_graph returned a summary. Requires node_id from a prior search_graph result.', {
         graphId: z.string().describe(GRAPH_ID_DESC),
         nodeId: z.string().describe("The node_id from a prior search_graph result (e.g. '2507.0'). MUST come from the search result's node_id field. Node IDs are NOT sequential integers — do NOT guess or invent IDs like '1', '2', '3'. Do NOT pass the trend name."),
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.')
@@ -1030,7 +1066,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             if (data && typeof data === 'object') {
                 data.theme = getFoddaTheme(graphId);
             }
-            appendUsageWarning(data, isTrial, resolveUserId(userId));
+            appendUsageWarning(data, resolveUserId(userId));
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (err) {
@@ -1042,7 +1078,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         }
     });
     // --- get_label_values ---
-    server.tool('get_label_values', 'List all values for a structured category within a graph — Brand names, Locations, Technologies, Audiences, RetailerTypes, or Trend names. Use when you need to enumerate what entities exist in a graph before filtering, or when the user asks "what brands are in the retail graph?" or "what locations does the fashion graph cover?". To enumerate every trend in a graph (especially industry-report graphs, where semantic search/search_insights may return only the top match or nothing if evidence is unlinked), call with label="Trend" — this returns the complete, deterministic list of trend names.', {
+    server.tool('get_label_values', 'List all brands, locations, technologies, audiences, or trends within a specific knowledge graph. Use to explore what a graph contains — e.g., "what brands are in the retail graph?" or "what locations does the fashion graph cover?". To get a complete list of every trend in a graph, call with label="Trend" — this returns the full deterministic list, useful for industry-report graphs where search may return partial results.', {
         graphId: z.string().describe(GRAPH_ID_DESC),
         label: z.string().describe("The label to fetch values for (e.g., 'Brand', 'Location', 'Technology', 'Audience', 'RetailerType', 'Trend')"),
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.'),
@@ -1064,7 +1100,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         }
     });
     // --- discover_adjacent_trends ---
-    server.tool('discover_adjacent_trends', 'Find trends semantically similar to a given trend using pre-computed embeddings — surfaces connections that keyword search would miss. Returns scored similarity matches and optionally editorial links across graphs. Use to expand research briefs, discover unexpected cross-domain connections, or map the territory around a strong signal. Web search cannot replicate this — it uses Fodda\'s internal embedding space.', {
+    server.tool('discover_adjacent_trends', 'Find trends similar to one you\'ve already found — surfaces unexpected cross-domain connections that keyword search would miss. Returns scored similarity matches and optionally editorial links across graphs. Use to expand research briefs, discover cross-industry parallels, or map the territory around a strong signal. This leverages Fodda\'s proprietary similarity index across all knowledge graphs.', {
         graphId: z.string().describe(GRAPH_ID_DESC),
         trend_id: z.string().describe("The node_id from a prior search_graph result (e.g. '2507.0'). MUST come from the search result's node_id field. Node IDs are NOT sequential integers — do NOT guess or invent IDs like '1', '2', '3'. Do NOT pass the trend name."),
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.'),
@@ -1075,6 +1111,8 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         try {
             if (graphId === 'psfk')
                 graphId = 'retail';
+            // Log query to Questions table (fire-and-forget, before cache)
+            logUserQuery(trend_id, 'discover_adjacent_trends', graphId);
             const params = new URLSearchParams({ node_id: trend_id });
             if (min_score !== undefined)
                 params.set('min_score', String(min_score));
@@ -1082,7 +1120,10 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             if (include_editorial !== undefined)
                 params.set('include_editorial', String(include_editorial));
             let data = await foddaRequest('GET', `/v1/graphs/${encodeURIComponent(graphId)}/adjacent?${params.toString()}`, apiKey, resolveUserId(userId, uid));
-            appendUsageWarning(data, isTrial, resolveUserId(userId));
+            appendUsageWarning(data, resolveUserId(userId));
+            const adjacentWithheld = await settleOrWithhold({ queryTypeCode: 'adjacent_trends', apiKey, userId: resolveUserId(userId, uid), query: trend_id }, 'discover_adjacent_trends');
+            if (adjacentWithheld)
+                return adjacentWithheld;
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (err) {
@@ -1100,8 +1141,13 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         const maxEv = Math.min(max_evidence || 10, 25);
         const brandLower = brandName.toLowerCase();
         // ── Fire static/brand-only supplemental queries in parallel ──
-        const amazonPromise = foddaRequest('GET', `/v1/supplemental/amazon?query=${encodeURIComponent(brandName)}&limit=8`, apiKey, resolveUserId(userId, uid));
-        const censusPromise = foddaRequest('GET', `/v1/supplemental/census/retail-snapshot`, apiKey, resolveUserId(userId, uid));
+        // These are created early but only awaited (via Promise.allSettled) ~500 lines later.
+        // A .catch() at creation is MANDATORY: if one rejects (e.g. a transient 503) during the
+        // intervening awaits, an unhandled rejection would crash the whole MCP process. Degrade to null.
+        const amazonPromise = foddaRequest('GET', `/v1/supplemental/amazon?query=${encodeURIComponent(brandName)}&limit=8`, apiKey, resolveUserId(userId, uid))
+            .catch((e) => { console.warn('[brand_tracker] amazon supplemental failed:', e?.message); return null; });
+        const censusPromise = foddaRequest('GET', `/v1/supplemental/census/retail-snapshot`, apiKey, resolveUserId(userId, uid))
+            .catch((e) => { console.warn('[brand_tracker] census supplemental failed:', e?.message); return null; });
         // Build graph lookup map
         const graphLookup = new Map();
         for (const g of getGraphs())
@@ -1620,10 +1666,15 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         try {
             // Log query to Questions table (fire-and-forget, before cache)
             logUserQuery(brand_name, 'brand_tracker');
+            // ── SPT pre-run coverage: refuse before spending compute if the token can't cover the task ──
+            const guard = sptGuard('brand_intelligence');
+            if (guard)
+                return guard;
             const { widget, EDITORIAL_INSTRUCTION } = await executeBrandTracker(brand_name, uid, graph_ids, include_evidence, max_evidence);
-            // ── Query-level billing ──
-            chargeQuery({ queryTypeCode: 'brand_intelligence', apiKey, userId: resolveUserId(userId, uid), query: brand_name, foddaRequest })
-                .catch(e => console.error('[brand_tracker] chargeQuery failed:', e.message));
+            // ── Query-level billing (settlement gates delivery for SPT) ──
+            const withheld = await settleOrWithhold({ queryTypeCode: 'brand_intelligence', apiKey, userId: resolveUserId(userId, uid), query: brand_name }, 'brand_tracker');
+            if (withheld)
+                return withheld;
             return { content: [
                     { type: 'text', text: '── WIDGET HTML ──\nIf your client supports HTML visualization (show_widget, visualize:show_widget, or artifacts), pass this HTML verbatim. Do not rewrite or restyle.\n\n' + widget.widget_html },
                     { type: 'text', text: EDITORIAL_INSTRUCTION },
@@ -1641,7 +1692,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
     // Replaces 21 individual supplemental tools with a single call.
     // The API routes to 6-10 relevant sources based on query + domain,
     // queries them in parallel, and returns a consolidated response.
-    server.tool('get_supplemental_context', 'Get institutional market data from up to 10 sources in a single call. The server automatically selects the most relevant sources based on your query and domain — economic indicators, trade data, product landscape, food economics, agricultural production, nutritional composition, commodity pricing, research signals, demographic surveys, and more. Use this AFTER graph searches to add macro context, or standalone for quantitative market intelligence. Returns categorized data blocks (demand_signals, economic_context, market_data, research_signals, demographic_context) with source attribution for citations. 5 API calls per standalone use.', {
+    server.tool('get_supplemental_context', 'Targeted pull for macro/institutional data — research workflows include this automatically; call directly only for standalone economic context. Gets real-time market data from 80+ authoritative sources in a single call — economic indicators, trade statistics, consumer demand signals, research trends, demographics, and more. The server automatically selects the most relevant sources for your query. Returns categorized data blocks (demand_signals, economic_context, market_data, research_signals, demographic_context) with source attribution for citations. Uses 5 tokens ($2.50 via SPT) per standalone use.', {
         query: z.string().describe("The topic or query to get supplemental data for (e.g., 'sustainable packaging', 'tequila spirits market', 'Gen Z beauty')"),
         domain: z.string().optional().describe("Domain hint to improve source routing: 'retail', 'beauty', 'fashion', 'sports', 'food', 'technology', 'culture', 'travel', 'design'. If omitted, inferred from query."),
         brands: z.array(z.string()).optional().describe("Brand names to include in demand/product lookups (e.g., ['Nike', 'Adidas']). Triggers Google Trends comparison and Amazon product search."),
@@ -1649,6 +1700,8 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.'),
     }, { title: 'Get Market Context Data', readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ query, domain, brands, graph_ids, userId: uid }) => {
         try {
+            // Log query to Questions table (fire-and-forget, before cache)
+            logUserQuery(query, 'supplemental_context');
             const body = { query };
             if (domain)
                 body.domain = domain;
@@ -1663,7 +1716,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 try {
                     const data = await foddaRequest('POST', '/v1/supplemental/context', apiKey, resolveUserId(userId, uid), body);
                     // ── Query-level billing ──
-                    chargeQuery({ queryTypeCode: 'standalone_supplemental', apiKey, userId: resolveUserId(userId, uid), query, foddaRequest })
+                    chargeQuery({ queryTypeCode: 'standalone_supplemental', apiKey, userId: resolveUserId(userId, uid), query, foddaRequest, spt: sptCtx?.token })
                         .catch(e => console.error('[supplemental] chargeQuery failed:', e.message));
                     activeSupplementalJobs.set(jobId, { status: 'COMPLETE', result: JSON.stringify(data, null, 2) });
                 }
@@ -1687,7 +1740,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         }
     });
     // --- check_supplemental_status ---
-    server.tool('check_supplemental_status', 'Check the status of a long-running supplemental data gathering job. If complete, this tool returns the full JSON data payload. You MUST poll this periodically until the status is COMPLETE or FAILED.', {
+    server.tool('check_supplemental_status', 'Check if market data gathering is complete and retrieve the results. Call this after get_supplemental_context — poll every 5-10 seconds until status is COMPLETE or FAILED.', {
         job_id: z.string().describe('The Job ID returned by get_supplemental_context'),
     }, { title: 'Check Supplemental Status', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ job_id }) => {
         const job = activeSupplementalJobs.get(job_id);
@@ -1727,7 +1780,12 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 body.max_evidence_per_trend = max_evidence_per_trend;
             if (min_score !== undefined)
                 body.min_score = min_score;
+            // Log query to Questions table (fire-and-forget, before cache)
+            logUserQuery(query, 'domain_intelligence');
             const data = await foddaRequest('POST', '/v1/search/domain', apiKey, resolveUserId(userId, uid), body);
+            const domainWithheld = await settleOrWithhold({ queryTypeCode: 'domain_intelligence', apiKey, userId: resolveUserId(userId, uid), query }, 'get_domain_intelligence');
+            if (domainWithheld)
+                return domainWithheld;
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (err) {
@@ -1757,7 +1815,12 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 body.max_evidence_per_trend = max_evidence_per_trend;
             if (min_score !== undefined)
                 body.min_score = min_score;
+            // Log query to Questions table (fire-and-forget, before cache)
+            logUserQuery(query, 'expert_intelligence');
             const data = await foddaRequest('POST', '/v1/search/expert', apiKey, resolveUserId(userId, uid), body);
+            const expertWithheld = await settleOrWithhold({ queryTypeCode: 'expert_intelligence', apiKey, userId: resolveUserId(userId, uid), query }, 'get_expert_intelligence');
+            if (expertWithheld)
+                return expertWithheld;
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (err) {
@@ -1787,7 +1850,12 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 body.max_evidence_per_trend = max_evidence_per_trend;
             if (min_score !== undefined)
                 body.min_score = min_score;
+            // Log query to Questions table (fire-and-forget, before cache)
+            logUserQuery(query, 'report_intelligence');
             const data = await foddaRequest('POST', '/v1/search/report', apiKey, resolveUserId(userId, uid), body);
+            const reportWithheld = await settleOrWithhold({ queryTypeCode: 'report_intelligence', apiKey, userId: resolveUserId(userId, uid), query }, 'get_report_intelligence');
+            if (reportWithheld)
+                return reportWithheld;
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (err) {
@@ -1798,7 +1866,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         }
     });
     // --- search_statistics ---
-    server.tool('search_statistics', "Search for specific quantitative data points — market sizes, growth rates, expert quotes, and brand case studies — directly in Fodda's knowledge graphs. Each result includes its parent trend context, enabling reverse lookup: data point → expert trend. Use this BEFORE supplemental tools when a query asks for specific numbers or statistics that Fodda's experts may have covered. Works on ALL graphs — PSFK curated graphs AND expert graphs. Try multiple graphs for coverage.", {
+    server.tool('search_statistics', "Find specific numbers, market sizes, growth rates, and quantitative data points across Fodda's knowledge graphs. Each result links back to the expert trend it supports. Use when a question asks for specific statistics — try this BEFORE supplemental data tools, as Fodda's experts may have already curated the answer. Works on ALL graphs — domain, expert, and report graphs. Search multiple graphs for best coverage.", {
         graph_id: z.string().describe("Graph ID to search. Works on ALL graphs — PSFK curated ('retail', 'fashion', 'beauty', 'sports', 'sic', 'ce-design', 'pew') AND expert graphs. Search across multiple graphs for best coverage."),
         query: z.string().describe("What data to search for (e.g., 'luxury resale market size', 'secondhand clothing sales volume', 'Gen Z spending behavior')"),
         limit: z.number().optional().describe('Max results to return (default: 10, max: 50)'),
@@ -1807,6 +1875,8 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.')
     }, { title: 'Search Statistics & Data Points', readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ graph_id, query, limit, min_score, include_signals, userId: uid }) => {
         try {
+            // Log query to Questions table (fire-and-forget, before cache)
+            logUserQuery(query, 'search_statistics', graph_id);
             const params = new URLSearchParams();
             params.set('query', query);
             if (limit !== undefined)
@@ -1821,6 +1891,9 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             if (data && typeof data === 'object') {
                 data.theme = getFoddaTheme(graph_id);
             }
+            const statsWithheld = await settleOrWithhold({ queryTypeCode: 'standalone_statistics', apiKey, userId: resolveUserId(userId, uid), query }, 'search_statistics');
+            if (statsWithheld)
+                return statsWithheld;
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (err) {
@@ -1831,7 +1904,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         }
     });
     // --- search_insights ---
-    server.tool('search_insights', 'Search for expert quotes, editorial interpretations, and qualitative evidence across knowledge graphs. Returns categorized evidence (metric, quote, interpretation, signal) with source attribution and parent trend context. Works on ALL graphs. Use when you need named-expert voices, strategic framing, or analytical perspectives on a topic — the kind of curated qualitative intelligence that web search cannot surface because it lives inside structured knowledge graphs, not on public web pages.', {
+    server.tool('search_insights', 'Find expert quotes, editorial analysis, and strategic perspectives on a topic — sourced from named strategists and industry leaders. Returns categorized evidence (metrics, quotes, interpretations, signals) with source attribution and parent trend context. Works on ALL graphs. Use when you need authoritative voices, strategic framing, or analytical depth that web search cannot provide.', {
         graph_id: z.string().describe("Graph ID to search. Works on ALL graphs — PSFK curated ('retail', 'sic', 'beauty', 'sports', 'fashion', 'ce-design', 'pew') AND expert graphs. Search across multiple graphs for best coverage."),
         query: z.string().describe("Natural language search query. E.g. 'expert views on Gen Z luxury' or 'resale market statistics'"),
         types: z.string().optional().describe("Comma-separated evidence types to search: metric, quote, interpretation, signal, or 'all' (default: 'metric,quote,interpretation')"),
@@ -1840,6 +1913,8 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.')
     }, { title: 'Search Expert Insights', readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ graph_id, query, types, limit, min_score, userId: uid }) => {
         try {
+            // Log query to Questions table (fire-and-forget, before cache)
+            logUserQuery(query, 'search_insights', graph_id);
             const searchTypes = types || 'metric,quote,interpretation';
             const params = new URLSearchParams();
             params.set('query', query);
@@ -1850,6 +1925,9 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 params.set('min_score', String(min_score));
             const path = `/v1/graphs/${graph_id}/statistics?${params.toString()}`;
             const data = await foddaRequest('GET', path, apiKey, resolveUserId(userId, uid));
+            const insightsWithheld = await settleOrWithhold({ queryTypeCode: 'standalone_insights', apiKey, userId: resolveUserId(userId, uid), query }, 'search_insights');
+            if (insightsWithheld)
+                return insightsWithheld;
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (err) {
@@ -1863,7 +1941,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
     // Cross-company and industry-level earnings call intelligence.
     // For single-brand earnings, brand_tracker already includes earningsIntelligence.
     // This tool is for: multi-company comparisons, industry/sector filters, and explicit earnings queries.
-    server.tool('get_earnings_intelligence', 'Query earnings call intelligence across companies, industries, or sectors. Returns structured evidence from public company earnings calls — management commentary, guidance, key topics, and analyst Q&A. Use for cross-company comparisons ("what are hotel companies saying about labor costs?"), industry-level queries ("earnings intelligence for consumer electronics"), or explicit earnings requests. For single-brand earnings, use brand_tracker instead — it includes earningsIntelligence automatically. Results include a source field: "knowledge_graph" (high confidence, structured Neo4j data) or "web_supplemental" (backfilled via web search). 5 API calls per use.', {
+    server.tool('get_earnings_intelligence', 'Targeted pull: use when you want ONLY earnings data for a known ticker/sector — not full research. For questions that mix earnings with trends, use deep_research_topic, which includes earnings automatically. Returns structured evidence from public company earnings calls — management commentary, guidance, key topics, and analyst Q&A. Use for cross-company comparisons ("what are hotel companies saying about labor costs?"), industry-level queries ("earnings intelligence for consumer electronics"), or explicit earnings requests. For single-brand earnings, use brand_tracker instead — it includes earningsIntelligence automatically. Results include a source field: "knowledge_graph" (high confidence, structured Neo4j data) or "web_supplemental" (backfilled via web search). Uses 5 tokens ($2.50 via SPT). For cross-company thematic comparisons. For per-ticker data (SWOT, sentiment, guidance), use get_company_earnings instead.', {
         ticker: z.string().optional().describe("Company stock ticker (e.g., 'NKE', 'LVMUY', 'HLT'). At least one filter required."),
         brand: z.string().optional().describe("Brand name for fuzzy matching (e.g., 'Nike', 'Marriott')"),
         industry: z.string().optional().describe("Industry filter (e.g., 'hotels', 'sportswear', 'consumer electronics')"),
@@ -1875,6 +1953,8 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.'),
     }, { title: 'Query Earnings Call Intelligence', readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ ticker, brand, industry, sector, search, dateFrom, dateTo, limit, userId: uid }) => {
         try {
+            // Log query to Questions table (fire-and-forget, before cache)
+            logUserQuery(search || brand || ticker || industry || sector || 'earnings snapshot', 'earnings_intelligence');
             const params = new URLSearchParams();
             if (ticker)
                 params.set('ticker', ticker);
@@ -1893,10 +1973,14 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             if (limit !== undefined)
                 params.set('limit', String(Math.min(limit, 50)));
             const qs = params.toString();
+            const earningsGuard = sptGuard('earnings_intelligence');
+            if (earningsGuard)
+                return earningsGuard;
             const data = await foddaRequest('GET', `/v1/supplemental/earnings/snapshot${qs ? '?' + qs : ''}`, apiKey, resolveUserId(userId, uid));
-            // ── Query-level billing ──
-            chargeQuery({ queryTypeCode: 'earnings_intelligence', apiKey, userId: resolveUserId(userId, uid), query: search || brand || ticker || sector || '', foddaRequest })
-                .catch(e => console.error('[get_earnings_intelligence] chargeQuery failed:', e.message));
+            // ── Query-level billing (settlement gates delivery for SPT) ──
+            const earningsWithheld = await settleOrWithhold({ queryTypeCode: 'earnings_intelligence', apiKey, userId: resolveUserId(userId, uid), query: search || brand || ticker || sector || '' }, 'get_earnings_intelligence');
+            if (earningsWithheld)
+                return earningsWithheld;
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (err) {
@@ -1909,7 +1993,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
     // --- get_earnings_divergence ---
     // Gaps between what analysts are concerned about and how management responds.
     // This is premium intelligence — surfaces deflection and narrative mismatches.
-    server.tool('get_earnings_divergence', 'Detect divergence between analyst concerns and management responses in earnings calls. Surfaces where executives are deflecting, reframing, or avoiding specific topics. Premium intelligence — shows the gap between what Wall Street is worried about and what companies are saying. Results include deflected topics, concern-vs-response framing, and connections to Fodda trends via :VALIDATES edges. Use for "where are executives deflecting?" or "divergence in [sector] earnings." 5 API calls per use.', {
+    server.tool('get_earnings_divergence', 'Targeted pull: use when you want ONLY earnings data for a known ticker/sector — not full research. For questions that mix earnings with trends, use deep_research_topic, which includes earnings automatically. Detects divergence between analyst concerns and management responses in earnings calls — surfaces where executives are deflecting, reframing, or avoiding specific topics. Premium intelligence — shows the gap between what Wall Street is worried about and what companies are saying. Results include deflected topics, concern-vs-response framing, and connections to Fodda trends via :VALIDATES edges. Use for "where are executives deflecting?" or "divergence in [sector] earnings." Uses 5 tokens ($2.50 via SPT). Detects management deflection of analyst concerns.', {
         sector: z.string().optional().describe("Sector filter (e.g., 'retail', 'technology', 'travel')"),
         industry: z.string().optional().describe("Industry filter (e.g., 'hotels', 'sportswear', 'luxury')"),
         search: z.string().optional().describe("Free text search (e.g., 'tariffs', 'AI capex', 'margin erosion')"),
@@ -1919,6 +2003,8 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.'),
     }, { title: 'Detect Earnings Call Divergence', readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ sector, industry, search, dateFrom, dateTo, limit, userId: uid }) => {
         try {
+            // Log query to Questions table (fire-and-forget, before cache)
+            logUserQuery(search || sector || industry || 'earnings divergence', 'earnings_divergence');
             const params = new URLSearchParams();
             if (sector)
                 params.set('sector', sector);
@@ -1933,10 +2019,116 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             if (limit !== undefined)
                 params.set('limit', String(Math.min(limit, 25)));
             const qs = params.toString();
+            const divergenceGuard = sptGuard('earnings_intelligence');
+            if (divergenceGuard)
+                return divergenceGuard;
             const data = await foddaRequest('GET', `/v1/supplemental/earnings/divergence${qs ? '?' + qs : ''}`, apiKey, resolveUserId(userId, uid));
-            // ── Query-level billing ──
-            chargeQuery({ queryTypeCode: 'earnings_intelligence', apiKey, userId: resolveUserId(userId, uid), query: search || sector || industry || 'divergence', foddaRequest })
-                .catch(e => console.error('[get_earnings_divergence] chargeQuery failed:', e.message));
+            // ── Query-level billing (settlement gates delivery for SPT) ──
+            const divergenceWithheld = await settleOrWithhold({ queryTypeCode: 'earnings_intelligence', apiKey, userId: resolveUserId(userId, uid), query: search || sector || industry || 'divergence' }, 'get_earnings_divergence');
+            if (divergenceWithheld)
+                return divergenceWithheld;
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (err) {
+            const trialResult = await handleTrialCreditExhaustion(err, apiKey, userId);
+            if (trialResult)
+                return trialResult;
+            return await handleAccessError(err, 'supplemental');
+        }
+    });
+    // --- get_company_earnings ---
+    // Per-ticker earnings intelligence: SWOT scores, sentiment, guidance, Q&A, competitive analysis.
+    // One tool with a `view` parameter — not 5 separate tools (context budget).
+    server.tool('get_company_earnings', 'Get per-ticker earnings intelligence for consumer-sector public companies. Returns SWOT scores, CEO/analyst sentiment, guidance status, competitive analysis, and validated consumer trends from Fodda\'s quarterly analysis pipeline. Uses 0–15 tokens depending on view (coverage is free, snapshot/history/guidance = 10, qa = 5, compare = 15). Use this for company-specific data. Use get_earnings_intelligence for cross-company thematic comparisons.', {
+        view: z.enum(['snapshot', 'history', 'qa', 'compare', 'guidance', 'coverage']).default('snapshot').describe('snapshot: full quarterly record with SWOT, sentiment, guidance, validated trends (10 tokens). history: SWOT/sentiment scores across quarters for trend analysis (10 tokens). qa: per-analyst Q&A entries with thematic tagging (5 tokens). compare: side-by-side comparison of 2-5 tickers (15 tokens). guidance: cross-coverage guidance changes — raised/cut/withdrawn (10 tokens). coverage: list all covered tickers (free).'),
+        ticker: z.string().optional().describe("Company ticker symbol (e.g. NKE, LULU, ONON). Required for snapshot, history, and qa views."),
+        tickers: z.string().optional().describe("Comma-separated ticker symbols for compare view (2-5 tickers). Only used when view=compare."),
+        period: z.string().optional().describe("Quarter filter (e.g. Q1-2026). Defaults to latest quarter."),
+        metrics: z.string().optional().describe("Comma-separated metric names for history view (e.g. swot_total,ceo_sentiment). Defaults to all."),
+        analyst: z.string().optional().describe("Analyst name filter for qa view."),
+        sector: z.string().optional().describe("Sector filter for guidance view."),
+        userId: z.string().optional().describe('Optional user identifier for trial usage tracking.'),
+    }, { title: 'Get Company Earnings', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ view, ticker, tickers, period, metrics, analyst, sector, userId: uid }) => {
+        try {
+            logUserQuery(ticker || tickers || sector || view || 'company earnings', 'earnings_company');
+            // ── Validation: require params per view ──
+            if ((view === 'snapshot' || view === 'history' || view === 'qa') && !ticker) {
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'MISSING_PARAM', message: `The "${view}" view requires a ticker parameter (e.g. ticker: "NKE").` }) }] };
+            }
+            if (view === 'compare' && !tickers) {
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'MISSING_PARAM', message: 'The "compare" view requires a tickers parameter with 2-5 comma-separated ticker symbols (e.g. tickers: "NKE,LULU,ONON").' }) }] };
+            }
+            // ── Route to API endpoint per view ──
+            let path;
+            let queryTypeCode;
+            switch (view) {
+                case 'snapshot': {
+                    const params = new URLSearchParams();
+                    if (period)
+                        params.set('period', period);
+                    const qs = params.toString();
+                    path = `/v1/earnings/company/${encodeURIComponent(ticker)}${qs ? '?' + qs : ''}`;
+                    queryTypeCode = 'earnings_company';
+                    break;
+                }
+                case 'history': {
+                    const params = new URLSearchParams();
+                    if (metrics)
+                        params.set('metrics', metrics);
+                    const qs = params.toString();
+                    path = `/v1/earnings/company/${encodeURIComponent(ticker)}/history${qs ? '?' + qs : ''}`;
+                    queryTypeCode = 'earnings_history';
+                    break;
+                }
+                case 'qa': {
+                    const params = new URLSearchParams();
+                    if (period)
+                        params.set('period', period);
+                    if (analyst)
+                        params.set('analyst', analyst);
+                    const qs = params.toString();
+                    path = `/v1/earnings/company/${encodeURIComponent(ticker)}/qa${qs ? '?' + qs : ''}`;
+                    queryTypeCode = 'earnings_qa';
+                    break;
+                }
+                case 'compare': {
+                    const params = new URLSearchParams();
+                    params.set('tickers', tickers);
+                    if (period)
+                        params.set('period', period);
+                    path = `/v1/earnings/compare?${params.toString()}`;
+                    queryTypeCode = 'earnings_compare';
+                    break;
+                }
+                case 'guidance': {
+                    const params = new URLSearchParams();
+                    if (sector)
+                        params.set('sector', sector);
+                    if (period)
+                        params.set('period', period);
+                    const qs = params.toString();
+                    path = `/v1/earnings/guidance-changes${qs ? '?' + qs : ''}`;
+                    queryTypeCode = 'earnings_guidance';
+                    break;
+                }
+                case 'coverage': {
+                    // Free endpoint — no billing
+                    const data = await foddaRequest('GET', '/v1/earnings/coverage', apiKey, resolveUserId(userId, uid));
+                    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+                }
+                default:
+                    return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_VIEW', message: `Unknown view "${view}". Valid views: snapshot, history, qa, compare, guidance, coverage.` }) }] };
+            }
+            // ── SPT pre-check ──
+            const guard = sptGuard(queryTypeCode);
+            if (guard)
+                return guard;
+            // ── API call ──
+            const data = await foddaRequest('GET', path, apiKey, resolveUserId(userId, uid));
+            // ── Settlement ──
+            const withheld = await settleOrWithhold({ queryTypeCode, apiKey, userId: resolveUserId(userId, uid), query: ticker || tickers || sector || view }, 'get_company_earnings');
+            if (withheld)
+                return withheld;
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         }
         catch (err) {
@@ -1950,7 +2142,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
     server.tool('update_user_profile', 'Save the user\'s research profile to improve the relevance of future responses. Call this after you understand the user\'s role, industry, and research needs. The profile persists across sessions — you only need to set it once, then update if their focus changes. Write BEHAVIORAL INSTRUCTIONS, not a bio. Format: one sentence of identity (who they are and how they use Fodda), then numbered directives that change how you synthesize and frame responses. Include: what evidence to prioritize, how to frame conclusions, geographic needs, and output structure preferences. Max 2000 chars per field.', {
         userContext: z.string().describe('Behavioral framing instructions for this person. Format: one sentence of identity, then numbered FRAMING INSTRUCTIONS. Example: "Agency strategist doing time-pressured pitches. (1) Lead with landscape orientation — top 3-5 macro forces. (2) Prioritize commercially validated signals over design concepts. (3) ALWAYS differentiate by geography. (4) Executive-ready framing — concise, pitch-deck-ready. (5) Strongest findings first, not exhaustive lists." Max 2000 chars.'),
         accountContext: z.string().optional().describe('Description of their company: industry, size, key markets, competitive position, mission. Shared across all users on this account. Max 2000 chars.'),
-    }, { title: 'Update Research Profile', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ userContext, accountContext }) => {
+    }, { title: 'Update Research Profile', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, async ({ userContext, accountContext }) => {
         try {
             const body = {};
             if (userContext)
@@ -1973,17 +2165,6 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             const msg = err.response?.data?.error?.message || err.response?.data?.message || err.message;
             console.error(`[update_user_profile] Error: ${msg}`);
             // Fail gracefully — don't break the conversation
-            if (isTrial) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                status: 'SKIPPED',
-                                message: 'Profile saving is available for Base accounts and above. I\'ll use this context for the current session. Sign up at app.fodda.ai to persist your preferences.',
-                            }, null, 2)
-                        }]
-                };
-            }
             return {
                 content: [{
                         type: 'text',
@@ -2001,7 +2182,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         target_id: z.string().describe('The ID of the graph, skill, or data source to toggle (e.g., "paralogy", "igloo", "retail", "get_bea_spending_snapshot"). Use the exact ID from list_graphs.'),
         enabled: z.boolean().describe('true to enable (turn on), false to disable (turn off).'),
         user_email: z.string().optional().describe('Optional. Use ONLY when operating as an Admin on behalf of another user to specify their email.')
-    }, { title: 'Toggle Graph or Skill', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ target_id, enabled, user_email }) => {
+    }, { title: 'Toggle Graph or Skill', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, async ({ target_id, enabled, user_email }) => {
         try {
             const body = { target_id, enabled };
             if (user_email)
@@ -2109,7 +2290,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
     });
     // --- sign_up_free_account ---
     const APP_BASE_URL = process.env.FODDA_APP_URL || 'https://app.fodda.ai';
-    server.tool('sign_up_free_account', 'Create a Fodda Base account for a trial user who has run out of credits. Call this when a trial user provides their email after being prompted. Creates an account with 100 API calls/month across ALL knowledge graphs and sends a confirmation email. Can also be called with additional profile fields (name, job_title, company).', {
+    server.tool('sign_up_free_account', 'Create a free Fodda Base account (100 API calls/month across ALL knowledge graphs) and send a confirmation email. GUARDRAIL: only call this AFTER the user has explicitly provided their email and asked to create an account — never sign someone up proactively or with an email inferred from earlier context. Can also pass profile fields (name, job_title, company).', {
         email: z.string().describe('User\'s email address (required)'),
         name: z.string().optional().describe('User\'s full name (optional — collect conversationally after signup)'),
         job_title: z.string().optional().describe('User\'s job title (optional)'),
@@ -2186,6 +2367,8 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         userId: z.string().optional().describe('Optional user identifier for trial usage tracking.'),
     }, { title: 'Brainstorm & Explore Topic', readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ query, depth, userId: uid }) => {
         try {
+            // Log query to Questions table (fire-and-forget, before cache)
+            logUserQuery(query, 'brainstorm_topic');
             const resolvedUserId = resolveUserId(userId, uid);
             const traversalDepth = Math.min(depth || 2, 2);
             // ── Step 1: Find seed trends across all relevant graphs ──
@@ -2347,7 +2530,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 _presentation_hint: 'Present as a brainstorm map. Center: the query. First ring: seed trends. Second ring: adjacent territories. Highlight cross-trend brands and unexpected connections. Suggest follow-up explorations.',
             };
             // ── Query-level billing ──
-            chargeQuery({ queryTypeCode: 'brainstorm', apiKey, userId: resolveUserId(userId, uid), query, foddaRequest })
+            chargeQuery({ queryTypeCode: 'brainstorm', apiKey, userId: resolveUserId(userId, uid), query, foddaRequest, spt: sptCtx?.token })
                 .catch(e => console.error('[brainstorm] chargeQuery failed:', e.message));
             return { content: [{ type: 'text', text: JSON.stringify(brainstormMap, null, 2) }] };
         }
@@ -2358,7 +2541,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         }
     });
     // --- generate_visual ---
-    server.tool('generate_visual', 'Generate a branded SVG data visualization from structured insight data. Use after research to create presentation-ready visuals. Available chart types: "cultural_shifts" (From→To transitions), "competitive_compass" (brands on 2 axes), "trend_constellation" (network of related trends), "implication_ladder" (Signal→Trend→So What→Do What), "innovation_pathway" (Now→Near-Term→Future), "opportunity_map" (2×2 white space analysis). Returns inline SVG that renders directly in the chat.', {
+    server.tool('generate_visual', 'Create a presentation-ready data visualization from research findings. Available chart types: "cultural_shifts" (From→To transitions), "competitive_compass" (brands on 2 axes), "trend_constellation" (network of related trends), "implication_ladder" (Signal→Trend→So What→Do What), "innovation_pathway" (Now→Near-Term→Future), "opportunity_map" (2×2 white space analysis). Returns a branded SVG that renders directly in the chat.', {
         chart_type: z.enum(['cultural_shifts', 'competitive_compass', 'trend_constellation', 'implication_ladder', 'innovation_pathway', 'opportunity_map']).describe('The type of visualization to generate'),
         data: z.string().describe('JSON string containing the chart data. Structure depends on chart_type. cultural_shifts: {shifts:[{from,to}]}. competitive_compass: {brands:[{name,x,y}], axes:{left,right,top,bottom}}. trend_constellation: {trends:[{name,x,y}], connections:[{from,to,strength}]}. implication_ladder: {signal,trend,so_what,do_what}. innovation_pathway: {now,near_term,future}. opportunity_map: {items:[{name,consumer_desire,market_activity}]}'),
     }, { title: 'Generate Visual', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ chart_type, data }) => {
@@ -2417,7 +2600,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             .describe('topic_research for sector trends, brand_intelligence for competitive tracking'),
         brands: z.array(z.string()).optional()
             .describe('For brand_intelligence: brand names to track (e.g., ["Nike", "Patagonia"])'),
-    }, { title: 'Manage Scheduled Reports', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ action, query, email, slack_webhook, graphs, schedule_id, cadence, timezone, report_type, brands }) => {
+    }, { title: 'Manage Scheduled Reports', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }, async ({ action, query, email, slack_webhook, graphs, schedule_id, cadence, timezone, report_type, brands }) => {
         try {
             if (action === 'create') {
                 if (!query)
@@ -2487,7 +2670,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         }
     });
     // --- read_url ---
-    server.tool('read_url', 'Extract clean text content from any URL. Use this when a user shares a link (competitor site, news article, client brief, trend report) and wants to cross-reference it against Fodda knowledge graphs. Returns structured text ready for analysis. Costs 15 API calls.', {
+    server.tool('read_url', 'Extract clean text content from any URL. Use this when a user shares a link (competitor site, news article, client brief, trend report) and wants to cross-reference it against Fodda knowledge graphs. Returns structured text ready for analysis. Uses 15 tokens ($7.50 via SPT).', {
         url: z.string().describe('The URL to read and extract content from'),
         userId: z.string().optional().describe('Optional user identifier for usage tracking.')
     }, { title: 'Read URL Content', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async ({ url, userId: uid }) => {
@@ -2507,7 +2690,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'Could not extract content from this URL. It may be behind a login or paywall.' }) }] };
             }
             // ── Query-level billing ──
-            chargeQuery({ queryTypeCode: 'url_as_prompt', apiKey, userId: resolveUserId(userId, uid), query: url, foddaRequest })
+            chargeQuery({ queryTypeCode: 'url_as_prompt', apiKey, userId: resolveUserId(userId, uid), query: url, foddaRequest, spt: sptCtx?.token })
                 .catch(e => console.error('[read_url] chargeQuery failed:', e.message));
             return {
                 content: [{
@@ -2535,7 +2718,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
     // Uses the fodda-researcher agent with 5 skill instruction files.
     // Flow: Pre-fetch graph data → Build skill-loaded system instruction → 
     // Call Gemini directly via waverunnerRequest → Stream progress via sendLoggingMessage.
-    server.tool('deep_research_topic', 'Launch an autonomous Deep Research session that combines Fodda knowledge graph intelligence with live web research to produce a comprehensive editorial-quality report. The Research Agent plans its own strategy, searches multiple graphs, validates with institutional data, and synthesizes into a narrative brief with inline source citations. Use for complex, multi-faceted questions that need both curated expert intelligence AND current web context — e.g., strategic briefings, market landscape reports, competitive deep dives. Depth: "light" (20 API calls, faster single-pass) or "heavy" (30 API calls, comprehensive multi-pass with validation).', {
+    server.tool('deep_research_topic', 'Launch an autonomous Deep Research session that combines Fodda knowledge graph intelligence with live web research to produce a comprehensive editorial-quality report. The Research Agent plans its own strategy, searches multiple graphs, validates with institutional data, and synthesizes into a narrative brief with inline source citations. Use for complex, multi-faceted questions that need both curated expert intelligence AND current web context — e.g., strategic briefings, market landscape reports, competitive deep dives. Depth: "light" (20 API calls, faster single-pass) or "heavy" (30 API calls, comprehensive multi-pass with validation). Automatically includes earnings-call intelligence and macro/supplemental data when the topic warrants it (public companies, sectors, economic conditions). You do not need to call the earnings or supplemental tools separately before or after.', {
         query: z.string().describe('The research query/topic'),
         graphId: z.string().optional().describe('Optional specific graph ID to limit the research to'),
         depth: z.enum(['light', 'heavy']).optional().describe('Research depth: "light" for faster single-pass (20 API calls), "heavy" for comprehensive multi-pass (30 API calls). Defaults to "light".'),
@@ -2547,6 +2730,10 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         const queryTypeCode = isHeavy ? 'deep_research_heavy' : 'deep_research_light';
         const maxGraphs = isHeavy ? 15 : 8;
         const startTime = Date.now();
+        // ── SPT pre-run coverage: refuse before kicking off the (long, expensive) job ──
+        const researchGuard = sptGuard(queryTypeCode);
+        if (researchGuard)
+            return researchGuard;
         try {
             // Log query to Questions table (fire-and-forget, before cache)
             logUserQuery(query, 'deep_research');
@@ -2556,15 +2743,40 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 data: `📋 Phase 1/5: Planning research approach for "${query.slice(0, 80)}"...`,
             });
             console.error(`[deep_research_topic] Starting ${isHeavy ? 'heavy' : 'light'} research: "${query}"`);
-            // Determine relevant graphs
-            const relevantGraphs = graphId
-                ? [{ graph: { graph_id: graphId } }]
-                : getRelevantGraphs(query).slice(0, maxGraphs);
-            const graphIds = relevantGraphs.map(g => g.graph.graph_id);
+            // Determine relevant sources — unified routing: graph selection is
+            // getRelevantGraphs() unchanged; earnings/supplemental are appended
+            // as additive extras that never displace graph slots.
+            const sourceCandidates = graphId ? [] : getRelevantSources(query);
+            const graphCandidates = sourceCandidates
+                .filter((c) => c.kind === 'graph')
+                .slice(0, maxGraphs);
+            const graphIds = graphId ? [graphId] : graphCandidates.map(c => c.graphId);
+            const earningsCandidate = sourceCandidates.find((c) => c.kind === 'earnings');
+            const supplementalCandidates = sourceCandidates.filter((c) => c.kind === 'supplemental');
+            // Routing visibility: every candidate selected, with why.
+            // Supplemental is async-only (job + poll) — v1 notes the candidate
+            // instead of fetching, pointing at the targeted tool.
+            const sourcePlan = [
+                ...(graphId
+                    ? [{ kind: 'graph', id: graphId, reason: 'explicitly requested via graphId' }]
+                    : graphCandidates.map(c => ({ kind: 'graph', id: c.graphId, reason: c.reason }))),
+                ...(earningsCandidate ? [{
+                        kind: 'earnings',
+                        ...(earningsCandidate.ticker ? { ticker: earningsCandidate.ticker } : {}),
+                        ...(earningsCandidate.brand ? { brand: earningsCandidate.brand } : {}),
+                        ...(earningsCandidate.sector ? { sector: earningsCandidate.sector } : {}),
+                        reason: earningsCandidate.reason,
+                    }] : []),
+                ...supplementalCandidates.map(c => ({
+                    kind: 'supplemental',
+                    category: c.category,
+                    reason: `${c.reason} — not auto-fetched in v1 (async source); targeted tool available: get_supplemental_context`,
+                })),
+            ];
             // ── Phase 2: Searching Fodda Knowledge Graphs ──
             await server.sendLoggingMessage({
                 level: 'info',
-                data: `🔍 Phase 2/5: Searching ${graphIds.length} knowledge graph${graphIds.length !== 1 ? 's' : ''}...`,
+                data: `🔍 Phase 2/5: Searching ${graphIds.length} knowledge graph${graphIds.length !== 1 ? 's' : ''}${earningsCandidate ? ' + earnings intelligence' : ''}...`,
             });
             // Pre-fetch graph data in parallel
             const graphSearchPromises = graphIds.map(async (gid) => {
@@ -2579,7 +2791,33 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                     return { graphId: gid, rows: [], evidence: [] };
                 }
             });
-            const graphResults = await Promise.all(graphSearchPromises);
+            // Earnings candidate: same endpoint as get_earnings_intelligence,
+            // fetched in parallel with graph searches. Failure is non-fatal.
+            const earningsPromise = earningsCandidate
+                ? (async () => {
+                    try {
+                        const params = new URLSearchParams();
+                        if (earningsCandidate.ticker)
+                            params.set('ticker', earningsCandidate.ticker);
+                        if (earningsCandidate.brand)
+                            params.set('brand', earningsCandidate.brand);
+                        if (earningsCandidate.sector)
+                            params.set('sector', earningsCandidate.sector);
+                        if (earningsCandidate.search)
+                            params.set('search', earningsCandidate.search);
+                        params.set('limit', '10');
+                        return await foddaRequest('GET', `/v1/supplemental/earnings/snapshot?${params.toString()}`, apiKey, resolvedUserId);
+                    }
+                    catch (err) {
+                        console.error(`[deep_research_topic] Earnings snapshot failed (non-fatal): ${err?.message}`);
+                        return null;
+                    }
+                })()
+                : Promise.resolve(null);
+            const [graphResults, earningsData] = await Promise.all([
+                Promise.all(graphSearchPromises),
+                earningsPromise,
+            ]);
             const totalTrends = graphResults.reduce((sum, g) => sum + g.rows.length, 0);
             const totalEvidence = graphResults.reduce((sum, g) => sum + g.evidence.length, 0);
             const activeGraphs = graphResults.filter(g => g.rows.length > 0);
@@ -2633,6 +2871,8 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 totalTrends,
                 totalEvidence,
                 focusGraphId: graphId,
+                // Distinct earnings block — attributed by source type at synthesis
+                ...(earningsData ? { earningsResults: JSON.stringify(earningsData).substring(0, 15000) } : {}),
             };
             // Build skill-loaded system instruction
             const systemInstruction = buildResearcherInstruction(query, graphContext);
@@ -2724,16 +2964,20 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                         return;
                     }
                     const durationSec = ((Date.now() - startTime) / 1000).toFixed(1);
-                    chargeQuery({
-                        queryTypeCode,
-                        apiKey,
-                        userId: resolvedUserId,
-                        query,
-                        graphsSearched: graphIds,
-                        foddaRequest,
-                    }).catch(e => console.error('[deep_research_topic] chargeQuery failed:', e.message));
+                    // ── Settlement gates delivery for SPT: only mark COMPLETE once the charge succeeds. ──
+                    if (sptCtx) {
+                        const r = await chargeQuery({ queryTypeCode, apiKey, userId: resolvedUserId, query, graphsSearched: graphIds, foddaRequest, spt: sptCtx.token });
+                        if (!r.charged) {
+                            activeResearchJobs.set(jobId, { status: 'FAILED', error: r.error || 'Payment could not be completed; report withheld.' });
+                            return;
+                        }
+                    }
+                    else {
+                        chargeQuery({ queryTypeCode, apiKey, userId: resolvedUserId, query, graphsSearched: graphIds, foddaRequest })
+                            .catch(e => console.error('[deep_research_topic] chargeQuery failed:', e.message));
+                    }
                     const header = [
-                        `_Research by Fodda Research Agent • ${activeGraphs.length} graph${activeGraphs.length !== 1 ? 's' : ''} searched • ${totalTrends} trends analyzed • ${durationSec}s_`,
+                        `_Research by Fodda Research Agent • ${activeGraphs.length} graph${activeGraphs.length !== 1 ? 's' : ''} searched • ${totalTrends} trends analyzed${earningsData ? ' • earnings intelligence included' : ''} • ${durationSec}s_`,
                         '',
                     ].join('\n');
                     activeResearchJobs.set(jobId, { status: 'COMPLETE', result: header + reportText });
@@ -2746,7 +2990,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             return {
                 content: [{
                         type: 'text',
-                        text: `Deep research job started! The agent is searching the graph and the live web. Job ID: ${jobId}\n\nIMPORTANT: You must use the check_research_status tool with this Job ID to poll the status of the job and retrieve the report.`
+                        text: `Deep research job started! The agent is searching the graph and the live web. Job ID: ${jobId}\n\nsource_plan (sources the router selected and why — earnings/supplemental are included automatically when relevant, so no separate earnings or supplemental calls are needed):\n${JSON.stringify(sourcePlan, null, 2)}\n\nIMPORTANT: You must use the check_research_status tool with this Job ID to poll the status of the job and retrieve the report.`
                     }]
             };
         }
@@ -2759,7 +3003,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         }
     });
     // --- check_research_status ---
-    server.tool('check_research_status', 'Check the status of a long-running deep research job. If complete, this tool returns the final report. You MUST poll this periodically until the status is COMPLETE or FAILED.', {
+    server.tool('check_research_status', 'Check if deep research is complete and retrieve the final report. Call this after deep_research_topic — poll every 10 seconds until status is COMPLETE or FAILED.', {
         job_id: z.string().describe('The Job ID returned by deep_research_topic'),
     }, { title: 'Check Research Status', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ job_id }) => {
         const job = activeResearchJobs.get(job_id);
@@ -2780,7 +3024,7 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
         return { isError: true, content: [{ type: 'text', text: `Unknown status for job ${job_id}` }] };
     });
     // --- consult_analyst ---
-    server.tool('consult_analyst', 'Consult a named Synthetic Analyst who answers in their expert voice using their curated knowledge graph. Each analyst has a unique methodology, domain expertise, and analytical lens that produces insights distinct from generic search or standard graph queries. Use when the user asks to talk to or consult a specific expert, or when you need a specialist perspective on culture, strategy, or innovation topics. Call list_analysts first to discover available analyst_id values. Responses may include a coverage status (in/adjacent/out), source attribution, and referrals to other expert graphs. Referrals MUST be presented in third-person platform voice (not the expert\'s voice) with an offer to query the referred graph.', {
+    server.tool('consult_analyst', 'Consult a named Synthetic Analyst who answers in their expert voice using their curated knowledge graph. Each analyst has a unique methodology, domain expertise, and analytical lens that produces insights distinct from generic search or standard graph queries. Use when the user asks to talk to or consult a specific expert, or when you need a specialist perspective on culture, strategy, or innovation topics. Call list_analysts first to discover available analyst_id values. Responses may include a coverage status (in/adjacent/out), source attribution, and referrals to other expert graphs. Referrals MUST be presented in third-person platform voice (not the expert\'s voice) with an offer to query the referred graph. The analyst researches on your behalf: they can search Fodda\'s graphs, earnings intelligence, and supplemental data mid-consultation, and may refer or consult other analysts. Their research reads bill to you at standard rates ($0.50/call) and are itemized in `sources_used`.', {
         analyst_id: z.string().describe("The analyst ID (e.g., 'ben-dietz-sic')"),
         query: z.string().describe("The question or topic to discuss with the analyst"),
         company: z.string().optional().describe("Optional company name or stock ticker (e.g., 'Tesla' or 'TSLA') to bind the analyst to a specific brand context."),
@@ -2799,6 +3043,10 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
                 ? result.result
                 : (typeof result.report === 'string' ? result.report : JSON.stringify(result, null, 2));
             const parts = [reportText];
+            // Surface server-side timing for observability
+            if (result.timing_ms != null) {
+                parts.push(`\n--- TIMING: ${result.timing_ms}ms server-side ---`);
+            }
             // --- Structured envelope fields (Phase 2 Digital Twin) ---
             if (result.coverage) {
                 parts.push(`\n--- COVERAGE: ${result.coverage} ---`);
@@ -2814,12 +3062,23 @@ export async function createServer(apiKey, userId, foddaRequest, waverunnerReque
             if (result.speaker_note) {
                 parts.push(`--- SPEAKER NOTE: ${result.speaker_note} ---`);
             }
+            const consultWithheld = await settleOrWithhold({ queryTypeCode: 'expert_agent', apiKey, userId: resolveUserId(userId, uid), query }, 'consult_analyst');
+            if (consultWithheld)
+                return consultWithheld;
             return { content: [{ type: 'text', text: parts.join('\n') }] };
         }
         catch (err) {
             const trialResult = await handleTrialCreditExhaustion(err, apiKey, userId);
             if (trialResult)
                 return trialResult;
+            // Surface timeout explicitly so clients get actionable guidance
+            if (err.code === 'ECONNABORTED' || err.message?.includes('timeout')) {
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({
+                                error: `Analyst consultation timed out (60s). The upstream API is processing a complex query with tool calls. Retry in a moment, or use search_graph / get_expert_intelligence for faster results.`,
+                                analyst_id,
+                                timeout: true
+                            }) }] };
+            }
             const msg = err.response?.data?.error?.message || err.response?.data?.message || err.message;
             return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: msg }) }] };
         }