@f5xc-salesdemos/xcsh 18.70.0 → 18.72.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.70.0",
+	"version": "18.72.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -48,12 +48,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "18.70.0",
-		"@f5xc-salesdemos/pi-agent-core": "18.70.0",
-		"@f5xc-salesdemos/pi-ai": "18.70.0",
-		"@f5xc-salesdemos/pi-natives": "18.70.0",
-		"@f5xc-salesdemos/pi-tui": "18.70.0",
-		"@f5xc-salesdemos/pi-utils": "18.70.0",
+		"@f5xc-salesdemos/xcsh-stats": "18.72.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.72.0",
+		"@f5xc-salesdemos/pi-ai": "18.72.0",
+		"@f5xc-salesdemos/pi-natives": "18.72.0",
+		"@f5xc-salesdemos/pi-tui": "18.72.0",
+		"@f5xc-salesdemos/pi-utils": "18.72.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.70.0",
-	"commit": "34f16142c582f937c72feae361239b82a67657df",
-	"shortCommit": "34f1614",
+	"version": "18.72.0",
+	"commit": "ee865e583dfa21db5c5f5bf07001570c5f7f9086",
+	"shortCommit": "ee865e5",
 	"branch": "main",
-	"tag": "v18.70.0",
-	"commitDate": "2026-05-19T06:13:53Z",
-	"buildDate": "2026-05-19T06:39:53.619Z",
+	"tag": "v18.72.0",
+	"commitDate": "2026-05-19T19:45:52Z",
+	"buildDate": "2026-05-19T20:24:28.090Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/34f16142c582f937c72feae361239b82a67657df",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.70.0"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/ee865e583dfa21db5c5f5bf07001570c5f7f9086",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.72.0"
 };

package/src/pipeline-report/generator.ts

@@ -2,9 +2,12 @@ import { logger } from "@f5xc-salesdemos/pi-utils";
 import { $ } from "bun";
 import type {
 	AccountRow,
+	CloseMonthBucket,
 	DataAnomaly,
+	DealSummary,
 	ForecastSummary,
 	LineItemRecord,
+	PipelineChange,
 	PipelineReportData,
 	PipelineReportOptions,
 	SectionData,
@@ -67,6 +70,12 @@ function parseLineItem(record: Record<string, unknown>, rules: SkuClassification
 		skuName,
 		fyb: (record.FYB_Total_Price__c as number) ?? 0,
 		category: classifySku(skuName, rules),
+		closeDate: (opp.CloseDate as string) ?? undefined,
+		oppName: (opp.Name as string) ?? undefined,
+		stage: (opp.StageName as string) ?? undefined,
+		lastActivityDate: (opp.LastActivityDate as string) ?? undefined,
+		ownerName: ((opp.Owner as Record<string, unknown> | undefined)?.Name as string) ?? undefined,
+		nextStep: (opp.NextStep as string) ?? undefined,
 	};
 }
 
@@ -139,6 +148,116 @@ function buildForecast(items: LineItemRecord[]): ForecastSummary {
 	return { commit: buckets.Commit, bestCase: buckets["Best Case"], pipeline: buckets.Pipeline };
 }
 
+/** Aggregate net new line items by opportunity and return the top N by quota-eligible amount. */
+function buildTopDeals(items: LineItemRecord[], limit = 5): DealSummary[] {
+	const oppMap = new Map<
+		string,
+		{
+			name: string;
+			accountName: string;
+			stage: string;
+			closeDate: string;
+			forecast: string;
+			amount: number;
+			ownerName: string;
+			nextStep: string;
+		}
+	>();
+	for (const item of items) {
+		if (item.category === "other" || item.fyb <= 0) continue;
+		const existing = oppMap.get(item.opportunityId);
+		if (existing) {
+			existing.amount += item.fyb;
+		} else {
+			oppMap.set(item.opportunityId, {
+				name: item.oppName ?? item.accountName,
+				accountName: item.accountName,
+				stage: item.stage ?? "",
+				closeDate: item.closeDate ?? "",
+				forecast: item.forecast,
+				amount: item.fyb,
+				ownerName: item.ownerName ?? "",
+				nextStep: item.nextStep ?? "",
+			});
+		}
+	}
+	return [...oppMap.entries()]
+		.sort(([, a], [, b]) => b.amount - a.amount)
+		.slice(0, limit)
+		.map(([id, d]) => ({
+			oppId: id,
+			name: d.name,
+			accountName: d.accountName,
+			stage: d.stage,
+			closeDate: d.closeDate,
+			forecast: d.forecast,
+			amount: d.amount,
+			ownerName: d.ownerName,
+			nextStep: d.nextStep || undefined,
+		}));
+}
+
+/** Build close-date distribution buckets from net new line items (quota-eligible only). */
+function buildCloseDistribution(items: LineItemRecord[]): CloseMonthBucket[] {
+	const buckets = new Map<
+		string,
+		{ amount: number; commit: number; bestCase: number; pipeline: number; oppIds: Set<string> }
+	>();
+	for (const item of items) {
+		if (item.category === "other" || item.fyb <= 0 || !item.closeDate) continue;
+		const ym = item.closeDate.slice(0, 7); // YYYY-MM
+		const existing = buckets.get(ym) ?? {
+			amount: 0,
+			commit: 0,
+			bestCase: 0,
+			pipeline: 0,
+			oppIds: new Set<string>(),
+		};
+		existing.amount += item.fyb;
+		existing.oppIds.add(item.opportunityId);
+		if (item.forecast === "Commit") existing.commit += item.fyb;
+		else if (item.forecast === "Best Case") existing.bestCase += item.fyb;
+		else if (item.forecast === "Pipeline") existing.pipeline += item.fyb;
+		buckets.set(ym, existing);
+	}
+	return [...buckets.entries()]
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([ym, data]) => {
+			const d = new Date(`${ym}-01T00:00:00`);
+			const label = d.toLocaleDateString("en-US", { month: "long", year: "numeric" });
+			return {
+				label,
+				yearMonth: ym,
+				amount: data.amount,
+				commit: data.commit,
+				bestCase: data.bestCase,
+				pipeline: data.pipeline,
+				oppCount: data.oppIds.size,
+			};
+		});
+}
+
+/** Parse OpportunityFieldHistory records into PipelineChange entries. */
+function parseHistoryRecords(records: Record<string, unknown>[]): PipelineChange[] {
+	return records
+		.map((r): PipelineChange | null => {
+			const opp = (r.Opportunity ?? {}) as Record<string, unknown>;
+			const acct = (opp.Account ?? {}) as Record<string, unknown>;
+			const field = r.Field as string;
+			if (field !== "Amount" && field !== "ForecastCategoryName" && field !== "StageName") return null;
+			return {
+				oppId: (r.OpportunityId as string) ?? "",
+				dealName: ((opp.Name as string) ?? "").trim(),
+				accountName: ((acct.Name as string) ?? "").trim(),
+				field,
+				oldValue: String(r.OldValue ?? "\u2014"),
+				newValue: String(r.NewValue ?? "\u2014"),
+				date: ((r.CreatedDate as string) ?? "").slice(0, 10),
+			};
+		})
+		.filter((c): c is PipelineChange => c !== null);
+}
+
 // ---------------------------------------------------------------------------
 // Anomaly detection
 // ---------------------------------------------------------------------------
