fix(mod-api): harden deferred trainer preparation

docs/modding.md

@@ -436,7 +436,7 @@ mod.hooks:wrap("trainer.before_battle", function(next, game, context, continue)
       continue({ playerPartyIndices = indices })
     end,
     onCancel = function()
-      continue()
+      continue({ cancel = true })
     end,
   })
   return true
@@ -444,7 +444,12 @@ end)
 ```
 
 Return `true` only when retaining `continue` for a later callback. Calling
-`continue()` uses the full save party; passing
+`continue({ cancel = true })` ends the encounter without constructing a battle;
+the normal encounter completion callback returns control to the overworld and
+no trainer-defeated state is written. A cancelled sight encounter is suppressed
+at the current player cell so it cannot immediately reopen; moving one cell or
+talking to the trainer permits a new challenge. Calling `continue()` uses the
+full save party; passing
 `{ playerPartyIndices = { 2, 4, 5 } }` uses those ordered, one-based party
 members for initial send, switching and forced replacement, exhaustion,
 experience traversal, and battle party displays. The continuation is one-shot.

docs/rfcs/0010-trainer-battle-party-scope.md

@@ -36,6 +36,7 @@ Add the guarded hook:
 mod.hooks:wrap("trainer.before_battle", function(next, game, context, continue)
   -- context = { trainerClass, partyIndex, mapId, npcId }
   -- Return true only when the battle has been deferred.
+  -- continue({ cancel = true }) returns without constructing a battle.
   -- Call continue() for the full save party, or:
   -- continue({ playerPartyIndices = { 2, 4, 5 } })
 end)
@@ -57,6 +58,13 @@ exhaustion/blackout checks, participant and EXP.ALL traversal, party counts,
 and party-ball presentation. Checkpoints preserve the index list and rebuild
 the same view before restoring battlers.
 
+`{ cancel = true }` ends a deferred encounter through its normal completion
+callback without constructing a battle or writing trainer-defeated state. A
+cancelled sight encounter is suppressed while the player remains on the same
+cell, preventing immediate reacquisition; moving or directly talking permits a
+new challenge. Cancellation is also one-shot; if supplied alongside a party
+index list, cancellation wins.
+
 The API sets no maximum, chooses no members, identifies no boss, and contains
 no scaling or challenge policy.