Adv 2.0 D&D layer: Phases 1-8 + Phase 9 SP1+SP2

Combines all uncommitted D&D work into one checkpoint:

Phases 1-8 (per gogobee_dnd_session_summary.md):
- Race/class/stats system, !setup flow, !sheet, !respec
- d20-vs-AC combat with race/class passives, auto-migration
- XP/level-up, skill checks, NPC refund hooks
- Equipment slot mapping, rarity, !rest short/long
- Pre-arm active abilities, resource pools
- Bestiary, !roll/!stats/!level, onboarding DM
- Audit fixes A-I, flavor wiring under internal/flavor/
- Phase 8 weapon dice + armor AC tables (gogobee_equipment_appendix)

Phase 9 SP1 — spell system foundations:
- 79 SpellDefinitions (76 in-scope + 3 reaction-deferred)
- dnd_known_spells, dnd_spell_slots tables
- pending_cast / concentration_* columns on dnd_character
- Slot tables for Mage/Cleric/Ranger, DC + attack-bonus math
- Long-rest refreshes slots; respec wipes spell state
- Auto-grant default known list on !setup confirm and auto-migration

Phase 9 SP2 — !cast / !spells / !prepare commands:
- Out-of-combat HEAL and UTILITY resolve immediately
- Damage/control/buff queue as pending_cast for next combat
- Audit-style save-then-debit, slot refund on save failure
- !cast --drop, concentration supersession, prep-cap enforcement
- Reaction spells refused with Phase 11 note

SP3 (combat-time resolution of pending_cast) and SP4 (full prep/learn
tests) are next. Build clean, full test suite green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

internal/plugin/dnd_onboarding.go

@@ -0,0 +1,73 @@
+package plugin
+
+import (
+	"fmt"
+	"log/slog"
+
+	"gogobee/internal/flavor"
+	"maunium.net/go/mautrix/id"
+)
+
+// One-shot onboarding DM fired the first time a legacy player encounters
+// the new D&D layer. Triggered from ensureDnDCharacterForCombat at the
+// moment of fresh auto-migration; suppressed for genuinely new players
+// (combat_level <= 1) since the message frames around "previous players".
+
+// dndLegacyMinLevel — players with combat_level at or above this are
+// considered "legacy players" who deserve the onboarding spiel. Anyone
+// at L1 is brand new and gets the standard !setup nudge instead.
+const dndLegacyMinLevel = 2
+
+// maybeSendDnDOnboarding sends the welcome DM iff the player has visible
+// legacy adventure progress AND hasn't been onboarded before. The
+// OnboardingSent flag survives draft cancellation, !respec, and any other
+// state mutation — once a player has seen the welcome, they never see it
+// again. Logs and continues on send failure (DM is best-effort, never blocks combat).
+func (p *AdventurePlugin) maybeSendDnDOnboarding(userID id.UserID, advChar *AdventureCharacter, dnd *DnDCharacter) {
+	if advChar == nil || advChar.CombatLevel < dndLegacyMinLevel {
+		return
+	}
+	if dnd == nil || dnd.OnboardingSent {
+		return
+	}
+	// Skip entirely if there's no Matrix client — tests construct empty
+	// AdventurePlugin{} and we shouldn't write to the DB on a nil-send.
+	if p == nil || p.Client == nil {
+		return
+	}
+	msg := dndOnboardingText(advChar.CombatLevel, dnd.Level)
+	if err := p.SendDM(userID, msg); err != nil {
+		slog.Error("dnd: onboarding DM failed", "user", userID, "err", err)
+		// Don't mark as sent if delivery failed — they should get a chance
+		// on their next combat. Send failures here are typically transient.
+		return
+	}
+	dnd.OnboardingSent = true
+	if err := SaveDnDCharacter(dnd); err != nil {
+		slog.Error("dnd: persist onboarding flag", "user", userID, "err", err)
+	}
+}
+
+func dndOnboardingText(oldLevel, newLevel int) string {
+	prelude := ""
+	if line := flavor.Pick(flavor.ExpeditionStart); line != "" {
+		prelude = "_" + line + "_\n\n"
+	}
+	return prelude + fmt.Sprintf(`Hi there! Welcome to the new Adventure game!
+
+We shamelessly cribbed.. aimed for feature parity with our competitors.
+And the result is this..! and adventure game with most of the best Dungeons & Drag-
+
+"AHEM!" *TwinBee glances at the Pinkerton agent in the corner of the room.
+
+..d20 System mechanics ready for you to explore!
+
+As a result of these amazing and entirely necessary changes that weren't done at the whim of a bored engineer.. the level system has changed. But no worries! We spent hours coming up with an algorithm that would ensure each player arrives at a level that is fully representative of their level under the previous system (..by dividing your previous level by five).
+
+Your previous level **%d** is now Adv 2.0 level **%d**.
+
+Enjoy!
+
+Type !setup to get your character situated under this hot new and legally distinct system.`,
+		oldLevel, newLevel)
+}