Merge pull request #1077 from MaxTomahawk/feat/battle-menu-auxiliary

feat(mods): add battle menu auxiliary action

docs/modding.md

@@ -340,6 +340,18 @@ failure as a failed first checkpoint rather than claiming restart safety.
 See RFC 0003, RFC 0004, RFC 0005, and RFC 0006 for exact contracts and error
 codes.
 
+At that same settled supported wild/trainer decision boundary, a tool may claim
+START through `battle.menu_auxiliary`. It receives `(next, game, context)`, where
+`context` is the data-only `{ kind = "wild" }` or `{ kind = "trainer" }`; it
+never receives the live battle controller. Return `true` to consume START after
+opening source-owned UI, or call `next(game, context)` to allow lower-priority
+handlers. With no handler, START remains inert. Ordinary encounters and the
+validated built-in scripted battle origins described by RFC 0005 are eligible;
+opaque scripts, link/Safari/ghost/demo battles, action queues,
+animation/messages, forced choices, and every phase that cannot safely be
+checkpointed remain excluded. Exceptions are contained by normal hook isolation
+and fall through without advancing a turn.
+
 ## Developer console
 
 Boot with developer mode on to unlock the in-game console and hot-reload

docs/rfcs/0007-battle-menu-auxiliary-actions.md

@@ -0,0 +1,46 @@
+# RFC 0007: Battle menu auxiliary actions
+
+## Status
+
+Proposed.
+
+## Problem
+
+Tool mods can inspect/capture a persistent checkpoint only at a settled
+ordinary wild/trainer player-decision boundary. Before this proposal, that
+boundary had no public semantic input/action seam: `BattleState` consumed the
+command loop directly. A mod could reach it only through private battle/input
+internals, which would be unsafe and incompatible with controller/touch input.
+
+## Contract
+
+`mod.hooks:wrap("battle.menu_auxiliary", callback)` is called only when START
+is pressed at the existing checkpoint-safe player-decision boundary. The
+callback signature is:
+
+```lua
+function callback(next, game, context)
+  -- context is { kind = "wild" } or { kind = "trainer" }
+  -- return true after claiming START, otherwise return next(game, context)
+end
+```
+
+The context is data-only. No live battle controller, input object, serializer,
+or restoration primitive is exposed. A `true` result consumes START for that
+fixed step without selecting a battle command. With no installed handler,
+START is inert exactly as before. Hook priorities and error isolation are the
+existing generic wrapper semantics: a throwing handler is skipped and cannot
+advance battle state.
+
+The engine reuses the same internal safety predicate as battle checkpoint
+capture. Link, Safari, ghost/demo, unsupported origins, scripts, queues,
+animations, messages, forced replacement/locked actions, and unsettled HP or
+status presentation never invoke the hook.
+
+## Compatibility and verification
+
+The call is additive and no-op with no handler. ROM-free engine tests prove
+wild/trainer delivery, cursor/turn preservation, and unsafe-phase refusal;
+the mod-SDK fixture proves a loaded mod can consume the semantic action using
+only its public hook facade. `gate_hooks` automatically includes the new call
+site in no-mod parity coverage.