earnrate 0.1.4 → 0.2.0

package/dist/cli/offers.js

@@ -1,10 +1,10 @@
 import { parseArgs } from 'node:util';
 import { CLI_NAME } from "../brand.js";
-import { walletProblems } from "../data/integrity.js";
 import { loadCatalog, walletPath } from "../data/load.js";
-import { compareOffers, } from "../engine/offers.js";
+import { compareOffers } from "../engine/offers.js";
 import { isValuationProfile, withValuationProfile } from "../engine/profiles.js";
-import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
+import { formatOffers } from "../format/offers.js";
+import { cardsToUse, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
 export const OFFERS_HELP = `Usage: ${CLI_NAME} offers [--cash | --points] [--no-fee] [--business] [options]
 
 Ranks the welcome offers on cards you don't have by first-year value: the
@@ -21,48 +21,6 @@ Options:
   --json                 Print the full comparison as JSON.
   -h, --help             Show this help.
 `;
-const TOP = 10;
-const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
-function reward(o, currencyName) {
-    if (o.dollars !== null)
-        return usd(o.dollars);
-    return `${(o.points ?? 0).toLocaleString('en-US')} ${currencyName}`;
-}
-function feeText(o) {
-    if (o.annualFee === null)
-        return 'annual fee not on file';
-    if (o.annualFee === 0)
-        return 'no annual fee';
-    if (o.firstYearFee !== null && o.firstYearFee !== o.annualFee)
-        return `${usd(o.annualFee)} annual fee (${o.firstYearFee === 0 ? 'waived' : usd(o.firstYearFee)} the first year)`;
-    return `${usd(o.annualFee)} annual fee`;
-}
-export function formatOffers(c, currencyName, all) {
-    if (c.offers.length === 0) {
-        return `No published welcome offers match.${c.withoutOffer.length > 0 ? ` ${String(c.withoutOffer.length)} matching card(s) have none on file.` : ''}\n`;
-    }
-    const shown = all ? c.offers : c.offers.slice(0, TOP);
-    const width = Math.max(...shown.map((o) => o.cardName.length));
-    const lines = [];
-    shown.forEach((o, i) => {
-        const weeks = (o.months * 52) / 12;
-        const pace = o.spend > 0 ? ` (about ${usd(Math.round(o.spend / weeks))} a week)` : '';
-        const spend = o.spend > 0
-            ? `after ${usd(o.spend)} in ${String(o.months)} month${o.months === 1 ? '' : 's'}${pace}`
-            : 'with no spending required';
-        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${usd(Math.round(o.firstYearValue))} the first year`, `    ${reward(o, currencyName(o.currency))} ${spend}. ${feeText(o)[0]?.toUpperCase() ?? ''}${feeText(o).slice(1)}.${o.held ? ' In your wallet.' : ''}`);
-        if (o.validTo)
-            lines.push(`    Offer ends ${o.validTo}.`);
-        if (o.note)
-            lines.push(`    ${o.note}`);
-    });
-    if (c.offers.length > shown.length)
-        lines.push(`  + ${String(c.offers.length - shown.length)} more (--all lists them)`);
-    if (c.withoutOffer.length > 0)
-        lines.push('', `${String(c.withoutOffer.length)} matching card(s) have no published offer on file.`);
-    lines.push('', ...c.notes);
-    return `${lines.join('\n')}\n`;
-}
 export async function runOffers(argv, io) {
     let parsed;
     try {
@@ -98,16 +56,14 @@ export async function runOffers(argv, io) {
         io.stderr(`Unknown valuation "${values.valuation}". Use flat or points-heavy.\n`);
         return USAGE_ERROR;
     }
-    const walletFile = walletPath(io.env);
-    const loaded = await readWallet(walletFile, io);
-    if (!loaded)
+    const found = await cardsToUse(walletPath(io.env), io, {
+        cards: null,
+        members: [],
+    });
+    if (found === null)
         return RUNTIME_ERROR;
     const catalog = await loadCatalog();
-    const problems = walletProblems(loaded, catalog);
-    if (problems.length > 0) {
-        io.stderr(`Your wallet at ${displayPath(walletFile)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
-        return RUNTIME_ERROR;
-    }
+    const loaded = found === 'none' ? { valuations: {}, memberships: [], cards: [] } : found;
     const wallet = values.valuation && isValuationProfile(values.valuation)
         ? withValuationProfile(loaded, values.valuation)
         : loaded;
@@ -125,3 +81,4 @@ export async function runOffers(argv, io) {
     io.stdout(formatOffers(comparison, currencyName, values.all ?? false));
     return 0;
 }
+export { formatOffers };

package/dist/cli/run.js

@@ -1,11 +1,14 @@
+import { access } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CLI_NAME, CONFIG_DIR, LLM_ENV_VAR, LLM_MAX_CALLS_ENV_VAR, LLM_MODEL_ENV_VAR, MERCHANT_CACHE_ENV_VAR, WALLET_ENV_VAR, } from "../brand.js";
 import { walletProblems } from "../data/integrity.js";
 import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
-import { withValuationProfile } from "../engine/profiles.js";
+import { VALUATION_PROFILES, withValuationProfile } from "../engine/profiles.js";
+import { ALL_PERSONAL_CARDS, categoryResolution, exploreCards, findCategory, } from "../engine/explore.js";
 import { recommend } from "../engine/recommend.js";
+import { walletFromCards } from "../engine/transient.js";
 import { DEFAULT_LLM_MODEL } from "../merchants/anthropic.js";
 import { DEFAULT_MAX_CALLS } from "../merchants/fallback.js";
 import { llmEnabled, openLlmSession } from "../merchants/from-env.js";
@@ -13,14 +16,16 @@ import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { packageVersion } from "../version.js";
 import { parseCliArgs } from "./args.js";
 import { runCheatSheet } from "./cheatsheet.js";
-import { runBest, runSimulate } from "./explore.js";
+import { formatExploration, runBest, runSimulate } from "./explore.js";
 import { runImport } from "./import.js";
 import { runOffers } from "./offers.js";
 import { runWalletCommand, WALLET_HELP } from "./wallet.js";
 import { formatRecommendation, plain } from "./format.js";
 export const HELP = `Usage: ${CLI_NAME} <merchant> [amount] [options]
 
-Picks the card in your wallet that earns the most at a merchant, and says why.
+Picks the card that earns the most at a merchant, and says why: from your
+wallet if you've saved one, from cards you name with --cards, or else from
+every card earnrate knows.
 
 Examples:
   ${CLI_NAME} whole foods 80
@@ -53,6 +58,9 @@ Options:
   --json                 Print the full recommendation as JSON.
   --date <YYYY-MM-DD>    Purchase date. Default: today.
   --country <code>       Where you're paying. Default: US.
+  --cards <ids>          Answer for these cards instead of your wallet, comma
+                         separated: --cards amex-gold,chase-prime-visa.
+  --member <name>        A membership you have, with --cards or no wallet.
   --category <id>        For a merchant earnrate doesn't know: its category,
                          e.g. grocery.supermarket. Ignored for known merchants.
   --llm, --no-llm        Ask Claude to classify merchants earnrate doesn't know.
@@ -75,6 +83,38 @@ export function displayPath(file) {
     const home = homedir();
     return file.startsWith(`${home}/`) ? `~${file.slice(home.length)}` : file;
 }
+// The cards to answer for: those named with --cards, else the wallet file.
+// 'none' means no wallet and no --cards, which answers from every card.
+export async function cardsToUse(file, io, named) {
+    const catalog = await loadCatalog();
+    if (named.cards !== null) {
+        const wallet = walletFromCards(catalog, {
+            cards: named.cards.map((id) => ({ id })),
+            memberships: named.members,
+        }, io.today);
+        if (typeof wallet === 'string') {
+            io.stderr(`${wallet}\n`);
+            return null;
+        }
+        return wallet;
+    }
+    try {
+        await access(file);
+    }
+    catch {
+        return 'none';
+    }
+    const loaded = await readWallet(file, io);
+    if (!loaded)
+        return null;
+    const problems = walletProblems(loaded, catalog);
+    if (problems.length > 0) {
+        io.stderr(`Your wallet at ${displayPath(file)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
+        return null;
+    }
+    return loaded;
+}
+export const NO_WALLET_HINT = `These are every card earnrate knows. For the best of your own cards, name them with --cards amex-gold,chase-prime-visa, or save them: ${CLI_NAME} add <card-id> (${CLI_NAME} cards finds ids).`;
 export async function readWallet(file, io) {
     try {
         return await loadWallet(file);
@@ -120,18 +160,10 @@ export async function run(argv, io) {
     const { options } = args;
     const llmOn = options.llm ?? llmEnabled(io.env);
     const file = walletPath(io.env);
-    const loaded = await readWallet(file, io);
-    if (!loaded)
+    const loaded = await cardsToUse(file, io, options);
+    if (loaded === null)
         return RUNTIME_ERROR;
     const catalog = await loadCatalog();
-    const problems = walletProblems(loaded, catalog);
-    if (problems.length > 0) {
-        io.stderr(`Your wallet at ${displayPath(file)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
-        return RUNTIME_ERROR;
-    }
-    const wallet = options.valuation
-        ? withValuationProfile(loaded, options.valuation)
-        : loaded;
     const purchase = {
         merchant: options.merchant,
         amount: options.amount,
@@ -144,7 +176,14 @@ export async function run(argv, io) {
         io.stderr(`Unknown category "${options.category}". Use one of: ${catalog.categories.map((c) => c.id).join(', ')}.\n`);
         return USAGE_ERROR;
     }
-    let merchant = withCallerCategory(resolveMerchant(catalog, purchase.merchant, purchase.channel), options.category);
+    // Plain category words ("restaurants", "groceries") work like stores.
+    const resolvedName = resolveMerchant(catalog, purchase.merchant, purchase.channel);
+    const named = resolvedName.source === 'none' && options.category === null
+        ? findCategory(catalog, purchase.merchant)
+        : null;
+    let merchant = named === null
+        ? withCallerCategory(resolvedName, options.category)
+        : categoryResolution(catalog, named, purchase.channel);
     const notices = [];
     if (llmOn && merchant.source === 'none') {
         const opened = await openLlmSession({
@@ -161,6 +200,33 @@ export async function run(argv, io) {
         merchant = resolved.merchant;
         notices.push(...resolved.notices);
     }
+    if (loaded === 'none') {
+        const explored = exploreCards(catalog, {
+            merchant: purchase.merchant,
+            category: null,
+            amount: purchase.amount,
+            channel: purchase.channel,
+            date: purchase.date,
+        }, {
+            filters: ALL_PERSONAL_CARDS,
+            memberships: options.members,
+            valuations: options.valuation
+                ? VALUATION_PROFILES[options.valuation]
+                : {},
+        }, merchant);
+        if (options.json) {
+            io.stdout(`${JSON.stringify(explored, null, 2)}\n`);
+        }
+        else {
+            io.stdout(`${formatExploration(explored, options.all)}\n${NO_WALLET_HINT}\n`);
+        }
+        for (const n of notices)
+            io.stderr(`${n}\n`);
+        return 0;
+    }
+    const wallet = options.valuation
+        ? withValuationProfile(loaded, options.valuation)
+        : loaded;
     const rec = recommend(catalog, wallet, purchase, merchant);
     if (options.json) {
         io.stdout(`${JSON.stringify(rec, null, 2)}\n`);

package/dist/cli/wallet.js

@@ -13,6 +13,13 @@ const CARD_OPTIONS = `Options:
   --anniversary <MM-DD>      Account anniversary, for caps that reset on it.
   --activated <rules>        Rules you've activated with the issuer, comma
                              separated. Replaces the current list.
+  --bonus-opened <date>      Track a welcome bonus: the day the account opened
+                             (YYYY-MM-DD). Spending needed and the deadline
+                             default to the card's published offer.
+  --bonus-spent <dollars>    Spending toward it so far. Default 0.
+  --bonus-spend <dollars>    The spending needed, if your offer differs.
+  --bonus-by <date>          The deadline, if your offer differs.
+  --no-bonus                 Stop tracking the welcome bonus.
   -h, --help                 Show this help.`;
 export const WALLET_HELP = {
     cards: `Usage: ${CLI_NAME} cards [search words]
@@ -105,6 +112,11 @@ export async function runWalletCommand(command, argv, io) {
                 pick: { type: 'string', multiple: true },
                 anniversary: { type: 'string' },
                 activated: { type: 'string' },
+                'bonus-opened': { type: 'string' },
+                'bonus-spent': { type: 'string' },
+                'bonus-spend': { type: 'string' },
+                'bonus-by': { type: 'string' },
+                'no-bonus': { type: 'boolean' },
                 none: { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
             },
@@ -186,6 +198,34 @@ export async function runWalletCommand(command, argv, io) {
             return usage(picks);
         input.picks = picks;
     }
+    const dollarsFlag = (flag, text) => {
+        if (text === undefined)
+            return undefined;
+        const n = Number(text.replace(/[$,]/g, ''));
+        return Number.isFinite(n) ? n : `--${flag} takes dollars, like 1200.`;
+    };
+    if (values['no-bonus']) {
+        input.bonus = null;
+    }
+    else if (values['bonus-opened'] !== undefined) {
+        const spent = dollarsFlag('bonus-spent', values['bonus-spent']);
+        const spend = dollarsFlag('bonus-spend', values['bonus-spend']);
+        if (typeof spent === 'string')
+            return usage(spent);
+        if (typeof spend === 'string')
+            return usage(spend);
+        input.bonus = {
+            opened: values['bonus-opened'],
+            ...(spent === undefined ? {} : { spent }),
+            ...(spend === undefined ? {} : { spend }),
+            ...(values['bonus-by'] === undefined ? {} : { by: values['bonus-by'] }),
+        };
+    }
+    else if (values['bonus-spent'] !== undefined ||
+        values['bonus-spend'] !== undefined ||
+        values['bonus-by'] !== undefined) {
+        return usage('Give --bonus-opened with the other --bonus options.');
+    }
     if (command === 'add') {
         const result = await addCard(file, catalog, input, io.today);
         return report(result, `Added ${name} to ${where}${result.ok && result.created ? ' (a new wallet)' : ''}.`, id, io);

package/dist/data/file-store.js

@@ -0,0 +1,56 @@
+import { bookPurchase } from "../engine/record.js";
+import { loadWallet } from "./load.js";
+import { addCard, removeCard, setMemberships, updateCard, } from "./wallet-setup.js";
+import { withWalletLock, writeBonusSpent, writeCapBooking, } from "./wallet-write.js";
+// The wallet as a YAML file (the CLI, the local MCP server, the .mcpb and the
+// local plugin). Edits splice lines so the user's comments survive.
+export class FileWalletStore {
+    where;
+    catalog;
+    constructor(catalog, file) {
+        this.catalog = catalog;
+        this.where = file;
+    }
+    async load() {
+        try {
+            return await loadWallet(this.where);
+        }
+        catch (e) {
+            if (e instanceof Error && 'code' in e && e.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+    }
+    addCard(input, today) {
+        return withWalletLock(this.where, () => addCard(this.where, this.catalog, input, today));
+    }
+    updateCard(input, today) {
+        return withWalletLock(this.where, () => updateCard(this.where, this.catalog, input, today));
+    }
+    removeCard(cardId) {
+        return withWalletLock(this.where, () => removeCard(this.where, this.catalog, cardId));
+    }
+    setMemberships(memberships) {
+        return withWalletLock(this.where, () => setMemberships(this.where, this.catalog, memberships));
+    }
+    record(purchase, merchant) {
+        return withWalletLock(this.where, async () => {
+            const wallet = await this.load();
+            if (!wallet)
+                return { ok: false, error: "There's no saved wallet to record it in." };
+            if (!wallet.cards.some((c) => c.id === purchase.cardId))
+                return { ok: false, error: `${purchase.cardId} isn't in the wallet.` };
+            const booked = bookPurchase(this.catalog, wallet, purchase, merchant);
+            try {
+                if (booked.cap)
+                    await writeCapBooking(this.where, booked.cap);
+                if (booked.bonus)
+                    await writeBonusSpent(this.where, purchase.cardId, booked.bonus.after);
+            }
+            catch (e) {
+                return { ok: false, error: e instanceof Error ? e.message : String(e) };
+            }
+            return { ok: true, ...booked };
+        });
+    }
+}

package/dist/data/load.js

@@ -39,8 +39,16 @@ export async function loadCatalog(dir = DATA_DIR) {
     ]);
     return { categories, currencies, cards, merchants: { seed, overrides } };
 }
+// MCP clients pass config values through without a shell, so "~" or
+// "${HOME}" can arrive as literal text; expand them here.
 export function walletPath(env = process.env) {
-    return env[WALLET_ENV_VAR] ?? path.join(homedir(), CONFIG_DIR, 'wallet.yaml');
+    const given = env[WALLET_ENV_VAR]?.trim();
+    if (!given)
+        return path.join(homedir(), CONFIG_DIR, 'wallet.yaml');
+    const expanded = given
+        .replace(/^~(?=$|[/\\])/, homedir())
+        .replace(/\$\{HOME\}|\$HOME\b/g, homedir());
+    return path.resolve(expanded);
 }
 export function loadWallet(file = walletPath()) {
     return readYaml(file, WalletSchema);

package/dist/data/store.js

@@ -0,0 +1,108 @@
+import { bookPurchase } from "../engine/record.js";
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, } from "../engine/wallet-change.js";
+import { WalletSchema } from "../schema/wallet.js";
+const failed = (error) => ({ ok: false, error });
+// A wallet stored as JSON text. Writes are serialized within this instance;
+// a backend shared across processes must serialize them itself (one Durable
+// Object per wallet does).
+export class JsonWalletStore {
+    where;
+    catalog;
+    backend;
+    queue = Promise.resolve();
+    constructor(catalog, backend, where) {
+        this.catalog = catalog;
+        this.backend = backend;
+        this.where = where;
+    }
+    async load() {
+        const text = await this.backend.read();
+        return text === null ? null : WalletSchema.parse(JSON.parse(text));
+    }
+    serialized(task) {
+        const run = this.queue.then(task, task);
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    change(apply) {
+        return this.serialized(async () => {
+            const before = await this.load();
+            const change = apply(before);
+            if (!change.ok)
+                return failed(change.error);
+            await this.backend.write(JSON.stringify(change.wallet));
+            return {
+                ok: true,
+                wallet: change.wallet,
+                created: before === null,
+                notes: change.notes,
+            };
+        });
+    }
+    needsWallet(apply) {
+        return (wallet) => wallet === null
+            ? failed("There's no saved wallet yet. Add a card first to start one.")
+            : apply(wallet);
+    }
+    addCard(input, today) {
+        return this.change((w) => addToWallet(this.catalog, w, input, today));
+    }
+    updateCard(input, today) {
+        return this.change(this.needsWallet((w) => updateInWallet(this.catalog, w, input, today)));
+    }
+    removeCard(cardId) {
+        return this.change(this.needsWallet((w) => removeFromWallet(w, cardId)));
+    }
+    setMemberships(memberships) {
+        return this.change(this.needsWallet((w) => withMemberships(this.catalog, w, memberships)));
+    }
+    replace(wallet) {
+        return this.change(() => ({ ok: true, wallet, fields: {}, notes: [] }));
+    }
+    erase() {
+        return this.serialized(() => this.backend.remove());
+    }
+    record(purchase, merchant) {
+        return this.serialized(async () => {
+            const wallet = await this.load();
+            if (!wallet)
+                return failed("There's no saved wallet to record it in.");
+            if (!wallet.cards.some((c) => c.id === purchase.cardId))
+                return failed(`${purchase.cardId} isn't in the wallet.`);
+            const booked = bookPurchase(this.catalog, wallet, purchase, merchant);
+            if (booked.cap || booked.bonus)
+                await this.backend.write(JSON.stringify(booked.wallet));
+            return { ok: true, ...booked };
+        });
+    }
+}
+// A store with nothing behind it, for tests and for a session that starts
+// empty and is thrown away.
+export function memoryBackend(initial = null) {
+    let text = initial;
+    return {
+        read: () => Promise.resolve(text),
+        write: (next) => {
+            text = next;
+            return Promise.resolve();
+        },
+        remove: () => {
+            text = null;
+            return Promise.resolve();
+        },
+    };
+}
+// No saved wallet, and saving refused: the public remote server before
+// anonymous saved wallets exist. Cards named in the conversation still work.
+export function noSavedWallet(where) {
+    const refused = () => Promise.resolve(failed("Saving a wallet isn't available here yet. Name your cards in the conversation instead; nothing is stored."));
+    return {
+        where,
+        load: () => Promise.resolve(null),
+        addCard: refused,
+        updateCard: refused,
+        removeCard: refused,
+        setMemberships: refused,
+        record: refused,
+    };
+}

package/dist/data/wallet-edit.js

@@ -38,6 +38,18 @@ function fieldLines(field, f, indent) {
             return f.activated === undefined
                 ? ''
                 : `${indent}activated: ${flowList(f.activated)}\n`;
+        case 'bonus': {
+            if (!f.bonus)
+                return '';
+            const b = f.bonus;
+            return [
+                `${indent}bonus:\n`,
+                `${indent}  opened: ${scalar(b.opened)}\n`,
+                `${indent}  spent: ${String(b.spent)}\n`,
+                b.spend === undefined ? '' : `${indent}  spend: ${String(b.spend)}\n`,
+                b.by === undefined ? '' : `${indent}  by: ${scalar(b.by)}\n`,
+            ].join('');
+        }
         case 'chosen': {
             if (f.chosen === undefined)
                 return '';
@@ -48,7 +60,13 @@ function fieldLines(field, f, indent) {
         }
     }
 }
-const FIELDS = ['checkout_label', 'anniversary', 'chosen', 'activated'];
+const FIELDS = [
+    'checkout_label',
+    'anniversary',
+    'chosen',
+    'activated',
+    'bonus',
+];
 function cardsSeq(text) {
     const doc = parseDocument(text);
     if (doc.errors.length > 0)
@@ -105,7 +123,12 @@ export function updateCardText(text, cardId, fields) {
         const indent = ' '.repeat(column(out, range(card)[0]));
         const lines = fieldLines(field, fields, indent);
         const pair = card.items.find((p) => keyOf(p) === field);
-        if (pair) {
+        if (pair && lines === '') {
+            const start = lineStart(out, range(pair.key)[0]);
+            const end = afterLine(out, range(pair.value)[1] - 1);
+            out = out.slice(0, start) + out.slice(end);
+        }
+        else if (pair) {
             const start = range(pair.key)[0];
             const end = afterLine(out, range(pair.value)[1] - 1);
             out = out.slice(0, start) + lines.trimStart() + out.slice(end);

package/dist/engine/cheat-sheet.js

@@ -1,5 +1,5 @@
 import { resolveMerchantById } from "../merchants/resolve.js";
-import { categoryResolution } from "./explore.js";
+import { categoryResolution, exploreCards, } from "./explore.js";
 import { periodKey } from "./periods.js";
 import { recommend } from "./recommend.js";
 import { setupNotes } from "./setup.js";
@@ -44,5 +44,60 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
         ...new Set(wallet.cards.flatMap((held) => setupNotes(catalog, wallet, held, date).map((n) => n.text))),
     ];
     const [year, q] = (periodKey('quarter', date, null) ?? '').split('-');
-    return { quarter: `${q ?? ''} ${year ?? ''}`, date, rows, notes };
+    return {
+        scope: 'wallet',
+        quarter: `${q ?? ''} ${year ?? ''}`,
+        date,
+        rows,
+        notes,
+    };
+}
+// The best card earnrate knows for each everyday kind of purchase, for
+// someone who hasn't named any cards. Each row's note says what the card
+// costs or needs.
+export function catalogCheatSheet(catalog, date, options, items = CHEAT_SHEET_ITEMS) {
+    const rows = items.map((item) => {
+        const top = exploreCards(catalog, 'merchant' in item
+            ? {
+                merchant: catalog.merchants.seed.find((m) => m.id === item.merchant)
+                    ?.name ??
+                    catalog.merchants.overrides.find((m) => m.id === item.merchant)
+                        ?.name ??
+                    item.label,
+                category: null,
+                amount: null,
+                channel: null,
+                date,
+            }
+            : {
+                merchant: null,
+                category: item.category,
+                amount: null,
+                channel: null,
+                date,
+            }, options).ranked[0];
+        const fee = top?.annualFee === null || top?.annualFee === undefined
+            ? null
+            : top.annualFee === 0
+                ? 'No annual fee.'
+                : `$${String(top.annualFee)} annual fee.`;
+        return {
+            label: item.label,
+            cardId: top?.cardId ?? null,
+            cardName: top?.cardName ?? null,
+            effectiveReturnPct: top?.effectiveReturnPct ?? null,
+            matchedRule: top?.matchedRule ?? null,
+            note: top
+                ? [fee, ...top.conditions].filter((n) => n !== null).join(' ')
+                : null,
+        };
+    });
+    const [year, q] = (periodKey('quarter', date, null) ?? '').split('-');
+    return {
+        scope: 'all cards',
+        quarter: `${q ?? ''} ${year ?? ''}`,
+        date,
+        rows,
+        notes: [],
+    };
 }

package/dist/engine/explore.js

@@ -92,7 +92,7 @@ export function categoryResolution(catalog, category, channel) {
         ambiguity: null,
         channel,
         confidence: 'high',
-        source: 'caller',
+        source: 'category',
         bookedVia: [],
         inference: null,
     };
@@ -198,10 +198,11 @@ function compareExplored(a, b) {
 }
 // Ranks every card in the catalog that passes the filters for one purchase,
 // each set up at its best: the pick that covers it, activated, cap unused.
-export function exploreCards(catalog, query, options) {
-    const merchant = query.merchant !== null
-        ? resolveMerchant(catalog, query.merchant, query.channel)
-        : categoryResolution(catalog, query.category ?? 'other', query.channel);
+export function exploreCards(catalog, query, options, resolved) {
+    const merchant = resolved ??
+        (query.merchant !== null
+            ? resolveMerchant(catalog, query.merchant, query.channel)
+            : categoryResolution(catalog, query.category ?? 'other', query.channel));
     const purchase = {
         merchant: merchant.input,
         amount: query.amount,
@@ -257,7 +258,7 @@ export function exploreCards(catalog, query, options) {
 }
 function exploreAssumptions(catalog, merchant, ranked, options) {
     const assumptions = [];
-    if (merchant.source === 'caller') {
+    if (merchant.source === 'category') {
         assumptions.push(`Ranks purchases that code as ${categoryPhrase(catalog, merchant.category)}.`);
     }
     else if (merchant.source !== 'none') {

package/dist/engine/recommend.js

@@ -258,6 +258,9 @@ function assumptionsFor(catalog, merchant, purchase, entries) {
     if (merchant.source === 'none') {
         assumptions.push(`Treats "${merchant.input}" as an everyday purchase with no bonus category.`);
     }
+    else if (merchant.source === 'category') {
+        assumptions.push(`Ranks purchases that code as ${categoryPhrase(catalog, merchant.category)}.`);
+    }
     else if (merchant.category === 'other') {
         assumptions.push(`Assumes ${merchant.resolvedName} falls outside the usual bonus categories.`);
     }