earnrate 0.1.2 → 0.1.4

package/README.md

@@ -9,7 +9,7 @@ I wanted a ghost card: one card that always charges the best of my cards. The ca
 
 **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.
 
-- Runs on your machine. No account, no telemetry, no affiliate links. See the [privacy page](https://earnrate.dev/privacy).
+- 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).
 - 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.
@@ -51,6 +51,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:
@@ -98,6 +100,16 @@ While the bonus is open, that card wins wherever it's accepted, and the answer s
 
 ### Which new card?
 
+No wallet needed for these:
+
+```sh
+earnrate best groceries                               # every card, ranked for one purchase
+earnrate simulate groceries=600 dining=300 other=1000 # best cards and pairs for a year
+earnrate simulate groceries=600 other=1000 --wallet   # what a new card would add to yours
+```
+
+`best` ranks every card earnrate knows for a merchant or a category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Rates that need a membership like Amazon Prime are listed separately unless you pass `--member amazon-prime`. `simulate` spends your monthly amounts for a year, applying caps as they fill and reset, and ranks single cards and two-card pairs by rewards minus annual fees. Both take `--no-fee`, `--cash` or `--points`, `--issuer`, `--business` and `--valuation`. Welcome bonuses are left out of both; for those:
+
 ```sh
 earnrate offers --cash
 ```
@@ -142,11 +154,13 @@ 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 ten tools:
+`earnrate mcp` runs earnrate as a local MCP server over stdio, with thirteen tools:
 
 - `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
@@ -155,6 +169,8 @@ 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`.
 
