Working on Plugins: Section Design

Both WASM plugins (plugins/*/parser/) and API adapters (worker/src/adapters/) produce the same GameState shape: identity, summary, and sections. This skill covers how to design sections so they work well with the MCP tools and AI consumers.

For the ndjson contract, WASM runtime, and plugin build system, see docs/plugins.md. For API adapter architecture, see docs/adapters.md.

Overview Section (Required)

get_save embeds one section's data as the overview in its response. It picks the first match from this list:

character_overview → player_summary → overview → summary

Every plugin MUST produce a section matching one of these names. If none match, get_save falls back to the first section alphabetically — which may be a 200KB deck list or item dump.

The overview section is the AI's first look at the save. It should contain enough context to answer "what is this character/save?" and guide the AI to the right detailed sections.

What belongs in the overview

• Identity: name, class, level, rank — whatever defines "who"
• Key stats: currency, progression milestones, win/loss record
• Index of available sections with pointers — deck names (not card lists), character names (not inventories), match list (not turn-by-turn logs)
• Anything that helps the AI decide which section to fetch next

What does NOT belong in the overview

• Full item lists, card lists, or inventories
• Turn-by-turn logs, match replays, or event histories
• Large nested objects that the AI won't use to route

Target: overview section < 15KB. A typical overview is 2-10KB.

Section Size Limits

If a section could exceed 80KB with realistic data, it MUST be split.

Progressive Disclosure Pattern

When a game has a large collection (decks, characters, items, matches), split into per-item sections with an index in the overview.

Pattern

overview section:
  decks: [{name: "Slivers", format: "Brawl", section: "deck:Slivers"}, ...]

deck:Slivers section:    (full card list, ~5KB)
deck:Control section:    (full card list, ~3KB)

The AI sees the index in the overview and fetches individual items as needed. This is how D2R shared stash (overview + tab1, tab2, ...) and MTGA (player_summary + deck:*, game:*) work.

When to split

Split when any of these are true:

• Collection has variable size controlled by the player (decks, blueprints, characters)
• A single collection item can be > 5KB (full card lists, turn-by-turn logs)
• Total collection could exceed 80KB (80 decks × 5KB = 400KB)

Section naming for per-item sections

Use prefix:human_readable_name — the AI requests sections by name, so readability matters.

deck:[HB] Slivers          (MTGA deck)
game:7a0be838-0033-4e16    (MTGA game log by matchId)
tab1, tab2, tab3            (D2R stash tabs)
character:Warrior            (per-character sections)

Stale section cleanup

The daemon sends allSectionNames in every PushSave message. The worker deletes any sections NOT in this list. Dynamic section names (deck:, game:) work correctly — the parser includes them all in the output, and the worker cleans up sections that no longer exist.

Section Descriptions

Section descriptions are the AI's guide for when to fetch a section. Write them as directives, not documentation.

Good (tells AI when/why to fetch):

"Deck list for [HB] Slivers (Brawl) — main deck, sideboard, and command zone cards"
"Turn-by-turn game log for match abc123 — use to analyze play sequencing and identify misplays"
"Aggregated character stats: resistances, magic find, FCR/FHR breakpoints — use to evaluate gear upgrades"

Bad (explains what it is, not when to use it):

"Contains the player's deck data"
"Game log information"
"Character statistics"

Existing Section Patterns by Game

Attribution (Required)

Every plugin must declare an [attribution] section in plugin.toml listing the third-party IP sources whose data it uses. The build pipeline reads this to embed legal disclaimers in views.

[attribution]
sources = ["wotc", "scryfall", "17lands"]

Valid source keys are defined in views/src/attributions.ts: wotc, scryfall, 17lands, blizzard, raiderio, ludeon, concernedape, kepler. To add a new source, add it to the SOURCES record in that file first.

The build fails if [attribution] is missing or uses an unknown key.

Checklist for New Plugins

• [ ] Overview section name matches OVERVIEW_SECTION_NAMES
• [ ] Overview section < 15KB with realistic data
• [ ] All sections < 80KB with realistic data
• [ ] Large collections use per-item sections with index in overview
• [ ] Section descriptions are AI-directive (when/why to fetch)
• [ ] Section data is always a JSON object (not array, string, or scalar)
• [ ] [attribution] declared in plugin.toml with valid source keys
• [ ] Tested with a real save file — measure actual section sizes