earnrate 0.2.0 → 0.2.1

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 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.
+**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. Save your cards and it tracks your caps and chosen categories. It's valuation-aware and transparent about its assumptions. It never sees a card number.
 
-- 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.
+- 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 and no affiliate links; the hosted server counts requests by tool name, nothing about what you ask. See the [privacy page](https://earnrate.dev/privacy).
+- U.S. cards and U.S. merchants, for now.
 
-> **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.
+> **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) (run 2026-10-24) for how it compares to an existing card-picking MCP server.
 
 ## Try it
 
@@ -27,13 +27,13 @@ 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 cards sapphire            # find your cards' IDs
 earnrate add chase-sapphire-preferred
 earnrate add amex-gold
 earnrate whole foods 80
 ```
 
-Adding a card tells you anything else it needs to earn correctly, such as the categories you picked on Cash+, Amazon Prime for Prime Visa's 5%, or which rotating categories you've activated. `earnrate update` sets those. Using an AI assistant instead? [Add the MCP server](#use-it-from-an-ai-agent-mcp) and tell it which cards you have.
+Adding a card tells you anything else it needs to earn correctly, such as the categories you picked on Cash+, Amazon Prime for Prime Visa's 5%, or which rotating categories you've activated. `earnrate update` sets those. Using an AI assistant instead? [Add earnrate to it](#use-it-in-an-ai-assistant-mcp) and ask; name your cards or save them there.
 
 With the [example wallet](wallet.example.yaml), it prints:
 
@@ -81,7 +81,7 @@ cards:
         two-percent: [gas-ev-charging]
 ```
 
-Rule IDs for `activated`, the choice slots for `chosen` and the membership IDs that unlock bonuses (such as `bofa-rewards-premier` for a BofA Rewards tier) are in each card's file. Currencies and their default values are in [`data/currencies.yaml`](data/currencies.yaml). Spending caps fill up as you record purchases from an AI agent or import a statement with `--apply`, and reset with each period.
+Rule IDs for `activated`, the choice slots for `chosen` and the membership IDs that unlock bonuses (such as `bofa-rewards-premier` for a BofA Rewards tier) are in each card's file. Currencies and their default values are in [`data/currencies.yaml`](data/currencies.yaml). Spending caps fill up as you record purchases from an AI assistant or import a statement with `--apply`, and reset with each period.
 
 ### Merchants earnrate doesn't know
 
@@ -113,7 +113,7 @@ While the bonus is open, that card wins wherever it's accepted, and the answer s
 
 ### Which new card?
 
-No wallet needed for these:
+These compare every card earnrate knows:
 
 ```sh
 earnrate best groceries                               # every card, ranked for one purchase
@@ -165,7 +165,7 @@ Something the format can't express yet (Bilt's rent earning, Citi Nights) is lis
 
 Spotted a wrong rate, or want a card added? [Open an issue](https://github.com/cwasley/earnrate/issues) with a link to the issuer's own page.
 
-## Use it from an AI agent (MCP)
+## Use it in an AI assistant (MCP)
 
 **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:
 
@@ -173,7 +173,9 @@ Spotted a wrong rate, or want a card added? [Open an issue](https://github.com/c
 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):
+Or install it as a Claude Code plugin, which connects Claude Code and Cowork to the same server: `/plugin marketplace add cwasley/earnrate`, then `/plugin install earnrate@earnrate`.
+
+**Or run it on your computer:** `earnrate mcp` runs earnrate as a local MCP server over stdio, with 13 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
@@ -184,13 +186,11 @@ claude mcp add --transport http earnrate https://mcp.earnrate.dev
 - `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
 
-There's no wallet to write first: tell the assistant which cards you have, and it finds them, adds them, and asks about anything a card needs, like this quarter's Cash+ picks.
+Saving cards is optional: name them in the conversation for one answer, or ask the assistant to save them, and it finds them, adds them, and asks about anything a card needs, like this quarter's Cash+ picks.
 
 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 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.
+**Claude Desktop, running locally:** 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:
 
@@ -222,12 +222,12 @@ 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, stale data, and a rotating card whose new quarter isn't in the data yet all show up in the answer.
+- **The engine is pure and deterministic.** Given a purchase, a date and a set of cards (yours, or every card), 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.
 
