feat(ai): ground deck suggestions in the deck's actual plan (#295)

[untraceablez]

Closes #295. With #294 merged, this closes out the Decks & EDH tooling milestone.

Why the picks were generic

The complaint in #295 is that AI suggestions return goodstuff rather than cards that fit the deck. The grounding explains it — three defects, each fixed here:

1. The commander's ability was truncated to its first line.

scan.commander_text = (oracle or "").split("\n")[0][:160]

A commander's engine is routinely on line two or three — an activated ability, a death trigger. For a large class of decks the model never saw the thing the deck is built around, then got asked to suggest cards that synergise with it. Now the full text, joined onto one line and bounded at 600 chars so a wall of reminder text can't crowd out the rest of the prompt.

2. Candidates were bare names. The model was asked to reason about synergy while being told only what the cards were called. Each candidate now arrives as Name — role | shared keywords | what it does.

3. The shortlist was arbitrary. Only so many candidates fit in a prompt, and the old code took list(pool.values())[:60] — the first 60 by oracle id. Most of the collection was never seen, and which part was seen had nothing to do with the deck. It's now the 40 best-fitting cards, scored with #294's deck_synergy. Fewer candidates, but the right ones — and the freed tokens pay for the annotations.

Prompt

Criteria are now explicitly ordered — the commander's specific ability, then the deck's themes and creature types, then thin roles — with an instruction not to suggest powerful cards that don't advance the plan, and a requirement that each reason name the specific interaction rather than calling something "solid value".

What deliberately did not change

Validation still covers the whole owned pool, not the shortlist. Narrowing what we send is exactly the change that could have accidentally narrowed what we accept, turning a legitimate pick into a "hallucination". There's a test for it: the model names a card that wasn't among the 40, and it still resolves.

llm._candidate_pool is deleted rather than left behind — the shortlist path replaced its only caller, and a second pool builder lying around is how two paths drift.

Verification

• 1285 passed, 100% coverage, 0 missed lines (11 new tests). ruff and mkdocs --strict clean. No migration.
• Tests assert against the actual prompt a fake client receives: that the commander's line-three ability is present, that a candidate line carries role and rules text, that a synergistic card survives into the shortlist when 60 generics compete for the slots, and that only keywords the deck cares about are spent on prompt space.
• One test I wrote failed and was right to: a commander that merely is an Elf but never mentions Elves does not make an Elf deck. That's now pinned as a negative case.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LxrePqFWyzQTcWaroSk4sH