@higher.archi/boe 1.0.17 → 1.0.18

package/dist/promotion/index.d.ts

@@ -1,3 +1,3 @@
-export type { PromotionOpportunity, PromotionTarget, PromotionResult } from './types';
-export { promotionPath } from './promotion';
+export type { PromotionOpportunity, PromotionTarget, PromotionResult, PromotionSummaryOptions, CategorySummaryOptions } from './types';
+export { promotionPath, summarizePromotionPath, summarizeCategoryBreakdown } from './promotion';
 //# sourceMappingURL=index.d.ts.map

package/dist/promotion/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/promotion/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGtF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/promotion/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAGvI,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC"}

package/dist/promotion/index.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.promotionPath = void 0;
+exports.summarizeCategoryBreakdown = exports.summarizePromotionPath = exports.promotionPath = void 0;
 // Core promotion path
 var promotion_1 = require("./promotion");
 Object.defineProperty(exports, "promotionPath", { enumerable: true, get: function () { return promotion_1.promotionPath; } });
+Object.defineProperty(exports, "summarizePromotionPath", { enumerable: true, get: function () { return promotion_1.summarizePromotionPath; } });
+Object.defineProperty(exports, "summarizeCategoryBreakdown", { enumerable: true, get: function () { return promotion_1.summarizeCategoryBreakdown; } });
 //# sourceMappingURL=index.js.map

package/dist/promotion/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/promotion/index.ts"],"names":[],"mappings":";;;AAGA,sBAAsB;AACtB,yCAA4C;AAAnC,0GAAA,aAAa,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/promotion/index.ts"],"names":[],"mappings":";;;AAGA,sBAAsB;AACtB,yCAAgG;AAAvF,0GAAA,aAAa,OAAA;AAAE,mHAAA,sBAAsB,OAAA;AAAE,uHAAA,0BAA0B,OAAA"}

package/dist/promotion/promotion.d.ts

@@ -8,7 +8,7 @@
  */
 import type { CompiledScoringRuleSet, ScoringOptions, TierDefinition } from '../engines/scoring/types';
 import type { FactInput } from '../core';
-import type { PromotionTarget, PromotionResult } from './types';
+import type { PromotionTarget, PromotionResult, PromotionSummaryOptions, CategorySummaryOptions } from './types';
 /**
  * Compute a promotion path — the ranked set of unfired rules that could
  * close the gap between a current score and a target score or tier.
@@ -21,7 +21,7 @@ import type { PromotionTarget, PromotionResult } from './types';
  *
  * @example
  * ```typescript
- * const path = promotionPath(athleteRuleset, athleteFacts, { tier: 'premium' });
+ * const path = promotionPath(vendorRuleset, vendorFacts, { tier: 'preferred' });
  *
  * console.log(`Current: ${path.currentScore} (${path.currentTier})`);
  * console.log(`Target: ${path.targetScore} (${path.targetTier})`);
@@ -34,4 +34,35 @@ import type { PromotionTarget, PromotionResult } from './types';
  * ```
  */
 export declare function promotionPath<T extends TierDefinition = TierDefinition>(ruleset: CompiledScoringRuleSet<T>, facts: FactInput[], target: PromotionTarget, options?: ScoringOptions): PromotionResult<T>;
+/**
+ * Generate a human-readable summary string from a PromotionResult.
+ *
+ * @param path - The promotion result to summarize
+ * @param options - Optional display settings
+ * @returns Formatted multi-line summary string
+ *
+ * @example
+ * ```typescript
+ * const path = promotionPath(ruleset, facts, { tier: 'preferred' });
+ * console.log(summarizePromotionPath(path));
+ * ```
+ */
+export declare function summarizePromotionPath(path: PromotionResult, options?: PromotionSummaryOptions): string;
+/**
+ * Generate a human-readable category breakdown from a PromotionResult.
+ *
+ * Groups opportunities by category and shows per-category recoverable
+ * points with individual opportunity details.
+ *
+ * @param path - The promotion result to summarize
+ * @param options - Optional display settings
+ * @returns Formatted multi-line category breakdown string
+ *
+ * @example
+ * ```typescript
+ * const path = promotionPath(ruleset, facts, { tier: 'elite' });
+ * console.log(summarizeCategoryBreakdown(path));
+ * ```
+ */
+export declare function summarizeCategoryBreakdown(path: PromotionResult, options?: CategorySummaryOptions): string;
 //# sourceMappingURL=promotion.d.ts.map

