Update Cards

Step 1: Capture Baseline IR Count

Before making any changes, record how many cards currently have IR data. Write a temp script (NEVER use node -e on Windows):

// .temp/baseline_ir_count.cjs
const Database = require('better-sqlite3');
const db = new Database('public/data/mtg_cards.db');
const ir = db.prepare('SELECT COUNT(*) as c FROM cards WHERE behavior_json IS NOT NULL').get();
const total = db.prepare('SELECT COUNT(*) as c FROM cards').get();
console.log(JSON.stringify({ ir_count: ir.c, total_cards: total.c }));
db.close();

Save these numbers for verification in Step 6.

Step 2: Hydrate — Pull New Cards from Scryfall

Run the hydrate script in delta mode (default):

python scripts/hydrate_cards.py

If --refresh-errata was requested:

python scripts/hydrate_cards.py --refresh-errata

If --dry-run was requested:

python scripts/hydrate_cards.py --dry-run

Check the output:

• Look for the [DELTA] line showing how many new cards were found
• If New: 0 and no errata, report "Already up to date — no new cards found." and STOP

If --hydrate-only was requested: Report the delta stats and STOP here.

Step 3: Export New Cards

Export only the new cards (from the delta file) to cards_raw.json:

python scripts/export_cards_for_ai.py --from-delta

Verify: Check that cards_raw.json was written and contains the expected number of cards.

Step 4: Compile IR for New Cards (Claude Code — FREE)

Do NOT use compile_with_ai.py (that calls the Claude API and costs money). Instead, compile IR directly using Claude Code.

4a: Load Reference Material

Read these files to understand the IR format and available actions:

1. docs/AI_CARD_COMPILATION.md — The full compilation pipeline docs, including IR schema, capability matrix workflow, and how to handle unknown actions
2. results/card_batches/_action_library_toc.md — Searchable index of all 1,212+ implemented action types, organized by category (P/T mods, counters, zone movement, draw, mana, combat, keywords, damage, tokens, search, conditionals, triggers, costs, special). Always search this before inventing a new action name.
3. capability_matrix.json — Machine-readable status of every action. Only use actions with status IMPLEMENTED or PARTIAL. Check the actions category for valid action types.
4. 3 example cards from cards_compiled.json — Look up Sol Ring (activated/mana ability), Beast Whisperer (triggered ability), and Swords to Plowshares (spell effect) to see canonical IR structure. Use a temp .cjs script to extract them (NEVER node -e on Windows).
5. cards_raw.json — The new cards to compile

Action lookup workflow:

1. Search _action_library_toc.md for your action name or a similar mechanic
2. Check capability_matrix.json to confirm status is IMPLEMENTED or PARTIAL
3. If not found, search src/batch/irExecutor.js for the closest existing handler
4. If a mechanic truly has no handler, use the closest existing action and note it

4b: Compile Cards in Batches

Process the new cards in chunks of ~20-30 at a time:

1. Read a chunk of cards from cards_raw.json
2. For each card, analyze its oracle_text and type_line
3. Generate the IR abilities array following the format from the example cards and docs
4. Write a temp script that merges the compiled cards into cards_compiled.json:

// .temp/merge_compiled_batch.cjs
const fs = require('fs');
const compiled = JSON.parse(fs.readFileSync('cards_compiled.json', 'utf-8'));
const newCards = {
  "card-uuid-here": {
    // full card object with ir field
  }
};
Object.assign(compiled.cards, newCards);
compiled.meta.total_cards = Object.keys(compiled.cards).length;
compiled.meta.last_updated = new Date().toISOString();
fs.writeFileSync('cards_compiled.json', JSON.stringify(compiled, null, 2));
console.log(`Merged ${Object.keys(newCards).length} cards. Total: ${compiled.meta.total_cards}`);

5. Run the merge script after each batch

Important compilation rules:

• Each compiled card must include ALL fields from cards_raw.json plus the ir field
• Add compiled_at timestamp and qa_status: "PENDING"
• Parse type_line into supertypes, card_types, subtypes arrays
• Only use action types found in capability_matrix.json or _action_library_toc.md
• For cards with no meaningful abilities (vanilla creatures, basic lands), use an empty abilities array []
• For keyword-only cards, use { "type": "KEYWORD", "keyword": "flying" } format
• Always include a meta block in the IR: { "engine_version": "2.0.0", "parsing_confidence": "HIGH" }

4c: Verify Compilation

After all batches are merged, verify the compiled count:

// .temp/verify_compilation.cjs
const compiled = require('./cards_compiled.json');
const delta = require('./delta_new_cards.json');
const newIds = delta.new_card_ids || [];
let found = 0, missing = [];
for (const id of newIds) {
  if (compiled.cards[id] && compiled.cards[id].ir) found++;
  else missing.push(id);
}
console.log(`Compiled: ${found}/${newIds.length}`);
if (missing.length > 0) console.log(`Missing:`, missing.slice(0, 10));

Step 5: Sync IR to SQLite

Push the newly compiled IR back to the SQLite database:

node scripts/sync_ir_to_sqlite.cjs

What happens:

• Reads cards_compiled.json
• UPDATEs only the behavior_json column for cards that have new IR
• Existing IR data is not touched

Step 5.5: Refresh Handler Registry

After syncing IR to SQLite, regenerate the handler registry to pick up any new handlers from newly compiled cards:

node scripts/generate_handler_registry.cjs

What happens:

• Re-scans irExecutor.js STEP_EXECUTORS for all handler definitions
• Deep-scans cards_compiled.json for action usage across all cards
• Cross-references scenario files for test coverage
• Regenerates docs/handler_registry.json, docs/handler_registry.md, docs/alias_map.md
• Reports: "Registry updated: X handlers, Y canonical, Z aliases"

Safety: This is a read-scan-write operation — it only reads source files and generates derived artifacts. No source data is modified. If the script detects fewer handlers than the previous run, it aborts without writing (guard against parse failures).

Step 6: Verify Data Integrity

Confirm that existing IR was preserved and new cards were added. Write a temp script:

// .temp/verify_integrity.cjs
const Database = require('better-sqlite3');
const db = new Database('public/data/mtg_cards.db');
const ir = db.prepare('SELECT COUNT(*) as c FROM cards WHERE behavior_json IS NOT NULL').get();
const total = db.prepare('SELECT COUNT(*) as c FROM cards').get();
const nullIr = db.prepare('SELECT COUNT(*) as c FROM cards WHERE behavior_json IS NULL').get();
const solRing = db.prepare("SELECT name, length(behavior_json) as ir_len FROM cards WHERE name='Sol Ring' LIMIT 1").get();
console.log('IR count:', ir.c);
console.log('Total cards:', total.c);
console.log('NULL IR:', nullIr.c);
console.log('Sol Ring check:', solRing);
db.close();

Verification checks:

1. IR count must NOT decrease from the baseline captured in Step 1
2. Total cards should have increased by the number of new cards
3. Sol Ring spot-check should still have IR data

Step 7: Report Summary

Print a summary like:

=== Card Database Update Complete ===
  New cards added: 305
  Cards with errata: 0
  Cards compiled: 305
  Compile errors: 0
  IR count before: 31,541
  IR count after: 31,846
  Total cards: 36,889
  Data integrity: VERIFIED

Error Handling

Key Files