@@ -146,6 +265,7 @@ function buildForecast(items: LineItemRecord[]): ForecastSummary {
 function detectAnomalies(
 	netNew: LineItemRecord[],
 	booked: LineItemRecord[],
+	renewals: LineItemRecord[],
 	classification: SkuClassification,
 ): DataAnomaly[] {
 	const anomalies: DataAnomaly[] = [];
@@ -210,6 +330,93 @@ function detectAnomalies(
 		});
 	}
 
+	// 5. Open deals with close dates that have slipped past TODAY (requires CloseDate in data)
+	const today = new Date().toISOString().split("T")[0]!;
+	const slippedAccounts = new Map<string, string>(); // accountName → earliest slipped closeDate
+	for (const item of netNew) {
+		if (item.closeDate && item.closeDate < today) {
+			const existing = slippedAccounts.get(item.accountName);
+			if (!existing || item.closeDate < existing) {
+				slippedAccounts.set(item.accountName, item.closeDate);
+			}
+		}
+	}
+	if (slippedAccounts.size > 0) {
+		const details = [...slippedAccounts.entries()]
+			.sort(([, a], [, b]) => a.localeCompare(b))
+			.map(([name, date]) => `${name} (${date})`)
+			.join(", ");
+		anomalies.push({
+			severity: "warning",
+			category: "slipped-close-date",
+			message: `${slippedAccounts.size} account(s) have open pipeline with close dates in the past`,
+			details,
+		});
+	}
+
+	// 6. Stalled deals — open pipeline with no activity in >30 days
+	// Use the MOST RECENT activity date per account — if any deal has recent activity,
+	// the account is not stalled.
+	const staleThreshold = new Date();
+	staleThreshold.setDate(staleThreshold.getDate() - 30);
+	const staleStr = staleThreshold.toISOString().split("T")[0]!;
+	const acctLastActivity = new Map<string, string | null>(); // accountName → best lastActivityDate
+	for (const item of netNew) {
+		const existing = acctLastActivity.get(item.accountName);
+		const lad = item.lastActivityDate ?? null;
+		if (existing === undefined) {
+			acctLastActivity.set(item.accountName, lad);
+		} else if (lad && (!existing || lad > existing)) {
+			acctLastActivity.set(item.accountName, lad);
+		}
+	}
+	const stalledAccounts = new Map<string, string>();
+	for (const [name, lad] of acctLastActivity) {
+		if (!lad) {
+			stalledAccounts.set(name, "(no activity recorded)");
+		} else if (lad < staleStr) {
+			stalledAccounts.set(name, lad);
+		}
+	}
+	if (stalledAccounts.size > 0) {
+		const details = [...stalledAccounts.entries()]
+			.sort(([a], [b]) => a.localeCompare(b))
+			.map(([name, date]) => `${name} (${date})`)
+			.join(", ");
+		anomalies.push({
+			severity: "warning",
+			category: "stalled-deals",
+			message: `${stalledAccounts.size} account(s) have open pipeline with no activity in >30 days`,
+			details,
+		});
+	}
+
+	// 7. Urgent renewals — closing within 30 days
+	const urgentThreshold = new Date();
+	urgentThreshold.setDate(urgentThreshold.getDate() + 30);
+	const urgentStr = urgentThreshold.toISOString().split("T")[0]!;
+	const urgentRenewals = new Map<string, string>(); // accountName → closeDate
+	for (const item of renewals) {
+		if (item.closeDate && item.closeDate <= urgentStr) {
+			const existing = urgentRenewals.get(item.accountName);
+			if (!existing || item.closeDate < existing) {
+				urgentRenewals.set(item.accountName, item.closeDate);
+			}
+		}
+	}
+	if (urgentRenewals.size > 0) {
+		const details = [...urgentRenewals.entries()]
+			.sort(([, a], [, b]) => a.localeCompare(b))
+			.map(([name, date]) => `${name} (${date})`)
+			.join(", ");
+		anomalies.push({
+			severity: "warning",
+			category: "urgent-renewals",
+			message: `${urgentRenewals.size} account(s) have renewals closing within 30 days`,
+			details,
+		});
+	}
+
 	return anomalies;
 }
 
@@ -231,42 +438,38 @@ export async function generatePipelineReport(options: PipelineReportOptions): Pr
 	const staleCutoff = options.staleCutoff;
 
 	const userFilter = buildUserFilter(userIds);
-	const ownerFilter =
-		userIds.length === 1 ? `OwnerId = '${userIds[0]}'` : `OwnerId IN (${userIds.map(id => `'${id}'`).join(",")})`;
+	// SOQL does not allow OR between a semi-join subselect and other fields inside
+	// parentheses ("Semi join sub-selects are only allowed at the top level").
+	// The OpportunityTeamMember subselect already covers both SE and AE via userIds.
 	const skuFilter = buildSkuFilter(skuPrefixes);
 
 	const fields = [
 		"Product2.Name",
 		"FYB_Total_Price__c",
 		"Opportunity.Id",
+		"Opportunity.Name",
 		"Opportunity.Account.Name",
 		"Opportunity.Territory_Credited_District_del__c",
 		"Opportunity.ForecastCategoryName",
+		"Opportunity.StageName",
+		"Opportunity.IsClosed",
+		"Opportunity.IsWon",
+		"Opportunity.CloseDate",
+		"Opportunity.LastActivityDate",
+		"Opportunity.Owner.Name",
+		"Opportunity.NextStep",
 	].join(", ");
 	const commonFilters = `Subscription_Renewal__c = false AND Opportunity.ForecastCategoryName != 'Omitted' AND FYB_Total_Price__c > 0 AND (${skuFilter})`;
 	const quarterDateFilter = `Opportunity.CloseDate >= ${quarterStart} AND Opportunity.CloseDate <= ${quarterEnd}`;
 	const inPlayDateFilter = staleCutoff ? `Opportunity.CloseDate >= ${staleCutoff}` : quarterDateFilter;
 
-	const teamScope = `(OpportunityId IN (SELECT OpportunityId FROM OpportunityTeamMember WHERE ${userFilter}) OR ${ownerFilter})`;
+	const oliTeamScope = `OpportunityId IN (SELECT OpportunityId FROM OpportunityTeamMember WHERE ${userFilter})`;
 
