earnrate 0.2.1 → 0.2.3

package/dist/engine/setup.js

@@ -1,4 +1,4 @@
-import { pickedCategories } from "./evaluate.js";
+import { isActivated, pickedCategories } from "./evaluate.js";
 import { daysBetween } from "./periods.js";
 import { rotationGap } from "./rotation.js";
 // Rules that start within this many days are worth activating now.
@@ -49,7 +49,7 @@ function needsAnniversary(card) {
     return (card.caps.some((c) => c.period === 'cardmember_year') ||
         card.rules.some((r) => typeof r.cap === 'object' && r.cap.period === 'cardmember_year'));
 }
-function activationRules(card, today) {
+export function activationRules(card, today) {
     return card.rules
         .filter((r) => r.requires?.activation === true &&
         (r.valid_to === undefined || r.valid_to >= today) &&
@@ -144,7 +144,7 @@ export function setupNotes(catalog, wallet, held, today) {
             text: `Some of ${name}'s rates need a membership: ${list(missing)}. Add any that apply to the wallet's memberships.`,
         });
     }
-    const toActivate = activationRules(card, today).filter((id) => !held.activated.includes(id));
+    const toActivate = activationRules(card, today).filter((id) => !isActivated(card, held, id));
     if (toActivate.length > 0) {
         notes.push({
             kind: 'activation',

package/dist/engine/wallet-change.js

@@ -1,3 +1,4 @@
+import { capByKey } from "./evaluate.js";
 import { choicePeriod, periodKey } from "./periods.js";
 import { knownMemberships, searchCards, setupNotes, } from "./setup.js";
 const failed = (error) => ({ ok: false, error });
@@ -25,7 +26,9 @@ function pickKey(card, today) {
 export function cardFields(card, held, input, today) {
     const problems = [];
     const fields = {};
-    if (input.checkoutLabel !== undefined) {
+    if (input.checkoutLabel === null)
+        fields.checkout_label = null;
+    else if (input.checkoutLabel !== undefined) {
         if (input.checkoutLabel.trim() === '')
             problems.push('The checkout label is empty.');
         // earnrate never stores card numbers; a last four is fine.
@@ -83,6 +86,34 @@ export function cardFields(card, held, input, today) {
             };
         }
     }
+    if (input.capSpent !== undefined) {
+        const usage = { ...held?.cap_usage };
+        const anniversary = fields.anniversary ?? held?.anniversary ?? null;
+        for (const [key, spent] of Object.entries(input.capSpent)) {
+            const cap = capByKey(card, key);
+            if (!cap) {
+                const keys = [
+                    ...card.caps.map((c) => c.id),
+                    ...card.rules
+                        .filter((r) => typeof r.cap === 'object')
+                        .map((r) => r.id),
+                ];
+                problems.push(keys.length > 0
+                    ? `${card.id} has no cap '${key}'. Its caps are: ${list(keys)}.`
+                    : `${card.id} has no spending caps.`);
+                continue;
+            }
+            if (!(spent >= 0))
+                problems.push('Spending on a cap must be $0 or more.');
+            const period = periodKey(cap.period, today, anniversary);
+            if (period === null) {
+                problems.push(`The '${key}' cap resets on the card's anniversary; give the anniversary (MM-DD) too.`);
+                continue;
+            }
+            usage[key] = { period, spent };
+        }
+        fields.cap_usage = usage;
+    }
     if (input.bonus === null)
         fields.bonus = null;
     else if (input.bonus !== undefined) {
@@ -115,15 +146,17 @@ const newHolding = (id) => ({
     cap_usage: {},
     activated: [],
 });
-const withFields = ({ bonus, ...held }, f) => ({
+const withFields = ({ bonus, checkout_label, ...held }, f) => ({
     ...held,
     ...(bonus && f.bonus === undefined ? { bonus } : {}),
-    ...(f.checkout_label === undefined
-        ? {}
-        : { checkout_label: f.checkout_label }),
+    ...(checkout_label !== undefined && f.checkout_label === undefined
+        ? { checkout_label }
+        : {}),
+    ...(f.checkout_label ? { checkout_label: f.checkout_label } : {}),
     ...(f.anniversary === undefined ? {} : { anniversary: f.anniversary }),
     ...(f.chosen === undefined ? {} : { chosen: f.chosen }),
     ...(f.activated === undefined ? {} : { activated: f.activated }),
+    ...(f.cap_usage === undefined ? {} : { cap_usage: f.cap_usage }),
     ...(f.bonus ? { bonus: f.bonus } : {}),
 });
 // `wallet` is null when there isn't one yet; adding a card starts it.
@@ -175,9 +208,8 @@ export function removeFromWallet(wallet, id) {
     if (!wallet.cards.some((c) => c.id === id)) {
         return failed(`${id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
     }
-    if (wallet.cards.length === 1) {
-        return failed(`${id} is the last card in the wallet, and a wallet needs one. Add the new card first, then remove this one.`);
-    }
+    // Removing the last card leaves an empty wallet, which each store keeps
+    // in its own way (or refuses, for a wallet file).
     return {
         ok: true,
         wallet: { ...wallet, cards: wallet.cards.filter((c) => c.id !== id) },

package/dist/engine/wallet-summary.js

@@ -1,10 +1,98 @@
 import { bonusStatus } from "./bonus.js";
-import { capUsed, pickedCategories } from "./evaluate.js";
+import { activationGroup, capUsed, isActivated, pickedCategories, } from "./evaluate.js";
 import { daysBetween } from "./periods.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
 import { rotationGap } from "./rotation.js";
+import { activationRules } from "./setup.js";
+import { categoryPhrase, earnText } from "./text.js";
 import { cardValuation } from "./valuation.js";
-function capSummaries(card, held, today) {
+const NUMBERS = {
+    one: '1',
+    two: '2',
+    three: '3',
+    four: '4',
+    five: '5',
+    six: '6',
+};
+// "five-percent" reads "5%"; other ids read as words.
+export function choiceName(id) {
+    return id
+        .replace(/\b(one|two|three|four|five|six)-percent\b/g, (_, n) => `${NUMBERS[n] ?? n}%`)
+        .replace(/[-_.]/g, ' ');
+}
+const listed = (parts) => parts.length <= 2
+    ? parts.join(' and ')
+    : `${parts.slice(0, -1).join(', ')} and ${parts.at(-1) ?? ''}`;
+function merchantName(catalog, id) {
+    const all = [...catalog.merchants.overrides, ...catalog.merchants.seed];
+    return all.find((m) => m.id === id)?.name ?? id.replace(/[-_.]/g, ' ');
+}
+function optionName(catalog, card, choiceId, option) {
+    const o = card.choices.find((c) => c.id === choiceId)?.options[option];
+    if (!o)
+        return option.replace(/[-_.]/g, ' ');
+    const parts = [
+        ...o.categories.map((c) => categoryPhrase(catalog, c)),
+        ...o.merchants.map((m) => merchantName(catalog, m)),
+    ];
+    if (o.online)
+        parts.push('online shopping');
+    return parts.length > 0 ? listed(parts) : option.replace(/[-_.]/g, ' ');
+}
+function ruleWhat(catalog, rule) {
+    if (rule.match.choice !== undefined)
+        return `your ${choiceName(rule.match.choice)} picks`;
+    const parts = [
+        ...(rule.match.categories ?? []).map((c) => categoryPhrase(catalog, c)),
+        ...(rule.match.merchants ?? []).map((m) => merchantName(catalog, m)),
+    ];
+    return parts.length > 0 ? listed(parts) : rule.id.replace(/[-_.]/g, ' ');
+}
+function periodEnd(period) {
+    const quarter = /^(\d{4})-Q([1-4])$/.exec(period);
+    if (quarter) {
+        const end = ['03-31', '06-30', '09-30', '12-31'][Number(quarter[2]) - 1];
+        return `${quarter[1] ?? ''}-${end ?? ''}`;
+    }
+    const month = /^(\d{4})-(\d{2})$/.exec(period);
+    if (month) {
+        const last = new Date(Date.UTC(Number(month[1]), Number(month[2]), 0));
+        return last.toISOString().slice(0, 10);
+    }
+    return /^\d{4}$/.test(period) ? `${period}-12-31` : null;
+}
+const applies = (rule, today) => (rule.valid_from === undefined || rule.valid_from <= today) &&
+    (rule.valid_to === undefined || rule.valid_to >= today);
+function headlineRates(catalog, card, currency, today) {
+    const best = card.rules
+        .filter((r) => applies(r, today) && r.rate > card.base_rate)
+        .sort((a, b) => b.rate - a.rate)
+        .slice(0, 4)
+        .map((r) => `${earnText(catalog, r.rate, currency)} on ${ruleWhat(catalog, r)}${r.requires?.activation ? ' (once activated)' : ''}`);
+    return [
+        ...best,
+        `${earnText(catalog, card.base_rate, currency)} on everything else`,
+    ];
+}
+function toActivate(catalog, card, held, today) {
+    const seen = new Set();
+    const out = [];
+    for (const id of activationRules(card, today)) {
+        if (seen.has(id) || isActivated(card, held, id))
+            continue;
+        const group = activationGroup(card, id);
+        for (const g of group)
+            seen.add(g);
+        const rules = card.rules.filter((r) => group.includes(r.id));
+        const first = rules[0];
+        const when = first?.valid_from !== undefined && first.valid_to !== undefined
+            ? ` (${first.valid_from} to ${first.valid_to})`
+            : '';
+        out.push(`${rules.map((r) => ruleWhat(catalog, r)).join(', ')}${when}`);
+    }
+    return out;
+}
+function capSummaries(catalog, card, held, today) {
     const caps = new Map();
     for (const shared of card.caps)
         caps.set(shared.id, { cap: shared, rules: [] });
@@ -20,8 +108,15 @@ function capSummaries(card, held, today) {
     }
     return [...caps].map(([key, { cap, rules }]) => {
         const { period: currentPeriod, spent } = capUsed(cap, key, held, today);
+        const covered = card.rules.filter((r) => rules.includes(r.id));
+        const shared = card.caps.find((c) => c.id === key);
+        const label = shared?.rotating
+            ? 'the rotating bonus categories'
+            : [...new Set(covered.map((r) => ruleWhat(catalog, r)))].join(', ') ||
+                key.replace(/[-_.]/g, ' ');
         return {
             key,
+            label,
             rules,
             amount: cap.amount,
             period: cap.period,
@@ -52,15 +147,22 @@ export function walletSummary(catalog, wallet, today) {
             verifiedBy: card.verified_by,
             dataIsStale: daysBetween(card.last_verified, today) > STALE_AFTER_DAYS,
             rotationGap: rotationGap(card, today),
-            caps: capSummaries(card, held, today),
+            caps: capSummaries(catalog, card, held, today),
             chosen: held.chosen
                 ? {
                     period: held.chosen.period,
                     current: pickedCategories(card, held, today).staleChoice === null,
+                    until: periodEnd(held.chosen.period),
                     picks: held.chosen.picks,
+                    pickNames: Object.fromEntries(Object.entries(held.chosen.picks).map(([choice, options]) => [
+                        choiceName(choice),
+                        options.map((o) => optionName(catalog, card, choice, o)),
+                    ])),
                 }
                 : null,
+            rates: headlineRates(catalog, card, valuation.currency, today),
             activated: held.activated,
+            toActivate: toActivate(catalog, card, held, today),
             anniversary: held.anniversary ?? null,
         });
     }

package/dist/format/offers.js

@@ -1,10 +1,17 @@
 import { feeText, money } from "../engine/text.js";
 const TOP = 10;
 function reward(o, currencyName) {
-    if (o.dollars !== null)
-        return money(o.dollars);
-    return `${(o.points ?? 0).toLocaleString('en-US')} ${currencyName}`;
+    const amount = o.dollars !== null
+        ? money(o.dollars)
+        : `${(o.points ?? 0).toLocaleString('en-US')} ${currencyName}`;
+    return o.varies ? `Up to ${amount}` : amount;
 }
+const asOf = (date) => new Date(`${date}T12:00:00Z`).toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+    timeZone: 'UTC',
+});
 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`;
@@ -19,8 +26,7 @@ export function formatOffers(c, currencyName, all) {
             ? `after ${money(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 ${money(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}.`);
+        lines.push(`    ${o.validTo ? `Offer ends ${o.validTo}. ` : ''}Public offer as of ${asOf(o.lastVerified)}; yours may differ.`);
         if (o.note)
             lines.push(`    ${o.note}`);
     });

package/dist/format/wallet.js

@@ -1,26 +1,55 @@
 import { money } from "../engine/text.js";
+const NETWORKS = {
+    visa: 'Visa',
+    mastercard: 'Mastercard',
+    amex: 'American Express',
+    discover: 'Discover',
+    store: 'store card',
+};
+const day = (date) => new Date(`${date}T12:00:00Z`).toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+    timeZone: 'UTC',
+});
 export function formatWalletSummary(summary) {
-    return summary.cards
-        .map((c) => {
-        const caps = c.caps
-            .filter((cap) => cap.remaining !== null)
-            .map((cap) => `${cap.key} ${money(cap.spent)} of ${money(cap.amount)} used for ${cap.currentPeriod ?? ''}`);
-        const chosen = c.chosen
-            ? `; chosen categories for ${c.chosen.period}${c.chosen.current ? '' : ' (out of date)'}`
+    const cards = summary.cards.map((c) => {
+        const label = c.checkoutLabel
+            ? `, shown at checkout as "${c.checkoutLabel}"`
             : '';
-        const onlyAt = c.onlyAt ? `; works only at ${c.onlyAt.join(', ')}` : '';
-        const rotation = c.rotationGap === null
-            ? ''
-            : `; rotating categories for ${c.rotationGap} not in earnrate yet`;
+        const lines = [
+            `- ${c.cardName} (${c.cardId})${label}: ${NETWORKS[c.network] ?? c.network}, ${c.currency} at ${String(c.centsPerUnit)}¢. Data checked ${c.lastVerified}${c.dataIsStale ? ' (old; check the issuer)' : ''}.`,
+            `  Earns: ${c.rates.join('; ')}.`,
+        ];
+        if (c.onlyAt)
+            lines.push(`  Works only at ${c.onlyAt.join(', ')}.`);
+        if (c.chosen) {
+            const picks = Object.entries(c.chosen.pickNames)
+                .map(([choice, names]) => `${choice}: ${names.join(', ')}`)
+                .join('; ');
+            const until = c.chosen.until ? `, through ${day(c.chosen.until)}` : '';
+            lines.push(c.chosen.current
+                ? `  Picks for ${c.chosen.period}${until}: ${picks}. Pick again after that.`
+                : `  Picks are for ${c.chosen.period}, which is over: ask for this period's picks.`);
+        }
+        if (c.toActivate.length > 0)
+            lines.push(`  Not activated yet: ${c.toActivate.join('; ')}. Activating once with the issuer covers each group.`);
+        if (c.rotationGap !== null)
+            lines.push(`  Rotating categories for ${c.rotationGap} aren't in earnrate yet.`);
+        for (const cap of c.caps)
+            if (cap.remaining !== null)
+                lines.push(`  Cap on ${cap.label}: ${money(cap.spent)} of ${money(cap.amount)} used for ${cap.currentPeriod ?? ''} (cap key ${cap.key}).`);
         const b = c.bonus;
-        const bonus = b?.state === 'open' && b.spend !== null
-            ? `; welcome bonus ${money(b.spent)} of ${money(b.spend)} spent, due ${b.deadline ?? ''}`
-            : b
-                ? `; welcome bonus ${b.state}`
-                : '';
-        return `- ${c.checkoutLabel ?? c.cardName} (${c.cardId}): ${c.currency} at ${String(c.centsPerUnit)}¢${caps.length > 0 ? `; ${caps.join(', ')}` : ''}${chosen}${rotation}${onlyAt}${bonus}`;
-    })
-        .join('\n');
+        if (b?.state === 'open' && b.spend !== null)
+            lines.push(`  Welcome bonus: ${money(b.spent)} of ${money(b.spend)} spent, due ${b.deadline ?? ''}.`);
+        else if (b)
+            lines.push(`  Welcome bonus: ${b.state}.`);
+        return lines.join('\n');
+    });
+    const memberships = summary.memberships.length > 0
+        ? `Memberships: ${summary.memberships.join(', ')}.`
+        : 'Memberships: none saved.';
+    return [...cards, memberships].join('\n');
 }
 export function formatBooking(amount, cardId, cap, bonus) {
     const messages = [];

package/dist/mcp/context.js

@@ -7,7 +7,7 @@ export const fail = (text) => ({
     content: [{ type: 'text', text }],
     isError: true,
 });
-export const ALL_CARDS_NOTE = "The user hasn't named their cards, so this covers every card earnrate knows. That's a complete answer. If they want the best of their own cards, they can name them (pass them as `cards`); saving a wallet is optional.";
+export const ALL_CARDS_NOTE = "No cards are saved or named, so this covers every card earnrate knows. That's a complete answer. If the user wants the best of their own cards, they can name them (pass them as `cards`); saving them is optional.";
 // What every tool shares: the saved wallet, merchant resolution, and which
 // cards an answer is about.
 export function makeContext(deps) {
@@ -15,7 +15,9 @@ export function makeContext(deps) {
     const theWallet = deps.savedWallets === 'file'
         ? `the wallet at ${deps.store.where}`
         : 'the saved wallet';
-    const noWallet = `There's no saved wallet yet${deps.savedWallets === 'file' ? ` (${deps.store.where})` : ''}. Answers don't need one: they cover every card, or the cards the user names. If the user wants their cards remembered, find each with search_cards and save it with add_card.`;
+    const noWallet = deps.savedWallets === 'file'
+        ? `There's no saved wallet yet (${deps.store.where}). Answers don't need one: they cover every card, or the cards the user names. If the user wants their cards remembered, find each with search_cards and save it with add_card.`
+        : "The user's saved wallet has no cards yet. Answers cover every card, or the cards the user names. If the user wants their cards remembered, find each with search_cards and save it with add_card.";
     // Read on every call, so edits to the wallet apply without a restart.
     async function wallet() {
         let loaded;
@@ -79,7 +81,9 @@ export function makeContext(deps) {
         };
         const text = [
             message,
-            `Wallet: ${output.cardIds.join(', ')}.`,
+            output.cardIds.length > 0
+                ? `Wallet: ${output.cardIds.join(', ')}.`
+                : 'The wallet has no cards now; answers cover every card.',
             ...(notes ? [formatNotes(result.notes)] : []),
         ].join('\n');
         return {

package/dist/mcp/inputs.js

@@ -46,8 +46,9 @@ const cardFields = {
     checkoutLabel: z
         .string()
         .min(1)
+        .nullable()
         .optional()
-        .describe('How the card appears at checkout or in a browser wallet, e.g. "Amex Gold". Optional.'),
+        .describe('How the card appears at checkout or in a browser wallet, e.g. "Amex Gold". Optional; null goes back to the card\'s own name.'),
     picks: z
         .record(z.string(), z.array(z.string()).min(1))
         .optional()
@@ -61,6 +62,10 @@ const cardFields = {
         .array(z.string())
         .optional()
         .describe('Rule ids the user has activated with the issuer, such as rotating categories. Replaces the current list.'),
+    capSpent: z
+        .record(z.string(), z.number().nonnegative())
+        .optional()
+        .describe('Dollars already spent this period on a capped bonus, for a card the user starts tracking partway through: cap key (as list_wallet shows it) → dollars, e.g. {"five-percent-quarterly": 400}. Ask; recorded purchases add to it from then on.'),
     bonus: z
         .object({
         opened: IsoDate.describe('The day the account opened, YYYY-MM-DD.'),
@@ -95,10 +100,12 @@ export function cardInput({ cardId, bonus, ...rest }) {
 }
 // Inputs that list the catalog's categories, issuers and memberships.
 export function makeInputs(catalog) {
-    const categoryIds = catalog.categories.map((c) => c.id);
-    const categoryList = catalog.categories
-        .map((c) => `${c.id} (${c.name})`)
-        .join(', ');
+    // A parent with subcategories and no merchant codes of its own ("Grocery")
+    // isn't something a purchase codes as, so it's left out.
+    const categories = catalog.categories.filter((c) => c.mccs.length > 0 ||
+        !catalog.categories.some((k) => k.id.startsWith(`${c.id}.`)));
+    const categoryIds = categories.map((c) => c.id);
+    const categoryList = categories.map((c) => `${c.id} (${c.name})`).join(', ');
     const membershipIds = knownMemberships(catalog);
     const issuers = [...new Set(catalog.cards.map((c) => c.issuer))].sort();
     const CategoryInput = z

package/dist/mcp/schemas.js

@@ -106,6 +106,7 @@ export const WalletSummarySchema = z.object({
         rotationGap: z.string().nullable(),
         caps: z.array(z.object({
             key: z.string(),
+            label: z.string(),
             rules: z.array(z.string()),
             amount: z.number(),
             period: CapPeriod,
@@ -117,10 +118,14 @@ export const WalletSummarySchema = z.object({
             .object({
             period: z.string(),
             current: z.boolean(),
+            until: z.string().nullable(),
             picks: z.record(z.string(), z.array(z.string())),
+            pickNames: z.record(z.string(), z.array(z.string())),
         })
             .nullable(),
+        rates: z.array(z.string()),
         activated: z.array(z.string()),
+        toActivate: z.array(z.string()),
         anniversary: z.string().nullable(),
     })),
 });
@@ -161,6 +166,7 @@ export const OfferComparisonSchema = z.object({
         spend: z.number(),
         months: z.number(),
         validTo: z.string().nullable(),
+        varies: z.boolean(), // the amount is the most the issuer shows
         note: z.string().nullable(),
         annualFee: z.number().nullable(),
         firstYearFee: z.number().nullable(),

package/dist/mcp/server.js

@@ -15,8 +15,7 @@ export const ANSWER_TOOLS = [
     'resolve_merchant',
     'search_cards',
 ];
-// The tools that read or change a saved wallet. The hosted server asks for
-// sign-in before running one.
+// The tools that read or change a saved wallet.
 export const SAVED_WALLET_TOOLS = [
     'list_wallet',
     'record_purchase',
@@ -27,14 +26,15 @@ export const SAVED_WALLET_TOOLS = [
     'export_wallet',
     'import_wallet',
     'delete_wallet',
+    'switch_wallet',
 ];
 const SAVING = {
     file: 'Only if they want earnrate to remember their cards, track spending caps or welcome bonuses, or record purchases, save a wallet with add_card and the other wallet tools.',
-    account: "Only if they want earnrate to remember their cards, track spending caps or welcome bonuses, or record purchases, save a wallet with add_card and the other wallet tools. Saved wallets are anonymous: the first wallet tool asks the user to open an earnrate page, where they start a wallet (it shows a recovery code to keep; no email or name) or reconnect one with their code. Never ask for the recovery code in the conversation; it's typed only on that page. To change the code, the user opens https://mcp.earnrate.dev/change-code.",
+    account: "The user signed in to earnrate when they connected it, to an anonymous saved wallet (no email or name). It may have no cards yet; answers then cover every card. Save cards with add_card only when the user agrees. The wallet can change outside this conversation when the user signs in again on earnrate's page, so read it with list_wallet rather than from memory. To use a different wallet or start a new one, call switch_wallet; the user then connects on earnrate's page with that wallet's recovery code. Never ask for the recovery code in the conversation; it's typed only on earnrate's page. To change the code, the user opens https://mcp.earnrate.dev/change-code. earnrate.dev and the earnrate command line keep their own separate wallets; export_wallet and import_wallet move one between them.",
 };
 const instructions = (savedWallets) => `earnrate answers which credit card earns the most for a purchase, from each issuer's own terms. Anyone can use it without entering anything: with no cards given, best_card_for_purchase, best_cards_for, cheat_sheet, simulate_spending and compare_welcome_offers answer from every card earnrate knows, and that's a complete answer. Never require the user's cards, and don't ask what they spend unless the answer depends on it; simulate_spending assumes typical amounts when none are given and says so.
 
-Personalizing is optional. If the user names their cards, pass them as \`cards\` (ids from search_cards) for that answer; nothing is saved. ${SAVING[savedWallets]} When a card needs category picks, memberships like Amazon Prime, or activations, ask the user rather than guessing.
+Personalizing is optional. If the user names their cards, pass them as \`cards\` (ids from search_cards) for that answer; nothing is saved. After answering, offer once to save those cards so earnrate remembers them, and save them with add_card only if the user says yes. ${SAVING[savedWallets]} When a card needs category picks, memberships like Amazon Prime, or activations, ask the user rather than guessing.
 
 The wallet lists cards by product id, never card numbers; never ask for card numbers, expiry dates or security codes.`;
 export function createEarnrateServer(deps) {

package/dist/mcp/tools/account.js

@@ -23,13 +23,17 @@ export function registerAccountTools(server, catalog, store, ctx) {
     });
     server.registerTool('import_wallet', {
         title: 'Import a wallet',
-        description: 'Replaces the saved wallet with a wallet.yaml from the earnrate command line or earnrate.dev, when the user pastes or attaches one. Wallet files only: never statements or card numbers. Confirm with the user first if they already have cards saved.',
+        description: 'Replaces the saved wallet with a wallet.yaml from the earnrate command line or earnrate.dev, when the user pastes or attaches one. Wallet files only: never statements or card numbers. If cards are already saved, it refuses unless replace is true: confirm with the user first.',
         inputSchema: z.object({
             yaml: z
                 .string()
                 .min(1)
                 .max(100_000)
                 .describe('The wallet.yaml text, as the user gave it.'),
+            replace: z
+                .boolean()
+                .optional()
+                .describe('true to replace a wallet that already has cards, after the user confirms.'),
         }),
         outputSchema: WalletChangeSchema,
         annotations: {
@@ -38,17 +42,24 @@ export function registerAccountTools(server, catalog, store, ctx) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ yaml }) => {
+    }, async ({ yaml, replace }) => {
         const parsed = parseWalletYaml(yaml, catalog);
         if (typeof parsed === 'string')
             return fail(parsed);
+        const current = await store.load().catch(() => null);
+        if (current !== null && current.cards.length > 0 && replace !== true)
+            return fail(`This would replace the ${String(current.cards.length)} ${current.cards.length === 1 ? 'card' : 'cards'} already saved (${current.cards.map((c) => c.id).join(', ')}). Ask the user, then call again with replace: true.`);
         const count = parsed.cards.length;
         return ctx.changed(await store.replace(parsed), `Imported a wallet with ${String(count)} ${count === 1 ? 'card' : 'cards'}.`, { notes: false });
     });
     server.registerTool('delete_wallet', {
         title: 'Delete the wallet',
-        description: 'Deletes the saved wallet now and for good, and signs out every app using it. Only when the user asks to delete it; confirm first, and offer export_wallet to keep a copy.',
-        inputSchema: z.object({}),
+        description: "Deletes the saved wallet and its recovery code now and for good, and signs out every Claude app connected to it, this one included. earnrate.dev and the earnrate command line keep their own wallets and aren't affected. Only when the user asks to delete it: offer export_wallet first, and pass confirm only after the user confirms. It refuses when the wallet has no cards, since there's nothing to delete.",
+        inputSchema: z.object({
+            confirm: z
+                .literal(true)
+                .describe('true, only after the user confirms the deletion.'),
+        }),
         outputSchema: z.object({ deleted: z.boolean() }),
         annotations: {
             readOnlyHint: false,
@@ -57,15 +68,41 @@ export function registerAccountTools(server, catalog, store, ctx) {
             openWorldHint: false,
         },
     }, async () => {
+        const current = await store.load().catch(() => null);
+        if (current === null || current.cards.length === 0)
+            return fail("This saved wallet has no cards, so there's nothing to delete. If the user meant a different wallet, it may already be deleted.");
         await store.erase();
         return {
             content: [
                 {
                     type: 'text',
-                    text: 'Deleted the saved wallet. Answers now cover every card, or the cards named in the conversation.',
+                    text: "Deleted the saved wallet and its recovery code, and signed out every Claude app connected to it, this one included. To keep using earnrate here, the user connects again on earnrate's page and starts a new wallet.",
                 },
             ],
             structuredContent: { deleted: true },
         };
     });
+    server.registerTool('switch_wallet', {
+        title: 'Switch wallets',
+        description: "Disconnects this app from its saved wallet so the user can connect a different one with its recovery code, or start a new one, on earnrate's page. Nothing is deleted. Use it when the user wants another wallet. Never ask for the recovery code in the conversation.",
+        inputSchema: z.object({}),
+        outputSchema: z.object({ disconnected: z.boolean() }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        await store.disconnect();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: "Disconnected from this saved wallet; nothing was deleted. earnrate's sign-in page opens on the next earnrate request (or reconnect earnrate in the app's connector settings). There the user chooses \"Already have a wallet?\" and types the other wallet's recovery code, or starts a new wallet. Other Claude accounts connected to this wallet through the same app are signed out too.",
+                },
+            ],
+            structuredContent: { disconnected: true },
+        };
+    });
 }

package/dist/mcp/tools/answers.js

@@ -125,6 +125,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
         description: "Ranks the public welcome (sign-up) offers on cards the user doesn't have by first-year value: the bonus at the user's point values minus the first year's annual fee. Use it when the user asks which new card to get or which has the best sign-up bonus. It covers only the cards earnrate knows, offers vary by person, and each offer's note gives the issuer's eligibility rules; pass those caveats on. It doesn't account for what a card would earn on the user's spending.",
         inputSchema: z.object({
             ...OfferFilters,
+            valuation: CatalogFilters.valuation,
             includeHeld: z
                 .boolean()
                 .optional()
@@ -137,7 +138,8 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
         const wallet = await ctx.cardsFor(args.cards, undefined);
         if (typeof wallet === 'string')
             return fail(wallet);
-        const comparison = compareOffers(catalog, wallet ?? EMPTY_WALLET, {
+        const base = wallet ?? EMPTY_WALLET;
+        const comparison = compareOffers(catalog, args.valuation ? withValuationProfile(base, args.valuation) : base, {
             kind: args.kind ?? 'any',
             noAnnualFee: args.noAnnualFee ?? false,
             business: args.business ?? false,
@@ -273,11 +275,16 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
     });
     server.registerTool('cheat_sheet', {
         title: 'Cheat sheet',
-        description: "The card to use for each everyday kind of purchase right now: groceries, dining, gas, Amazon, Costco, travel, streaming, drugstores and everything else. With no cards given and no saved wallet, it picks from every card earnrate knows (`scope: all cards`, each row noting the card's fee and conditions). With cards named in the conversation or a saved wallet, it picks from the user's own cards, with caps, picks and activations as they are. For one specific store, call best_card_for_purchase instead. Pass on the notes.",
+        description: "The card to use for each everyday kind of purchase right now: groceries, dining, gas, Amazon, Costco, travel, streaming, drugstores and everything else. With no cards given and no saved wallet, it picks from every card earnrate knows (`scope: all cards`, each row noting the card's fee and conditions). With cards named in the conversation or a saved wallet, it picks from the user's own cards, with caps, picks and activations as they are. The kind, noAnnualFee, business and issuer filters apply only when it picks from every card. For one specific store, call best_card_for_purchase instead. Pass on the notes.",
         inputSchema: z.object({
             date: DateInput,
             cards: NamedCards,
             memberships: NamedMemberships,
+            kind: CatalogFilters.kind,
+            noAnnualFee: CatalogFilters.noAnnualFee,
+            business: CatalogFilters.business,
+            issuer: CatalogFilters.issuer,
+            valuation: CatalogFilters.valuation,
         }),
         outputSchema: CheatSheetSchema,
         annotations: { readOnlyHint: true, openWorldHint: false },
@@ -288,10 +295,12 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
         const date = args.date ?? deps.today();
         const sheet = wallet === null
             ? {
-                ...catalogCheatSheet(catalog, date, settings({ memberships: args.memberships })),
+                ...catalogCheatSheet(catalog, date, settings(args)),
                 notes: [ALL_CARDS_NOTE],
             }
-            : cheatSheet(catalog, wallet, date);
+            : cheatSheet(catalog, args.valuation
+                ? withValuationProfile(wallet, args.valuation)
+                : wallet, date);
         return {
             content: [{ type: 'text', text: formatCheatSheet(sheet) }],
             structuredContent: sheet,

package/dist/schema/card.js

@@ -75,6 +75,10 @@ export const WelcomeOfferSchema = z
     spend: z.number().nonnegative(), // dollars of purchases required
     months: z.number().int().positive(), // from account opening
     valid_to: IsoDate.optional(), // when the issuer says the offer ends
+    // The issuer shows each applicant their own amount ("as high as"), or
+    // the page showed different offers on different visits. The amount
+    // above is then the most it shows.
+    varies: z.literal(true).optional(),
     note: z.string().optional(),
 })
     .refine((o) => (o.points === undefined) !== (o.dollars === undefined), 'a welcome offer needs points or dollars, not both');