earnrate 0.1.1 → 0.1.2

package/README.md

@@ -9,23 +9,26 @@ 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.
+- Runs on your machine. 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.
 
 ## Try it
 
-Needs Node 24 or later.
+Needs Node 22 or later.
 
 ```sh
 npm install -g earnrate
-mkdir -p ~/.earnrate
-curl -o ~/.earnrate/wallet.yaml https://raw.githubusercontent.com/cwasley/earnrate/main/wallet.example.yaml
+earnrate cards sapphire            # find your cards' ids
+earnrate add chase-sapphire-preferred
+earnrate add amex-gold
 earnrate whole foods 80
 ```
 
-Then edit `~/.earnrate/wallet.yaml` to list your own cards (see [Your wallet](#your-wallet)).
+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.
+
+With the [example wallet](wallet.example.yaml), it prints:
 
 ```
 Whole Foods Market · $80
@@ -50,7 +53,7 @@ Options: `--online` or `--in-store`, `--valuation flat|points-heavy`, `--all`, `
 
 ### Your wallet
 
-The wallet is a YAML file listing your cards by ID, which is each card's file name in [`data/cards/`](data/cards). Only the cards are required:
+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:
 
 ```yaml
 valuations:
@@ -139,13 +142,16 @@ 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 five tools:
+`earnrate mcp` runs earnrate as a local MCP server over stdio, with ten tools:
 
 - `best_card_for_purchase`: which card to use, with reasons
 - `resolve_merchant`: how a merchant was identified
 - `list_wallet`: your cards, caps left this period, chosen categories and welcome-bonus progress
 - `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
+
+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.
 
 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`.
 

package/data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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.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.
+
+| Card                                                          | Field                       | Old → new                | Source |
+| ------------------------------------------------------------- | --------------------------- | ------------------------ | ------ |
+| chase-freedom-flex                                            | caps.five-percent-quarterly | adds `rotating`          | n/a    |
+| capital-one-venture-x, capital-one-venture, capital-one-savor | issuer                      | capitalone → capital-one | n/a    |
+
 ## 2026.10.28.2
 
 Bank of America Customized Cash Rewards, reviewed by Collin (`verified_by: collin`). Choice options can now be "any online purchase except these categories", and a choice period can be `until_changed` for picks that carry over.

package/data/VERSION

@@ -1 +1 @@
-2026.10.28.2
+2026.10.30.1

package/data/cards/capital-one-savor.yaml

@@ -1,6 +1,6 @@
 id: capital-one-savor
 name: Capital One Savor Rewards Credit Card
-issuer: capitalone
+issuer: capital-one
 # The card page never names the network in visible text; its embedded
 # product data says MasterCard.
 network: mastercard

package/data/cards/capital-one-venture-x.yaml

@@ -1,6 +1,6 @@
 id: capital-one-venture-x
 name: Capital One Venture X Rewards Credit Card
-issuer: capitalone
+issuer: capital-one
 network: visa # Visa Infinite, per the card page's footnotes
 currency: C1
 last_verified: 2026-10-26

package/data/cards/capital-one-venture.yaml

@@ -1,6 +1,6 @@
 id: capital-one-venture
 name: Capital One Venture Rewards Credit Card
-issuer: capitalone
+issuer: capital-one
 # The card page never names the network in visible text. Its embedded product
 # data says MasterCard; older Venture accounts may be on Visa.
 network: mastercard

package/data/cards/chase-freedom-flex.yaml

@@ -31,6 +31,7 @@ caps:
     amount: 1500
     period: quarter
     then_rate: 1
+    rotating: true
 rules:
   - id: chase-travel
     match: { merchants: [chase-travel] }

package/dist/cli/cards.js

@@ -0,0 +1,34 @@
+const NETWORKS = {
+    visa: 'Visa',
+    mastercard: 'Mastercard',
+    amex: 'Amex',
+    discover: 'Discover',
+    store: 'store card',
+};
+export function formatCardInfo(card) {
+    const fee = card.annualFee === null
+        ? ''
+        : card.annualFee === 0
+            ? ', no annual fee'
+            : `, $${String(card.annualFee)} a year`;
+    const needs = [
+        ...card.choices.map((c) => `${c.id}: pick ${String(c.pick)} of ${c.options.join(', ')}${c.default ? ` (default ${c.default.join(', ')})` : ''}`),
+        ...(card.memberships.length > 0
+            ? [`rates that need a membership: ${card.memberships.join(', ')}`]
+            : []),
+        ...(card.activation.length > 0
+            ? [`activate with the issuer: ${card.activation.join(', ')}`]
+            : []),
+        ...(card.needsAnniversary ? ['cap resets on the card anniversary'] : []),
+        ...(card.onlyAt ? [`works only at ${card.onlyAt.join(', ')}`] : []),
+    ];
+    return [
+        `${card.id}: ${card.name} (${NETWORKS[card.network]}${fee})${card.held ? ' [in wallet]' : ''}`,
+        ...needs.map((n) => `    ${n}`),
+    ].join('\n');
+}
+export function formatNotes(notes) {
+    return notes.length === 0
+        ? 'Nothing else to set up for it.'
+        : `Still to set:\n${notes.map((n) => `- ${n.text}`).join('\n')}`;
+}

package/dist/cli/run.js

@@ -14,6 +14,7 @@ import { packageVersion } from "../version.js";
 import { parseCliArgs } from "./args.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]
 
@@ -24,11 +25,18 @@ Examples:
   ${CLI_NAME} costco --in-store
   ${CLI_NAME} delta.com 450 --valuation points-heavy
 
+Set up your wallet:
+  ${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.
+  ${CLI_NAME} remove <card-id>                     Remove a card.
+  ${CLI_NAME} memberships [names...]               Show or set memberships (amazon-prime).
+
 Other commands:
   ${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.
-  Add --help to import or offers for its options.
+  Add --help to any command for its options.
 
 Options:
   --online, --in-store   How you're paying. Default: inferred from the merchant.
@@ -66,7 +74,7 @@ export async function readWallet(file, io) {
     }
     catch (e) {
         if (e instanceof Error && 'code' in e && e.code === 'ENOENT') {
-            io.stderr(`No wallet at ${displayPath(file)}. Copy the example there and edit it:\n  mkdir -p ${displayPath(path.dirname(file))} && cp ${displayPath(EXAMPLE_WALLET)} ${displayPath(file)}\nOr set ${WALLET_ENV_VAR} to your wallet's path.\n`);
+            io.stderr(`No wallet at ${displayPath(file)} yet. Add the cards you hold:\n  ${CLI_NAME} cards sapphire          find a card's id\n  ${CLI_NAME} add chase-sapphire-preferred\nOr start from the example: mkdir -p ${displayPath(path.dirname(file))} && cp ${displayPath(EXAMPLE_WALLET)} ${displayPath(file)}\nOr set ${WALLET_ENV_VAR} to your wallet's path.\n`);
         }
         else {
             io.stderr(`Couldn't read your wallet:\n${e instanceof Error ? e.message : String(e)}\n`);
@@ -79,6 +87,10 @@ export async function run(argv, io) {
         return runImport(argv.slice(1), io);
     if (argv[0] === 'offers')
         return runOffers(argv.slice(1), io);
+    const command = argv[0];
+    if (command !== undefined && Object.hasOwn(WALLET_HELP, command)) {
+        return runWalletCommand(command, argv.slice(1), io);
+    }
     if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) {
         io.stdout(`${CLI_NAME} ${await packageVersion()}\n`);
         return 0;

package/dist/cli/wallet.js

@@ -0,0 +1,194 @@
+import { parseArgs } from 'node:util';
+import { CLI_NAME } from "../brand.js";
+import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
+import { addCard, removeCard, setMemberships, updateCard, } from "../data/wallet-setup.js";
+import { knownMemberships, searchCards } from "../engine/setup.js";
+import { formatCardInfo, formatNotes } from "./cards.js";
+import { displayPath, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
+const CARD_OPTIONS = `Options:
+  --label <text>             How the card appears at checkout, e.g. "Amex Gold".
+  --pick <choice>=<options>  Bonus categories you picked for this period, e.g.
+                             --pick five-percent=fast-food,movie-theaters.
+                             Repeat for each choice.
+  --anniversary <MM-DD>      Account anniversary, for caps that reset on it.
+  --activated <rules>        Rules you've activated with the issuer, comma
+                             separated. Replaces the current list.
+  -h, --help                 Show this help.`;
+export const WALLET_HELP = {
+    cards: `Usage: ${CLI_NAME} cards [search words]
+
+Finds cards in earnrate's catalog by name or issuer, with the id to add them
+by and anything they need set up. With no words, lists every card.
+
+Examples:
+  ${CLI_NAME} cards sapphire
+  ${CLI_NAME} cards bofa
+`,
+    add: `Usage: ${CLI_NAME} add <card-id> [options]
+
+Adds a card you hold to your wallet, creating the wallet if needed. Find the
+id with \`${CLI_NAME} cards\`.
+
+${CARD_OPTIONS}
+`,
+    update: `Usage: ${CLI_NAME} update <card-id> [options]
+
+Changes a card in your wallet: picks for this period, label, anniversary or
+activations. Picks for the current period are merged with ones already set.
+
+${CARD_OPTIONS}
+`,
+    remove: `Usage: ${CLI_NAME} remove <card-id>
+
+Removes a card from your wallet, with its tracked cap usage.
+`,
+    memberships: `Usage: ${CLI_NAME} memberships [<membership>...] [--none]
+
+With no arguments, shows your memberships and the ones earnrate knows. With
+names, replaces the list. --none clears it.
+`,
+};
+const HINTS = {
+    pick: (id) => `${CLI_NAME} update ${id} --pick <choice>=<option>,...`,
+    membership: () => `${CLI_NAME} memberships <membership>...`,
+    activation: (id) => `${CLI_NAME} update ${id} --activated <rule>,...`,
+    anniversary: (id) => `${CLI_NAME} update ${id} --anniversary MM-DD`,
+};
+function parsePicks(values) {
+    const picks = {};
+    for (const v of values) {
+        const [choice, options] = v.split('=', 2);
+        const ids = (options ?? '')
+            .split(',')
+            .map((o) => o.trim())
+            .filter((o) => o !== '');
+        if (!choice || ids.length === 0) {
+            return `"--pick ${v}" should look like --pick five-percent=fast-food,movie-theaters.`;
+        }
+        picks[choice] = ids;
+    }
+    return picks;
+}
+async function heldWallet(io) {
+    try {
+        return await loadWallet(walletPath(io.env));
+    }
+    catch {
+        return null;
+    }
+}
+function report(result, message, cardId, io) {
+    if (!result.ok) {
+        io.stderr(`${result.error}\n`);
+        return RUNTIME_ERROR;
+    }
+    const lines = [message];
+    if (cardId !== null) {
+        lines.push(formatNotes(result.notes));
+        const hints = [...new Set(result.notes.map((n) => n.kind))]
+            .map((kind) => HINTS[kind]?.(cardId))
+            .filter((h) => h !== undefined);
+        if (hints.length > 0)
+            lines.push(`Set them with:\n${hints.map((h) => `  ${h}`).join('\n')}`);
+    }
+    io.stdout(`${lines.join('\n')}\n`);
+    return 0;
+}
+export async function runWalletCommand(command, argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                label: { type: 'string' },
+                pick: { type: 'string', multiple: true },
+                anniversary: { type: 'string' },
+                activated: { type: 'string' },
+                none: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\nRun ${CLI_NAME} ${command} --help for usage.\n`);
+        return USAGE_ERROR;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        io.stdout(WALLET_HELP[command]);
+        return 0;
+    }
+    const usage = (message) => {
+        io.stderr(`${message}\nRun ${CLI_NAME} ${command} --help for usage.\n`);
+        return USAGE_ERROR;
+    };
+    const cardOptionsGiven = values.label !== undefined ||
+        values.pick !== undefined ||
+        values.anniversary !== undefined ||
+        values.activated !== undefined;
+    if (command !== 'add' && command !== 'update' && cardOptionsGiven) {
+        return usage(`${CLI_NAME} ${command} doesn't take card options.`);
+    }
+    if (command !== 'memberships' && values.none) {
+        return usage('--none is only for memberships.');
+    }
+    const catalog = await loadCatalog();
+    const file = walletPath(io.env);
+    const where = displayPath(file);
+    if (command === 'cards') {
+        const query = positionals.join(' ');
+        const result = searchCards(catalog, query, await heldWallet(io), io.today);
+        if (result.cards.length === 0) {
+            io.stderr(`No card matches "${query}". Run ${CLI_NAME} cards with no words to list all ${String(catalog.cards.length)}.\n`);
+            return RUNTIME_ERROR;
+        }
+        const header = result.exact ? '' : 'No card matches every word. Closest:\n';
+        io.stdout(`${header}${result.cards.map(formatCardInfo).join('\n')}\n`);
+        return 0;
+    }
+    if (command === 'memberships') {
+        if (positionals.length === 0 && !values.none) {
+            const held = await heldWallet(io);
+            io.stdout(`Yours: ${held && held.memberships.length > 0 ? held.memberships.join(', ') : 'none'}\nKnown: ${knownMemberships(catalog).join(', ')}\n`);
+            return 0;
+        }
+        if (positionals.length > 0 && values.none) {
+            return usage('Give memberships or --none, not both.');
+        }
+        const list = values.none ? [] : positionals;
+        return report(await setMemberships(file, catalog, list), list.length > 0
+            ? `Memberships set to ${list.join(', ')} in ${where}.`
+            : `Memberships cleared in ${where}.`, null, io);
+    }
+    if (positionals.length !== 1) {
+        return usage('Give one card id.');
+    }
+    const id = positionals[0] ?? '';
+    const name = catalog.cards.find((c) => c.id === id)?.name ?? id;
+    if (command === 'remove') {
+        return report(await removeCard(file, catalog, id), `Removed ${name} from ${where}.`, null, io);
+    }
+    const input = { id };
+    if (values.label !== undefined)
+        input.checkoutLabel = values.label;
+    if (values.anniversary !== undefined)
+        input.anniversary = values.anniversary;
+    if (values.activated !== undefined) {
+        input.activated = values.activated
+            .split(',')
+            .map((r) => r.trim())
+            .filter((r) => r !== '');
+    }
+    if (values.pick !== undefined) {
+        const picks = parsePicks(values.pick);
+        if (typeof picks === 'string')
+            return usage(picks);
+        input.picks = picks;
+    }
+    if (command === 'add') {
+        const result = await addCard(file, catalog, input, io.today);
+        return report(result, `Added ${name} to ${where}${result.ok && result.created ? ' (a new wallet)' : ''}.`, id, io);
+    }
+    return report(await updateCard(file, catalog, input, io.today), `Updated ${name} in ${where}.`, id, io);
+}

package/dist/data/integrity.js

@@ -136,6 +136,20 @@ function cardProblems(card, catalog, merchantIds) {
             problems.push(`${where} ${context}: unknown cap '${rule.cap}'`);
         }
     }
+    for (const cap of card.caps.filter((c) => c.rotating)) {
+        const rules = card.rules.filter((r) => r.cap === cap.id);
+        if (rules.length === 0) {
+            problems.push(`${where} cap ${cap.id}: rotating, but no rule uses it`);
+        }
+        for (const r of rules) {
+            if (r.valid_from === undefined || r.valid_to === undefined) {
+                problems.push(`${where} rule ${r.id}: rules on rotating cap '${cap.id}' need valid_from and valid_to`);
+            }
+        }
+        if (cap.period === 'cardmember_year') {
+            problems.push(`${where} cap ${cap.id}: a rotating cap can't use cardmember years`);
+        }
+    }
     return problems;
 }
 export function catalogProblems(catalog) {

package/dist/data/wallet-edit.js

@@ -0,0 +1,162 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { isMap, isSeq, parseDocument, stringify } from 'yaml';
+import { WalletSchema } from "../schema/wallet.js";
+const NEW_WALLET = `# Your earnrate wallet: the cards you hold, by id. Never card numbers.
+# Format: https://github.com/cwasley/earnrate#your-wallet
+
+`;
+const BY_HAND = 'edit the wallet by hand';
+const lineStart = (text, at) => text.lastIndexOf('\n', at - 1) + 1;
+function afterLine(text, at) {
+    const end = text.indexOf('\n', at);
+    return end === -1 ? text.length : end + 1;
+}
+function insertLines(text, at, lines) {
+    const head = text.slice(0, at);
+    const gap = head.length > 0 && !head.endsWith('\n') ? '\n' : '';
+    return `${head}${gap}${lines}${text.slice(at)}`;
+}
+function range(node) {
+    const r = node?.range;
+    if (!r)
+        throw new Error(`a wallet value has no source position; ${BY_HAND}`);
+    return r;
+}
+const keyOf = (pair) => pair.key?.value;
+const scalar = (value) => stringify(value).trimEnd();
+const flowList = (ids) => `[${ids.join(', ')}]`;
+function fieldLines(field, f, indent) {
+    switch (field) {
+        case 'checkout_label':
+        case 'anniversary': {
+            const value = f[field];
+            return value === undefined ? '' : `${indent}${field}: ${scalar(value)}\n`;
+        }
+        case 'activated':
+            return f.activated === undefined
+                ? ''
+                : `${indent}activated: ${flowList(f.activated)}\n`;
+        case 'chosen': {
+            if (f.chosen === undefined)
+                return '';
+            const picks = Object.entries(f.chosen.picks)
+                .map(([choice, ids]) => `${indent}    ${choice}: ${flowList(ids)}\n`)
+                .join('');
+            return `${indent}chosen:\n${indent}  period: ${scalar(f.chosen.period)}\n${indent}  picks:\n${picks}`;
+        }
+    }
+}
+const FIELDS = ['checkout_label', 'anniversary', 'chosen', 'activated'];
+function cardsSeq(text) {
+    const doc = parseDocument(text);
+    if (doc.errors.length > 0)
+        throw new Error(doc.errors[0]?.message);
+    const cards = doc.get('cards', true);
+    if (!isSeq(cards) || cards.flow) {
+        throw new Error(`"cards" isn't a block list; ${BY_HAND}`);
+    }
+    return { doc, cards };
+}
+function findCard(text, cardId) {
+    const { cards } = cardsSeq(text);
+    const card = cards.items.find((item) => isMap(item) && item.get('id') === cardId);
+    if (!isMap(card))
+        throw new Error(`no card '${cardId}' in the wallet`);
+    if (card.flow)
+        throw new Error(`card '${cardId}' is written inline; ${BY_HAND}`);
+    return card;
+}
+const column = (text, at) => at - lineStart(text, at);
+// Appends a card after the last one, matching the list's indentation.
+export function addCardText(text, entry) {
+    if (text === null || text.trim() === '') {
+        return `${NEW_WALLET}cards:\n${cardLines(entry, '  ')}`;
+    }
+    const { cards } = cardsSeq(text);
+    const first = cards.items[0];
+    if (!isMap(first))
+        throw new Error(`"cards" is empty; ${BY_HAND}`);
+    const keyColumn = column(text, range(first)[0]);
+    if (keyColumn < 2 || text[range(first)[0] - 2] !== '-') {
+        throw new Error(`can't tell how the cards are indented; ${BY_HAND}`);
+    }
+    const at = afterLine(text, range(cards)[1] - 1);
+    return insertLines(text, at, cardLines(entry, ' '.repeat(keyColumn - 2)));
+}
+function cardLines(entry, dashIndent) {
+    const indent = `${dashIndent}  `;
+    return `${dashIndent}- id: ${entry.id}\n${FIELDS.map((f) => fieldLines(f, entry, indent)).join('')}`;
+}
+export function removeCardText(text, cardId) {
+    const card = findCard(text, cardId);
+    const start = lineStart(text, range(card)[0]);
+    const end = afterLine(text, range(card)[1] - 1);
+    return text.slice(0, start) + text.slice(end);
+}
+// Replaces each given field in place, or adds it after the card's last line.
+export function updateCardText(text, cardId, fields) {
+    let out = text;
+    for (const field of FIELDS) {
+        if (fields[field] === undefined)
+            continue;
+        const card = findCard(out, cardId);
+        const indent = ' '.repeat(column(out, range(card)[0]));
+        const lines = fieldLines(field, fields, indent);
+        const pair = card.items.find((p) => keyOf(p) === field);
+        if (pair) {
+            const start = range(pair.key)[0];
+            const end = afterLine(out, range(pair.value)[1] - 1);
+            out = out.slice(0, start) + lines.trimStart() + out.slice(end);
+        }
+        else {
+            out = insertLines(out, afterLine(out, range(card)[1] - 1), lines);
+        }
+    }
+    return out;
+}
+export function setMembershipsText(text, memberships) {
+    const { doc } = cardsSeq(text);
+    const root = doc.contents;
+    if (!isMap(root))
+        throw new Error(`the wallet isn't a map; ${BY_HAND}`);
+    const line = `memberships: ${flowList(memberships)}\n`;
+    const pair = root.items.find((p) => keyOf(p) === 'memberships');
+    if (pair) {
+        const start = range(pair.key)[0];
+        const end = afterLine(text, (pair.value === null ? range(pair.key) : range(pair.value))[1] - 1);
+        return text.slice(0, start) + line + text.slice(end);
+    }
+    const cards = root.items.find((p) => keyOf(p) === 'cards');
+    return insertLines(text, lineStart(text, range(cards?.key)[0]), line);
+}
+async function readText(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (e) {
+        if (e instanceof Error && 'code' in e && e.code === 'ENOENT')
+            return null;
+        throw e;
+    }
+}
+export async function readWalletText(file) {
+    const text = await readText(file);
+    return {
+        text,
+        wallet: text === null ? null : WalletSchema.parse(parseDocument(text).toJS()),
+    };
+}
+// Writes `after` only if it parses to exactly `expected`, so a splice that
+// went wrong can never change anything it wasn't meant to.
+export async function commitWalletText(file, after, expected) {
+    const parsed = WalletSchema.safeParse(parseDocument(after).toJS());
+    if (!parsed.success || !isDeepStrictEqual(parsed.data, expected)) {
+        throw new Error(`couldn't update ${file} safely; ${BY_HAND}`);
+    }
+    await mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${String(process.pid)}.tmp`;
+    await writeFile(tmp, after);
+    await rename(tmp, file);
+}

package/dist/data/wallet-setup.js

@@ -0,0 +1,202 @@
+import { periodKey } from "../engine/periods.js";
+import { knownMemberships, searchCards, setupNotes, } from "../engine/setup.js";
+import { WalletCardSchema, WalletSchema, } from "../schema/wallet.js";
+import { addCardText, commitWalletText, readWalletText, removeCardText, setMembershipsText, updateCardText, } from "./wallet-edit.js";
+const failed = (error) => ({ ok: false, error });
+const list = (ids) => ids.join(', ');
+function findCatalogCard(catalog, id, today) {
+    const card = catalog.cards.find((c) => c.id === id);
+    if (card)
+        return card;
+    const near = searchCards(catalog, id, null, today).cards.map((c) => c.id);
+    return near.length > 0
+        ? `No card '${id}' in earnrate. Closest: ${list(near)}.`
+        : `No card '${id}' in earnrate. Search the catalog to find its id.`;
+}
+function isAnniversary(text) {
+    const m = /^(\d{2})-(\d{2})$/.exec(text);
+    if (!m)
+        return false;
+    const date = new Date(`2024-${text}T00:00:00Z`); // a leap year allows 02-29
+    return (!Number.isNaN(date.getTime()) && date.toISOString().slice(5, 10) === text);
+}
+// The period key picks are filed under: the card's choice period, or for
+// picks that carry over, the current year (it's never compared).
+function choicePeriod(card, today) {
+    const periods = [
+        ...new Set(card.choices.map((c) => c.period).filter((p) => p !== 'until_changed')),
+    ];
+    if (periods.length > 1)
+        return null;
+    return periodKey(periods[0] ?? 'calendar_year', today, null);
+}
+function fieldsFor(card, held, input, today) {
+    const problems = [];
+    const fields = {};
+    if (input.checkoutLabel !== undefined) {
+        if (input.checkoutLabel.trim() === '')
+            problems.push('The checkout label is empty.');
+        // earnrate never stores card numbers; a last four is fine.
+        if (/\d{8,}/.test(input.checkoutLabel.replace(/[\s-]/g, '')))
+            problems.push('The checkout label looks like it has a card number in it. earnrate never stores card numbers; use a name like "Amex Gold".');
+        fields.checkout_label = input.checkoutLabel.trim();
+    }
+    if (input.anniversary !== undefined) {
+        if (!isAnniversary(input.anniversary)) {
+            problems.push(`"${input.anniversary}" isn't an anniversary. Use MM-DD, like 03-15.`);
+        }
+        fields.anniversary = input.anniversary;
+    }
+    if (input.activated !== undefined) {
+        const needing = card.rules
+            .filter((r) => r.requires?.activation)
+            .map((r) => r.id);
+        for (const id of input.activated) {
+            if (!needing.includes(id)) {
+                problems.push(needing.length > 0
+                    ? `'${id}' isn't a ${card.id} rule that needs activating. Those are: ${list(needing)}.`
+                    : `${card.id} has no rules that need activating.`);
+            }
+        }
+        fields.activated = [...new Set(input.activated)];
+    }
+    if (input.picks !== undefined) {
+        for (const [choiceId, picks] of Object.entries(input.picks)) {
+            const choice = card.choices.find((c) => c.id === choiceId);
+            if (!choice) {
+                problems.push(card.choices.length > 0
+                    ? `${card.id} has no '${choiceId}' pick. Its picks are: ${list(card.choices.map((c) => c.id))}.`
+                    : `${card.id} has no categories to pick.`);
+                continue;
+            }
+            const options = Object.keys(choice.options);
+            for (const p of picks) {
+                if (!options.includes(p)) {
+                    problems.push(`'${p}' isn't a ${choiceId} option for ${card.id}. Options: ${list(options)}.`);
+                }
+            }
+            if (picks.length === 0 || picks.length > choice.pick) {
+                problems.push(`${choiceId} takes ${choice.pick === 1 ? '1 pick' : `1 to ${String(choice.pick)} picks`}, not ${String(picks.length)}.`);
+            }
+        }
+        const period = choicePeriod(card, today);
+        if (period === null) {
+            problems.push(`${card.id} has picks on different schedules; edit the wallet by hand.`);
+        }
+        else {
+            const kept = held?.chosen?.period === period ? held.chosen.picks : {};
+            fields.chosen = {
+                period,
+                picks: { ...kept, ...input.picks },
+            };
+        }
+    }
+    return problems.length > 0 ? problems.join('\n') : fields;
+}
+const applyFields = (held, f) => WalletCardSchema.parse({
+    ...held,
+    ...(f.checkout_label === undefined
+        ? {}
+        : { checkout_label: f.checkout_label }),
+    ...(f.anniversary === undefined ? {} : { anniversary: f.anniversary }),
+    ...(f.chosen === undefined ? {} : { chosen: f.chosen }),
+    ...(f.activated === undefined ? {} : { activated: f.activated }),
+});
+async function attempt(task) {
+    try {
+        return await task();
+    }
+    catch (e) {
+        return failed(e instanceof Error ? e.message : String(e));
+    }
+}
+const noWallet = (file) => `No wallet at ${file} yet. Add a card first to create it.`;
+export function addCard(file, catalog, input, today) {
+    return attempt(async () => {
+        const card = findCatalogCard(catalog, input.id, today);
+        if (typeof card === 'string')
+            return failed(card);
+        const { text, wallet } = await readWalletText(file);
+        if (wallet?.cards.some((c) => c.id === card.id)) {
+            return failed(`${card.id} is already in the wallet. Update it instead.`);
+        }
+        const fields = fieldsFor(card, null, input, today);
+        if (typeof fields === 'string')
+            return failed(fields);
+        const held = applyFields(WalletCardSchema.parse({ id: card.id }), fields);
+        const expected = wallet
+            ? { ...wallet, cards: [...wallet.cards, held] }
+            : WalletSchema.parse({ cards: [held] });
+        await commitWalletText(file, addCardText(text, { id: card.id, ...fields }), expected);
+        return {
+            ok: true,
+            wallet: expected,
+            created: text === null,
+            notes: setupNotes(catalog, expected, held, today),
+        };
+    });
+}
+export function updateCard(file, catalog, input, today) {
+    return attempt(async () => {
+        const { text, wallet } = await readWalletText(file);
+        if (text === null || wallet === null)
+            return failed(noWallet(file));
+        const held = wallet.cards.find((c) => c.id === input.id);
+        const card = catalog.cards.find((c) => c.id === input.id);
+        if (!held || !card) {
+            return failed(`${input.id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
+        }
+        const fields = fieldsFor(card, held, input, today);
+        if (typeof fields === 'string')
+            return failed(fields);
+        if (Object.keys(fields).length === 0)
+            return failed('Nothing to change.');
+        const updated = applyFields(held, fields);
+        const expected = {
+            ...wallet,
+            cards: wallet.cards.map((c) => (c.id === held.id ? updated : c)),
+        };
+        await commitWalletText(file, updateCardText(text, held.id, fields), expected);
+        return {
+            ok: true,
+            wallet: expected,
+            created: false,
+            notes: setupNotes(catalog, expected, updated, today),
+        };
+    });
+}
+export function removeCard(file, _catalog, id) {
+    return attempt(async () => {
+        const { text, wallet } = await readWalletText(file);
+        if (text === null || wallet === null)
+            return failed(noWallet(file));
+        if (!wallet.cards.some((c) => c.id === id)) {
+            return failed(`${id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
+        }
+        if (wallet.cards.length === 1) {
+            return failed(`${id} is the last card in the wallet, and a wallet needs one. Add the new card first, then remove this one.`);
+        }
+        const expected = {
+            ...wallet,
+            cards: wallet.cards.filter((c) => c.id !== id),
+        };
+        await commitWalletText(file, removeCardText(text, id), expected);
+        return { ok: true, wallet: expected, created: false, notes: [] };
+    });
+}
+export function setMemberships(file, catalog, memberships) {
+    return attempt(async () => {
+        const known = knownMemberships(catalog);
+        const unknown = memberships.filter((m) => !known.includes(m));
+        if (unknown.length > 0) {
+            return failed(`No card rule uses ${unknown.map((m) => `'${m}'`).join(', ')}. Memberships earnrate knows: ${list(known)}.`);
+        }
+        const { text, wallet } = await readWalletText(file);
+        if (text === null || wallet === null)
+            return failed(noWallet(file));
+        const unique = [...new Set(memberships)];
+        const expected = { ...wallet, memberships: unique };
+        await commitWalletText(file, setMembershipsText(text, unique), expected);
+        return { ok: true, wallet: expected, created: false, notes: [] };
+    });
+}

package/dist/engine/recommend.js

@@ -2,6 +2,7 @@ import { resolveMerchant, resolveMerchantById } from "../merchants/resolve.js";
 import { evaluateCard, purchaseContext, } from "./evaluate.js";
 import { bonusStatus } from "./bonus.js";
 import { daysBetween } from "./periods.js";
+import { rotationGap } from "./rotation.js";
 import { cardValuation } from "./valuation.js";
 const EPSILON = 1e-9;
 export const STALE_AFTER_DAYS = 180;
@@ -327,6 +328,14 @@ export function recommend(catalog, wallet, purchase, merchant = resolveMerchant(
             : '';
         warnings.push(`Not every business takes ${NETWORK_NAMES[winner.card.network] ?? winner.card.network}.${fallback}`);
     }
+    for (const held of wallet.cards) {
+        const card = catalog.cards.find((c) => c.id === held.id);
+        const gap = card ? rotationGap(card, purchase.date) : null;
+        if (card && gap !== null) {
+            const name = held.checkout_label ?? card.name;
+            warnings.push(`${name}'s rotating categories for ${gap} aren't in earnrate's data yet, so it's ranked without them. If this purchase is in that period's categories, ${name} may earn more.`);
+        }
+    }
     const tie = tieNote(entries);
     if (tie)
         notes.push(tie);

package/dist/engine/rotation.js

@@ -0,0 +1,16 @@
+import { periodKey } from "./periods.js";
+// The period of the card's rotating categories that `date` falls in, when no
+// rule in the data covers it yet; null when it's covered or the card doesn't
+// rotate.
+export function rotationGap(card, date) {
+    for (const cap of card.caps) {
+        if (!cap.rotating || cap.period === 'cardmember_year')
+            continue;
+        const covered = card.rules.some((r) => r.cap === cap.id &&
+            (r.valid_from ?? '') <= date &&
+            date <= (r.valid_to ?? ''));
+        if (!covered)
+            return periodKey(cap.period, date, null);
+    }
+    return null;
+}

package/dist/engine/setup.js

@@ -0,0 +1,168 @@
+import { pickedCategories } from "./evaluate.js";
+import { daysBetween } from "./periods.js";
+import { rotationGap } from "./rotation.js";
+// Rules that start within this many days are worth activating now.
+const ACTIVATION_LOOKAHEAD_DAYS = 45;
+const ISSUER_NICKNAMES = {
+    amex: 'american express',
+    'bank-of-america': 'bofa boa bankofamerica',
+    'capital-one': 'capitalone',
+    citi: 'citibank',
+    usbank: 'us bank',
+    'wells-fargo': 'wf wellsfargo',
+    'td-bank': 'td',
+    column: 'bilt',
+};
+const words = (s) => s
+    .toLowerCase()
+    .replace(/\+/g, ' plus ')
+    .replace(/&/g, ' and ')
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length > 0);
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = row[0] ?? 0;
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const above = row[j] ?? 0;
+            row[j] = Math.min(above + 1, (row[j - 1] ?? 0) + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return row[b.length] ?? 0;
+}
+function matcher(card) {
+    const haystack = [
+        ...words(card.id),
+        ...words(card.name),
+        ...words(card.issuer),
+        ...words(ISSUER_NICKNAMES[card.issuer] ?? ''),
+    ];
+    const compact = haystack.join('');
+    return (token) => haystack.some((w) => w.startsWith(token)) ||
+        (token.length >= 4 && compact.includes(token)) ||
+        (token.length >= 5 &&
+            haystack.some((w) => editDistance(w, token) <= (token.length >= 8 ? 2 : 1)));
+}
+function needsAnniversary(card) {
+    return (card.caps.some((c) => c.period === 'cardmember_year') ||
+        card.rules.some((r) => typeof r.cap === 'object' && r.cap.period === 'cardmember_year'));
+}
+function activationRules(card, today) {
+    return card.rules
+        .filter((r) => r.requires?.activation === true &&
+        (r.valid_to === undefined || r.valid_to >= today) &&
+        (r.valid_from === undefined ||
+            daysBetween(today, r.valid_from) <= ACTIVATION_LOOKAHEAD_DAYS))
+        .map((r) => r.id);
+}
+export function membershipsUsed(card) {
+    return [
+        ...new Set(card.rules.flatMap((r) => r.requires?.membership === undefined ? [] : [r.requires.membership])),
+    ];
+}
+export function knownMemberships(catalog) {
+    return [...new Set(catalog.cards.flatMap(membershipsUsed))].sort();
+}
+export function cardInfo(card, wallet, today) {
+    return {
+        id: card.id,
+        name: card.name,
+        issuer: card.issuer,
+        network: card.network,
+        currency: card.currency,
+        annualFee: card.annual_fee ?? null,
+        business: card.business,
+        onlyAt: card.only_at ?? null,
+        held: wallet?.cards.some((c) => c.id === card.id) ?? false,
+        choices: card.choices.map((c) => ({
+            id: c.id,
+            pick: c.pick,
+            period: c.period,
+            options: Object.keys(c.options),
+            default: c.default ?? null,
+        })),
+        memberships: membershipsUsed(card),
+        activation: activationRules(card, today),
+        needsAnniversary: needsAnniversary(card),
+    };
+}
+// Every word of the query has to match a word of the card's id, name or
+// issuer (as a prefix, or with a typo or two in a long word). With no full
+// match, the cards matching the most words come back instead.
+export function searchCards(catalog, query, wallet, today) {
+    const tokens = words(query);
+    const scored = catalog.cards.map((card) => {
+        const matches = matcher(card);
+        return { card, score: tokens.filter((t) => matches(t)).length };
+    });
+    const byShortestId = (a, b) => words(a.card.id).length - words(b.card.id).length ||
+        a.card.id.localeCompare(b.card.id);
+    const full = scored.filter((s) => s.score === tokens.length);
+    const best = Math.max(0, ...scored.map((s) => s.score));
+    const exact = full.length > 0;
+    const chosen = exact
+        ? full.sort(byShortestId)
+        : best === 0
+            ? []
+            : scored
+                .filter((s) => s.score === best)
+                .sort(byShortestId)
+                .slice(0, 5);
+    return {
+        cards: chosen.map((s) => cardInfo(s.card, wallet, today)),
+        exact,
+    };
+}
+const list = (ids) => ids.join(', ');
+// What a card in the wallet still needs before its answers are right.
+export function setupNotes(catalog, wallet, held, today) {
+    const card = catalog.cards.find((c) => c.id === held.id);
+    if (!card)
+        return [];
+    const notes = [];
+    const name = held.checkout_label ?? card.name;
+    const { picked, staleChoice } = pickedCategories(card, held, today);
+    for (const choice of card.choices) {
+        const current = held.chosen?.picks[choice.id] !== undefined &&
+            (staleChoice === null || choice.period === 'until_changed');
+        if (current)
+            continue;
+        const options = list(Object.keys(choice.options));
+        notes.push({
+            kind: 'pick',
+            text: choice.default && picked.has(choice.id)
+                ? `${name}'s ${choice.id} pick is assumed to be ${list(choice.default)}, the default. Set it if a different one was picked (${String(choice.pick)} of: ${options}).`
+                : `${name} needs its ${choice.id} pick for this period (${String(choice.pick)} of: ${options}). Until then those categories earn the base rate.`,
+        });
+    }
+    const missing = membershipsUsed(card).filter((m) => !wallet.memberships.includes(m));
+    if (missing.length > 0) {
+        notes.push({
+            kind: 'membership',
+            text: `Some of ${name}'s rates need a membership: ${list(missing)}. Add any that apply to the wallet's memberships.`,
+        });
+    }
+    const toActivate = activationRules(card, today).filter((id) => !held.activated.includes(id));
+    if (toActivate.length > 0) {
+        notes.push({
+            kind: 'activation',
+            text: `${name} has rates that apply only once activated with the issuer: ${list(toActivate)}. Mark the ones already activated.`,
+        });
+    }
+    if (needsAnniversary(card) && held.anniversary === undefined) {
+        notes.push({
+            kind: 'anniversary',
+            text: `${name} has a cap that resets on the card's anniversary. Add the anniversary (MM-DD) so it can be tracked.`,
+        });
+    }
+    const gap = rotationGap(card, today);
+    if (gap !== null) {
+        notes.push({
+            kind: 'rotation',
+            text: `${name}'s rotating categories for ${gap} aren't in earnrate's data yet.`,
+        });
+    }
+    return notes;
+}

package/dist/engine/wallet-summary.js

@@ -1,6 +1,7 @@
 import { bonusStatus } from "./bonus.js";
 import { pickedCategories } from "./evaluate.js";
 import { daysBetween, periodKey } from "./periods.js";
+import { rotationGap } from "./rotation.js";
 import { STALE_AFTER_DAYS } from "./recommend.js";
 import { cardValuation } from "./valuation.js";
 function capSummaries(card, held, today) {
@@ -54,6 +55,7 @@ export function walletSummary(catalog, wallet, today) {
             lastVerified: card.last_verified,
             verifiedBy: card.verified_by,
             dataIsStale: daysBetween(card.last_verified, today) > STALE_AFTER_DAYS,
+            rotationGap: rotationGap(card, today),
             caps: capSummaries(card, held, today),
             chosen: held.chosen
                 ? {

package/dist/mcp/schemas.js

@@ -103,6 +103,7 @@ export const WalletSummarySchema = z.object({
         lastVerified: z.string(),
         verifiedBy: z.string(),
         dataIsStale: z.boolean(),
+        rotationGap: z.string().nullable(),
         caps: z.array(z.object({
             key: z.string(),
             rules: z.array(z.string()),
@@ -172,3 +173,48 @@ export const OfferComparisonSchema = z.object({
     withoutOffer: z.array(z.string()),
     notes: z.array(z.string()),
 });
+export const CardSearchSchema = z.object({
+    exact: z.boolean(),
+    cards: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        issuer: z.string(),
+        network: CardNetwork,
+        currency: z.string(),
+        annualFee: z.number().nullable(),
+        business: z.boolean(),
+        onlyAt: z.array(z.string()).nullable(),
+        held: z.boolean(),
+        choices: z.array(z.object({
+            id: z.string(),
+            pick: z.number(),
+            period: z.enum([
+                'month',
+                'quarter',
+                'calendar_year',
+                'until_changed',
+            ]),
+            options: z.array(z.string()),
+            default: z.array(z.string()).nullable(),
+        })),
+        memberships: z.array(z.string()),
+        activation: z.array(z.string()),
+        needsAnniversary: z.boolean(),
+    })),
+});
+export const WalletChangeSchema = z.object({
+    message: z.string(),
+    created: z.boolean(),
+    cardIds: z.array(z.string()),
+    memberships: z.array(z.string()),
+    notes: z.array(z.object({
+        kind: z.enum([
+            'pick',
+            'membership',
+            'activation',
+            'anniversary',
+            'rotation',
+        ]),
+        text: z.string(),
+    })),
+});

package/dist/mcp/server.js

@@ -1,19 +1,22 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { MCP_SERVER_NAME } from "../brand.js";
+import { formatCardInfo, formatNotes } from "../cli/cards.js";
 import { formatRecommendation } from "../cli/format.js";
 import { formatOffers } from "../cli/offers.js";
 import { walletProblems } from "../data/integrity.js";
 import { loadWallet } from "../data/load.js";
 import { withWalletLock, writeBonusSpent, writeCapBooking, } from "../data/wallet-write.js";
+import { addCard, removeCard, setMemberships, updateCard, } from "../data/wallet-setup.js";
 import { bonusStatus, countsTowardBonus } from "../engine/bonus.js";
 import { compareOffers } from "../engine/offers.js";
 import { capBooking } from "../engine/record.js";
 import { recommend } from "../engine/recommend.js";
+import { knownMemberships, searchCards } from "../engine/setup.js";
 import { walletSummary } from "../engine/wallet-summary.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { IsoDate } from "../schema/common.js";
-import { MerchantResolutionSchema, RecommendationSchema, OfferComparisonSchema, RecordResultSchema, WalletSummarySchema, } from "./schemas.js";
+import { CardSearchSchema, MerchantResolutionSchema, RecommendationSchema, OfferComparisonSchema, RecordResultSchema, WalletChangeSchema, WalletSummarySchema, } from "./schemas.js";
 const Merchant = z
     .string()
     .min(1)
@@ -23,13 +26,16 @@ const ChannelInput = z
     .optional()
     .describe('How the purchase is made. Omit if unknown; the answer says what it assumed.');
 const DateInput = IsoDate.optional().describe('Purchase date, YYYY-MM-DD. Defaults to today.');
+const INSTRUCTIONS = `earnrate picks which of the user's credit cards earns the most for a purchase. Its wallet lists the cards they hold by product id, never card numbers; never ask for card numbers, expiry dates or security codes.
+
+If a tool says there's no wallet yet, ask the user which cards they have, find each with search_cards, and add it with add_card. add_card and update_card reply with what a card still needs, such as category picks, memberships like Amazon Prime, or activated bonus categories. Ask the user about those and set them with update_card or set_memberships.`;
 const fail = (text) => ({
     content: [{ type: 'text', text }],
     isError: true,
 });
 const dollars = (n) => `$${n.toLocaleString('en-US', { maximumFractionDigits: 2 })}`;
 export function createEarnrateServer(deps) {
-    const server = new McpServer({ name: MCP_SERVER_NAME, version: deps.version });
+    const server = new McpServer({ name: MCP_SERVER_NAME, version: deps.version }, { instructions: INSTRUCTIONS });
     const { catalog } = deps;
     // Read on every call, so edits to the wallet file apply without a restart.
     async function wallet() {
@@ -38,6 +44,9 @@ export function createEarnrateServer(deps) {
             loaded = await loadWallet(deps.walletFile);
         }
         catch (e) {
+            if (e instanceof Error && 'code' in e && e.code === 'ENOENT') {
+                return `There's no wallet yet (${deps.walletFile}). Ask the user which credit cards they have, find each one with search_cards, and add it with add_card.`;
+            }
             return `Couldn't read the wallet at ${deps.walletFile}: ${e instanceof Error ? e.message : String(e)}`;
         }
         const problems = walletProblems(loaded, catalog);
@@ -145,13 +154,16 @@ export function createEarnrateServer(deps) {
                 ? `; chosen categories for ${c.chosen.period}${c.chosen.current ? '' : ' (out of date)'}`
                 : '';
             const onlyAt = c.onlyAt ? `; works only at ${c.onlyAt.join(', ')}` : '';
+            const rotation = c.rotationGap === null
+                ? ''
+                : `; rotating categories for ${c.rotationGap} not in earnrate yet`;
             const b = c.bonus;
             const bonus = b?.state === 'open' && b.spend !== null
                 ? `; welcome bonus ${dollars(b.spent)} of ${dollars(b.spend)} spent, due ${b.deadline ?? ''}`
                 : b
                     ? `; welcome bonus ${b.state}`
                     : '';
-            return `- ${c.checkoutLabel ?? c.cardName} (${c.cardId}): ${c.currency} at ${String(c.centsPerUnit)}¢${caps.length > 0 ? `; ${caps.join(', ')}` : ''}${chosen}${onlyAt}${bonus}`;
+            return `- ${c.checkoutLabel ?? c.cardName} (${c.cardId}): ${c.currency} at ${String(c.centsPerUnit)}¢${caps.length > 0 ? `; ${caps.join(', ')}` : ''}${chosen}${rotation}${onlyAt}${bonus}`;
         });
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
@@ -304,5 +316,149 @@ export function createEarnrateServer(deps) {
             structuredContent: output,
         };
     }));
+    const CardId = z
+        .string()
+        .min(1)
+        .describe('The card id from search_cards, e.g. chase-sapphire-preferred.');
+    const cardFields = {
+        checkoutLabel: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('How the card appears at checkout or in a browser wallet, e.g. "Amex Gold". Optional.'),
+        picks: z
+            .record(z.string(), z.array(z.string()).min(1))
+            .optional()
+            .describe('For cards where the cardholder picks bonus categories: choice id → option ids, from search_cards, e.g. {"five-percent": ["tv-internet-streaming", "fast-food"]}. Saved for the current period. Ask the user; don\'t guess.'),
+        anniversary: z
+            .string()
+            .regex(/^\d{2}-\d{2}$/)
+            .optional()
+            .describe("The account's anniversary as MM-DD, for cards whose cap resets on it."),
+        activated: z
+            .array(z.string())
+            .optional()
+            .describe('Rule ids the user has activated with the issuer, such as rotating categories. Replaces the current list.'),
+    };
+    // A card change reports what that card still needs; other changes don't.
+    function changed(result, message, cardChange = true) {
+        if (!result.ok)
+            return fail(result.error);
+        const output = {
+            message,
+            created: result.created,
+            cardIds: result.wallet.cards.map((c) => c.id),
+            memberships: result.wallet.memberships,
+            notes: result.notes,
+        };
+        const text = [
+            message,
+            `Wallet: ${output.cardIds.join(', ')}.`,
+            ...(cardChange ? [formatNotes(result.notes)] : []),
+        ].join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: output,
+        };
+    }
+    const cardInput = (args) => ({
+        id: args.cardId,
+        ...(args.checkoutLabel === undefined
+            ? {}
+            : { checkoutLabel: args.checkoutLabel }),
+        ...(args.picks === undefined ? {} : { picks: args.picks }),
+        ...(args.anniversary === undefined
+            ? {}
+            : { anniversary: args.anniversary }),
+        ...(args.activated === undefined ? {} : { activated: args.activated }),
+    });
+    const cardName = (id) => catalog.cards.find((c) => c.id === id)?.name ?? id;
+    server.registerTool('search_cards', {
+        title: 'Search cards',
+        description: 'Finds credit cards in earnrate\'s catalog by name or issuer, e.g. "sapphire", "amex gold" or "bofa". Returns each card\'s id (for add_card), network, annual fee, whether it\'s already in the wallet, and what it needs set up: category picks and their options, memberships, activations. Leave the query out to list every card. US cards only.',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe('Card name or issuer, as the user said it.'),
+        }),
+        outputSchema: CardSearchSchema,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ query }) => {
+        const held = await loadWallet(deps.walletFile).catch(() => null);
+        const result = searchCards(catalog, query ?? '', held, deps.today());
+        const header = result.exact
+            ? ''
+            : result.cards.length > 0
+                ? 'No card matched every word. Closest:\n'
+                : `No card matched "${query ?? ''}". earnrate covers ${String(catalog.cards.length)} US cards; list them all by leaving the query out.`;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: header + result.cards.map(formatCardInfo).join('\n'),
+                },
+            ],
+            structuredContent: result,
+        };
+    });
+    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.",
+        inputSchema: z.object({ cardId: CardId, ...cardFields }),
+        outputSchema: WalletChangeSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, (args) => withWalletLock(deps.walletFile, async () => {
+        const result = await addCard(deps.walletFile, catalog, cardInput(args), deps.today());
+        return changed(result, `Added ${cardName(args.cardId)} (${args.cardId})${result.ok && result.created ? `, starting a new wallet at ${deps.walletFile}` : ''}.`);
+    }));
+    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 or activated categories. Picks for the current period are merged with the ones already saved. Use it when the user picks new categories, such as each quarter on U.S. Bank Cash+.',
+        inputSchema: z.object({ cardId: CardId, ...cardFields }),
+        outputSchema: WalletChangeSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, (args) => withWalletLock(deps.walletFile, async () => changed(await updateCard(deps.walletFile, catalog, cardInput(args), deps.today()), `Updated ${cardName(args.cardId)} (${args.cardId}).`)));
+    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.",
+        inputSchema: z.object({ cardId: CardId }),
+        outputSchema: WalletChangeSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, ({ cardId }) => withWalletLock(deps.walletFile, async () => changed(await removeCard(deps.walletFile, catalog, cardId), `Removed ${cardName(cardId)} (${cardId}).`, false)));
+    const memberships = knownMemberships(catalog);
+    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. Replaces the whole list, so include the ones to keep.",
+        inputSchema: z.object({
+            memberships: z
+                .array(z.enum(memberships))
+                .describe(`Every membership the user has. Known: ${memberships.join(', ')}.`),
+        }),
+        outputSchema: WalletChangeSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, (args) => withWalletLock(deps.walletFile, async () => changed(await setMemberships(deps.walletFile, catalog, args.memberships), args.memberships.length > 0
+        ? `Memberships set to ${args.memberships.join(', ')}.`
+        : 'Memberships cleared.', false)));
     return server;
 }

package/dist/schema/card.js

@@ -12,7 +12,13 @@ export const CapSchema = z.strictObject({
     period: CapPeriod,
     then_rate: z.number().nonnegative(),
 });
-export const SharedCapSchema = CapSchema.extend({ id: KebabId });
+export const SharedCapSchema = CapSchema.extend({
+    id: KebabId,
+    // Rotating categories (Freedom Flex): every rule on this cap covers one
+    // dated period, and a period with no rule means the issuer's categories
+    // aren't in the data yet, not that there's no bonus.
+    rotating: z.literal(true).optional(),
+});
 const hasAny = (m) => Object.values(m).some((v) => v === true || (v !== undefined && v.length > 0));
 // Kinds combine with AND, values within a kind with OR: `{ merchants:
 // [lyft], categories: [transit] }` is a Lyft purchase that codes as transit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "earnrate",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Picks the best credit card from your wallet for a merchant, and explains why",
   "keywords": [
     "credit cards",
@@ -21,7 +21,7 @@
   "mcpName": "io.github.cwasley/earnrate",
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "bin": {
     "earnrate": "./dist/cli/bin.js",