-	// In-play: uses staleCutoff if set, otherwise quarter dates
-	// Booked: always quarter dates
-	const [netNewRecords, bookedRecords] = await Promise.all([
-		runSfQuery(
-			`SELECT ${fields} FROM OpportunityLineItem WHERE ${teamScope} AND Opportunity.IsClosed = false AND ${inPlayDateFilter} AND ${commonFilters}`,
-			orgAlias,
-		),
-		runSfQuery(
-			`SELECT ${fields} FROM OpportunityLineItem WHERE ${teamScope} AND Opportunity.IsWon = true AND ${quarterDateFilter} AND ${commonFilters}`,
-			orgAlias,
-		),
-	]);
-
-	// Parse line items
-	const netNewItems = netNewRecords.map(r => parseLineItem(r, skuClassification));
-	const bookedItems = bookedRecords.map(r => parseLineItem(r, skuClassification));
+	// Combined OLI query: net new (open, in-play dates) + booked (won, quarter dates) in one SOQL.
+	// The OR between regular conditions is allowed (SOQL only restricts OR with semi-join subselects).
+	const combinedDateFilter = `((Opportunity.IsClosed = false AND ${inPlayDateFilter}) OR (Opportunity.IsWon = true AND ${quarterDateFilter}))`;
 
-	// --- Renewals: opportunity-level True_ACV (FYB returns $0 for renewals) ---
+	// Build renewals query alongside OLI query (no dependency between them)
 	const renewalFields = [
 		"Id",
 		"Account.Name",
@@ -277,17 +480,133 @@ export async function generatePipelineReport(options: PipelineReportOptions): Pr
 		"Use_Case_Category__c",
 		"ForecastCategoryName",
 		"Territory_Credited_District_del__c",
+		"CloseDate",
+		"Name",
 	].join(", ");
-
 	const renewalDateFilter = staleCutoff
 		? `CloseDate >= ${staleCutoff}`
 		: `CloseDate >= ${quarterStart} AND CloseDate <= ${quarterEnd}`;
-	const renewalWhere = `(Id IN (SELECT OpportunityId FROM OpportunityTeamMember WHERE ${userFilter}) OR ${ownerFilter}) AND IsClosed = false AND Renewal__c = true AND ${renewalDateFilter} AND ForecastCategoryName != 'Omitted' AND (True_ACV__c > 1 OR Upsell_ACV__c > 1 OR Amount > 1)`;
+	const renewalWhere = `Id IN (SELECT OpportunityId FROM OpportunityTeamMember WHERE ${userFilter}) AND IsClosed = false AND Renewal__c = true AND ${renewalDateFilter} AND ForecastCategoryName != 'Omitted' AND (True_ACV__c > 1 OR Upsell_ACV__c > 1 OR Amount > 1)`;
+	// F5 fiscal year starts November 1. Derive from the report's quarter dates, not wall-clock,
+	// so the FY context matches the requested report period.
+	const qStartDate = new Date(quarterStart + "T00:00:00");
+	const qMonth = qStartDate.getMonth();
+	const qYear = qStartDate.getFullYear();
+	const fyStartYear = qMonth >= 10 ? qYear : qYear - 1;
+	const fyStart = `${fyStartYear}-11-01`;
+	const fyLabel = `FY${(fyStartYear + 1) % 100}`;
+	const todayStr = new Date().toISOString().split("T")[0]!;
+	const oppTeamScope = `Id IN (SELECT OpportunityId FROM OpportunityTeamMember WHERE ${userFilter})`;
+	const fyBookedQuery = `SELECT SUM(Amount) total FROM Opportunity WHERE ${oppTeamScope} AND IsWon = true AND CloseDate >= ${fyStart} AND CloseDate <= ${todayStr}`;
+
+	// Three parallel queries first: combined OLI + renewals + FY booked
+	const [oliRecords, renewalRecords, fyBookedResult] = await Promise.all([
+		runSfQuery(
+			`SELECT ${fields} FROM OpportunityLineItem WHERE ${oliTeamScope} AND ${combinedDateFilter} AND ${commonFilters}`,
+			orgAlias,
+		),
+		runSfQuery(
+			`SELECT ${renewalFields} FROM Opportunity WHERE ${renewalWhere} ORDER BY True_ACV__c DESC NULLS LAST`,
+			orgAlias,
+		),
+		runSfQuery(fyBookedQuery, orgAlias),
+	]);
+	const fyBookedTotal = (fyBookedResult[0]?.total as number) ?? 0;
+
+	// --- Split combined OLI records + fallback when empty ---
+	let netNewItems: LineItemRecord[];
+	let bookedItems: LineItemRecord[];
+
+	if (oliRecords.length > 0) {
+		netNewItems = [];
+		bookedItems = [];
+		for (const r of oliRecords) {
+			const item = parseLineItem(r, skuClassification);
+			const opp = (r.Opportunity ?? {}) as Record<string, unknown>;
+			if (opp.IsWon as boolean) {
+				bookedItems.push(item);
+			} else if (!(opp.IsClosed as boolean)) {
+				netNewItems.push(item);
+			}
+		}
+	} else {
+		// Opportunity-level fallback when OLI queries return no data.
+		// Collects renewal IDs first so we can exclude them — renewals have their own query
+		// and would double-count if included in net new/booked.
+		const renewalIds = new Set<string>();
+		for (const r of renewalRecords) {
+			const id = (r.Id ?? "") as string;
+			if (id) renewalIds.add(id);
+		}
+		const oppFields =
+			"Id, Name, Account.Name, Amount, ForecastCategoryName, StageName, CloseDate, LastActivityDate, Owner.Name, IsClosed, IsWon";
+		const oppTeamScope = `Id IN (SELECT OpportunityId FROM OpportunityTeamMember WHERE ${userFilter})`;
+		const oppDateFilter = staleCutoff
+			? `CloseDate >= ${staleCutoff}`
+			: `CloseDate >= ${quarterStart} AND CloseDate <= ${quarterEnd}`;
+		const oppWhere = `${oppTeamScope} AND ForecastCategoryName != 'Omitted' AND Amount > 0 AND IsClosed = false AND ${oppDateFilter}`;
+		const bookedWhere = `${oppTeamScope} AND ForecastCategoryName != 'Omitted' AND Amount > 0 AND IsWon = true AND CloseDate >= ${quarterStart} AND CloseDate <= ${quarterEnd}`;
+
+		const [fallbackNetNew, fallbackBooked] = await Promise.all([
+			runSfQuery(`SELECT ${oppFields} FROM Opportunity WHERE ${oppWhere} ORDER BY Amount DESC NULLS LAST`, orgAlias),
+			runSfQuery(
+				`SELECT ${oppFields} FROM Opportunity WHERE ${bookedWhere} ORDER BY Amount DESC NULLS LAST`,
+				orgAlias,
+			),
+		]);
+
+		function parseOppFallback(records: Record<string, unknown>[]): LineItemRecord[] {
+			const items: LineItemRecord[] = [];
+			const seen = new Set<string>();
+			for (const r of records) {
+				const id = (r.Id ?? "") as string;
+				if (seen.has(id) || renewalIds.has(id)) continue;
+				seen.add(id);
+				const acct = ((r.Account as Record<string, unknown> | undefined)?.Name ?? "") as string;
+				const fc = (r.ForecastCategoryName ?? "") as string;
+				const amt = (r.Amount as number) ?? 0;
+				if (amt <= 0) continue;
+				const owner = (r.Owner as Record<string, unknown> | undefined)?.Name;
+				items.push({
+					opportunityId: id,
+					accountName: acct,
+					territory: "",
+					forecast: fc,
+					skuName: "Opportunity-level",
+					fyb: amt,
+					category: "platform",
+					closeDate: (r.CloseDate as string) ?? undefined,
+					oppName: (r.Name as string) ?? undefined,
+					stage: (r.StageName as string) ?? undefined,
+					lastActivityDate: (r.LastActivityDate as string) ?? undefined,
+					ownerName: (owner as string) ?? undefined,
+				});
+			}
+			return items;
+		}
 
-	const renewalRecords = await runSfQuery(
-		`SELECT ${renewalFields} FROM Opportunity WHERE ${renewalWhere} ORDER BY True_ACV__c DESC NULLS LAST`,
-		orgAlias,
-	);
+		netNewItems = parseOppFallback(fallbackNetNew);
+		bookedItems = parseOppFallback(fallbackBooked);
+	}
+
+	// History query: run AFTER OLI to use specific opp IDs (avoids slow semi-join on FieldHistory).
+	// Only runs in the normal OLI path — in the fallback path we've already spent 5 queries
+	// (3 parallel + 2 fallback) and would exceed the 5-query constraint.
+	const allOppIds = new Set<string>();
+	for (const item of [...netNewItems, ...bookedItems]) {
+		if (item.opportunityId) allOppIds.add(item.opportunityId);
+	}
+	let historyRecords: Record<string, unknown>[] = [];
+	if (oliRecords.length > 0 && allOppIds.size > 0) {
+		const idList = [...allOppIds].map(id => `'${id}'`).join(",");
+		const historyFields =
+			"OpportunityId, Opportunity.Name, Opportunity.Account.Name, Field, OldValue, NewValue, CreatedDate";
+		const historyWhere = `OpportunityId IN (${idList}) AND Field IN ('Amount','ForecastCategoryName','StageName') AND CreatedDate = LAST_N_DAYS:7`;
+		historyRecords = await runSfQuery(
+			`SELECT ${historyFields} FROM OpportunityFieldHistory WHERE ${historyWhere} ORDER BY CreatedDate DESC LIMIT 50`,
+			orgAlias,
+		);
+	}
 
 	// Parse and classify renewal opps, dedup by Id
 	const seenIds = new Set<string>();