+**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 add it to Claude Code:
 
 ```sh
@@ -185,8 +201,8 @@ merchant text
 
 - **Card terms are data, not code.** Each card is a YAML file of rules (category, rate, cap, channel, dates, activation, required membership), validated with Zod. Every rule carries a short quote from the issuer's own page, and a test fails if one is missing. The engine has no card-specific branches.
 - **Merchants resolve to a category plus the assumption behind it.** "Whole Foods codes as a supermarket (MCC 5411)" is stated in the answer, and venues that can code more than one way (a restaurant inside a stadium or hotel) come back at medium confidence with the alternative spelled out. Unknown merchants fall back to base rates, or to an opt-in, cached and labeled Claude guess.
-- **The engine is pure and deterministic.** Given a purchase, a date and a wallet, it checks every rule against network acceptance, the date window, caps already used (split when a purchase straddles one), quarterly picks and activations, then values points at your cents-per-point, including pooling (Freedom Unlimited points are worth Sapphire points when you hold both). Ties, the valuation at which the runner-up would win, and stale data all show up in the answer.
-- **Wallet edits keep your file intact.** Recording a purchase rewrites only the numbers that changed, so comments and formatting in your YAML survive.
+- **The engine is pure and deterministic.** Given a purchase, a date and a wallet, it checks every rule against network acceptance, the date window, caps already used (split when a purchase straddles one), quarterly picks and activations, then values points at your cents-per-point, including pooling (Freedom Unlimited points are worth Sapphire points when you hold both). Ties, the valuation at which the runner-up would win, stale data, and a rotating card whose new quarter isn't in the data yet all show up in the answer.
+- **Wallet edits keep your file intact.** Adding or changing a card, or recording a purchase, splices in only the lines that changed and checks the result before saving, so comments and formatting in your YAML survive.
 - **Drift detection.** A weekly GitHub Action opens each issuer page in a headless browser, checks every quote is still there, and opens an issue when terms move. It stores only hashes of issuer text.
 - **Tested end to end.** Golden cases written from issuer terms, CLI snapshot tests, an MCP round trip over real stdio, an install test that packs and installs the npm package, and a check that no committed file contains a card number. CI runs all of it on every push.
 
@@ -201,6 +217,8 @@ Every rule in `data/cards/` carries a short quote from the issuer's own page. In
 
 A GitHub Action runs it every Monday and opens a "Card source changes" issue when something moved. After updating a card file, run `yarn check-sources --update` to record the new baseline. Some issuers block headless browsers on shared servers; those pages are listed as "couldn't check", and running the command locally covers them. The first run needs `yarn playwright install chromium`.
 
+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.
+
 ## 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.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.
+
+| Card             | Field               | Old → new  | Source                                                                      |
+| ---------------- | ------------------- | ---------- | --------------------------------------------------------------------------- |
+| citi-custom-cash | applications_closed | 2026-05-28 | [card page](https://www.citi.com/credit-cards/citi-custom-cash-credit-card) |
+
 ## 2026.10.30.1
 
 Freedom Flex's quarterly cap is marked `rotating`, so a quarter whose categories aren't in the data yet gets a warning instead of quietly ranking Flex at its everyday rates. Capital One's issuer id is now spelled the same on every card. No rates changed.

package/data/VERSION

@@ -1 +1 @@
-2026.10.30.1
+2026.10.30.2

package/data/cards/citi-custom-cash.yaml

@@ -5,9 +5,10 @@ network: mastercard
 currency: cash
 last_verified: 2026-10-26
 verified_by: collin
-# Citi stopped taking applications on May 28, 2026; existing cardmembers keep
-# the card and its rewards. The card page no longer lists the categories, so
-# the definitions come from the card's current ThankYou terms (Sept 2026).
+applications_closed: 2026-05-28
+# Existing cardmembers keep the card and its rewards. The card page no longer
+# lists the categories, so the definitions come from the card's current
+# ThankYou terms (Sept 2026).
 source_urls:
   - https://www.citi.com/credit-cards/citi-custom-cash-credit-card
   - https://www.thankyou.com/ccterms

package/data/categories.yaml

@@ -5,24 +5,30 @@
 
 - id: dining
   name: Restaurants
+  aliases: [dining, restaurant, food, eating out, takeout]
   mccs: [5812, 5813, 5814]
 - id: dining.fast_food
   name: Fast food
+  aliases: [fast food restaurants]
   mccs: [5814]
 
 - id: grocery
   name: Grocery
 - id: grocery.supermarket
   name: Supermarkets
+  aliases: [groceries, grocery, grocery stores, supermarket]
   mccs: [5411]
 - id: grocery.online
   name: Online grocery and delivery
+  aliases: [grocery delivery]
 
 - id: superstore
   name: Superstores
+  aliases: [superstore, big box stores]
   mccs: [5310]
 - id: warehouse_club
   name: Warehouse clubs
+  aliases: [warehouse club, wholesale clubs]
   mccs: [5300]
 
 - id: convenience_store
@@ -31,6 +37,7 @@
 
 - id: gas
   name: Gas stations
+  aliases: [gas, fuel, gas station]
   mccs: [5541, 5542]
 - id: gas.grocery_store
   name: Gas at grocery stores
@@ -38,6 +45,7 @@
   name: Gas at superstores and warehouse clubs
 - id: ev_charging
   name: EV charging
+  aliases: [ev, charging]
   mccs: [5552]
 
 - id: transit
@@ -45,6 +53,7 @@
   mccs: [4111, 4112, 4131, 4784, 7523]
 - id: transit.rideshare
   name: Rideshare and taxis
+  aliases: [rideshare, taxi, taxis]
   mccs: [4121]
 
 - id: travel
@@ -52,41 +61,53 @@
   mccs: [4722]
 - id: travel.flights
   name: Flights
+  aliases: [flights, airfare, airlines]
   mccs: [4511]
 - id: travel.hotels
   name: Hotels
+  aliases: [hotel]
   mccs: [7011]
 - id: travel.car_rental
   name: Car rental
+  aliases: [car rentals, rental cars]
   mccs: [7512]
 - id: travel.cruise
   name: Cruises
+  aliases: [cruise]
   mccs: [4411]
 
 - id: streaming
   name: Streaming services
+  aliases: [streaming, subscriptions]
   mccs: [4899, 5815]
 - id: tv_internet
   name: TV and internet service
+  aliases: [internet, cable]
   mccs: [4899]
 - id: phone
   name: Cell phone service
+  aliases: [phone, cell phone, wireless]
   mccs: [4814]
 - id: utilities
   name: Home utilities
+  aliases: [utilities, electric, electricity]
   mccs: [4900]
 
 - id: drugstore
   name: Drugstores and pharmacies
+  aliases: [drugstores, pharmacy, pharmacies]
   mccs: [5912]
 - id: movie_theaters
   name: Movie theaters
+  aliases: [movies, movie theater]
   mccs: [7832]
 - id: entertainment
   name: Live entertainment and events
+  aliases: [concerts, events, tickets]
   mccs: [7922, 7941]
 - id: fitness
   name: Gyms and fitness
+  aliases: [gym, gyms, fitness]
   mccs: [7997]
 
 - id: department_store
@@ -103,6 +124,7 @@
   mccs: [5941]
 - id: home_improvement
   name: Home improvement
+  aliases: [hardware stores]
   mccs: [5200, 5211]
 - id: furniture
   name: Furniture stores
@@ -110,6 +132,7 @@
 
 - id: online_retail
   name: Online retail
+  aliases: [online shopping, shopping online]
 - id: office_supply
   name: Office supply stores
 - id: shipping
@@ -119,3 +142,4 @@
 
 - id: other
   name: Everything else
+  aliases: [everything, everything else, other]

package/dist/cli/cheatsheet.js

@@ -0,0 +1,81 @@
+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 { cheatSheet } from "../engine/cheat-sheet.js";
+import { isValuationProfile, withValuationProfile } from "../engine/profiles.js";
+import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
+export const CHEATSHEET_HELP = `Usage: ${CLI_NAME} cheatsheet [options]
+
+The card in your wallet to use for each everyday kind of purchase this
+quarter, with your caps, picks and activations as they are now.
+
+Options:
+  --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.
+`;
+const pct = (n) => `${String(Number(n.toFixed(2)))}%`;
+export function formatCheatSheet(sheet) {
+    const labelWidth = Math.max(...sheet.rows.map((r) => r.label.length));
+    const cardWidth = Math.max(...sheet.rows.map((r) => (r.cardName ?? 'none of your cards').length));
+    const lines = [`Your cheat sheet for ${sheet.quarter}`, ''];
+    for (const row of sheet.rows) {
+        lines.push(`  ${row.label.padEnd(labelWidth)}  ${(row.cardName ?? 'none of your cards').padEnd(cardWidth)}  ${row.effectiveReturnPct === null ? '' : pct(row.effectiveReturnPct).padStart(5)}`.trimEnd());
+        if (row.note)
+            lines.push(`  ${' '.repeat(labelWidth)}  ! ${row.note}`);
+    }
+    if (sheet.notes.length > 0)
+        lines.push('', ...sheet.notes);
+    return `${lines.join('\n')}\n`;
+}
+export async function runCheatSheet(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            options: {
+                valuation: { type: 'string' },
+                date: { type: 'string' },
+                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 file = walletPath(io.env);
+    const loaded = await readWallet(file, io);
+    if (!loaded)
+        return RUNTIME_ERROR;
+    const catalog = await loadCatalog();
+    const problems = walletProblems(loaded, catalog);
+    if (problems.length > 0) {
+        io.stderr(`Your wallet at ${displayPath(file)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
+        return RUNTIME_ERROR;
+    }
+    const wallet = values.valuation !== undefined && isValuationProfile(values.valuation)
+        ? withValuationProfile(loaded, values.valuation)
+        : loaded;
+    const sheet = cheatSheet(catalog, wallet, values.date ?? io.today);
+    io.stdout(values.json
+        ? `${JSON.stringify(sheet, null, 2)}\n`
+        : formatCheatSheet(sheet));
+    return 0;
+}