earnrate 0.1.3 → 0.2.0

package/README.md

@@ -7,12 +7,12 @@
 
 I wanted a ghost card: one card that always charges the best of my cards. The card networks won't allow one, so I built the next best thing.
 
-**earnrate is the best-card decision layer for people and AI agents.** Give it a merchant, and it tells you which card in your wallet earns the most there, and why. It's stateful (it knows your caps and chosen categories), valuation-aware, and transparent about its assumptions. It never sees a card number.
+**earnrate is the best-card decision layer for people and AI agents.** Give it a merchant, and it tells you which card earns the most there, from your own cards or from every card it knows, and why. It's stateful (it knows your caps and chosen categories), valuation-aware, and transparent about its assumptions. It never sees a card number.
 
-- Runs on your machine, or in your browser at [earnrate.dev](https://earnrate.dev) with nothing to install. No account, no telemetry, no affiliate links. See the [privacy page](https://earnrate.dev/privacy).
+- Runs on your machine, in your browser at [earnrate.dev](https://earnrate.dev), or in Claude as a connector at `https://mcp.earnrate.dev`, with nothing to install. No account, no telemetry, no affiliate links. See the [privacy page](https://earnrate.dev/privacy).
 - US cards and US merchants, for now.
 
-> **Status:** early, and it works: the engine, CLI, optional Claude merchant lookup and MCP server. See [the benchmark](docs/benchmark.md) for how it compares to an existing card-picking MCP server.
+> **Status:** early, and it works: the engine, CLI, optional Claude merchant lookup, MCP server and the hosted Claude connector. See [the benchmark](docs/benchmark.md) for how it compares to an existing card-picking MCP server.
 
 ## Try it
 
@@ -20,6 +20,13 @@ Needs Node 22 or later.
 
 ```sh
 npm install -g earnrate
+earnrate restaurants               # the best cards earnrate knows, no setup
+earnrate whole foods 80 --cards amex-gold,chase-prime-visa   # just these cards
+```
+
+You never have to enter your cards: with none, every answer covers every card earnrate knows. To have earnrate remember yours, track caps and welcome bonuses, and give a cheat sheet for your own wallet, save them:
+
+```sh
 earnrate cards sapphire            # find your cards' ids
 earnrate add chase-sapphire-preferred
 earnrate add amex-gold
@@ -51,6 +58,8 @@ Assumes Whole Foods Market codes as supermarkets (MCC 5411).
 
 Options: `--online` or `--in-store`, `--valuation flat|points-heavy`, `--all`, `--json`, `--date`, `--country`. Run `earnrate --help` for details. To keep the wallet somewhere else, set `EARNRATE_WALLET` to its path.
 
+`earnrate cheatsheet` prints the card to use for each everyday kind of purchase this quarter (groceries, dining, gas, Amazon, Costco, travel, streaming, drugstores, everything else), with your caps, picks and activations as they are now. It's also in the My wallet tab on [earnrate.dev](https://earnrate.dev).
+
 ### Your wallet
 
 The wallet is a YAML file (`~/.earnrate/wallet.yaml`) listing your cards by ID, which is each card's file name in [`data/cards/`](data/cards). `earnrate add`, `update`, `remove` and `memberships` write it for you and keep your comments, or you can edit it by hand. Only the cards are required:
@@ -85,14 +94,20 @@ earnrate ships with a curated list of merchants. For anything else it falls back
 
 ### Welcome bonuses
 
-When you're working toward a card's sign-up bonus, add it to that card in your wallet:
+When you're working toward a card's sign-up bonus, tell earnrate when the account opened:
+
+```sh
+earnrate update chase-sapphire-preferred --bonus-opened 2026-10-01 --bonus-spent 400
+```
+
+Or tell your AI assistant ("I opened my Sapphire Preferred on October 1"), or check "I'm working on this card's welcome bonus" in My wallet on earnrate.dev. `--no-bonus` stops tracking it. In the wallet file it looks like this:
 
 ```yaml
 - id: chase-sapphire-preferred
   bonus: { opened: 2026-10-01, spend: 5000, by: 2026-12-31, points: 75000 }
 ```
 
-While the bonus is open, that card wins wherever it's accepted, and the answer says how much is left, the weekly pace to finish on time, what the bonus is worth at your point values, and what using it costs compared with your best earner. Spend counts up as you record purchases from an AI agent or import a statement with `--apply`; refunds count down. Once it's met or the deadline passes, the card goes back to the normal ranking. With two open bonuses, the one needing more spend per day comes first.
+While the bonus is open, that card wins wherever it's accepted, and the answer says how much is left, the weekly pace to finish on time, what the bonus is worth at your point values, and what using it costs compared with your best earner. Spend counts up as you record purchases (from an AI assistant or the website) or import a statement with `--apply`; refunds count down. Once it's met or the deadline passes, the card goes back to the normal ranking. With two open bonuses, the one needing more spend per day comes first.
 
 `spend`, `by` and the reward (`points`, or `dollars` for cash back) default to the card's published offer once earnrate has one; set them when your offer was different.
 
@@ -152,12 +167,19 @@ Spotted a wrong rate, or want a card added? [Open an issue](https://github.com/c
 
 ## Use it from an AI agent (MCP)
 
-`earnrate mcp` runs earnrate as a local MCP server over stdio, with twelve tools:
+**In Claude, nothing to install:** add a custom connector (Settings → Connectors) with the address `https://mcp.earnrate.dev`. It works in Claude on the web, desktop and phone. Questions need no sign-in. If you ask it to save your cards, it opens an earnrate page where you start an anonymous wallet: no email, just a recovery code you keep. The wallet tracks caps and welcome bonuses across your Claude apps, and you can export it for the command line or delete it from the chat. In Claude Code:
+
+```sh
+claude mcp add --transport http earnrate https://mcp.earnrate.dev
+```
+
+**Or run it on your computer:** `earnrate mcp` runs earnrate as a local MCP server over stdio, with thirteen tools (the connector has the same ones, plus `export_wallet`, `import_wallet` and `delete_wallet` for its saved wallets):
 
 - `best_card_for_purchase`: which card to use, with reasons
 - `best_cards_for` and `simulate_spending`: compare every card earnrate knows, for one purchase or a year of spending, with no wallet needed
 - `resolve_merchant`: how a merchant was identified
 - `list_wallet`: your cards, caps left this period, chosen categories and welcome-bonus progress
+- `cheat_sheet`: the card to use for each everyday kind of purchase this quarter
 - `compare_welcome_offers`: the best public sign-up offers on cards you don't have
 - `record_purchase`: books a purchase against its cap and any open welcome bonus in your wallet file, keeping your comments
 - `search_cards`, `add_card`, `update_card`, `remove_card` and `set_memberships`: set up the wallet in conversation
@@ -166,7 +188,11 @@ There's no wallet to write first: tell the assistant which cards you have, and i
 
 For a merchant earnrate doesn't know, the calling model can pass a `category` (e.g. `grocery.supermarket`). It's used only for unknown merchants and is labeled in the answer. The command line takes the same thing as `--category`.
 
-To add it to Claude Code:
+**Claude Code plugin:** `/plugin install earnrate --marketplace cwasley/earnrate` connects Claude Code and Cowork to the same hosted server as the connector.
+
+**Claude Desktop, one click:** download [earnrate.mcpb](https://github.com/cwasley/earnrate/releases/latest/download/earnrate.mcpb) and open it; Claude Desktop installs it (Settings → Extensions). No terminal or Node install needed. Its one setting is where your wallet file lives, by default `~/.earnrate/wallet.yaml`, the same file the command line uses.
+
+To run it locally in Claude Code:
 
 ```sh
 claude mcp add --scope user earnrate -- npx -y earnrate mcp
@@ -214,6 +240,18 @@ A GitHub Action runs it every Monday and opens a "Card source changes" issue whe
 
 Rotating categories (Freedom Flex) are added each quarter once the issuer posts them. Until then, answers say that quarter's categories are missing rather than guessing.
 
+## Privacy Policy
+
+earnrate needs no account and has no telemetry. The full policy is at [earnrate.dev/privacy](https://earnrate.dev/privacy); in short:
+
+- **The Claude connector:** earnrate's server at mcp.earnrate.dev receives each question Claude asks it (a store or kind of purchase, and any amount, spending or cards you gave) and answers without keeping it; request logging is off. It counts requests by tool name only. A saved wallet is optional and anonymous (a recovery code, no email), holds card ids and the details you gave, never card numbers, and is encrypted with its own key that only your recovery code or your connected apps can unlock. Delete it any time; it's deleted automatically after 13 months unused.
+- **What it stores locally:** your wallet, a YAML file on your computer (`~/.earnrate/wallet.yaml` unless you set `EARNRATE_WALLET`). It lists cards by product id, like `amex-gold`, plus your category picks, activations and how much you've spent toward caps. earnrate never asks for or stores card numbers, expiry dates, security codes or bank logins.
+- **What the local version sends:** nothing, by default. The optional merchant lookup (off unless you turn it on with your own Anthropic API key) sends only the name of a store earnrate doesn't recognize to Anthropic's API, and saves the answer in `~/.earnrate/merchant-cache.json`.
+- **AI assistants:** when you use earnrate through Claude or another assistant, that assistant's provider sees the conversation, including earnrate's answers, under its own privacy policy.
+- **earnrate.dev:** everything you enter on the site stays in your browser. The site counts visits with Cloudflare Web Analytics, without cookies.
+- **Retention:** locally, your data lives only in files you control, for as long as you keep them. Delete the wallet file, or clear the site's data in your browser, to remove it. A connector wallet lasts until you delete it or leave it unused for 13 months.
+- **Contact:** [hello@earnrate.dev](mailto:hello@earnrate.dev).
+
 ## Working on earnrate
 
 ```sh

package/data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every change to card rules, merchants, categories or currencies under `data/`. Bump `data/VERSION` (`YYYY.MM.DD`, plus `.N` for a second release on the same day) and add a section here in the same commit. Each row cites the issuer page the new value came from.
 
+## 2026.10.30.3
+
+More everyday words find categories, for questions asked without a store name ("coffee shop", "dinner", "train"). Each maps to the category those purchases already fall under. No rates changed.
+
+| Category                                                                                                                  | Field   | Old → new           | Source |
+| ------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------- | ------ |
+| dining, dining.fast_food, gas, transit, travel.hotels, travel.flights, convenience_store, home_improvement, online_retail | aliases | adds everyday words | n/a    |
+
 ## 2026.10.30.2
 
 Cards record when the issuer stopped taking applications, so "best card for" lists can leave out cards nobody can get. Categories gain `aliases`, the everyday words people search by ("groceries" finds supermarkets). No rates changed.

package/data/VERSION

@@ -1 +1 @@
-2026.10.30.2
+2026.10.30.3

package/data/categories.yaml

@@ -5,11 +5,24 @@
 
 - id: dining
   name: Restaurants
-  aliases: [dining, restaurant, food, eating out, takeout]
+  aliases:
+    [
+      dining,
+      restaurant,
+      food,
+      eating out,
+      takeout,
+      dinner,
+      lunch,
+      breakfast,
+      brunch,
+      food delivery,
+    ]
   mccs: [5812, 5813, 5814]
 - id: dining.fast_food
   name: Fast food
-  aliases: [fast food restaurants]
+  aliases:
+    [fast food restaurants, coffee shop, coffee shops, coffee, cafe, cafes]
   mccs: [5814]
 
 - id: grocery
@@ -33,11 +46,12 @@
 
 - id: convenience_store
   name: Convenience stores
+  aliases: [convenience store, corner store, bodega]
   mccs: [5499]
 
 - id: gas
   name: Gas stations
-  aliases: [gas, fuel, gas station]
+  aliases: [gas, fuel, gas station, gas stations]
   mccs: [5541, 5542]
 - id: gas.grocery_store
   name: Gas at grocery stores
@@ -50,6 +64,7 @@
 
 - id: transit
   name: Transit
+  aliases: [public transit, train, trains, bus, commuting]
   mccs: [4111, 4112, 4131, 4784, 7523]
 - id: transit.rideshare
   name: Rideshare and taxis
@@ -61,11 +76,11 @@
   mccs: [4722]
 - id: travel.flights
   name: Flights
-  aliases: [flights, airfare, airlines]
+  aliases: [flights, airfare, airlines, flight, plane tickets]
   mccs: [4511]
 - id: travel.hotels
   name: Hotels
-  aliases: [hotel]
+  aliases: [hotel, hotels, motel, motels]
   mccs: [7011]
 - id: travel.car_rental
   name: Car rental
@@ -124,7 +139,7 @@
   mccs: [5941]
 - id: home_improvement
   name: Home improvement
-  aliases: [hardware stores]
+  aliases: [hardware stores, hardware store, home improvement store]
   mccs: [5200, 5211]
 - id: furniture
   name: Furniture stores
@@ -132,7 +147,7 @@
 
 - id: online_retail
   name: Online retail
-  aliases: [online shopping, shopping online]
+  aliases: [online shopping, shopping online, online]
 - id: office_supply
   name: Office supply stores
 - id: shipping

package/dist/cli/args.js

@@ -32,6 +32,8 @@ export function parseCliArgs(argv) {
                 category: { type: 'string' },
                 all: { type: 'boolean' },
                 llm: { type: 'boolean' },
+                cards: { type: 'string' },
+                member: { type: 'string', multiple: true },
                 help: { type: 'boolean', short: 'h' },
             },
         });
@@ -108,6 +110,13 @@ export function parseCliArgs(argv) {
             all: values.all ?? false,
             category: values.category ?? null,
             llm: values.llm ?? null,
+            cards: values.cards === undefined
+                ? null
+                : values.cards
+                    .split(',')
+                    .map((c) => c.trim())
+                    .filter((c) => c !== ''),
+            members: values.member ?? [],
         },
     };
 }

