earnrate 0.2.5 → 0.2.6

package/dist/mcp/tools/account.js

@@ -1,16 +1,33 @@
 import { z } from 'zod';
+import { emptyWallet } from "../../data/store.js";
 import { parseWalletYaml, walletYaml } from "../../format/wallet-yaml.js";
+import { listed } from "../../engine/text.js";
+import { savedSettingsText } from "../../engine/wallet-summary.js";
 import { fail } from "../context.js";
 import { WalletChangeSchema } from "../schemas.js";
 // A saved wallet on the hosted server has no file to copy or delete, so
 // these do it.
 export function registerAccountTools(server, catalog, store, ctx) {
+    const cardsText = (n) => `${String(n)} ${n === 1 ? 'card' : 'cards'}`;
+    // Everything a saved wallet holds, in words; empty when there's nothing.
+    const contents = (w) => [
+        ...(w.cards.length > 0
+            ? [
+                `${cardsText(w.cards.length)} (${w.cards.map((c) => c.id).join(', ')})`,
+            ]
+            : []),
+        ...savedSettingsText(catalog, w),
+    ];
     server.registerTool('export_wallet', {
         title: 'Export the wallet',
         description: 'The saved wallet as a wallet.yaml file the earnrate command line and earnrate.dev can import: card ids, picks, activations, memberships, point values, cap usage and bonus progress. Never card numbers.',
         inputSchema: z.object({}),
         outputSchema: z.object({ yaml: z.string() }),
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'Export the wallet',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async () => {
         const w = await ctx.wallet();
         if (typeof w === 'string')
@@ -23,7 +40,7 @@ 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. If cards are already saved, it refuses unless replace is true: confirm with the user first.',
+        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 anything is already saved (cards, memberships or point values), it refuses unless replace is true: confirm with the user first.',
         inputSchema: z.object({
             yaml: z
                 .string()
@@ -33,10 +50,11 @@ export function registerAccountTools(server, catalog, store, ctx) {
             replace: z
                 .boolean()
                 .optional()
-                .describe('true to replace a wallet that already has cards, after the user confirms.'),
+                .describe('true to replace what the wallet already holds, after the user confirms.'),
         }),
         outputSchema: WalletChangeSchema,
         annotations: {
+            title: 'Import a wallet',
             readOnlyHint: false,
             destructiveHint: true,
             idempotentHint: true,
@@ -55,17 +73,16 @@ export function registerAccountTools(server, catalog, store, ctx) {
                 return fail(`Couldn't read the saved wallet to check what it holds (${e instanceof Error ? e.message : String(e)}). Ask the user, then call again with replace: true to overwrite it.`);
             current = 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 cards = (n) => `${String(n)} ${n === 1 ? 'card' : 'cards'}`;
-        const before = current?.cards.length ?? 0;
-        return ctx.changed(await store.replace(parsed), before > 0
-            ? `Replaced the ${cards(before)} that were saved with the ${cards(parsed.cards.length)} imported.`
-            : `Imported a wallet with ${cards(parsed.cards.length)}.`, { notes: false });
+        const before = current === null ? [] : contents(current);
+        if (before.length > 0 && replace !== true)
+            return fail(`This would replace what's saved: ${listed(before)}. Ask the user, then call again with replace: true.`);
+        return ctx.changed(await store.replace(parsed), before.length > 0
+            ? `Replaced what was saved (${listed(before)}) with the imported wallet: ${listed(contents(parsed))}.`
+            : `Imported a wallet with ${listed(contents(parsed)) || 'nothing in it'}.`, { notes: false });
     });
     server.registerTool('delete_wallet', {
         title: 'Delete the wallet',
-        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: show it with list_wallet, offer export_wallet, and pass confirm and cards only after the user confirms. It refuses if the wallet no longer holds that many cards, so a retried call can't delete a different wallet.",
+        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: show it with list_wallet, offer export_wallet, and pass confirm, cards and saved only after the user confirms. It refuses if the wallet no longer holds what list_wallet showed, so a retried call can't delete a different wallet.",
         inputSchema: z.object({
             confirm: z
                 .literal(true)
@@ -75,20 +92,30 @@ export function registerAccountTools(server, catalog, store, ctx) {
                 .int()
                 .nonnegative()
                 .describe('How many cards the wallet held when the user confirmed, from list_wallet: 0 for an empty wallet.'),
+            saved: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe('How many memberships and point values list_wallet showed, counted together: 0 if none.'),
         }),
         outputSchema: z.object({ deleted: z.boolean() }),
         annotations: {
+            title: 'Delete the wallet',
             readOnlyHint: false,
             destructiveHint: true,
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ cards }) => {
+    }, async ({ cards, saved }) => {
         // An unreadable wallet can still be deleted: the user confirmed it.
-        const current = await store.load().catch(() => undefined);
-        const held = current === undefined ? cards : (current?.cards.length ?? 0);
-        if (held !== cards)
-            return fail(`This saved wallet holds ${String(held)} ${held === 1 ? 'card' : 'cards'}, not ${String(cards)}, so it isn't the wallet the user confirmed (it may have been deleted and a new one connected). Show it with list_wallet and confirm again.`);
+        const loaded = await store.load().catch(() => undefined);
+        if (loaded !== undefined) {
+            const current = loaded ?? emptyWallet();
+            const settings = savedSettingsText(catalog, current);
+            if (current.cards.length !== cards || settings.length !== (saved ?? 0))
+                return fail(`This saved wallet holds ${listed(contents(current)) || 'nothing'}, not what the user confirmed (${cardsText(cards)}${saved === undefined ? '' : ` and ${String(saved)} memberships and point values`}); it may have changed, or be a different wallet. Show it with list_wallet, confirm again, and pass cards: ${String(current.cards.length)} and saved: ${String(settings.length)}.`);
+        }
         await store.erase();
         return {
             content: [
@@ -106,6 +133,7 @@ export function registerAccountTools(server, catalog, store, ctx) {
         inputSchema: z.object({}),
         outputSchema: z.object({ disconnected: z.boolean() }),
         annotations: {
+            title: 'Switch wallets',
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: true,

package/dist/mcp/tools/answers.js

@@ -13,6 +13,7 @@ import { formatCheatSheet } from "../../format/cheat-sheet.js";
 import { formatAdditions, formatCatalogSimulation, formatExploration, } from "../../format/explore.js";
 import { formatOffers } from "../../format/offers.js";
 import { formatRecommendation } from "../../format/recommendation.js";
+import { resolvePlace, withCallerCategory } from "../../merchants/resolve.js";
 import { ALL_CARDS_NOTE, fail } from "../context.js";
 import { ChannelInput, DateInput, Merchant, settings, } from "../inputs.js";
 import { CardSearchSchema, CheatSheetSchema, ExplorationSchema, MerchantResolutionSchema, OfferComparisonSchema, PurchaseAnswerSchema, SpendingSimulationSchema, } from "../schemas.js";
@@ -46,16 +47,21 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             category: CategoryInput,
             cards: NamedCards,
             memberships: NamedMemberships,
+            valuation: CatalogFilters.valuation,
         }),
         outputSchema: PurchaseAnswerSchema,
         annotations: {
+            title: 'Best card for a purchase',
             readOnlyHint: true,
             openWorldHint: deps.llm !== null,
         },
-    }, async ({ merchant, amount, channel, date, category, cards, memberships, }) => {
-        const wallet = await ctx.cardsFor(cards, memberships);
-        if (typeof wallet === 'string')
-            return fail(wallet);
+    }, async ({ merchant, amount, channel, date, category, cards, memberships, valuation, }) => {
+        const held = await ctx.cardsFor(cards, memberships);
+        if (typeof held === 'string')
+            return fail(held);
+        const wallet = held !== null && valuation
+            ? withValuationProfile(held, valuation)
+            : held;
         const purchase = {
             merchant,
             amount: amount ?? null,
@@ -74,7 +80,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 amount: purchase.amount,
                 channel: purchase.channel,
                 date: purchase.date,
-            }, settings({ memberships }, await ctx.saved()), resolved.merchant);
+            }, settings({ memberships, valuation }, await ctx.saved()), resolved.merchant);
             const allCards = { ...explored, ranked: explored.ranked.slice(0, TOP) };
             const empty = recommend(catalog, EMPTY_WALLET, purchase, resolved.merchant);
             return {
@@ -101,7 +107,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             content: [
                 {
                     type: 'text',
-                    text: `${retry}${formatRecommendation(output, purchase, { all: true })}`,
+                    text: `${retry}${ctx.fromCards(cards)}${formatRecommendation(output, purchase, { all: true })}`,
                 },
             ],
             structuredContent: output,
@@ -116,7 +122,11 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             category: CategoryInput,
         }),
         outputSchema: MerchantResolutionSchema,
-        annotations: { readOnlyHint: true, openWorldHint: deps.llm !== null },
+        annotations: {
+            title: 'Resolve a merchant',
+            readOnlyHint: true,
+            openWorldHint: deps.llm !== null,
+        },
     }, async ({ merchant, channel, category }) => {
         const resolved = await ctx.resolve(merchant, channel ?? null, category ?? null);
         const m = resolved.merchant;
@@ -151,7 +161,11 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             cards: NamedCards,
         }),
         outputSchema: OfferComparisonSchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'Compare welcome offers',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async (args) => {
         const wallet = await ctx.cardsFor(args.cards, undefined);
         if (typeof wallet === 'string')
@@ -174,7 +188,8 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             content: [
                 {
                     type: 'text',
-                    text: formatOffers(trimmed, (id) => currencyName(catalog, id), true) +
+                    text: (wallet === null ? '' : ctx.fromCards(args.cards)) +
+                        formatOffers(trimmed, (id) => currencyName(catalog, id), true) +
                         (more > 0
                             ? `\nThe top ${String(TOP)} of ${String(comparison.offers.length)} offers${trimmed.offers.length > TOP ? `, plus ${String(trimmed.offers.length - TOP)} likely not eligible` : ''}. Narrow them with kind, noAnnualFee or business.\n`
                             : ''),
@@ -185,7 +200,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
     });
     server.registerTool('best_cards_for', {
         title: 'Best cards for a purchase',
-        description: 'Ranks every card earnrate knows, not only the user\'s, for one purchase or category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Use it for questions like "what\'s the best card for groceries?" or "which card should I get for Amazon?". It needs no wallet. For which of the user\'s own cards to use, call best_card_for_purchase instead. Mention the annual fee and any conditions alongside each card.',
+        description: 'Ranks every card earnrate knows that takes new applicants, not only the user\'s, for one purchase or category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Use it for questions like "what\'s the best card for groceries?" or "which card should I get for Amazon?". It needs no wallet. For which of the user\'s own cards to use, call best_card_for_purchase instead. Mention the annual fee and any conditions alongside each card.',
         inputSchema: z.object({
             merchant: Merchant.optional(),
             category: CatalogCategory.optional(),
@@ -198,17 +213,24 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             ...CatalogFilters,
         }),
         outputSchema: ExplorationSchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'Best cards for a purchase',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async (args) => {
         if (args.merchant === undefined && args.category === undefined)
             return fail('Give a merchant or a category.');
+        const channel = args.channel ?? null;
         const result = exploreCards(catalog, {
             merchant: args.merchant ?? null,
-            category: args.merchant === undefined ? (args.category ?? null) : null,
+            category: args.category ?? null,
             amount: args.amount ?? null,
-            channel: args.channel ?? null,
+            channel,
             date: deps.today(),
-        }, settings(args, await ctx.saved()));
+        }, settings(args, await ctx.saved()), args.merchant === undefined
+            ? undefined
+            : withCallerCategory(resolvePlace(catalog, args.merchant, channel), args.category ?? null));
         const trimmed = { ...result, ranked: result.ranked.slice(0, TOP) };
         return {
             content: [
@@ -237,7 +259,11 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             ...CatalogFilters,
         }),
         outputSchema: SpendingSimulationSchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'Simulate a year of spending',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async (args) => {
         const given = args.spending ?? [];
         if (given.some((l) => l.merchant === undefined && l.category === undefined))
@@ -269,7 +295,7 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 ? withValuationProfile(wallet, args.valuation)
                 : wallet;
             const result = simulateAdditions(catalog, valued, lines, options);
-            const text = formatAdditions(result, catalog, false);
+            const text = `${ctx.fromCards(args.cards)}${formatAdditions(result, catalog, false)}`;
             return {
                 content: [{ type: 'text', text: [...notes, text].join('\n\n') }],
                 structuredContent: {
@@ -316,7 +342,11 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
             valuation: CatalogFilters.valuation,
         }),
         outputSchema: CheatSheetSchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'Cheat sheet',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async (args) => {
         const wallet = args.everyCard === true
             ? null
@@ -335,7 +365,12 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 ? withValuationProfile(wallet, args.valuation)
                 : wallet, date);
         return {
-            content: [{ type: 'text', text: formatCheatSheet(sheet) }],
+            content: [
+                {
+                    type: 'text',
+                    text: `${wallet === null ? '' : ctx.fromCards(args.cards)}${formatCheatSheet(sheet)}`,
+                },
+            ],
             structuredContent: sheet,
         };
     });
@@ -349,7 +384,11 @@ export function registerAnswerTools(server, deps, ctx, inputs) {
                 .describe('Card name or issuer, as the user said it.'),
         }),
         outputSchema: CardSearchSchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'Search cards',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async ({ query }) => {
         const held = await deps.store.load().catch(() => null);
         const result = searchCards(catalog, query ?? '', held, deps.today());

package/dist/mcp/tools/wallet.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
 import { membershipsFor, needsAnniversary } from "../../engine/setup.js";
-import { choiceName, currencyLabel, money, shortDate, words, } from "../../engine/text.js";
+import { choiceName, currencyLabel, listed, money, shortDate, words, } from "../../engine/text.js";
+import { membershipName } from "../../engine/memberships.js";
 import { profileText, VALUATION_PROFILES } from "../../engine/profiles.js";
-import { walletSummary } from "../../engine/wallet-summary.js";
+import { optionName, walletSummary } from "../../engine/wallet-summary.js";
 import { formatBooking, formatWalletSummary } from "../../format/wallet.js";
 import { fail } from "../context.js";
 import { CardChange, CardId, cardInput, ChannelInput, DateInput, Merchant, } from "../inputs.js";
@@ -20,13 +21,14 @@ function startedText(started, now) {
             : minutes < 48 * 60
                 ? `${String(Math.floor(minutes / 60))} hour${minutes < 120 ? '' : 's'} ago`
                 : `on ${shortDate(started.slice(0, 10))}`;
-    return `Saved wallet started ${ago}.`;
+    return `It was started ${ago}.`;
 }
 // What update_card changed, so the reply confirms the values it saved.
-function changes(args) {
+function changes(catalog, args) {
+    const card = catalog.cards.find((c) => c.id === args.cardId);
     const out = [];
     for (const [choice, options] of Object.entries(args.picks ?? {}))
-        out.push(`${choiceName(choice)} picks: ${options.map(words).join(', ')}`);
+        out.push(`${choiceName(choice)} picks: ${options.map((o) => (card ? optionName(catalog, card, choice, o) : words(o))).join('; ')}`);
     if (args.checkoutLabel === null)
         out.push('checkout name cleared');
     else if (args.checkoutLabel !== undefined)
@@ -50,9 +52,13 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     const { catalog, store } = deps;
     server.registerTool('list_wallet', {
         title: 'List wallet',
-        description: "Lists the user's cards: checkout label, network, rewards currency and its value, spending caps with how much is left this period, chosen bonus categories (and whether they're current), welcome-bonus progress, which stores a store card works at, when each card's data was last verified, the point values the user saved, and (for the hosted wallet) when it was started.",
+        description: `Lists the user's cards: checkout label, network, rewards currency and its value, spending caps with how much is left this period, chosen bonus categories (and whether they're current), welcome-bonus progress, which stores a store card works at, when each card's data was last verified, the point values the user saved, and (for the hosted wallet) when it was started. ${ctx.walletUse}`,
         outputSchema: WalletSummarySchema,
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: {
+            title: 'List wallet',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
     }, async () => {
         const read = await ctx.readableWallet();
         if (typeof read === 'string')
@@ -62,12 +68,14 @@ export function registerWalletTools(server, deps, ctx, inputs) {
             ...walletSummary(catalog, read.wallet, deps.today()),
             started,
         };
-        const when = started === null ? '' : `${startedText(started, Date.now())}\n`;
+        const when = started === null
+            ? `This is ${ctx.walletName}.\n`
+            : `This is ${ctx.walletName}. ${startedText(started, Date.now())}\n`;
         return {
             content: [
                 {
                     type: 'text',
-                    text: `${when}${read.start ?? formatWalletSummary(summary)}`,
+                    text: `${when}${read.start === null ? '' : `${read.start}\n`}${formatWalletSummary(summary)}`,
                 },
             ],
             structuredContent: summary,
@@ -75,7 +83,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     server.registerTool('record_purchase', {
         title: 'Record a purchase',
-        description: "Records a purchase the user has already made, so spending caps and welcome-bonus progress stay accurate for future recommendations. It updates the user's saved wallet. Only call it after the purchase has happened, and only once per purchase: calling it twice counts the spend twice. Purchases with no cap and no open welcome bonus are acknowledged and nothing is written. For a merchant earnrate doesn't recognize it asks for category first, so caps aren't missed.",
+        description: `Records a purchase the user has already made, so spending caps and welcome-bonus progress stay accurate for future recommendations. It updates the user's saved wallet. Only call it after the purchase has happened, and only once per purchase: calling it twice counts the spend twice. Purchases with no cap and no open welcome bonus are acknowledged and nothing is written. For a merchant earnrate doesn't recognize it asks for category first, so caps aren't missed. ${ctx.walletUse}`,
         inputSchema: z.object({
             cardId: z
                 .string()
@@ -89,6 +97,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
         }),
         outputSchema: RecordResultSchema,
         annotations: {
+            title: 'Record a purchase',
             ...WRITE,
             destructiveHint: false,
             idempotentHint: false,
@@ -119,7 +128,7 @@ export function registerWalletTools(server, deps, ctx, inputs) {
                 recorded: true,
                 booking,
                 bonus,
-                message: formatBooking(amount, cardId, booking, bonus),
+                message: `${formatBooking(amount, cardId, booking, bonus)} Saved in ${ctx.walletName}.`,
             }
             : {
                 recorded: false,
@@ -139,10 +148,15 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     server.registerTool('add_card', {
         title: 'Add a card',
-        description: "Adds a card the user holds to their wallet by its id from search_cards, creating the wallet if there isn't one. The reply says what the card still needs (category picks, memberships, activations); ask the user about those. Stores only the card's product id and settings, never card numbers.",
+        description: `Adds a card the user holds to their wallet by its id from search_cards, creating the wallet if there isn't one. The reply says what the card still needs (category picks, memberships, activations); ask the user about those. Stores only the card's product id and settings, never card numbers. ${ctx.walletUse}`,
         inputSchema: CardChange,
         outputSchema: WalletChangeSchema,
-        annotations: { ...WRITE, destructiveHint: false, idempotentHint: false },
+        annotations: {
+            title: 'Add a card',
+            ...WRITE,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
     }, async (args) => {
         const result = await store.addCard(cardInput(args), deps.today());
         const started = !result.ok || !result.created
@@ -154,12 +168,17 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     server.registerTool('update_card', {
         title: 'Update a card',
-        description: 'Changes settings on a card already in the wallet: its category picks for this period, checkout label, anniversary, activated categories, cap spending so far (capSpent) or a welcome bonus to track. Picks replace the saved ones in each choice group you set (other groups are kept) for the current period. Use it when the user picks new categories, such as each quarter on U.S. Bank Cash+.',
+        description: `Changes settings on a card already in the wallet: its category picks for this period, checkout label, anniversary, activated categories, cap spending so far (capSpent) or a welcome bonus to track. Picks replace the saved ones in each choice group you set (other groups are kept) for the current period. Use it when the user picks new categories, such as each quarter on U.S. Bank Cash+. ${ctx.walletUse}`,
         inputSchema: CardChange,
         outputSchema: WalletChangeSchema,
-        annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
+        annotations: {
+            title: 'Update a card',
+            ...WRITE,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
     }, async (args) => {
-        const what = changes(args);
+        const what = changes(catalog, args);
         const card = catalog.cards.find((c) => c.id === args.cardId);
         const unused = args.anniversary !== undefined && card && !needsAnniversary(card)
             ? " None of its caps reset on the account anniversary, so earnrate doesn't use it."
@@ -168,17 +187,27 @@ export function registerWalletTools(server, deps, ctx, inputs) {
     });
     server.registerTool('remove_card', {
         title: 'Remove a card',
-        description: "Removes a card from the wallet, with its tracked cap usage and bonus progress. Only when the user says they no longer have it or don't want it considered.",
+        description: `Removes a card from the wallet, with its tracked cap usage and bonus progress. Memberships and point values stay, even when the last card goes. Only when the user says they no longer have it or don't want it considered. ${ctx.walletUse}`,
         inputSchema: z.object({ cardId: CardId }),
         outputSchema: WalletChangeSchema,
-        annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
+        annotations: {
+            title: 'Remove a card',
+            ...WRITE,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
     }, async ({ cardId }) => ctx.changed(await store.removeCard(cardId), `Removed ${ctx.cardName(cardId)} (${cardId}).`, { notes: false }));
     server.registerTool('set_memberships', {
         title: 'Set memberships',
-        description: "Sets the memberships that unlock some cards' rates, such as amazon-prime for Prime Visa's 5% or a Bank of America Preferred Rewards tier, and costco for a Costco membership (so spending answers don't count its cost against Costco Anywhere). Replaces the whole list, so include the ones to keep.",
+        description: `Sets the memberships that unlock some cards' rates, such as amazon-prime for Prime Visa's 5% or a Bank of America Preferred Rewards tier, and costco for a Costco membership (so spending answers don't count its cost against Costco Anywhere). Replaces the whole list, so include the ones to keep. It saves them even with no cards saved, and every answer then uses them. ${ctx.walletUse}`,
         inputSchema: z.object({ memberships: inputs.AllMemberships }),
         outputSchema: WalletChangeSchema,
-        annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
+        annotations: {
+            title: 'Set memberships',
+            ...WRITE,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
     }, async ({ memberships }) => {
         const result = await store.setMemberships(memberships);
         const used = new Set((result.ok ? result.wallet.cards : []).flatMap((held) => {
@@ -187,12 +216,12 @@ export function registerWalletTools(server, deps, ctx, inputs) {
         }));
         const unused = memberships.filter((m) => !used.has(m));
         return ctx.changed(result, `${memberships.length > 0
-            ? `Memberships set to ${memberships.join(', ')}.`
-            : 'Memberships cleared.'}${unused.length > 0 ? ` ${unused.join(', ')} ${unused.length === 1 ? "doesn't" : "don't"} change any saved card's rates yet; kept for cards that use ${unused.length === 1 ? 'it' : 'them'}.` : ''}`, { notes: false });
+            ? `Memberships set to ${memberships.map((m) => `${membershipName(catalog, m)} (${m})`).join(', ')}.`
+            : 'Memberships cleared.'}${unused.length > 0 ? ` ${listed(unused.map((m) => membershipName(catalog, m)))} ${unused.length === 1 ? "doesn't" : "don't"} change any saved card's rates yet; kept for cards that use ${unused.length === 1 ? 'it' : 'them'}.` : ''}`, { notes: false });
     });
     server.registerTool('set_point_values', {
         title: 'Set point values',
-        description: `Saves what the user's points are worth to them, in cents per point, in their saved wallet; every answer then compares cards at those values unless a valuation profile is asked for. It needs a saved wallet with a card in it. Use it when the user says what their points are worth ("I value Chase points at 1.5¢") or that they transfer points to airlines and hotels (profile points-heavy). Values change only the currencies given; null goes back to earnrate's default. Currencies: ${catalog.currencies.map((c) => c.id).join(', ')}.`,
+        description: `Saves what the user's points are worth to them, in cents per point, in their saved wallet; every answer then compares cards at those values unless a valuation profile is asked for. No saved cards are needed. Use it when the user says what their points are worth ("I value Chase points at 1.5¢") or that they transfer points to airlines and hotels (profile points-heavy). Values change only the currencies given; null goes back to earnrate's default. Currencies: ${catalog.currencies.map((c) => c.id).join(', ')}. ${ctx.walletUse}`,
         inputSchema: z.object({
             values: z
                 .record(z.string(), z.number().nullable())
@@ -204,7 +233,12 @@ export function registerWalletTools(server, deps, ctx, inputs) {
                 .describe(`A preset: flat (${profileText('flat')}) or points-heavy (${profileText('points-heavy')}). Values given too win over it.`),
         }),
         outputSchema: WalletChangeSchema,
-        annotations: { ...WRITE, destructiveHint: true, idempotentHint: true },
+        annotations: {
+            title: 'Set point values',
+            ...WRITE,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
     }, async ({ values, profile }) => {
         const changes = {
             ...(profile ? VALUATION_PROFILES[profile] : {}),

package/dist/merchants/cache.js

@@ -38,16 +38,6 @@ export function merchantCachePath(env = process.env) {
     return (env[MERCHANT_CACHE_ENV_VAR] ??
         path.join(homedir(), CONFIG_DIR, 'merchant-cache.json'));
 }
-export function memoryCache() {
-    const entries = new Map();
-    return {
-        get: (key) => entries.get(key),
-        set: (key, value) => {
-            entries.set(key, value);
-            return Promise.resolve();
-        },
-    };
-}
 // A cache file that can't be read is left alone rather than overwritten, so a
 // hand edit gone wrong doesn't lose every saved classification.
 export async function openMerchantCache(file) {

package/dist/merchants/resolve.js

@@ -116,17 +116,94 @@ function fromMerchant(found, source, input, channel, typedDomain) {
         inference: null,
     };
 }
+// A merchant's record by id; an override replaces the seed entry.
+export function findMerchant(catalog, id) {
+    return (catalog.merchants.overrides.find((m) => m.id === id) ??
+        catalog.merchants.seed.find((m) => m.id === id));
+}
 export function resolveMerchantById(catalog, id, channel) {
     const override = catalog.merchants.overrides.find((m) => m.id === id);
-    const found = override ?? catalog.merchants.seed.find((m) => m.id === id);
+    const found = findMerchant(catalog, id);
     if (!found)
         return null;
     return fromMerchant(found, override ? 'override' : 'seed', found.name, channel, false);
 }
-// Used only when the merchant is unknown: curated data always wins over a
-// category supplied with the request.
+// Curated merchant data always wins over a category supplied with the
+// request; the caller's category wins over an unknown name or a different
+// category word.
 export function withCallerCategory(merchant, category) {
-    if (merchant.source !== 'none' || category === null)
+    if (category === null)
+        return merchant;
+    const otherWord = merchant.source === 'category' && merchant.category !== category;
+    if (merchant.source !== 'none' && !otherWord)
         return merchant;
     return { ...merchant, category, confidence: 'medium', source: 'caller' };
 }
+const plainWords = (s) => s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+// A category from everyday words: an alias ("groceries") first, then the
+// name, then the id, so "grocery" means supermarkets rather than the parent.
+export function findCategory(catalog, text) {
+    const wanted = plainWords(text);
+    if (wanted === '')
+        return null;
+    // "grocery store" finds "grocery stores", and "drugstore" "drugstores".
+    const forms = [
+        wanted,
+        wanted.endsWith('s') ? wanted.slice(0, -1) : `${wanted}s`,
+    ];
+    for (const form of forms) {
+        const by = (key) => catalog.categories.find((c) => key(c).map(plainWords).includes(form))?.id;
+        const found = by((c) => c.aliases) ?? by((c) => [c.name]) ?? by((c) => [c.id]);
+        if (found !== undefined)
+            return found;
+    }
+    return null;
+}
+export function categoryResolution(catalog, category, channel) {
+    const found = catalog.categories.find((c) => c.id === category);
+    if (!found)
+        throw new Error(`unknown category '${category}'`);
+    return {
+        input: found.name,
+        merchantId: null,
+        resolvedName: found.name,
+        category,
+        likelyMcc: null,
+        accepts: null,
+        ambiguity: null,
+        channel,
+        confidence: 'high',
+        source: 'category',
+        bookedVia: [],
+        inference: null,
+    };
+}
+// Words around a place that don't name it: "a restaurant", "the grocery
+// store", "a gas station near me".
+const LEADING = /^(?:(?:a|an|the|my|any|some|our|your|this|that|local|nearby|nearest)\s+)+/i;
+const TRAILING = /\s+(?:near me|nearby|around here|close by)$/i;
+// What someone typed: a store earnrate knows, else a category word
+// ("restaurants", "gas"), else unrecognized. Names are tried as given first,
+// so a store like The Home Depot keeps its "The".
+export function resolvePlace(catalog, text, channel) {
+    const attempt = (t) => {
+        const known = resolveMerchant(catalog, t, channel);
+        if (known.source !== 'none')
+            return known;
+        const category = findCategory(catalog, t);
+        return category === null
+            ? known
+            : categoryResolution(catalog, category, channel);
+    };
+    const asGiven = attempt(text);
+    if (asGiven.source !== 'none')
+        return asGiven;
+    const bare = text.trim().replace(TRAILING, '').replace(LEADING, '');
+    if (bare === '' || bare === text.trim())
+        return asGiven;
+    const found = attempt(bare);
+    return found.source === 'none' ? asGiven : found;
+}

package/dist/schema/card.js

@@ -58,12 +58,15 @@ export const RuleSchema = z
         .optional(),
     valid_from: IsoDate.optional(),
     valid_to: IsoDate.optional(),
+    // The issuer's last day to activate a bonus that needs it.
+    activate_by: IsoDate.optional(),
     // Set when a rule isn't confirmed against the issuer's terms. The engine
     // warns when an unverified rule decides the winner.
     unverified: z.string().optional(),
     note: z.string().optional(),
 })
-    .refine((r) => !r.valid_from || !r.valid_to || r.valid_from <= r.valid_to, 'valid_from must not be after valid_to');
+    .refine((r) => !r.valid_from || !r.valid_to || r.valid_from <= r.valid_to, 'valid_from must not be after valid_to')
+    .refine((r) => r.activate_by === undefined || r.requires?.activation === true, 'activate_by needs requires.activation');
 // The public sign-up bonus on the issuer's page. Offers vary by person and
 // channel, so a wallet can override it.
 export const WelcomeOfferSchema = z

package/dist/schema/issuer.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { KebabId } from "./common.js";
+export const IssuerSchema = z.strictObject({
+    id: KebabId,
+    name: z.string().min(1), // as shown: "American Express"
+    search: z.array(z.string().min(1)).default([]), // other words people use
+});
+export const IssuersFileSchema = z.array(IssuerSchema).min(1);