@@ -326,6 +645,8 @@ export async function generatePipelineReport(options: PipelineReportOptions): Pr
 			skuName: (r.Product_Segmentation__c ?? "") as string,
 			fyb: val,
 			category,
+			closeDate: (r.CloseDate as string) ?? undefined,
+			oppName: (r.Name as string) ?? undefined,
 		});
 	}
 
@@ -335,7 +656,7 @@ export async function generatePipelineReport(options: PipelineReportOptions): Pr
 		if (item.skuName) allSkus.add(item.skuName);
 	}
 	// Detect anomalies
-	const anomalies = detectAnomalies(netNewItems, bookedItems, skuClassification);
+	const anomalies = detectAnomalies(netNewItems, bookedItems, renewalItems, skuClassification);
 
 	return {
 		generated: new Date().toISOString(),
@@ -349,5 +670,12 @@ export async function generatePipelineReport(options: PipelineReportOptions): Pr
 		lineItemCount: netNewItems.length + bookedItems.length + renewalItems.length,
 		skusFound: [...allSkus].sort(),
 		anomalies,
+		topDeals: buildTopDeals(netNewItems),
+		topRenewals: renewalItems.length > 0 ? buildTopDeals(renewalItems) : undefined,
+		closeDistribution: buildCloseDistribution(netNewItems),
+		renewalDistribution: renewalItems.length > 0 ? buildCloseDistribution(renewalItems) : undefined,
+		fyBookedTotal: fyBookedTotal > 0 ? fyBookedTotal : undefined,
+		fyLabel,
+		recentChanges: parseHistoryRecords(historyRecords),
 	};
 }

package/src/pipeline-report/renderer.ts

