earnrate 0.2.4 → 0.2.5

package/dist/cli/explore.js

@@ -2,19 +2,20 @@ import { parseArgs } from 'node:util';
 import { CLI_NAME } from "../brand.js";
 import { loadCatalog, walletPath } from "../data/load.js";
 import { ALL_PERSONAL_CARDS, exploreCards, findCategory, } from "../engine/explore.js";
-import { isValuationProfile, VALUATION_PROFILES, withValuationProfile, } from "../engine/profiles.js";
+import { isValuationProfile, profileText, VALUATION_PROFILES, withValuationProfile, } from "../engine/profiles.js";
 import { resolveSpendLines, simulateAdditions, simulateCatalog, spendLineFor, TYPICAL_MONTHLY_SPEND, TYPICAL_SPEND_NOTE, } from "../engine/simulate.js";
 import { formatAdditions, formatCatalogSimulation, formatExploration, } from "../format/explore.js";
 import { BOTH_CHANNELS, cardList, channelOf, dateProblem, membershipProblem, splitAmount, valuationProblem, } from "./args.js";
-import { cardsToUse, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
+import { cardsToUse, RUNTIME_ERROR, savedSettings, USAGE_ERROR, } from "./run.js";
 const FILTER_OPTIONS = `  --cash, --points        Cash back cards only, or points and miles cards only.
   --no-fee                Cards with no annual fee.
   --issuer <id>           One issuer's cards, e.g. chase or amex.
   --business              Business cards instead of personal ones.
   --closed                Include cards the issuer no longer takes applications for.
   --member <name>         A membership you have, e.g. amazon-prime or costco. Repeatable.
-  --valuation <profile>   flat (points at 1¢, the default) or points-heavy
-                          (MR and UR at 1.7¢).`;
+  --valuation <profile>   flat (${profileText('flat')}) or points-heavy
+                          (${profileText('points-heavy')}), instead of your
+                          saved point values.`;
 const BEST_HELP = `Usage: ${CLI_NAME} best <merchant or category> [amount] [options]
 
 Ranks every card in earnrate's catalog for one purchase, not just yours. Each
@@ -67,7 +68,7 @@ const FILTER_FLAGS = {
     json: { type: 'boolean' },
     help: { type: 'boolean', short: 'h' },
 };
-function settingsFrom(values, catalog) {
+function settingsFrom(values, catalog, saved) {
     if (values.cash && values.points)
         return 'Pick --cash or --points, not both.';
     const problem = valuationProblem(values.valuation) ??
@@ -86,10 +87,10 @@ function settingsFrom(values, catalog) {
             issuer: values.issuer ?? null,
             includeClosed: values.closed ?? false,
         },
-        memberships: values.member ?? [],
+        memberships: values.member ?? saved.memberships,
         valuations: values.valuation !== undefined && isValuationProfile(values.valuation)
             ? VALUATION_PROFILES[values.valuation]
-            : {},
+            : saved.valuations,
     };
 }
 export async function runBest(argv, io) {
@@ -135,7 +136,7 @@ export async function runBest(argv, io) {
         return USAGE_ERROR;
     }
     const catalog = await loadCatalog();
-    const settings = settingsFrom(values, catalog);
+    const settings = settingsFrom(values, catalog, await savedSettings(io));
     if (typeof settings === 'string') {
         io.stderr(`${settings}\n`);
         return USAGE_ERROR;
@@ -150,7 +151,7 @@ export async function runBest(argv, io) {
     }, settings);
     io.stdout(values.json
         ? `${JSON.stringify(result, null, 2)}\n`
-        : formatExploration(result, values.all ?? false));
+        : formatExploration(result, catalog, values.all ?? false));
     return 0;
 }
 function parseSpend(catalog, args) {
@@ -195,7 +196,7 @@ export async function runSimulate(argv, io) {
         return 0;
     }
     const catalog = await loadCatalog();
-    const settings = settingsFrom(values, catalog);
+    const settings = settingsFrom(values, catalog, await savedSettings(io));
     if (typeof settings === 'string') {
         io.stderr(`${settings}\n`);
         return USAGE_ERROR;

package/dist/cli/import.js

@@ -12,6 +12,7 @@ import { cardValuation } from "../engine/valuation.js";
 import { analyzeStatement, } from "../import/analyze.js";
 import { parseStatement } from "../import/statement.js";
 import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
+import { dollarsAndCents } from "../engine/text.js";
 const IMPORT_HELP = `Usage: ${CLI_NAME} import <statement.csv> --card <card-id> [--apply]
        ${CLI_NAME} import <statement.csv>:<card-id> [<statement.csv>:<card-id> ...]
 
@@ -44,7 +45,6 @@ const LedgerSchema = z.strictObject({
 const fingerprint = ({ cardId, line }, kind = 'cap') => createHash('sha256')
     .update(`${kind === 'bonus' ? 'bonus|' : ''}${cardId}|${line.date}|${String(line.amount)}|${line.description}`)
     .digest('hex');
-const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
 // "statement.csv:chase-sapphire-preferred" names the card inline.
 function splitTarget(arg) {
     const m = /^(.+):([a-z0-9]+(?:-[a-z0-9]+)*)$/.exec(arg);
@@ -77,20 +77,20 @@ function formatAnalysis(a, labelOf, valuation, categoryName) {
         several
             ? `${String(a.byCard.length)} statements (${names.join(', ')}) · ${a.from} to ${a.to}`
             : `${names[0] ?? ''} statement · ${a.from} to ${a.to}`,
-        `${String(a.purchases)} purchases, ${usd(a.spend)}${a.refunds > 0 ? ` (refunds and credits: ${usd(a.refunds)})` : ''}`,
+        `${String(a.purchases)} purchases, ${dollarsAndCents(a.spend)}${a.refunds > 0 ? ` (refunds and credits: ${dollarsAndCents(a.refunds)})` : ''}`,
         '',
     ];
     if (several) {
-        out.push(`Earned on the cards you used: about ${usd(a.earned)}`);
+        out.push(`Earned on the cards you used: about ${dollarsAndCents(a.earned)}`);
         const width = Math.max(...names.map((n) => n.length));
         for (const t of a.byCard) {
-            out.push(`  ${labelOf(t.cardId).padEnd(width)}  ${String(t.purchases).padStart(4)} × ${usd(t.spend).padStart(11)}  ${usd(t.earned)}`);
+            out.push(`  ${labelOf(t.cardId).padEnd(width)}  ${String(t.purchases).padStart(4)} × ${dollarsAndCents(t.spend).padStart(11)}  ${dollarsAndCents(t.earned)}`);
         }
     }
     else {
-        out.push(`Earned on ${names[0] ?? ''}: about ${usd(a.earned)}`);
+        out.push(`Earned on ${names[0] ?? ''}: about ${dollarsAndCents(a.earned)}`);
     }
-    out.push(`With earnrate's picks: about ${usd(a.best)} (+${usd(a.best - a.earned)})`, valuation);
+    out.push(`With earnrate's picks: about ${dollarsAndCents(a.best)} (+${dollarsAndCents(a.best - a.earned)})`, valuation);
     if (a.missed.length > 0) {
         out.push('', 'Where another card would have earned more:');
         const shown = a.missed.slice(0, 10);
@@ -99,7 +99,7 @@ function formatAnalysis(a, labelOf, valuation, categoryName) {
         const cardWidth = Math.max(...shown.map((m) => labelOf(m.usedCardId).length));
         for (const m of shown) {
             const used = several ? `${labelOf(m.usedCardId).padEnd(cardWidth)}  ` : '';
-            out.push(`  ${name(m).slice(0, width).padEnd(width)}  ${used}${String(m.count).padStart(3)} × ${usd(m.spend).padStart(10)}  ${usd(m.earned)} → ${m.bestCard} ${usd(m.best)}  (+${usd(m.best - m.earned)})`);
+            out.push(`  ${name(m).slice(0, width).padEnd(width)}  ${used}${String(m.count).padStart(3)} × ${dollarsAndCents(m.spend).padStart(10)}  ${dollarsAndCents(m.earned)} → ${m.bestCard} ${dollarsAndCents(m.best)}  (+${dollarsAndCents(m.best - m.earned)})`);
         }
         if (a.missed.length > 10)
             out.push(`  …and ${String(a.missed.length - 10)} more merchants`);
@@ -117,7 +117,7 @@ function formatAnalysis(a, labelOf, valuation, categoryName) {
         const last = new Map();
         for (const { cardId, booking } of a.bookings)
             last.set(several ? `${labelOf(cardId)} ${booking.capKey}` : booking.capKey, booking.after);
-        out.push(`Cap usage for the current period: ${[...last].map(([k, v]) => `${k} ${usd(v)}`).join(', ')}.`);
+        out.push(`Cap usage for the current period: ${[...last].map(([k, v]) => `${k} ${dollarsAndCents(v)}`).join(', ')}.`);
     }
     else if (a.alreadyImported > 0) {
         out.push(`Caps: nothing new to record. ${String(a.alreadyImported)} purchase(s) were recorded by an earlier import.`);
@@ -129,7 +129,7 @@ function formatAnalysis(a, labelOf, valuation, categoryName) {
         out.push('Caps: nothing new to record.');
     }
     for (const b of a.bonuses) {
-        out.push(`Welcome bonus on ${labelOf(b.cardId)}: ${usd(b.before)} → ${usd(b.after)} of ${usd(b.spend)}${b.deadline ? ` by ${b.deadline}` : ''}.`);
+        out.push(`Welcome bonus on ${labelOf(b.cardId)}: ${dollarsAndCents(b.before)} → ${dollarsAndCents(b.after)} of ${dollarsAndCents(b.spend)}${b.deadline ? ` by ${b.deadline}` : ''}.`);
     }
     return `${out.join('\n')}\n`;
 }

package/dist/cli/offers.js

@@ -9,7 +9,8 @@ import { cardsToUse, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
 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
-bonus at your point values minus the first year's annual fee.
+bonus at your point values minus the first year's annual fee and any
+membership the card needs that you don't have.
 
 Options:
   --cash                 Cash back cards only.

package/dist/cli/run.js

@@ -6,7 +6,7 @@ import { CLI_NAME, CONFIG_DIR, LLM_ENV_VAR, LLM_MAX_CALLS_ENV_VAR, LLM_MODEL_ENV
 import { walletProblems } from "../data/integrity.js";
 import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
 import { ALL_PERSONAL_CARDS, categoryResolution, exploreCards, findCategory, } from "../engine/explore.js";
-import { VALUATION_PROFILES, withValuationProfile } from "../engine/profiles.js";
+import { profileText, VALUATION_PROFILES, withValuationProfile, } from "../engine/profiles.js";
 import { recommend } from "../engine/recommend.js";
 import { walletFromCards } from "../engine/transient.js";
 import { formatExploration } from "../format/explore.js";
@@ -43,6 +43,7 @@ Save your cards (optional):
   ${CLI_NAME} update <card-id> [--pick ...]        Change picks, label or activations.
   ${CLI_NAME} remove <card-id>                     Remove a card.
   ${CLI_NAME} memberships [names...]               Show or set memberships (amazon-prime, costco).
+  ${CLI_NAME} values [UR=1.5 ...]                  Show or set what your points are worth.
 
 Other commands:
   ${CLI_NAME} cheatsheet                           The best card for each category this quarter.
@@ -53,7 +54,8 @@ Other commands:
 
 Options:
   --online, --in-store   How you're paying. Default: inferred from the merchant.
-  --valuation <profile>  flat (points at 1¢) or points-heavy (MR and UR at 1.7¢).
+  --valuation <profile>  flat (${profileText('flat')}) or points-heavy (${profileText('points-heavy')}),
+                         instead of your saved point values.
                          Default: the values in your wallet.
   --all                  List every card, not just the top three.
   --json                 Print the full recommendation as JSON.
@@ -120,6 +122,18 @@ export async function cardsToUse(catalog, file, io, named) {
     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).`;
+// The point values and memberships saved in the wallet, which every answer
+// uses unless --valuation or --member says otherwise. No wallet, or one that
+// can't be read, has none.
+export async function savedSettings(io) {
+    try {
+        const { valuations, memberships } = await loadWallet(walletPath(io.env));
+        return { valuations, memberships };
+    }
+    catch {
+        return { valuations: {}, memberships: [] };
+    }
+}
 export async function readWallet(file, io) {
     try {
         return await loadWallet(file);
@@ -222,7 +236,7 @@ export async function run(argv, io) {
             io.stdout(`${JSON.stringify(explored, null, 2)}\n`);
         }
         else {
-            io.stdout(`${formatExploration(explored, options.all)}\n${NO_WALLET_HINT}\n`);
+            io.stdout(`${formatExploration(explored, catalog, options.all)}\n${NO_WALLET_HINT}\n`);
         }
         for (const n of notices)
             io.stderr(`${n}\n`);

package/dist/cli/wallet.js

@@ -2,6 +2,7 @@ import { parseArgs } from 'node:util';
 import { CLI_NAME } from "../brand.js";
 import { FileWalletStore } from "../data/file-store.js";
 import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
+import { isValuationProfile, profileText, VALUATION_PROFILES, } from "../engine/profiles.js";
 import { knownMemberships, searchCards } from "../engine/setup.js";
 import { formatCardInfo, formatNotes } from "../format/cards.js";
 import { displayPath, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
@@ -53,6 +54,20 @@ Removes a card from your wallet, with its tracked cap usage.
 
 With no arguments, shows your memberships and the ones earnrate knows. With
 names, replaces the list. --none clears it.
+`,
+    values: `Usage: ${CLI_NAME} values [<currency>=<cents>...] [--profile <name>]
+
+What your points are worth to you, in cents per point, saved in your wallet
+file; every answer then uses them unless you pass --valuation. With no
+arguments, shows them.
+
+Examples:
+  ${CLI_NAME} values UR=1.5 MR=1.6
+  ${CLI_NAME} values UR=default          back to earnrate's value
+  ${CLI_NAME} values --profile points-heavy
+
+Options:
+  --profile <name>       flat (${profileText('flat')}) or points-heavy (${profileText('points-heavy')}).
 `,
 };
 const HINTS = {
@@ -118,6 +133,7 @@ export async function runWalletCommand(command, argv, io) {
                 'bonus-by': { type: 'string' },
                 'no-bonus': { type: 'boolean' },
                 none: { type: 'boolean' },
+                profile: { type: 'string' },
                 help: { type: 'boolean', short: 'h' },
             },
         });
@@ -160,6 +176,32 @@ export async function runWalletCommand(command, argv, io) {
         io.stdout(`${header}${result.cards.map(formatCardInfo).join('\n')}\n`);
         return 0;
     }
+    if (command === 'values') {
+        const changes = {};
+        if (values.profile !== undefined) {
+            if (!isValuationProfile(values.profile))
+                return usage(`Unknown profile "${values.profile}". Use flat or points-heavy.`);
+            Object.assign(changes, VALUATION_PROFILES[values.profile]);
+        }
+        for (const arg of positionals) {
+            const [id, value] = arg.split('=');
+            const cents = value === 'default' ? null : Number(value);
+            if (!id ||
+                value === undefined ||
+                (cents !== null && !Number.isFinite(cents)))
+                return usage(`"${arg}" isn't <currency>=<cents>, like UR=1.5.`);
+            changes[id] = cents;
+        }
+        if (Object.keys(changes).length === 0) {
+            const held = await heldWallet(io);
+            const set = Object.entries(held?.valuations ?? {});
+            io.stdout(`${set.length > 0 ? `Yours: ${set.map(([id, v]) => `${id}=${typeof v === 'number' ? String(v) : JSON.stringify(v)}`).join(' ')}` : "Yours: earnrate's defaults"}\nCurrencies: ${catalog.currencies.map((c) => c.id).join(', ')}\n`);
+            return 0;
+        }
+        return report(await store.setValuations(changes), `Point values updated in ${where}: ${Object.entries(changes)
+            .map(([id, c]) => `${id} ${c === null ? 'back to the default' : `${String(c)}¢`}`)
+            .join(', ')}.`, null, io);
+    }
     if (command === 'memberships') {
         if (positionals.length === 0 && !values.none) {
             const held = await heldWallet(io);

package/dist/data/file-store.js

@@ -1,7 +1,7 @@
 import { bookPurchase } from "../engine/record.js";
-import { addToWallet, removeFromWallet, updateInWallet, withMemberships, } from "../engine/wallet-change.js";
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, withValuations, } from "../engine/wallet-change.js";
 import { loadWallet } from "./load.js";
-import { addCardText, commitWalletText, readWalletText, removeCardText, setMembershipsText, updateCardText, writeProgress, } from "./wallet-edit.js";
+import { addCardText, commitWalletText, readWalletText, removeCardText, setMembershipsText, setValuationsText, updateCardText, writeProgress, } from "./wallet-edit.js";
 const failed = (error) => ({ ok: false, error });
 const errorText = (e) => (e instanceof Error ? e.message : String(e));
 const queues = new Map();
@@ -76,6 +76,9 @@ export class FileWalletStore {
     setMemberships(memberships) {
         return this.change(this.existing((w) => withMemberships(this.catalog, w, memberships)), (text, change) => setMembershipsText(text ?? '', change.wallet.memberships));
     }
+    setValuations(changes) {
+        return this.change(this.existing((w) => withValuations(this.catalog, w, changes)), (text) => setValuationsText(text ?? '', changes));
+    }
     record(purchase, merchant) {
         return withWalletLock(this.where, async () => {
             const wallet = await this.load();

package/dist/data/integrity.js

@@ -60,8 +60,19 @@ function cardProblems(card, catalog, merchantIds) {
     for (const id of card.welcome_offer?.not_with ?? [])
         if (!cardIds.has(id))
             problems.push(`${where} welcome_offer.not_with: unknown card '${id}'`);
-    for (const m of card.requires_membership?.members_shop_at ?? [])
-        checkMerchant(m, 'requires_membership');
+    const memberships = new Set(catalog.memberships.map((m) => m.id));
+    for (const id of [
+        ...(card.requires_membership === undefined
+            ? []
+            : [card.requires_membership]),
+        ...card.rules.flatMap((r) => r.requires?.membership ?? []),
+    ])
+        if (!memberships.has(id))
+            problems.push(`${where}: unknown membership '${id}' (data/memberships.yaml)`);
+    if (card.requires_membership !== undefined &&
+        catalog.memberships.find((m) => m.id === card.requires_membership)
+            ?.annual_fee === undefined)
+        problems.push(`${where}: requires_membership '${card.requires_membership}' has no annual_fee`);
     if (card.pools_into) {
         if (!currencies.has(card.pools_into.currency)) {
             problems.push(`${where} pools_into: unknown currency '${card.pools_into.currency}'`);
@@ -167,6 +178,7 @@ export function catalogProblems(catalog) {
         ['category', catalog.categories.map((c) => c.id)],
         ['currency', catalog.currencies.map((c) => c.id)],
         ['card', catalog.cards.map((c) => c.id)],
+        ['membership', catalog.memberships.map((m) => m.id)],
     ]) {
         for (const id of duplicates(ids))
             problems.push(`duplicate ${kind} id '${id}'`);
@@ -187,6 +199,10 @@ export function catalogProblems(catalog) {
                 problems.push(`merchant ${m.id}: booked_via '${via}' is not a merchant`);
         }
     }
+    for (const m of catalog.memberships)
+        for (const id of m.members_shop_at)
+            if (!merchantIds.has(id))
+                problems.push(`membership ${m.id}: members_shop_at '${id}' is not a merchant`);
     for (const card of catalog.cards) {
         problems.push(...cardProblems(card, catalog, merchantIds));
     }

package/dist/data/load.js

@@ -8,6 +8,7 @@ import { CONFIG_DIR, WALLET_ENV_VAR } from "../brand.js";
 import { CardSchema } from "../schema/card.js";
 import { CategoriesFileSchema } from "../schema/category.js";
 import { CurrenciesFileSchema } from "../schema/currency.js";
+import { MembershipsFileSchema } from "../schema/membership.js";
 import { MerchantsFileSchema } from "../schema/merchant.js";
 import { WalletSchema } from "../schema/wallet.js";
 export const DATA_DIR = fileURLToPath(new URL('../../data/', import.meta.url));
@@ -30,14 +31,21 @@ async function loadCards(dir) {
     }));
 }
 export async function loadCatalog(dir = DATA_DIR) {
-    const [categories, currencies, cards, seed, overrides] = await Promise.all([
+    const [categories, currencies, memberships, cards, seed, overrides] = await Promise.all([
         readYaml(path.join(dir, 'categories.yaml'), CategoriesFileSchema),
         readYaml(path.join(dir, 'currencies.yaml'), CurrenciesFileSchema),
+        readYaml(path.join(dir, 'memberships.yaml'), MembershipsFileSchema),
         loadCards(path.join(dir, 'cards')),
         readYaml(path.join(dir, 'merchants', 'seed.yaml'), MerchantsFileSchema),
         readYaml(path.join(dir, 'merchants', 'overrides.yaml'), MerchantsFileSchema),
     ]);
-    return { categories, currencies, cards, merchants: { seed, overrides } };
+    return {
+        categories,
+        currencies,
+        memberships,
+        cards,
+        merchants: { seed, overrides },
+    };
 }
 // MCP clients pass config values through without a shell, so "~" or
 // "${HOME}" can arrive as literal text; expand them here.

package/dist/data/store.js

@@ -1,5 +1,5 @@
 import { bookPurchase } from "../engine/record.js";
-import { addToWallet, removeFromWallet, updateInWallet, withMemberships, } from "../engine/wallet-change.js";
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, withValuations, } 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;
@@ -60,6 +60,9 @@ export class JsonWalletStore {
     setMemberships(memberships) {
         return this.change(this.needsWallet((w) => withMemberships(this.catalog, w, memberships)));
     }
+    setValuations(changes) {
+        return this.change(this.needsWallet((w) => withValuations(this.catalog, w, changes)));
+    }
     replace(wallet) {
         return this.change(() => ({ ok: true, wallet, fields: {}, notes: [] }));
     }
@@ -70,6 +73,10 @@ export class JsonWalletStore {
     disconnect() {
         return Promise.resolve();
     }
+    // The backend doesn't record when it began.
+    started() {
+        return Promise.resolve(null);
+    }
     record(purchase, merchant) {
         return this.serialized(async () => {
             const wallet = await this.load();

package/dist/data/wallet-edit.js

@@ -170,6 +170,81 @@ export function setMembershipsText(text, memberships) {
     const cards = root.items.find((p) => keyOf(p) === 'cards');
     return insertLines(text, lineStart(text, range(cards?.key)[0]), line);
 }
+// Point values, one currency at a time so the rest of the file, comments
+// included, stays as it was: a value is replaced in place, a new one goes
+// after the last, a removed one loses its line. An inline map is rewritten.
+export function setValuationsText(text, changes) {
+    let out = text;
+    for (const [id, cents] of Object.entries(changes))
+        out = setValuationText(out, id, cents);
+    return out;
+}
+// The start of the line at `at`, moved up past the comments right above it,
+// so a comment stays with the line it describes.
+function aboveComments(text, at) {
+    let start = lineStart(text, at);
+    while (start > 0) {
+        const previous = lineStart(text, start - 1);
+        if (!text.slice(previous, start).trimStart().startsWith('#'))
+            break;
+        start = previous;
+    }
+    return start;
+}
+function setValuationText(text, id, cents) {
+    const { doc } = cardsSeq(text);
+    const root = doc.contents;
+    if (!isMap(root))
+        throw new Error(`the wallet isn't a map; ${BY_HAND}`);
+    const pair = root.items.find((p) => keyOf(p) === 'valuations');
+    const map = pair?.value;
+    const line = cents === null ? '' : `${id}: ${String(cents)}`;
+    if (!pair || map === null || (isMap(map) && map.items.length === 0)) {
+        if (cents === null)
+            return text;
+        const block = `valuations:\n  ${line}\n`;
+        if (pair) {
+            const start = range(pair.key)[0];
+            const end = afterLine(text, range(map ?? pair.key)[1] - 1);
+            return text.slice(0, start) + block + text.slice(end);
+        }
+        const before = root.items.find((p) => keyOf(p) === 'memberships' || keyOf(p) === 'cards');
+        return insertLines(text, aboveComments(text, range(before?.key)[0]), block);
+    }
+    if (!isMap(map))
+        throw new Error(`"valuations" isn't a map; ${BY_HAND}`);
+    if (map.flow) {
+        const values = Object.entries(map.toJSON()).filter(([k]) => k !== id);
+        if (cents !== null)
+            values.push([id, cents]);
+        const entries = values.map(([k, v]) => `${k}: ${stringify(v, { flow: true }).trimEnd()}`);
+        const start = range(pair.key)[0];
+        const end = afterLine(text, range(map)[1] - 1);
+        return (text.slice(0, start) +
+            (entries.length === 0 ? '' : `valuations: { ${entries.join(', ')} }\n`) +
+            text.slice(end));
+    }
+    const own = map.items.find((p) => keyOf(p) === id);
+    if (own) {
+        if (cents === null) {
+            if (map.items.length === 1) {
+                const start = lineStart(text, range(pair.key)[0]);
+                return (text.slice(0, start) + text.slice(afterLine(text, range(map)[1] - 1)));
+            }
+            const start = lineStart(text, range(own.key)[0]);
+            return (text.slice(0, start) +
+                text.slice(afterLine(text, range(own.value)[1] - 1)));
+        }
+        const [start, end] = range(own.value);
+        return text.slice(0, start) + String(cents) + text.slice(end);
+    }
+    if (cents === null)
+        return text;
+    const first = map.items[0];
+    const last = map.items.at(-1);
+    const indent = ' '.repeat(column(text, range(first?.key)[0]));
+    return insertLines(text, afterLine(text, range(last?.value ?? last?.key)[1] - 1), `${indent}${line}\n`);
+}
 function flowUsage(booking) {
     const period = /^\d+$/.test(booking.period)
         ? `"${booking.period}"`

package/dist/engine/cheat-sheet.js

@@ -1,11 +1,14 @@
 import { resolveMerchantById } from "../merchants/resolve.js";
 import { categoryResolution, exploreCards, } from "./explore.js";
 import { bonusStatus } from "./bonus.js";
+import { EPSILON, isClose } from "./compare.js";
 import { periodKey } from "./periods.js";
 import { recommend } from "./recommend.js";
 import { setupNotes } from "./setup.js";
-import { listed, money, shortDate } from "./text.js";
-const CHEAT_SHEET_ITEMS = [
+import { feeText, listed, money, shortDate } from "./text.js";
+// The everyday kinds of purchase: the cheat sheet's rows and the site's
+// quick picks.
+export const EVERYDAY_PURCHASES = [
     { label: 'Groceries', category: 'grocery.supermarket' },
     { label: 'Dining', category: 'dining' },
     { label: 'Gas', category: 'gas' },
@@ -18,7 +21,7 @@ const CHEAT_SHEET_ITEMS = [
 ];
 // The best card in the wallet for each everyday kind of purchase on `date`,
 // with caps, picks and activations as the wallet has them.
-export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
+export function cheatSheet(catalog, wallet, date, items = EVERYDAY_PURCHASES) {
     const ranked = [];
     const rows = items.map((item) => {
         const merchant = 'merchant' in item
@@ -53,8 +56,8 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
         const name = held.checkout_label ??
             catalog.cards.find((c) => c.id === held.id)?.name ??
             held.id;
-        // Rows where the bonus card matches the row's card, or comes within a
-        // point and three quarters of its rate (as single answers mention it).
+        // Rows where the bonus card matches the row's card, or is close to it
+        // (as single answers mention it).
         const matches = [];
         const near = [];
         for (const { label, cards } of ranked) {
@@ -62,9 +65,9 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
             const own = cards.find((c) => c.cardId === held.id)?.effectiveReturnPct;
             if (best === undefined || own === undefined)
                 continue;
-            if (best - own < 1e-9)
+            if (best - own < EPSILON)
                 matches.push(label.toLowerCase());
-            else if (best - own <= 1 && own >= best * 0.75)
+            else if (isClose(own, best))
                 near.push(label.toLowerCase());
         }
         const where = [
@@ -97,14 +100,12 @@ export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
 // 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 capitalized = (t) => t.charAt(0).toUpperCase() + t.slice(1);
+export function catalogCheatSheet(catalog, date, options, items = EVERYDAY_PURCHASES) {
     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 ??
+                merchant: resolveMerchantById(catalog, item.merchant, null)?.resolvedName ??
                     item.label,
                 category: null,
                 amount: null,
@@ -118,11 +119,7 @@ export function catalogCheatSheet(catalog, date, options, items = CHEAT_SHEET_IT
                 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.`;
+        const fee = top ? `${capitalized(feeText(top))}.` : null;
         return {
             label: item.label,
             cardId: top?.cardId ?? null,

package/dist/engine/compare.js

@@ -0,0 +1,8 @@
+// Returns closer than this are equal: floating-point noise, not a difference.
+export const EPSILON = 1e-9;
+// A card close to the best one: within a percentage point, and at least
+// three quarters of its rate. Answers and cheat sheets mention a welcome
+// bonus card when it's this close.
+export function isClose(own, best) {
+    return best - own <= 1 && own >= best * 0.75;
+}

package/dist/engine/explore.js

@@ -1,13 +1,14 @@
 import { resolveMerchant } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext } from "./evaluate.js";
-import { membershipNeeded, paidMemberships } from "./memberships.js";
+import { membershipName, membershipNeeded, paidMemberships, } from "./memberships.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { recommend } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
 import { membershipsUsed } from "./setup.js";
-import { categoryPhrase, choiceName, codesAs, earnText, membershipName, money, pointValuesText, words, } from "./text.js";
+import { optionName } from "./wallet-summary.js";
+import { CAP_PERIODS, categoryPhrase, choiceName, codesAs, earnText, money, PICK_PERIODS, pointValuesText, } from "./text.js";
 import { cardValuation } from "./valuation.js";
-const EPSILON = 1e-9;
+import { EPSILON } from "./compare.js";
 export const ALL_PERSONAL_CARDS = {
     kind: 'any',
     business: false,
@@ -48,18 +49,6 @@ export function idealHolding(card, date, picks = {}) {
             : {}),
     };
 }
-const PICK_PERIODS = {
-    month: 'set each month',
-    quarter: 'picked each quarter',
-    calendar_year: 'picked each year',
-    until_changed: 'until you change it',
-};
-const CAP_PERIODS = {
-    month: 'a month',
-    quarter: 'a quarter',
-    calendar_year: 'a calendar year',
-    cardmember_year: 'a cardmember year',
-};
 const plainWords = (s) => s
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, ' ')
@@ -148,17 +137,17 @@ function requirementsFor(catalog, card, held, wallet, merchant, purchase) {
             : null,
     };
 }
-function conditionsText(catalog, r) {
+function conditionsText(catalog, card, r) {
     const conditions = [];
     if (r.pick) {
-        conditions.push(`Needs ${r.pick.options.map(words).join(' or ')} as its ${choiceName(r.pick.choice)} pick (${PICK_PERIODS[r.pick.period]}).`);
+        conditions.push(`Needs ${r.pick.options.map((o) => optionName(catalog, card, r.pick?.choice ?? '', o)).join(' or ')} as its ${choiceName(r.pick.choice)} pick (${r.pick.period === 'until_changed' ? '' : 'picked '}${PICK_PERIODS[r.pick.period]}).`);
     }
     if (r.activation !== null)
         conditions.push('Needs its bonus activated with the issuer (free).');
     if (r.membership !== null)
-        conditions.push(`Needs ${membershipName(r.membership)}.`);
+        conditions.push(`With your ${membershipName(catalog, r.membership)}.`);
     if (r.cap) {
-        conditions.push(`Up to ${money(r.cap.amount)} ${CAP_PERIODS[r.cap.period] ?? ''} at this rate, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}.`);
+        conditions.push(`Up to ${money(r.cap.amount)} ${CAP_PERIODS[r.cap.period]} at this rate, then ${earnText(catalog, r.cap.thenRate, r.cap.currency)}.`);
     }
     return conditions;
 }
@@ -243,8 +232,8 @@ export function exploreCards(catalog, query, options, resolved) {
             picks,
             requirements,
             conditions: [
-                ...conditionsText(catalog, requirements),
-                ...membershipNeeded(card, paid),
+                ...conditionsText(catalog, card, requirements),
+                ...membershipNeeded(catalog, card, paid),
             ],
             evidence: evidence ? { quote: evidence.quote, url: evidence.url } : null,
             withMembership: membershipUpgrades(catalog, card, held, merchant, purchase, options, top.effectiveReturnPct),