-The code is TypeScript run directly by Node 24 (`src/`), with the engine in `src/engine/`, merchant resolution in `src/merchants/`, and the CLI and MCP server as thin layers over them.
+The code is TypeScript run directly by Node 24 (`src/`), with the engine in `src/engine/`, merchant resolution in `src/merchants/`, and the CLI and MCP server as thin layers over them. `site/` is earnrate.dev, which runs the same engine in the browser, and `remote/` is the hosted server at mcp.earnrate.dev.
 
 ## Keeping card data current
 
@@ -242,18 +242,20 @@ Rotating categories (Freedom Flex) are added each quarter once the issuer posts
 
 ## Privacy Policy
 
-earnrate needs no account and has no telemetry. The full policy is at [earnrate.dev/privacy](https://earnrate.dev/privacy); in short:
+earnrate needs no account. The local version has no telemetry; the hosted server counts requests by tool name only. 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.
+- **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, or a week if it's never used.
+- **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.
+- **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 saved wallet on mcp.earnrate.dev lasts until you delete it or leave it unused for 13 months.
 - **Contact:** [hello@earnrate.dev](mailto:hello@earnrate.dev).
 
 ## Working on earnrate
 
+Development needs Node 24 or later.
+
 ```sh
 git clone https://github.com/cwasley/earnrate.git && cd earnrate
 yarn install

package/dist/brand.js

@@ -1,6 +1,5 @@
-// The only place the product name lives. package.json `name` and `bin` can't
-// import this, so keep them in sync by hand.
-export const PRODUCT_NAME = 'earnrate';
+// Names users type or set. package.json's `name` and `bin` must match
+// CLI_NAME by hand, since JSON can't import this.
 export const CLI_NAME = 'earnrate';
 export const MCP_SERVER_NAME = 'earnrate';
 export const CONFIG_DIR = '.earnrate'; // under the home directory

package/dist/cli/args.js

@@ -1,5 +1,8 @@
 import { parseArgs } from 'node:util';
 import { isValuationProfile, } from "../engine/profiles.js";
+import { knownMemberships } from "../engine/setup.js";
+// Shared by every subcommand, so each flag means the same thing everywhere.
+// A string result is the error to show.
 const LOOKS_LIKE_AMOUNT = /^\$?[\d,]*\.?\d+$/;
 const AMOUNT = /^\$?(\d{1,3}(,\d{3})+|\d+)(\.\d{1,2})?$/;
 function parseAmount(text) {
@@ -9,11 +12,54 @@ function parseAmount(text) {
     const amount = Number(text.replace(/[$,]/g, ''));
     return amount > 0 ? amount : 'The amount must be more than $0.';
 }
-function isValidDate(text) {
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(text))
-        return false;
+// A trailing number is the amount only when something comes before it, so
+// a merchant named "76" still works on its own.
+export function splitAmount(positionals) {
+    const words = [...positionals];
+    const last = words.at(-1);
+    let amount = null;
+    if (words.length > 1 && last !== undefined && LOOKS_LIKE_AMOUNT.test(last)) {
+        const result = parseAmount(last);
+        if (typeof result === 'string')
+            return result;
+        amount = result;
+        words.pop();
+    }
+    return { text: words.join(' ').trim(), amount };
+}
+export function dateProblem(text) {
+    if (text === undefined)
+        return null;
     const date = new Date(`${text}T00:00:00Z`);
-    return !Number.isNaN(date.getTime()) && date.toISOString().startsWith(text);
+    return /^\d{4}-\d{2}-\d{2}$/.test(text) &&
+        !Number.isNaN(date.getTime()) &&
+        date.toISOString().startsWith(text)
+        ? null
+        : `"${text}" isn't a date. Use YYYY-MM-DD.`;
+}
+export function valuationProblem(text) {
+    return text === undefined || isValuationProfile(text)
+        ? null
+        : `Unknown valuation "${text}". Use flat or points-heavy.`;
+}
+export function membershipProblem(catalog, members) {
+    const known = knownMemberships(catalog);
+    const unknown = members.filter((m) => !known.includes(m));
+    return unknown.length === 0
+        ? null
+        : `Unknown membership "${unknown.join('", "')}". Use one of: ${known.join(', ')}.`;
+}
+export const BOTH_CHANNELS = 'Pick --online or --in-store, not both.';
+export function channelOf(values) {
+    return values.online ? 'online' : values['in-store'] ? 'in_store' : null;
+}
+export function cardList(text) {
+    return text === undefined
+        ? null
+        : text
+            .split(',')
+            .map((c) => c.trim())
+            .filter((c) => c !== '');
 }
 export function parseCliArgs(argv) {
     let parsed;
@@ -47,49 +93,21 @@ export function parseCliArgs(argv) {
     const { values, positionals } = parsed;
     if (values.help)
         return { kind: 'help' };
-    // A trailing number is the amount only when something comes before it, so
-    // a merchant named "76" still works on its own.
-    const words = [...positionals];
-    let amount = null;
-    const last = words.at(-1);
-    if (words.length > 1 && last !== undefined && LOOKS_LIKE_AMOUNT.test(last)) {
-        const result = parseAmount(last);
-        if (typeof result === 'string')
-            return { kind: 'error', message: result };
-        amount = result;
-        words.pop();
-    }
-    const merchant = words.join(' ').trim();
+    const split = splitAmount(positionals);
+    if (typeof split === 'string')
+        return { kind: 'error', message: split };
+    const { text: merchant, amount } = split;
     if (merchant === '') {
         return { kind: 'error', message: 'Name a merchant, like "whole foods".' };
     }
-    if (values.online && values['in-store']) {
-        return {
-            kind: 'error',
-            message: 'Pick one of --online and --in-store.',
-        };
-    }
-    const channel = values.online
-        ? 'online'
-        : values['in-store']
-            ? 'in_store'
-            : null;
-    let valuation = null;
-    if (values.valuation !== undefined) {
-        if (!isValuationProfile(values.valuation)) {
-            return {
-                kind: 'error',
-                message: `Unknown valuation "${values.valuation}". Use flat or points-heavy.`,
-            };
-        }
-        valuation = values.valuation;
-    }
-    if (values.date !== undefined && !isValidDate(values.date)) {
-        return {
-            kind: 'error',
-            message: `"${values.date}" isn't a date. Use YYYY-MM-DD.`,
-        };
-    }
+    if (values.online && values['in-store'])
+        return { kind: 'error', message: BOTH_CHANNELS };
+    const problem = valuationProblem(values.valuation) ?? dateProblem(values.date);
+    if (problem !== null)
+        return { kind: 'error', message: problem };
+    const valuation = values.valuation !== undefined && isValuationProfile(values.valuation)
+        ? values.valuation
+        : null;
     const country = values.country ?? 'US';
     if (!/^[A-Za-z]{2}$/.test(country)) {
         return {
@@ -102,7 +120,7 @@ export function parseCliArgs(argv) {
         options: {
             merchant,
             amount,
-            channel,
+            channel: channelOf(values),
             valuation,
             date: values.date ?? null,
             country: country.toUpperCase(),
@@ -110,12 +128,7 @@ 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 !== ''),
+            cards: cardList(values.cards),
             members: values.member ?? [],
         },
     };

package/dist/cli/cheatsheet.js

@@ -2,11 +2,12 @@ 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 { formatCheatSheet } from "../format/cheat-sheet.js";
+import { cardList, dateProblem, valuationProblem } from "./args.js";
 import { cardsToUse, NO_WALLET_HINT, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
-export const CHEATSHEET_HELP = `Usage: ${CLI_NAME} cheatsheet [options]
+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
@@ -44,21 +45,18 @@ export async function runCheatSheet(argv, io) {
         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`);
+    const problem = valuationProblem(values.valuation) ?? dateProblem(values.date);
+    if (problem !== null) {
+        io.stderr(`${problem}\n`);
         return USAGE_ERROR;
     }
-    const loaded = await cardsToUse(walletPath(io.env), io, {
-        cards: values.cards === undefined ? null : values.cards.split(','),
+    const catalog = await loadCatalog();
+    const loaded = await cardsToUse(catalog, walletPath(io.env), io, {
+        cards: cardList(values.cards),
         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, {
@@ -82,4 +80,3 @@ export async function runCheatSheet(argv, io) {
         : formatCheatSheet(sheet));
     return 0;
 }
-export { formatCheatSheet };

package/dist/cli/explore.js

@@ -4,8 +4,8 @@ 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, spendLineFor, TYPICAL_MONTHLY_SPEND, TYPICAL_SPEND_NOTE, } from "../engine/simulate.js";
-import { knownMemberships } from "../engine/setup.js";
 import { formatAdditions, formatCatalogSimulation, formatExploration, } from "../format/explore.js";
+import { BOTH_CHANNELS, cardList, channelOf, dateProblem, membershipProblem, splitAmount, valuationProblem, } from "./args.js";
 import { cardsToUse, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
 const FILTER_OPTIONS = `  --cash, --points        Cash back cards only, or points and miles cards only.
   --no-fee                Cards with no annual fee.
@@ -15,7 +15,7 @@ const FILTER_OPTIONS = `  --cash, --points        Cash back cards only, or point
   --member <name>         A membership you have, e.g. amazon-prime. Repeatable.
   --valuation <profile>   flat (points at 1¢, the default) or points-heavy
                           (MR and UR at 1.7¢).`;
-export const BEST_HELP = `Usage: ${CLI_NAME} best <merchant or category> [amount] [options]
+const BEST_HELP = `Usage: ${CLI_NAME} best <merchant or category> [amount] [options]
 
 Ranks every card in earnrate's catalog for one purchase, not just yours. Each
 card is set up at its best: the right category pick, activated, cap unused.
@@ -33,7 +33,7 @@ ${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]
+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
@@ -70,15 +70,13 @@ const FILTER_FLAGS = {
 function settingsFrom(values, catalog) {
     if (values.cash && values.points)
         return 'Pick --cash or --points, not both.';
-    if (values.valuation !== undefined && !isValuationProfile(values.valuation))
-        return `Unknown valuation "${values.valuation}". Use flat or points-heavy.`;
+    const problem = valuationProblem(values.valuation) ??
+        membershipProblem(catalog, values.member ?? []);
+    if (problem !== null)
+        return problem;
     const issuers = [...new Set(catalog.cards.map((c) => c.issuer))].sort();
     if (values.issuer !== undefined && !issuers.includes(values.issuer))
         return `Unknown issuer "${values.issuer}". Use one of: ${issuers.join(', ')}.`;
-    const known = knownMemberships(catalog);
-    const unknown = (values.member ?? []).filter((m) => !known.includes(m));
-    if (unknown.length > 0)
-        return `Unknown membership "${unknown.join('", "')}". Use one of: ${known.join(', ')}.`;
     return {
         filters: {
             ...ALL_PERSONAL_CARDS,
@@ -117,20 +115,23 @@ export async function runBest(argv, io) {
         io.stdout(BEST_HELP);
         return 0;
     }
-    const words = [...positionals];
-    const last = words.at(-1);
-    const amount = words.length > 1 && last !== undefined && /^\$?\d+(\.\d+)?$/.test(last)
-        ? Number(last.replace('$', ''))
-        : null;
-    if (amount !== null)
-        words.pop();
-    const text = words.join(' ').trim();
+    const split = splitAmount(positionals);
+    if (typeof split === 'string') {
+        io.stderr(`${split}\n`);
+        return USAGE_ERROR;
+    }
+    const { text, amount } = split;
     if (text === '') {
         io.stderr(`Say what you're buying, e.g. ${CLI_NAME} best groceries.\n`);
         return USAGE_ERROR;
     }
     if (values.online && values['in-store']) {
-        io.stderr('Pick --online or --in-store, not both.\n');
+        io.stderr(`${BOTH_CHANNELS}\n`);
+        return USAGE_ERROR;
+    }
+    const dated = dateProblem(values.date);
+    if (dated !== null) {
+        io.stderr(`${dated}\n`);
         return USAGE_ERROR;
     }
     const catalog = await loadCatalog();
@@ -144,11 +145,7 @@ export async function runBest(argv, io) {
         merchant: category === null ? text : null,
         category,
         amount,
-        channel: values.online
-            ? 'online'
-            : values['in-store']
-                ? 'in_store'
-                : null,
+        channel: channelOf(values),
         date: values.date ?? io.today,
     }, settings);
     io.stdout(values.json
@@ -156,7 +153,7 @@ export async function runBest(argv, io) {
         : formatExploration(result, values.all ?? false));
     return 0;
 }
-export function parseSpend(catalog, args) {
+function parseSpend(catalog, args) {
     const lines = [];
     for (const arg of args) {
         const match = /^(.+)=\$?(\d+(?:\.\d+)?)$/.exec(arg);
@@ -217,10 +214,15 @@ export async function runSimulate(argv, io) {
         io.stderr(`Not a category or a merchant earnrate knows: ${unknown.map((l) => `"${l.merchant.input}"`).join(', ')}. Categories include groceries, dining, gas, travel, streaming and other.\n`);
         return USAGE_ERROR;
     }
+    const started = dateProblem(values.start);
+    if (started !== null) {
+        io.stderr(`${started}\n`);
+        return USAGE_ERROR;
+    }
     const options = { ...settings, start: values.start ?? io.today };
     if (values.wallet || values.cards !== undefined) {
-        const wallet = await cardsToUse(walletPath(io.env), io, {
-            cards: values.cards === undefined ? null : values.cards.split(','),
+        const wallet = await cardsToUse(catalog, walletPath(io.env), io, {
+            cards: cardList(values.cards),
             members: values.member ?? [],
         });
         if (wallet === null)
@@ -244,4 +246,3 @@ export async function runSimulate(argv, io) {
         : `${typical ? `${TYPICAL_SPEND_NOTE}\n\n` : ''}${formatCatalogSimulation(result, catalog, values.all ?? false)}`);
     return 0;
 }
-export { formatAdditions, formatCatalogSimulation, formatExploration };

package/dist/cli/import.js

@@ -6,13 +6,13 @@ import { z } from 'zod';
 import { CLI_NAME } from "../brand.js";
 import { walletProblems } from "../data/integrity.js";
 import { loadCatalog, walletPath } from "../data/load.js";
-import { writeBonusSpent, writeCapBooking } from "../data/wallet-write.js";
+import { writeProgress } from "../data/wallet-edit.js";
 import { isValuationProfile, withValuationProfile } from "../engine/profiles.js";
 import { cardValuation } from "../engine/valuation.js";
 import { analyzeStatement, } from "../import/analyze.js";
 import { parseStatement } from "../import/statement.js";
 import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
-export const IMPORT_HELP = `Usage: ${CLI_NAME} import <statement.csv> --card <card-id> [--apply]
+const IMPORT_HELP = `Usage: ${CLI_NAME} import <statement.csv> --card <card-id> [--apply]
        ${CLI_NAME} import <statement.csv>:<card-id> [<statement.csv>:<card-id> ...]
 
 Reads card statements (Amex and Chase activity CSVs) and reports:
@@ -241,12 +241,7 @@ export async function runImport(argv, io) {
             : `Nothing was written. Run again with --apply to record ${toRecord.join(' and ')}.\n`);
         return 0;
     }
-    for (const { booking } of analysis.bookings) {
-        await writeCapBooking(walletFile, booking);
-    }
-    for (const b of analysis.bonuses) {
-        await writeBonusSpent(walletFile, b.cardId, b.after);
-    }
+    await writeProgress(walletFile, analysis.bookings.map((e) => e.booking), analysis.bonuses);
     for (const entry of analysis.bookings)
         recorded.add(fingerprint(entry));
     for (const entry of bonusEntries)

package/dist/cli/offers.js

@@ -4,8 +4,9 @@ import { loadCatalog, walletPath } from "../data/load.js";
 import { compareOffers } from "../engine/offers.js";
 import { isValuationProfile, withValuationProfile } from "../engine/profiles.js";
 import { formatOffers } from "../format/offers.js";
+import { valuationProblem } from "./args.js";
 import { cardsToUse, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
-export const OFFERS_HELP = `Usage: ${CLI_NAME} offers [--cash | --points] [--no-fee] [--business] [options]
+const OFFERS_HELP = `Usage: ${CLI_NAME} offers [--cash | --points] [--no-fee] [--business] [options]
 
 Ranks the welcome offers on cards you don't have by first-year value: the
 bonus at your point values minus the first year's annual fee.
@@ -52,17 +53,18 @@ export async function runOffers(argv, io) {
         io.stderr('Pick --cash or --points, not both.\n');
         return USAGE_ERROR;
     }
-    if (values.valuation !== undefined && !isValuationProfile(values.valuation)) {
-        io.stderr(`Unknown valuation "${values.valuation}". Use flat or points-heavy.\n`);
+    const problem = valuationProblem(values.valuation);
+    if (problem !== null) {
+        io.stderr(`${problem}\n`);
         return USAGE_ERROR;
     }
-    const found = await cardsToUse(walletPath(io.env), io, {
+    const catalog = await loadCatalog();
+    const found = await cardsToUse(catalog, walletPath(io.env), io, {
         cards: null,
         members: [],
     });
     if (found === null)
         return RUNTIME_ERROR;
-    const catalog = await loadCatalog();
     const loaded = found === 'none' ? { valuations: {}, memberships: [], cards: [] } : found;
     const wallet = values.valuation && isValuationProfile(values.valuation)
         ? withValuationProfile(loaded, values.valuation)
@@ -81,4 +83,3 @@ export async function runOffers(argv, io) {
     io.stdout(formatOffers(comparison, currencyName, values.all ?? false));
     return 0;
 }
-export { formatOffers };

package/dist/cli/run.js

@@ -5,23 +5,24 @@ import { fileURLToPath } from 'node:url';
 import { CLI_NAME, CONFIG_DIR, LLM_ENV_VAR, LLM_MAX_CALLS_ENV_VAR, LLM_MODEL_ENV_VAR, MERCHANT_CACHE_ENV_VAR, WALLET_ENV_VAR, } from "../brand.js";
 import { walletProblems } from "../data/integrity.js";
 import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
-import { VALUATION_PROFILES, withValuationProfile } from "../engine/profiles.js";
 import { ALL_PERSONAL_CARDS, categoryResolution, exploreCards, findCategory, } from "../engine/explore.js";
+import { VALUATION_PROFILES, withValuationProfile } from "../engine/profiles.js";
 import { recommend } from "../engine/recommend.js";
 import { walletFromCards } from "../engine/transient.js";
+import { formatExploration } from "../format/explore.js";
+import { formatRecommendation, plain, } from "../format/recommendation.js";
 import { DEFAULT_LLM_MODEL } from "../merchants/anthropic.js";
 import { DEFAULT_MAX_CALLS } from "../merchants/fallback.js";
 import { llmEnabled, openLlmSession } from "../merchants/from-env.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { packageVersion } from "../version.js";
-import { parseCliArgs } from "./args.js";
+import { membershipProblem, parseCliArgs } from "./args.js";
 import { runCheatSheet } from "./cheatsheet.js";
-import { formatExploration, runBest, runSimulate } from "./explore.js";
+import { runBest, runSimulate } from "./explore.js";
 import { runImport } from "./import.js";
 import { runOffers } from "./offers.js";
 import { runWalletCommand, WALLET_HELP } from "./wallet.js";
-import { formatRecommendation, plain } from "./format.js";
-export const HELP = `Usage: ${CLI_NAME} <merchant> [amount] [options]
+const HELP = `Usage: ${CLI_NAME} <merchant> [amount] [options]
 
 Picks the card that earns the most at a merchant, and says why: from your
 wallet if you've saved one, from cards you name with --cards, or else from
@@ -36,7 +37,7 @@ Compare every card, no wallet needed:
   ${CLI_NAME} best <merchant or category>          Rank all cards for one purchase.
   ${CLI_NAME} simulate groceries=600 dining=300    Best cards and pairs for a year of spending.
 
-Set up your wallet:
+Save your cards (optional):
   ${CLI_NAME} cards [search words]                 Find cards and their ids.
   ${CLI_NAME} add <card-id> [--pick ...]           Add a card you hold.
   ${CLI_NAME} update <card-id> [--pick ...]        Change picks, label or activations.
@@ -44,10 +45,10 @@ Set up your wallet:
   ${CLI_NAME} memberships [names...]               Show or set memberships (amazon-prime).
 
 Other commands:
-  ${CLI_NAME} cheatsheet                           Your best card for each category this quarter.
+  ${CLI_NAME} cheatsheet                           The best card for each category this quarter.
   ${CLI_NAME} import <statement.csv> --card <id>   Replay a statement against your wallet.
   ${CLI_NAME} offers [--cash | --points]           Rank welcome offers on cards you don't have.
-  ${CLI_NAME} mcp                                  Run the MCP server over stdio, for AI agents.
+  ${CLI_NAME} mcp                                  Run the MCP server over stdio, for AI assistants.
   Add --help to any command for its options.
 
 Options:
@@ -85,8 +86,12 @@ export function displayPath(file) {
 }
 // The cards to answer for: those named with --cards, else the wallet file.
 // 'none' means no wallet and no --cards, which answers from every card.
-export async function cardsToUse(file, io, named) {
-    const catalog = await loadCatalog();
+export async function cardsToUse(catalog, file, io, named) {
+    const problem = membershipProblem(catalog, named.members);
+    if (problem !== null) {
+        io.stderr(`${problem}\n`);
+        return null;
+    }
     if (named.cards !== null) {
         const wallet = walletFromCards(catalog, {
             cards: named.cards.map((id) => ({ id })),
@@ -159,11 +164,10 @@ export async function run(argv, io) {
     }
     const { options } = args;
     const llmOn = options.llm ?? llmEnabled(io.env);
-    const file = walletPath(io.env);
-    const loaded = await cardsToUse(file, io, options);
+    const catalog = await loadCatalog();
+    const loaded = await cardsToUse(catalog, walletPath(io.env), io, options);
     if (loaded === null)
         return RUNTIME_ERROR;
-    const catalog = await loadCatalog();
     const purchase = {
         merchant: options.merchant,
         amount: options.amount,