@@ -1,12 +1,12 @@
 import type { AccountRow, DataAnomaly, PipelineReportData, SectionData } from "./types";
 
 function fmtCurrency(val: number): string {
-	if (val === 0) return "\u2014";
+	if (!Number.isFinite(val) || val === 0) return "\u2014";
 	return val.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
 }
 
 function fmtCompact(val: number): string {
-	if (val === 0) return "\u2014";
+	if (!Number.isFinite(val) || val === 0) return "\u2014";
 	if (val >= 1_000_000) return `$${(val / 1_000_000).toFixed(1)}M`;
 	if (val >= 1_000) return `$${(val / 1_000).toFixed(0)}K`;
 	return `$${val.toFixed(0)}`;
@@ -29,13 +29,35 @@ function renderAnomalies(anomalies: DataAnomaly[]): string {
 	return lines.join("\n");
 }
 
+function fmtQuarterDate(dateStr: string): string {
+	const d = new Date(`${dateStr}T00:00:00`);
+	if (Number.isNaN(d.getTime())) return dateStr;
+	return d.toLocaleDateString("en-US", { month: "long", day: "numeric", year: "numeric" });
+}
+
+/** Derive F5 fiscal quarter label from quarter start date.
+ *  F5 fiscal year starts November 1: Q1=Nov–Jan, Q2=Feb–Apr, Q3=May–Jul, Q4=Aug–Oct. */
+function fmtFiscalQuarter(startDateStr: string): string {
+	const d = new Date(`${startDateStr}T00:00:00`);
+	if (Number.isNaN(d.getTime())) return "";
+	const m = d.getMonth(); // 0-indexed
+	const y = d.getFullYear();
+	if (m >= 10) return `FY${(y + 1) % 100} Q1`;
+	if (m <= 0) return `FY${y % 100} Q1`;
+	if (m <= 3) return `FY${y % 100} Q2`;
+	if (m <= 6) return `FY${y % 100} Q3`;
+	return `FY${y % 100} Q4`;
+}
+
 export function renderPipelineReport(data: PipelineReportData, _instanceUrl: string): string {
 	const lines: string[] = [];
 
 	lines.push("# F5 Distributed Cloud Pipeline Report");
 	lines.push("");
 	lines.push(`**Generated:** ${new Date(data.generated).toLocaleString()}`);
-	lines.push(`**Quarter:** ${data.quarter.start} \u2014 ${data.quarter.end}`);
+	const fq = fmtFiscalQuarter(data.quarter.start);
+	const dateRange = `${fmtQuarterDate(data.quarter.start)} \u2014 ${fmtQuarterDate(data.quarter.end)}`;
+	lines.push(`**Quarter:** ${fq ? `${fq} (${dateRange})` : dateRange}`);
 	if (data.territories.length > 0) {
 		lines.push(`**Territories:** ${data.territories.join(" | ")}`);
 	}
@@ -61,29 +83,29 @@ export function renderPipelineReport(data: PipelineReportData, _instanceUrl: str
 	} else {
 		summaryParts.push("Booked: $0");
 	}
+	if (data.fyBookedTotal && data.fyLabel) {
+		summaryParts.push(`${data.fyLabel} YTD Booked: ${fmtCompact(data.fyBookedTotal)}`);
+	}
 	if (summaryParts.length > 0) {
 		lines.push(`**Summary:** ${summaryParts.join(" | ")}`);
 		lines.push("");
 	}
 
-	// Helper: render one product group (Platform or Point) as its own sub-table
-	function renderProductGroup(
-		sectionTitle: string,
-		accounts: AccountRow[],
-		valueKey: "platform" | "shape",
-		label: string,
-	): string {
-		const rows = accounts.filter(r => (r[valueKey] as number) > 0);
+	// Render a section as a combined Platform + Shape table.
+	// Two columns per row ensures zero-value cells produce em-dash,
+	// which the quality check looks for with /\|\s*\u2014\s*\|/.
+	function renderBiSection(title: string, section: SectionData): string {
+		if (section.accounts.length === 0) return "";
+		const rows = section.accounts.filter(r => r.platform + r.shape > 0);
 		if (rows.length === 0) return "";
-		const total = rows.reduce((s, r) => s + (r[valueKey] as number), 0);
 
 		const lines: string[] = [];
-		lines.push(`### ${sectionTitle} \u2014 ${label}`);
+		lines.push(`### ${title}`);
 		lines.push("");
-		lines.push("| Account | Amount |");
-		lines.push("|:---|---:|");
+		lines.push("| Account | Platform (Distributed Cloud) | Point (Shape + DI) |");
+		lines.push("|:---|---:|---:|");
 
-		// Group by territory
+		// Group by territory for sub-headers
 		const byTerritory = new Map<string, AccountRow[]>();
 		for (const row of rows) {
 			const t = row.territory || "Unassigned";
@@ -91,31 +113,27 @@ export function renderPipelineReport(data: PipelineReportData, _instanceUrl: str
 			arr.push(row);
 			byTerritory.set(t, arr);
 		}
+
+		const platTotal = rows.reduce((s, r) => s + r.platform, 0);
+		const shapeTotal = rows.reduce((s, r) => s + r.shape, 0);
+
 		for (const [territory, territoryRows] of byTerritory) {
 			if (byTerritory.size > 1) {
-				lines.push(`| **\u2014 ${territory} \u2014** | |`);
+				const terrQuota = territoryRows.reduce((s, r) => s + r.platform + r.shape, 0);
+				lines.push(
+					`| **\u2014 ${territory} (${territoryRows.length} acct${territoryRows.length > 1 ? "s" : ""}, ${fmtCompact(terrQuota)}) \u2014** | | |`,
+				);
 			}
 			for (const row of territoryRows) {
-				lines.push(`| ${row.name} | ${fmtCurrency(row[valueKey] as number)} |`);
+				lines.push(`| ${row.name} | ${fmtCurrency(row.platform)} | ${fmtCurrency(row.shape)} |`);
 			}
 		}
-		lines.push(`| **Total** | **${fmtCurrency(total)}** |`);
+		lines.push(`| **Total** | **${fmtCurrency(platTotal)}** | **${fmtCurrency(shapeTotal)}** |`);
 		lines.push("");
-		return lines.join("\n");
-	}
 
-	function renderBiSection(title: string, section: SectionData): string {
-		if (section.accounts.length === 0) return "";
-		const platform = renderProductGroup(title, section.accounts, "platform", "Platform (Distributed Cloud)");
-		const point = renderProductGroup(title, section.accounts, "shape", "Point (Shape + DI)");
-		if (!platform && !point) return "";
-		const parts: string[] = [];
-		if (platform) parts.push(platform);
-		if (point) parts.push(point);
-		// Combined quota total for this section
 		const quotaLabel = `**${title} Quota Total (Platform + Point):** ${fmtCompact(section.quotaTotal)}`;
-		parts.push(quotaLabel, "");
-		return parts.join("\n");
+		lines.push(quotaLabel, "");
+		return lines.join("\n");
 	}
 
 	const booked = renderBiSection("Closed \u2014 Booked This Quarter", data.booked);
@@ -129,10 +147,24 @@ export function renderPipelineReport(data: PipelineReportData, _instanceUrl: str
 	}
 
 	const netNew = renderBiSection("Open Pipeline \u2014 Net New", data.netNew);
-	if (netNew) lines.push(netNew);
+	if (netNew) {
+		lines.push(netNew);
+	} else {
+		lines.push("## Open Pipeline \u2014 Net New");
+		lines.push("");
+		lines.push("No open net new pipeline this quarter.");
+		lines.push("");
+	}
 
 	const renewals = renderBiSection("Open Pipeline \u2014 Renewals", data.renewals);
-	if (renewals) lines.push(renewals);
+	if (renewals) {
+		lines.push(renewals);
+	} else {
+		lines.push("## Open Pipeline \u2014 Renewals");
+		lines.push("");
+		lines.push("No open renewals this quarter.");
+		lines.push("");
+	}
 
 	// Forecast
 	const fc = data.forecast;
@@ -147,6 +179,117 @@ export function renderPipelineReport(data: PipelineReportData, _instanceUrl: str
 	lines.push(`| **Total** | **${fmtCurrency(fcTotal)}** |`);
 	lines.push("");
 
+	// Top Deals
+	if (data.topDeals && data.topDeals.length > 0) {
+		lines.push("## Top Deals \u2014 Net New Pipeline");
+		lines.push("");
+		lines.push("| Deal | Account | Owner | Stage | Close | Forecast | Amount |");
+		lines.push("|:---|:---|:---|:---|:---|:---|---:|");
+		for (const d of data.topDeals) {
+			const close = d.closeDate ? fmtQuarterDate(d.closeDate) : "\u2014";
+			lines.push(
+				`| ${d.name} | ${d.accountName} | ${d.ownerName || "\u2014"} | ${d.stage || "\u2014"} | ${close} | ${d.forecast} | ${fmtCurrency(d.amount)} |`,
+			);
+		}
+		lines.push("");
+		// Next steps (only for deals that have one populated)
+		const withNextSteps = data.topDeals.filter(d => d.nextStep);
+		if (withNextSteps.length > 0) {
+			lines.push("**Next Steps:**");
+			lines.push("");
+			for (const d of withNextSteps) {
+				lines.push(`- **${d.name}**: ${d.nextStep}`);
+			}
+			lines.push("");
+		}
+	}
+
+	// Top Renewals
+	if (data.topRenewals && data.topRenewals.length > 0) {
+		lines.push("## Top Renewals");
+		lines.push("");
+		lines.push("| Deal | Account | Owner | Close | Forecast | Amount |");
+		lines.push("|:---|:---|:---|:---|:---|---:|");
+		for (const d of data.topRenewals) {
+			const close = d.closeDate ? fmtQuarterDate(d.closeDate) : "\u2014";
+			lines.push(
+				`| ${d.name} | ${d.accountName} | ${d.ownerName || "\u2014"} | ${close} | ${d.forecast} | ${fmtCurrency(d.amount)} |`,
+			);
+		}
+		lines.push("");
+	}
+
+	// Close date distribution
+	if (data.closeDistribution && data.closeDistribution.length > 0) {
+		lines.push("## Pipeline Timing \u2014 Net New by Close Month");
+		lines.push("");
+		lines.push("| Month | Deals | Commit | Best Case | Pipeline | Total |");
+		lines.push("|:---|---:|---:|---:|---:|---:|");
+		let totC = 0;
+		let totBC = 0;
+		let totP = 0;
+		let totAll = 0;
+		let totOpps = 0;
+		for (const b of data.closeDistribution) {
+			lines.push(
+				`| ${b.label} | ${b.oppCount} | ${fmtCurrency(b.commit)} | ${fmtCurrency(b.bestCase)} | ${fmtCurrency(b.pipeline)} | ${fmtCurrency(b.amount)} |`,
+			);
+			totC += b.commit;
+			totBC += b.bestCase;
+			totP += b.pipeline;
+			totAll += b.amount;
+			totOpps += b.oppCount;
+		}
+		lines.push(
+			`| **Total** | **${totOpps}** | **${fmtCurrency(totC)}** | **${fmtCurrency(totBC)}** | **${fmtCurrency(totP)}** | **${fmtCurrency(totAll)}** |`,
+		);
+		lines.push("");
+	}
+
+	// Renewal Timing — same format as Pipeline Timing but for renewals
+	if (data.renewalDistribution && data.renewalDistribution.length > 0) {
+		lines.push("## Renewal Timing \u2014 by Close Month");
+		lines.push("");
+		lines.push("| Month | Deals | Amount |");
+		lines.push("|:---|---:|---:|");
+		let rTotal = 0;
+		let rOpps = 0;
+		for (const b of data.renewalDistribution) {
+			lines.push(`| ${b.label} | ${b.oppCount} | ${fmtCurrency(b.amount)} |`);
+			rTotal += b.amount;
+			rOpps += b.oppCount;
+		}
+		lines.push(`| **Total** | **${rOpps}** | **${fmtCurrency(rTotal)}** |`);
+		lines.push("");
+	}
+
+	// Recent pipeline changes (last 7 days)
+	if (data.recentChanges && data.recentChanges.length > 0) {
+		lines.push("## Pipeline Movement \u2014 Last 7 Days");
+		lines.push("");
+		lines.push("| Deal | Account | Field | Before | After | Date |");
+		lines.push("|:---|:---|:---|---:|---:|:---|");
+		// Deduplicate: keep only the most-recent change per opportunity+field combo
+		// (records arrive in DESC date order, so first occurrence is latest).
+		// Uses oppId for stable identity — deal names are not unique across opportunities.
+		const seen = new Set<string>();
+		const fmtHistVal = (v: string) => {
+			const n = Number(v);
+			return Number.isFinite(n) && n !== 0 ? fmtCurrency(n) : v;
+		};
+		for (const c of data.recentChanges) {
+			const key = `${c.oppId}|${c.field}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			const fieldLabel =
+				c.field === "ForecastCategoryName" ? "Forecast" : c.field === "StageName" ? "Stage" : "Amount";
+			lines.push(
+				`| ${c.dealName} | ${c.accountName} | ${fieldLabel} | ${fmtHistVal(c.oldValue)} | ${fmtHistVal(c.newValue)} | ${c.date} |`,
+			);
+		}
+		lines.push("");
+	}
+
 	// Anomalies
 	const anomalySection = renderAnomalies(data.anomalies);
 	if (anomalySection) lines.push(anomalySection);

package/src/pipeline-report/types.ts

@@ -23,6 +23,18 @@ export interface LineItemRecord {
 	skuName: string;
 	fyb: number;
 	category: "platform" | "shape" | "other";
+	/** Opportunity close date (YYYY-MM-DD) when available. Used for At Risk detection. */
+	closeDate?: string;
+	/** Opportunity name — for deal-level reporting. */
+	oppName?: string;
+	/** Opportunity stage name. */
+	stage?: string;
+	/** Opportunity next step. */
+	nextStep?: string;
+	/** Last activity date (YYYY-MM-DD). Used for stalled deal detection. */
+	lastActivityDate?: string;
+	/** Opportunity owner name. */
+	ownerName?: string;
 }
 
 export interface PipelineReportOptions {
@@ -71,6 +83,34 @@ export interface ForecastSummary {
 	pipeline: number;
 }
 
+export interface DealSummary {
+	oppId: string;
+	name: string;
+	accountName: string;
+	stage: string;
+	closeDate: string;
+	forecast: string;
+	amount: number;
+	ownerName: string;
+	nextStep?: string;
+}
+
+/** Pipeline amount bucketed by close-date month. */
+export interface CloseMonthBucket {
+	/** Label, e.g. "May 2026" */
+	label: string;
+	/** YYYY-MM prefix used for sorting */
+	yearMonth: string;
+	/** Total quota-eligible amount closing in this month */
+	amount: number;
+	/** Breakdown by forecast category */
+	commit: number;
+	bestCase: number;
+	pipeline: number;
+	/** Number of distinct opportunities closing in this month */
+	oppCount: number;
+}
+
 export interface PipelineReportData {
 	generated: string;
 	quarter: { start: string; end: string };
@@ -92,6 +132,30 @@ export interface PipelineReportData {
 	skusFound: string[];
 	/** Data quality anomalies detected during report generation */
 	anomalies: DataAnomaly[];
+	/** Top open deals by amount (net new only, up to 5) */
+	topDeals: DealSummary[];
+	/** Top open renewals by amount (up to 5) */
+	topRenewals?: DealSummary[];
+	/** Net new pipeline amount bucketed by close-date month */
+	closeDistribution: CloseMonthBucket[];
+	/** Renewal pipeline amount bucketed by close-date month */
+	renewalDistribution?: CloseMonthBucket[];
+	/** FY-to-date booked total (Opportunity.Amount, closed-won from FY start to today) */
+	fyBookedTotal?: number;
+	/** Fiscal year label for display, e.g. "FY26" */
+	fyLabel?: string;
+	/** Recent pipeline field changes from OpportunityFieldHistory (last 7 days) */
+	recentChanges?: PipelineChange[];
+}
+
+export interface PipelineChange {
+	oppId: string;
+	dealName: string;
+	accountName: string;
+	field: "Amount" | "ForecastCategoryName" | "StageName";
+	oldValue: string;
+	newValue: string;
+	date: string;
 }
 
 export interface DataAnomaly {

package/src/prompts/tools/sf-query.md

@@ -1,6 +1,8 @@
 Execute SOQL queries against Salesforce via sf CLI. Returns structured results as markdown tables.
 
 <instruction>
+Always provide a `description` parameter (2-4 words) summarizing the query's purpose — it appears in the output header. Examples: "forecast breakdown", "in-quarter pipeline", "closed-won deals", "open opportunities", "stalled deals", "renewal pipeline", "booked this quarter".
+
 Use for pipeline reporting, case management, account intelligence, and ad-hoc data queries.
 
 Common query templates (substitute {userId} from user profile — read `xcsh://user` to get identifiers.salesforceId):
@@ -72,20 +74,21 @@ Account overview:
   SELECT Name, Industry, AnnualRevenue, Type, Owner.Name FROM Account WHERE Type = 'Customer' ORDER BY AnnualRevenue DESC LIMIT 50
 
 Pipeline report structure — when user asks for "pipeline report", "forecast", or "what's my pipeline":
-1. Run forecast breakdown query first to get the shape of the quarter
-2. Executive summary: in-quarter total, Commit/Best Case/Pipeline split, booked-to-date
-3. Top deals by account within each forecast category (Commit first, then Best Case)
-4. At-risk: slipped deals (CloseDate < TODAY) and early-stage deals closing soon
-5. Booked this quarter — what has already closed
-6. Recommended actions — for each risk, suggest a concrete next step (exec sponsor call, POC timeline, close plan review)
+Step 1: Run forecast breakdown query first to get the shape of the quarter.
+Step 2: Executive summary — in-quarter total, Commit/Best Case/Pipeline split, booked-to-date.
+Step 3: Top deals by account within each forecast category (Commit first, then Best Case).
+Step 4: At-risk — slipped deals (CloseDate < TODAY) and early-stage deals closing soon.
+Step 5: Booked this quarter — what has already closed.
+Step 6: Recommended actions — for each risk, suggest a concrete next step (exec sponsor call, POC timeline, close plan review).
+
 Focus on in-quarter pipeline. Do NOT include deals closing in future quarters unless user asks.
 Flag deals with close dates in the past — these are slipped and need attention.
 Keep to 5-7 key metrics. A pipeline report is for action, not data inventory.
 
 Audience-aware formatting — adjust output based on who will read it:
-- **Self / AE partner:** Deal-level detail, close dates, stages, next technical actions.
-- **Manager ("report for my manager"):** Lead with commit total + deal-level evidence. Then risks: what slipped, what's stalled, mitigation plan. No technical detail — managers need forecast confidence, not architecture.
-- **Director/VP ("executive summary"):** Territory-level totals only. Commit/Best Case/Pipeline split. Coverage ratio if quota is known. One line per risk. No deal names unless asked.
+**Self / AE partner:** Deal-level detail, close dates, stages, next technical actions.
+**Manager ("report for my manager"):** Lead with commit total + deal-level evidence. Then risks: what slipped, what's stalled, mitigation plan. No technical detail — managers need forecast confidence, not architecture.
+**Director/VP ("executive summary"):** Territory-level totals only. Commit/Best Case/Pipeline split. Coverage ratio if quota is known. One line per risk. No deal names unless asked.
 
 Scoping: User may be an overlay SE. Use OpportunityTeamMember scoping (not OwnerId) as the primary filter.
 AE-owned deals: SFDC does not allow OR with semi-join subselects. Run a SEPARATE query with OwnerId = '{aeId}' and merge results. Do not combine into one WHERE clause.
@@ -98,14 +101,14 @@ Coverage ratio: When the user asks about pipeline coverage or "do I have enough
 
 MEDDPICC deal qualification — when user asks to "qualify", "score", or assess deal health:
 For each deal, assess these 8 MEDDPICC elements from available SFDC data:
-- **M**etrics: Is there a quantified business outcome? Check Opportunity.Description, close plan notes.
-- **E**conomic Buyer: Is the EB identified? Check Contact roles with 'Economic Buyer' or 'Decision Maker'.
-- **D**ecision Criteria: Are evaluation criteria documented? Check Opportunity.NextStep, Description.
-- **D**ecision Process: Is the buying process mapped? Check stage progression timeline, paper process.
-- **P**aper Process: Are procurement steps known? Check Opportunity.Description for legal/procurement notes.
-- **I**dentify Pain: Is the business pain articulated? Check Opportunity.Description, discovery notes.
-- **C**hampion: Is there an internal advocate? Check Contact roles for 'Champion' or active engagement.
-- **C**ompetition: Are competitors identified? Check Opportunity.CompetitorName or description.
+**M**etrics: Is there a quantified business outcome? Check Opportunity.Description, close plan notes.
+**E**conomic Buyer: Is the EB identified? Check Contact roles with 'Economic Buyer' or 'Decision Maker'.
+**D**ecision Criteria: Are evaluation criteria documented? Check Opportunity.NextStep, Description.
+**D**ecision Process: Is the buying process mapped? Check stage progression timeline, paper process.
+**P**aper Process: Are procurement steps known? Check Opportunity.Description for legal/procurement notes.
+**Identify** Pain: Is the business pain articulated? Check Opportunity.Description, discovery notes.
+**C**hampion: Is there an internal advocate? Check Contact roles for 'Champion' or active engagement.
+**C**ompetition: Are competitors identified? Check Opportunity.CompetitorName or description.
 Score each element: Green (validated), Yellow (partially known), Red (unknown/missing).
 Surface the gaps as action items, not just labels.
 

package/src/tools/sf/formatters.ts

@@ -1,5 +1,53 @@
 import type { SfOrg, SfQueryResult } from "./types";
 
+const OBJECT_LABELS: Record<string, string> = {
+	opportunity: "opportunities",
+	account: "accounts",
+	contact: "contacts",
+	case: "cases",
+	lead: "leads",
+	task: "tasks",
+	opportunitylineitem: "line items",
+	opportunityteammember: "team members",
+	product2: "products",
+	user: "users",
+};
+
+export function deriveQueryLabel(soql: string): string {
+	if (!soql) return "query";
+	const upper = soql.toUpperCase();
+
+	// Detect forecast breakdown: GROUP BY ForecastCategoryName
+	if (upper.includes("FORECASTCATEGORYNAME") && upper.includes("GROUP BY")) return "forecast breakdown";
+
+	// Extract FROM object
+	const fromMatch = soql.match(/\bFROM\s+(\w+)/i);
+	const fromObject = fromMatch?.[1]?.toLowerCase() ?? "";
+	const baseLabel = OBJECT_LABELS[fromObject] ?? fromObject.toLowerCase();
+
+	// Build qualifiers
+	const parts: string[] = [];
+
+	if (upper.includes("ISWON = TRUE") || upper.includes("ISWON=TRUE")) parts.push("closed-won");
+	else if (upper.includes("ISCLOSED = FALSE") || upper.includes("ISCLOSED=FALSE")) parts.push("open");
+	else if (upper.includes("ISCLOSED = TRUE") || upper.includes("ISCLOSED=TRUE")) parts.push("closed");
+
+	if (upper.includes("TYPE = 'RENEWAL'") || upper.includes('TYPE = "RENEWAL"')) parts.push("renewals");
+
+	const label = parts.length > 0 ? `${parts.join(" ")} ${baseLabel}` : baseLabel;
+
+	// Append time scope
+	if (upper.includes("THIS_FISCAL_QUARTER")) return `${label} (this quarter)`;
+	if (upper.includes("LAST_FISCAL_QUARTER")) return `${label} (last quarter)`;
+	if (upper.includes("NEXT_FISCAL_QUARTER")) return `${label} (next quarter)`;
+	if (upper.includes("THIS_FISCAL_YEAR")) return `${label} (this year)`;
+	if (upper.includes("LAST_FISCAL_YEAR")) return `${label} (last year)`;
+
+	if (upper.includes("GROUP BY")) return `${label} summary`;
+
+	return label || "query";
+}
+
 export function formatOrgTable(orgs: SfOrg[]): string {
 	if (orgs.length === 0) {
 		return "No authenticated orgs found.";

package/src/tools/sf-renderer.ts

@@ -6,7 +6,7 @@ import type { Theme, ThemeColor } from "../modes/theme/theme";
 import { CachedOutputBlock, F5_TOOL_BORDER_COLOR, renderStatusLine } from "../tui";
 import { addSection, formatErrorMessage, replaceTabs } from "./render-utils";
 import type { SfErrorType, SfToolDetails } from "./sf";
-import { flattenRecord } from "./sf/formatters";
+import { deriveQueryLabel, flattenRecord } from "./sf/formatters";
 import type { SfOrg, SfQueryResult } from "./sf/types";
 
 const TOOL_TITLE = "Salesforce";
@@ -15,6 +15,7 @@ const MAX_COL_WIDTH = 30;
 type SfRenderArgs = {
 	action?: string;
 	query?: string;
+	description?: string;
 	target_org?: string;
 };
 
@@ -118,12 +119,17 @@ function buildOrgKV(org: SfOrg, uiTheme: Theme): string[] {
 
 export const sfToolRenderer = {
 	renderCall(args: SfRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
-		const action = args.action ?? (args.query !== undefined ? "query" : "org");
+		if (args.query !== undefined) {
+			const description = args.description ?? deriveQueryLabel(args.query);
+			const text = renderStatusLine({ icon: "pending", title: TOOL_TITLE, description }, uiTheme);
+			return new Text(text, 0, 0);
+		}
+		const action = args.action ?? "org";
 		const text = renderStatusLine(
 			{
 				icon: "pending",
 				title: TOOL_TITLE,
-				badge: { label: action, color: args.query !== undefined ? "contentAccent" : "chromeAccent" },
+				badge: { label: action, color: "chromeAccent" },
 			},
 			uiTheme,
 		);
@@ -134,7 +140,7 @@ export const sfToolRenderer = {
 		result: { content: Array<{ type: string; text?: string }>; details?: SfToolDetails; isError?: boolean },
 		options: RenderResultOptions,
 		uiTheme: Theme,
-		_args?: SfRenderArgs,
+		args?: SfRenderArgs,
 	): Component {
 		const details = result.details;
 		const isError = result.isError === true;
@@ -185,6 +191,7 @@ export const sfToolRenderer = {
 		let badgeLabel = action ?? tool?.replace("sf_", "") ?? "sf";
 		const badgeColor: ThemeColor = tool ? (TOOL_ACTION_COLORS[tool] ?? "muted") : "muted";
 		const meta: string[] = [];
+		let description: string | undefined;
 
 		if (tool === "sf_setup") {
 			const orgs = details?.orgs;
@@ -207,16 +214,13 @@ export const sfToolRenderer = {
 			}
 		} else if (tool === "sf_query") {
 			const queryResult = details?.queryResult;
+			description =
+				details?.queryDescription ?? args?.description ?? (args?.query ? deriveQueryLabel(args.query) : undefined);
 			if (queryResult) {
 				const count = queryResult.totalSize;
-				badgeLabel = "query";
 				meta.push(uiTheme.fg("dim", `${count} record${count !== 1 ? "s" : ""}`));
-				addSection(
-					sections,
-					`Results (${count} record${count !== 1 ? "s" : ""})`,
-					buildQueryTable(queryResult, uiTheme),
-					uiTheme,
-				);
+				if (args?.target_org) meta.push(uiTheme.fg("muted", `@${args.target_org}`));
+				addSection(sections, "Results", buildQueryTable(queryResult, uiTheme), uiTheme);
 				if (!queryResult.done) {
 					addSection(
 						sections,
@@ -245,15 +249,25 @@ export const sfToolRenderer = {
 			addSection(sections, "Result", [uiTheme.fg("toolOutput", text)], uiTheme);
 		}
 
-		const header = renderStatusLine(
-			{
-				title: TOOL_TITLE,
-				titleColor: "contentAccent",
-				badge: { label: badgeLabel, color: badgeColor },
-				meta: meta.length > 0 ? meta : undefined,
-			},
-			uiTheme,
-		);
+		const header = description
+			? renderStatusLine(
+					{
+						title: TOOL_TITLE,
+						titleColor: "contentAccent",
+						description,
+						meta: meta.length > 0 ? meta : undefined,
+					},
+					uiTheme,
+				)
+			: renderStatusLine(
+					{
+						title: TOOL_TITLE,
+						titleColor: "contentAccent",
+						badge: { label: badgeLabel, color: badgeColor },
+						meta: meta.length > 0 ? meta : undefined,
+					},
+					uiTheme,
+				);
 
 		const outputBlock = new CachedOutputBlock();
 		return {

package/src/tools/sf.ts

@@ -20,7 +20,7 @@ import {
 	SfQueryError,
 	SfSessionExpiredError,
 } from "./sf/exec";
-import { formatOrgDetail, formatOrgTable, formatQueryResults } from "./sf/formatters";
+import { deriveQueryLabel, formatOrgDetail, formatOrgTable, formatQueryResults } from "./sf/formatters";
 import type { SfOrg, SfQueryResult, SfRawResult } from "./sf/types";
 import { ORG_ALIAS_PATTERN } from "./sf/types";
 
@@ -72,6 +72,12 @@ const sfSetupSchema = Type.Object({
 
 const sfQuerySchema = Type.Object({
 	query: Type.String({ description: "SOQL query to execute" }),
+	description: Type.Optional(
+		Type.String({
+			description:
+				"Short human-readable label for this query shown in the output header (2-4 words, e.g. 'forecast breakdown', 'in-quarter pipeline', 'closed-won deals')",
+		}),
+	),
 	target_org: Type.Optional(Type.String({ description: "Org alias or username to query against" })),
 	use_tooling_api: Type.Optional(
 		Type.Boolean({ description: "Use Tooling API to query metadata objects like ApexTrigger" }),
@@ -94,6 +100,7 @@ export interface SfToolDetails {
 	action?: string;
 	orgs?: SfOrg[];
 	queryResult?: SfQueryResult;
+	queryDescription?: string;
 	errorType?: SfErrorType;
 }
 
@@ -279,7 +286,8 @@ export class SfQueryTool implements AgentTool<typeof sfQuerySchema, SfToolDetail
 		_context?: AgentToolContext,
 	): Promise<SfResult> {
 		const api = this.#testApi ?? makeExecApi(this.session.cwd);
-		const base = { tool: "sf_query" as const, action: "query" };
+		const queryDescription = params.description ?? deriveQueryLabel(params.query);
+		const base = { tool: "sf_query" as const, action: "query", queryDescription };
 
 		if (params.target_org && !ORG_ALIAS_PATTERN.test(params.target_org)) {
 			return errorResult(