package/dist/cli/cheatsheet.js

@@ -0,0 +1,85 @@
+import { parseArgs } from 'node:util';
+import { CLI_NAME } from "../brand.js";
+import { loadCatalog, walletPath } from "../data/load.js";
+import { catalogCheatSheet, cheatSheet } from "../engine/cheat-sheet.js";
+import { formatCheatSheet } from "../format/cheat-sheet.js";
+import { ALL_PERSONAL_CARDS } from "../engine/explore.js";
+import { isValuationProfile, VALUATION_PROFILES, withValuationProfile, } from "../engine/profiles.js";
+import { cardsToUse, NO_WALLET_HINT, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
+export const CHEATSHEET_HELP = `Usage: ${CLI_NAME} cheatsheet [options]
+
+The card to use for each everyday kind of purchase this quarter: from your
+wallet (with your caps, picks and activations as they are now), from cards you
+name with --cards, or else from every card earnrate knows.
+
+Options:
+  --cards <ids>          Use these cards instead of your wallet, comma separated.
+  --member <name>        A membership you have, like amazon-prime. Repeatable.
+  --valuation <profile>  flat or points-heavy, instead of your wallet's values.
+  --date <YYYY-MM-DD>    The day to check. Default: today.
+  --json                 Print the cheat sheet as JSON.
+  -h, --help             Show this help.
+`;
+export async function runCheatSheet(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            options: {
+                valuation: { type: 'string' },
+                date: { type: 'string' },
+                cards: { type: 'string' },
+                member: { type: 'string', multiple: true },
+                json: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\n${CHEATSHEET_HELP}`);
+        return USAGE_ERROR;
+    }
+    const { values } = parsed;
+    if (values.help) {
+        io.stdout(CHEATSHEET_HELP);
+        return 0;
+    }
+    if (values.valuation !== undefined && !isValuationProfile(values.valuation)) {
+        io.stderr(`Unknown valuation "${values.valuation}". Use flat or points-heavy.\n`);
+        return USAGE_ERROR;
+    }
+    if (values.date !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(values.date)) {
+        io.stderr(`"${values.date}" isn't a date. Use YYYY-MM-DD.\n`);
+        return USAGE_ERROR;
+    }
+    const loaded = await cardsToUse(walletPath(io.env), io, {
+        cards: values.cards === undefined ? null : values.cards.split(','),
+        members: values.member ?? [],
+    });
+    if (loaded === null)
+        return RUNTIME_ERROR;
+    const catalog = await loadCatalog();
+    const date = values.date ?? io.today;
+    if (loaded === 'none') {
+        const sheet = catalogCheatSheet(catalog, date, {
+            filters: ALL_PERSONAL_CARDS,
+            memberships: values.member ?? [],
+            valuations: values.valuation !== undefined && isValuationProfile(values.valuation)
+                ? VALUATION_PROFILES[values.valuation]
+                : {},
+        });
+        io.stdout(values.json
+            ? `${JSON.stringify(sheet, null, 2)}\n`
+            : `${formatCheatSheet(sheet)}\n${NO_WALLET_HINT}\n`);
+        return 0;
+    }
+    const wallet = values.valuation !== undefined && isValuationProfile(values.valuation)
+        ? withValuationProfile(loaded, values.valuation)
+        : loaded;
+    const sheet = cheatSheet(catalog, wallet, date);
+    io.stdout(values.json
+        ? `${JSON.stringify(sheet, null, 2)}\n`
+        : formatCheatSheet(sheet));
+    return 0;
+}
+export { formatCheatSheet };

package/dist/cli/explore.js

@@ -1,12 +1,12 @@
 import { parseArgs } from 'node:util';
 import { CLI_NAME } from "../brand.js";
-import { walletProblems } from "../data/integrity.js";
 import { loadCatalog, walletPath } from "../data/load.js";
 import { ALL_PERSONAL_CARDS, exploreCards, findCategory, } from "../engine/explore.js";
 import { isValuationProfile, VALUATION_PROFILES, withValuationProfile, } from "../engine/profiles.js";
-import { resolveSpendLines, simulateAdditions, simulateCatalog, } from "../engine/simulate.js";
+import { resolveSpendLines, simulateAdditions, simulateCatalog, spendLineFor, TYPICAL_MONTHLY_SPEND, TYPICAL_SPEND_NOTE, } from "../engine/simulate.js";
 import { knownMemberships } from "../engine/setup.js";
-import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
+import { formatAdditions, formatCatalogSimulation, formatExploration, } from "../format/explore.js";
+import { cardsToUse, RUNTIME_ERROR, 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.
@@ -33,12 +33,12 @@ ${FILTER_OPTIONS}
   --json                  Print the full result as JSON.
   -h, --help              Show this help.
 `;
-export const SIMULATE_HELP = `Usage: ${CLI_NAME} simulate <what>=<dollars a month>... [options]
+export const SIMULATE_HELP = `Usage: ${CLI_NAME} simulate [<what>=<dollars a month>...] [options]
 
 Spends this much every month for a year and ranks the cards, and the
 two-card pairs, that earn the most after annual fees. Each <what> is a
 category (groceries, dining, gas, travel, streaming, other) or a merchant
-(amazon, costco).
+(amazon, costco). With no amounts, it uses typical ones for a U.S. household.
 
 Examples:
   ${CLI_NAME} simulate groceries=600 dining=300 gas=150 other=1000
@@ -47,6 +47,7 @@ Examples:
 Options:
   --wallet                Start from your wallet and rank the cards that would
                           add the most to it, after their fee.
+  --cards <ids>           The same, for cards you name instead of your wallet.
 ${FILTER_OPTIONS}
   --start <YYYY-MM-DD>    First month of the year simulated. Default: today.
   --all                   List more results.
@@ -93,130 +94,6 @@ function settingsFrom(values, catalog) {
             : {},
     };
 }
-const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
-const wholeUsd = (n) => usd(Math.round(n));
-const pct = (n) => `${String(Number(n.toFixed(2)))}%`;
-function feeText(e) {
-    if (e.annualFee === null)
-        return 'annual fee not on file';
-    if (e.annualFee === 0)
-        return 'no annual fee';
-    if (e.firstYearFee !== null && e.firstYearFee !== e.annualFee)
-        return `${usd(e.annualFee)} annual fee (${e.firstYearFee === 0 ? 'waived' : usd(e.firstYearFee)} the first year)`;
-    return `${usd(e.annualFee)} annual fee`;
-}
-const TOP_BEST = 10;
-export function formatExploration(r, all) {
-    const m = r.merchant;
-    const title = m.source === 'caller'
-        ? m.resolvedName.toLowerCase()
-        : m.source === 'none'
-            ? `"${m.input}" (not recognized)`
-            : m.resolvedName;
-    if (r.ranked.length === 0)
-        return `No cards match at ${title}.\n`;
-    const shown = all ? r.ranked : r.ranked.slice(0, TOP_BEST);
-    const width = Math.max(...shown.map((e) => e.cardName.length));
-    const lines = [`Best cards for ${title}:`, ''];
-    shown.forEach((e, i) => {
-        const earned = e.earned === null ? '' : `  ${usd(e.earned)}`;
-        lines.push(`${String(i + 1).padStart(2)}. ${e.cardName.padEnd(width)}  ${pct(e.effectiveReturnPct).padStart(5)}${earned}  ${feeText(e)}`);
-        for (const c of e.conditions)
-            lines.push(`    ${c}`);
-        const upgrade = e.withMembership[0];
-        if (upgrade)
-            lines.push(`    With ${upgrade.membership}: ${pct(upgrade.effectiveReturnPct)}.`);
-        for (const w of e.warnings)
-            lines.push(`    ! ${w}`);
-    });
-    if (r.ranked.length > shown.length)
-        lines.push(`  + ${String(r.ranked.length - shown.length)} more (--all lists them)`);
-    for (const w of r.warnings)
-        lines.push('', `! ${w}`);
-    lines.push('', ...r.assumptions);
-    return `${lines.join('\n')}\n`;
-}
-function picksText(picks) {
-    const parts = Object.entries(picks).map(([choice, options]) => `${choice}: ${options.join(', ')}`);
-    return parts.length === 0 ? '' : ` (picks ${parts.join('; ')})`;
-}
-function cardNamer(catalog) {
-    return (id) => catalog.cards.find((c) => c.id === id)?.name ?? id;
-}
-function splitText(sim, name) {
-    const byCard = new Map();
-    for (const line of sim.lines) {
-        const first = line.cards[0];
-        if (first === undefined)
-            continue;
-        byCard.set(first, [...(byCard.get(first) ?? []), line.label]);
-    }
-    return [...byCard].map(([id, labels]) => `${labels.join(', ')} → ${name(id)}`);
-}
-const TOP_SIMULATED = 5;
-export function formatCatalogSimulation(r, catalog, all) {
-    const name = cardNamer(catalog);
-    const first = r.singles[0];
-    if (!first)
-        return 'No cards match.\n';
-    const top = all ? 20 : TOP_SIMULATED;
-    const lines = [
-        `A year of this spending: ${wholeUsd(first.spend)}.`,
-        '',
-        'Best single cards (rewards minus annual fee, per year):',
-    ];
-    r.singles.slice(0, top).forEach((s, i) => {
-        const card = s.cards[0];
-        if (!card)
-            return;
-        lines.push(`${String(i + 1).padStart(2)}. ${name(card.cardId)}  ${wholeUsd(s.net)}  (${wholeUsd(s.rewards)} rewards, ${wholeUsd(s.annualFees)} fee)${picksText(card.picks)}`);
-    });
-    const pairs = r.pairs.slice(0, top);
-    if (pairs.length > 0) {
-        lines.push('', 'Best two-card pairs:');
-        pairs.forEach((s, i) => {
-            lines.push(`${String(i + 1).padStart(2)}. ${s.cards.map((c) => `${name(c.cardId)}${picksText(c.picks)}`).join(' + ')}  ${wholeUsd(s.net)}`);
-            if (s.alternatives.length > 0)
-                lines.push(`    Same result with ${s.alternatives.map(name).join(' or ')} as the second card.`);
-            for (const split of splitText(s, name))
-                lines.push(`    ${split}`);
-        });
-        const bestPair = r.pairs[0];
-        if (bestPair && bestPair.net <= first.net)
-            lines.push('', `One card is enough here: no pair beats ${name(first.cards[0]?.cardId ?? '')}.`);
-    }
-    const notes = new Set([
-        ...r.singles.slice(0, top).flatMap((s) => s.notes),
-        ...pairs.flatMap((s) => s.notes),
-    ]);
-    if (notes.size > 0)
-        lines.push('', ...notes);
-    lines.push('', "Assumes each card's best picks, activations done each quarter, and no welcome bonuses.");
-    return `${lines.join('\n')}\n`;
-}
-export function formatAdditions(r, catalog, all) {
-    const name = cardNamer(catalog);
-    const lines = [
-        `Your wallet earns about ${wholeUsd(r.current.rewards)} a year on this spending${r.current.annualFees > 0 ? `, with ${wholeUsd(r.current.annualFees)} in annual fees` : ''}.`,
-    ];
-    for (const split of splitText(r.current, name))
-        lines.push(`  ${split}`);
-    const gains = r.additions.filter((a) => a.gain > 0);
-    if (gains.length === 0) {
-        lines.push('', 'No card would add more than its annual fee costs.');
-    }
-    else {
-        lines.push('', 'Cards that would add the most (after their annual fee):');
-        gains.slice(0, all ? 20 : TOP_SIMULATED).forEach((a, i) => {
-            lines.push(`${String(i + 1).padStart(2)}. ${name(a.cardId)}  +${wholeUsd(a.gain)} a year  (+${wholeUsd(a.extraRewards)} rewards, ${wholeUsd(a.annualFee)} fee)${picksText(a.picks)}`);
-        });
-    }
-    const notes = new Set(r.current.notes);
-    if (notes.size > 0)
-        lines.push('', ...notes);
-    lines.push('', 'Assumes your picks carry over, rotating categories get activated, and caps start fresh.');
-    return `${lines.join('\n')}\n`;
-}
 export async function runBest(argv, io) {
     let parsed;
     try {
@@ -306,6 +183,7 @@ export async function runSimulate(argv, io) {
             options: {
                 ...FILTER_FLAGS,
                 wallet: { type: 'boolean' },
+                cards: { type: 'string' },
                 start: { type: 'string' },
             },
         });
@@ -325,7 +203,10 @@ export async function runSimulate(argv, io) {
         io.stderr(`${settings}\n`);
         return USAGE_ERROR;
     }
-    const spend = parseSpend(catalog, positionals);
+    const typical = positionals.length === 0;
+    const spend = typical
+        ? TYPICAL_MONTHLY_SPEND.map((t) => spendLineFor(catalog, t.what, t.monthly))
+        : parseSpend(catalog, positionals);
     if (typeof spend === 'string') {
         io.stderr(`${spend}\n`);
         return USAGE_ERROR;
@@ -337,15 +218,16 @@ export async function runSimulate(argv, io) {
         return USAGE_ERROR;
     }
     const options = { ...settings, start: values.start ?? io.today };
-    if (values.wallet) {
-        const file = walletPath(io.env);
-        const wallet = await readWallet(file, io);
-        if (!wallet)
-            return RUNTIME_ERROR;
-        const problems = walletProblems(wallet, catalog);
-        if (problems.length > 0) {
-            io.stderr(`Your wallet at ${displayPath(file)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
+    if (values.wallet || values.cards !== undefined) {
+        const wallet = await cardsToUse(walletPath(io.env), io, {
+            cards: values.cards === undefined ? null : values.cards.split(','),
+            members: values.member ?? [],
+        });
+        if (wallet === null)
             return RUNTIME_ERROR;
+        if (wallet === 'none') {
+            io.stderr(`No saved wallet yet. Name your cards instead: --cards amex-gold,chase-prime-visa\n`);
+            return USAGE_ERROR;
         }
         const valued = values.valuation !== undefined && isValuationProfile(values.valuation)
             ? withValuationProfile(wallet, values.valuation)
@@ -353,12 +235,13 @@ export async function runSimulate(argv, io) {
         const result = simulateAdditions(catalog, valued, lines, options);
         io.stdout(values.json
             ? `${JSON.stringify(result, null, 2)}\n`
-            : formatAdditions(result, catalog, values.all ?? false));
+            : `${typical ? `${TYPICAL_SPEND_NOTE}\n\n` : ''}${formatAdditions(result, catalog, values.all ?? false)}`);
         return 0;
     }
     const result = simulateCatalog(catalog, lines, options);
     io.stdout(values.json
         ? `${JSON.stringify(result, null, 2)}\n`
-        : formatCatalogSimulation(result, catalog, values.all ?? false));
+        : `${typical ? `${TYPICAL_SPEND_NOTE}\n\n` : ''}${formatCatalogSimulation(result, catalog, values.all ?? false)}`);
     return 0;
 }
+export { formatAdditions, formatCatalogSimulation, formatExploration };

package/dist/cli/format.js

@@ -14,11 +14,13 @@ function header(rec, purchase) {
             ? `"${m.resolvedName}" (not recognized)`
             : m.source === 'caller'
                 ? `${m.resolvedName} (category given)`
-                : m.source === 'llm'
-                    ? m.category === 'other'
-                        ? `"${m.resolvedName}" (Claude couldn't place it)`
-                        : `${m.resolvedName} (classified by Claude)`
-                    : m.resolvedName,
+                : m.source === 'category'
+                    ? m.resolvedName
+                    : m.source === 'llm'
+                        ? m.category === 'other'
+                            ? `"${m.resolvedName}" (Claude couldn't place it)`
+                            : `${m.resolvedName} (classified by Claude)`
+                        : m.resolvedName,
     ];
     if (purchase.amount !== null)
         parts.push(amountText(purchase.amount));