package/dist/promotion/promotion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"promotion.d.ts","sourceRoot":"","sources":["../../src/promotion/promotion.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,sBAAsB,EACtB,cAAc,EACd,cAAc,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAwB,MAAM,SAAS,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACrE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAClC,KAAK,EAAE,SAAS,EAAE,EAClB,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,cAAmB,GAC3B,eAAe,CAAC,CAAC,CAAC,CAmGpB"}
+{"version":3,"file":"promotion.d.ts","sourceRoot":"","sources":["../../src/promotion/promotion.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,sBAAsB,EACtB,cAAc,EACd,cAAc,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAwB,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEvI;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACrE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAClC,KAAK,EAAE,SAAS,EAAE,EAClB,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,cAAmB,GAC3B,eAAe,CAAC,CAAC,CAAC,CAmGpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,eAAe,EACrB,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAqCR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,eAAe,EACrB,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAqCR"}

package/dist/promotion/promotion.js

@@ -9,6 +9,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.promotionPath = promotionPath;
+exports.summarizePromotionPath = summarizePromotionPath;
+exports.summarizeCategoryBreakdown = summarizeCategoryBreakdown;
 const engine_1 = require("../engines/scoring/engine");
 /**
  * Compute a promotion path — the ranked set of unfired rules that could
@@ -22,7 +24,7 @@ const engine_1 = require("../engines/scoring/engine");
  *
  * @example
  * ```typescript
- * const path = promotionPath(athleteRuleset, athleteFacts, { tier: 'premium' });
+ * const path = promotionPath(vendorRuleset, vendorFacts, { tier: 'preferred' });
  *
  * console.log(`Current: ${path.currentScore} (${path.currentTier})`);
  * console.log(`Target: ${path.targetScore} (${path.targetTier})`);
@@ -126,4 +128,98 @@ function promotionPath(ruleset, facts, target, options = {}) {
         executionTimeMs,
     };
 }
+/**
+ * Generate a human-readable summary string from a PromotionResult.
+ *
+ * @param path - The promotion result to summarize
+ * @param options - Optional display settings
+ * @returns Formatted multi-line summary string
+ *
+ * @example
+ * ```typescript
+ * const path = promotionPath(ruleset, facts, { tier: 'preferred' });
+ * console.log(summarizePromotionPath(path));
+ * ```
+ */
+function summarizePromotionPath(path, options = {}) {
+    const { maxOpportunities } = options;
+    const lines = [];
+    const currentLabel = path.currentTier ? `${path.currentScore} (${path.currentTier})` : `${path.currentScore}`;
+    const targetLabel = path.targetTier ? `${path.targetScore} (${path.targetTier})` : `${path.targetScore}`;
+    lines.push(`Current: ${currentLabel}`);
+    lines.push(`Target:  ${targetLabel}`);
+    lines.push(`Gap:     ${path.gap} points`);
+    lines.push(`Recoverable: ${path.totalRecoverable} points from ${path.opportunities.length} opportunities`);
+    if (path.alreadyMet) {
+        lines.push('');
+        lines.push('Target already met.');
+        return lines.join('\n');
+    }
+    const opps = maxOpportunities != null
+        ? path.opportunities.slice(0, maxOpportunities)
+        : path.opportunities;
+    if (opps.length > 0) {
+        lines.push('');
+        for (const opp of opps) {
+            const impact = opp.dynamic ? 'variable' : `+${opp.potentialScore}`;
+            lines.push(`  [${impact}] ${opp.ruleName ?? opp.ruleId}`);
+            if (opp.reason)
+                lines.push(`           ${opp.reason}`);
+        }
+        if (maxOpportunities != null && path.opportunities.length > maxOpportunities) {
+            const remaining = path.opportunities.length - maxOpportunities;
+            lines.push(`  ... and ${remaining} more`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Generate a human-readable category breakdown from a PromotionResult.
+ *
+ * Groups opportunities by category and shows per-category recoverable
+ * points with individual opportunity details.
+ *
+ * @param path - The promotion result to summarize
+ * @param options - Optional display settings
+ * @returns Formatted multi-line category breakdown string
+ *
+ * @example
+ * ```typescript
+ * const path = promotionPath(ruleset, facts, { tier: 'elite' });
+ * console.log(summarizeCategoryBreakdown(path));
+ * ```
+ */
+function summarizeCategoryBreakdown(path, options = {}) {
+    const { maxPerCategory } = options;
+    const lines = [];
+    // Group by category
+    const byCategory = new Map();
+    for (const opp of path.opportunities) {
+        const cat = opp.category ?? '(uncategorized)';
+        if (!byCategory.has(cat))
+            byCategory.set(cat, []);
+        byCategory.get(cat).push(opp);
+    }
+    for (const [category, opps] of byCategory) {
+        const categoryTotal = opps.reduce((sum, o) => sum + (o.potentialScore ?? 0), 0);
+        lines.push(`${category} (${categoryTotal} recoverable points):`);
+        const displayed = maxPerCategory != null ? opps.slice(0, maxPerCategory) : opps;
+        for (const opp of displayed) {
+            const impact = opp.dynamic ? 'variable' : `+${opp.potentialScore}`;
+            lines.push(`  [${impact}] ${opp.ruleName ?? opp.ruleId}`);
+            if (opp.reason)
+                lines.push(`           ${opp.reason}`);
+        }
+        if (maxPerCategory != null && opps.length > maxPerCategory) {
+            const remaining = opps.length - maxPerCategory;
+            lines.push(`  ... and ${remaining} more`);
+        }
+        lines.push('');
+    }
+    // Remove trailing blank line
+    if (lines.length > 0 && lines[lines.length - 1] === '') {
+        lines.pop();
+    }
+    return lines.join('\n');
+}
 //# sourceMappingURL=promotion.js.map

package/dist/promotion/promotion.js.map

@@ -1 +1 @@
-{"version":3,"file":"promotion.js","sourceRoot":"","sources":["../../src/promotion/promotion.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"promotion.js","sourceRoot":"","sources":["../../src/promotion/promotion.ts"],"names":[],"mappings":"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"}

package/dist/promotion/types.d.ts

@@ -22,6 +22,14 @@ export type PromotionTarget = {
     score: number;
     tier?: never;
 };
+/** Options for summarizePromotionPath */
+export type PromotionSummaryOptions = {
+    maxOpportunities?: number;
+};
+/** Options for summarizeCategoryBreakdown */
+export type CategorySummaryOptions = {
+    maxPerCategory?: number;
+};
 /** Promotion path result */
 export type PromotionResult<T extends TierDefinition = TierDefinition> = {
     currentScore: number;

package/dist/promotion/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/promotion/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE9E,+DAA+D;AAC/D,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC/B;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpC,4BAA4B;AAC5B,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,OAAO,CAAC;IACpB,aAAa,EAAE,oBAAoB,EAAE,CAAC;IACtC,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/promotion/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE9E,+DAA+D;AAC/D,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC/B;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpC,yCAAyC;AACzC,MAAM,MAAM,uBAAuB,GAAG;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,6CAA6C;AAC7C,MAAM,MAAM,sBAAsB,GAAG;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,4BAA4B;AAC5B,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,OAAO,CAAC;IACpB,aAAa,EAAE,oBAAoB,EAAE,CAAC;IACtC,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@higher.archi/boe",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "A multi-strategy rule engine supporting forward chaining, backward chaining, scoring, sequential, fuzzy logic, and Bayesian inference",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/promotion/index.ts

@@ -1,5 +1,5 @@
 // Types
-export type { PromotionOpportunity, PromotionTarget, PromotionResult } from './types';
+export type { PromotionOpportunity, PromotionTarget, PromotionResult, PromotionSummaryOptions, CategorySummaryOptions } from './types';
 
 // Core promotion path
-export { promotionPath } from './promotion';
+export { promotionPath, summarizePromotionPath, summarizeCategoryBreakdown } from './promotion';

package/src/promotion/promotion.ts

@@ -14,7 +14,7 @@ import type {
   TierDefinition
 } from '../engines/scoring/types';
 import type { FactInput } from '../core';
-import type { PromotionTarget, PromotionResult, PromotionOpportunity } from './types';
+import type { PromotionTarget, PromotionResult, PromotionOpportunity, PromotionSummaryOptions, CategorySummaryOptions } from './types';
 
 /**
  * Compute a promotion path — the ranked set of unfired rules that could
@@ -28,7 +28,7 @@ import type { PromotionTarget, PromotionResult, PromotionOpportunity } from './t
  *
  * @example
  * ```typescript
- * const path = promotionPath(athleteRuleset, athleteFacts, { tier: 'premium' });
+ * const path = promotionPath(vendorRuleset, vendorFacts, { tier: 'preferred' });
  *
  * console.log(`Current: ${path.currentScore} (${path.currentTier})`);
  * console.log(`Target: ${path.targetScore} (${path.targetTier})`);
@@ -145,3 +145,116 @@ export function promotionPath<T extends TierDefinition = TierDefinition>(
     executionTimeMs,
   };
 }
+
+/**
+ * Generate a human-readable summary string from a PromotionResult.
+ *
+ * @param path - The promotion result to summarize
+ * @param options - Optional display settings
+ * @returns Formatted multi-line summary string
+ *
+ * @example
+ * ```typescript
+ * const path = promotionPath(ruleset, facts, { tier: 'preferred' });
+ * console.log(summarizePromotionPath(path));
+ * ```
+ */
+export function summarizePromotionPath(
+  path: PromotionResult,
+  options: PromotionSummaryOptions = {}
+): string {
+  const { maxOpportunities } = options;
+  const lines: string[] = [];
+
+  const currentLabel = path.currentTier ? `${path.currentScore} (${path.currentTier})` : `${path.currentScore}`;
+  const targetLabel = path.targetTier ? `${path.targetScore} (${path.targetTier})` : `${path.targetScore}`;
+
+  lines.push(`Current: ${currentLabel}`);
+  lines.push(`Target:  ${targetLabel}`);
+  lines.push(`Gap:     ${path.gap} points`);
+  lines.push(`Recoverable: ${path.totalRecoverable} points from ${path.opportunities.length} opportunities`);
+
+  if (path.alreadyMet) {
+    lines.push('');
+    lines.push('Target already met.');
+    return lines.join('\n');
+  }
+
+  const opps = maxOpportunities != null
+    ? path.opportunities.slice(0, maxOpportunities)
+    : path.opportunities;
+
+  if (opps.length > 0) {
+    lines.push('');
+    for (const opp of opps) {
+      const impact = opp.dynamic ? 'variable' : `+${opp.potentialScore}`;
+      lines.push(`  [${impact}] ${opp.ruleName ?? opp.ruleId}`);
+      if (opp.reason) lines.push(`           ${opp.reason}`);
+    }
+
+    if (maxOpportunities != null && path.opportunities.length > maxOpportunities) {
+      const remaining = path.opportunities.length - maxOpportunities;
+      lines.push(`  ... and ${remaining} more`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate a human-readable category breakdown from a PromotionResult.
+ *
+ * Groups opportunities by category and shows per-category recoverable
+ * points with individual opportunity details.
+ *
+ * @param path - The promotion result to summarize
+ * @param options - Optional display settings
+ * @returns Formatted multi-line category breakdown string
+ *
+ * @example
+ * ```typescript
+ * const path = promotionPath(ruleset, facts, { tier: 'elite' });
+ * console.log(summarizeCategoryBreakdown(path));
+ * ```
+ */
+export function summarizeCategoryBreakdown(
+  path: PromotionResult,
+  options: CategorySummaryOptions = {}
+): string {
+  const { maxPerCategory } = options;
+  const lines: string[] = [];
+
+  // Group by category
+  const byCategory = new Map<string, PromotionOpportunity[]>();
+  for (const opp of path.opportunities) {
+    const cat = opp.category ?? '(uncategorized)';
+    if (!byCategory.has(cat)) byCategory.set(cat, []);
+    byCategory.get(cat)!.push(opp);
+  }
+
+  for (const [category, opps] of byCategory) {
+    const categoryTotal = opps.reduce((sum, o) => sum + (o.potentialScore ?? 0), 0);
+    lines.push(`${category} (${categoryTotal} recoverable points):`);
+
+    const displayed = maxPerCategory != null ? opps.slice(0, maxPerCategory) : opps;
+    for (const opp of displayed) {
+      const impact = opp.dynamic ? 'variable' : `+${opp.potentialScore}`;
+      lines.push(`  [${impact}] ${opp.ruleName ?? opp.ruleId}`);
+      if (opp.reason) lines.push(`           ${opp.reason}`);
+    }
+
+    if (maxPerCategory != null && opps.length > maxPerCategory) {
+      const remaining = opps.length - maxPerCategory;
+      lines.push(`  ... and ${remaining} more`);
+    }
+
+    lines.push('');
+  }
+
+  // Remove trailing blank line
+  if (lines.length > 0 && lines[lines.length - 1] === '') {
+    lines.pop();
+  }
+
+  return lines.join('\n');
+}

package/src/promotion/types.ts

@@ -22,6 +22,16 @@ export type PromotionTarget =
   | { tier: string; score?: never }
   | { score: number; tier?: never };
 
+/** Options for summarizePromotionPath */
+export type PromotionSummaryOptions = {
+  maxOpportunities?: number;  // max opportunities to display (default: all)
+};
+
+/** Options for summarizeCategoryBreakdown */
+export type CategorySummaryOptions = {
+  maxPerCategory?: number;  // max opportunities per category (default: all)
+};
+
 /** Promotion path result */
 export type PromotionResult<T extends TierDefinition = TierDefinition> = {
   currentScore: number;