Document Eagle battle and conquest flow (#8427)

docs/eagle0pedia/src/content/docs/commands/index.md

@@ -19,6 +19,7 @@ Source map for numeric command details:
 - Divine: divinable heroes are unaffiliated heroes with RecruitmentInfo.NotDivined; see src/main/scala/net/eagle0/eagle/library/actions/availability/AvailableDivineCommandsFactory.scala and src/main/scala/net/eagle0/eagle/library/actions/impl/command/DivineCommand.scala.
 - Issue Orders: order availability comes from src/main/scala/net/eagle0/eagle/library/actions/availability/AvailableIssueOrdersCommandFactory.scala; vassal order behavior comes from src/main/scala/net/eagle0/eagle/library/actions/impl/action/PerformVassalCommandsPhaseAction.scala, src/main/scala/net/eagle0/eagle/library/util/command_choice_helpers/CommandChoiceHelpers.scala, and src/main/scala/net/eagle0/eagle/library/util/command_choice_helpers/ExpandCommandSelector.scala.
 - Send Supplies: shipment scheduling comes from src/main/scala/net/eagle0/eagle/library/actions/impl/command/SendSuppliesCommand.scala; arrival comes from src/main/scala/net/eagle0/eagle/library/actions/impl/action/PerformProvinceMoveResolutionAction.scala and src/main/scala/net/eagle0/eagle/library/actions/impl/action/ShipmentArrivedAction.scala; timing/loss settings are src/main/resources/net/eagle0/eagle/settings.tsv fields turnsToResolveShipment=1 and shipSuppliesLoss=0.1.
+- Battle Aftermath Decision: availability comes from src/main/scala/net/eagle0/eagle/library/actions/availability/AvailableBattleAftermathDecisionCommandFactory.scala; selection comes from src/main/scala/net/eagle0/eagle/library/actions/impl/command/BattleAftermathDecisionCommand.scala; finalization comes from src/main/scala/net/eagle0/eagle/library/actions/impl/action/FinalizeAftermathAction.scala.
 -->
 
 ## Normal Command Phase Commands
@@ -558,8 +559,12 @@ Gift success is probabilistic. The chance is based on the province leader's Char
 
 <b>Vigor cost:</b> None.
 
-<b>Available when:</b> a battle has just ended.
+<b>Available when:</b> multiple allied attacking factions won the same province and Eagle needs to decide which claimant keeps it.
 
-<b>Effect:</b> Choose what to do after a battle. The command states whether the province can be kept, lists adjacent withdrawal provinces, shows surviving units, remaining decision makers, available supplies, and explanatory info text.
+<b>Effect:</b> Decide what your surviving claimant army does after a shared victory. If no ally has claimed the province yet, you may choose **Keep Province** and become the conqueror. If an ally has already claimed it, you must withdraw.
+
+Keeping the province finalizes conquest: your surviving non-fled heroes become the new ruling heroes, surviving battalions become the province battalions, support is reset to 0, province orders reset to **Entrust**, and non-fled defenders or former ruling heroes can become prisoners.
+
+Withdrawing sends your surviving units to an adjacent province as a moving army. You may take up to the gold and food your claimant army brought into the battle. The withdrawal army arrives next round and does not use the normal Send Supplies transit loss.
 
 <b>Selection:</b> choose whether to keep the province or withdraw. If withdrawing, choose destination province and supplies to take.

docs/eagle0pedia/src/content/docs/concepts/eagle-to-shardok/index.md

@@ -7,8 +7,11 @@ description: How strategic Eagle armies become tactical Shardok battles.
 Source map:
 - Movement resolution: src/main/scala/net/eagle0/eagle/library/actions/impl/action/PerformProvinceMoveResolutionAction.scala.
 - Battle setup phase: src/main/scala/net/eagle0/eagle/library/actions/impl/action/PerformHostileArmySetupAction.scala.
+- Uncontested conquest: src/main/scala/net/eagle0/eagle/library/actions/impl/action/PerformUncontestedConquestAction.scala.
 - Battle request creation: src/main/scala/net/eagle0/eagle/library/actions/impl/action/RequestBattlesAction.scala.
 - Tactical battle resolution back into Eagle: src/main/scala/net/eagle0/eagle/library/actions/impl/action/ResolveBattleAction.scala.
+- Province held/conquered outcomes: src/main/scala/net/eagle0/eagle/library/actions/impl/action/ProvinceHeldAction.scala and src/main/scala/net/eagle0/eagle/library/actions/impl/action/ProvinceConqueredAction.scala.
+- Multi-winner aftermath: src/main/scala/net/eagle0/eagle/library/actions/impl/action/MultiVictorBattleSetupAction.scala, src/main/scala/net/eagle0/eagle/library/actions/impl/command/BattleAftermathDecisionCommand.scala, and src/main/scala/net/eagle0/eagle/library/actions/impl/action/FinalizeAftermathAction.scala.
 - Battle aftermath decisions: src/main/scala/net/eagle0/eagle/library/actions/impl/action/FinalizeAftermathAction.scala and AutoResolveBattleAftermathAction.scala.
 -->
 
@@ -22,13 +25,25 @@ Because Eagle is simultaneous, multiple factions can send armies during the same
 
 ## Arrival
 
-When an army arrives, Eagle checks the destination province:
+When an army reaches its destination, the first question is whether it is friendly to the province's current ruler.
 
-- If there is no defending force, the attack may become an uncontested conquest.
-- If attackers and defenders are both present, Eagle prepares a Shardok battle.
+Friendly armies arrive during Province Move Resolution. Their heroes, battalions, gold, and food enter the destination province at that point.
+
+Hostile armies do not immediately enter the province. They are converted into hostile army groups later in the round, after player commands, with one group per attacking faction. Each group keeps the armies, units, supplies, and approach direction from the province it marched from.
+
+After hostile setup, Eagle checks for cases that do not need a tactical battle:
+
+- If a hostile army reaches an unruled province, the largest army group takes it during Uncontested Conquest. Ties are broken by troop power and then a deterministic random tie-breaker.
+- If a single attacking army is attacking and there is no defending army, Eagle can resolve the attack directly as a conquest.
 - If diplomacy or truces apply, armies may turn back before fighting.
 
-The player may also see attack or defense decision phases before a battle is requested.
+Otherwise, the player may see attack or defense decision phases before a battle is requested.
+
+## Attack and Defense Decisions
+
+Hostile army groups first wait for an attack decision. An attacking faction can choose whether to press the attack when the game asks for that decision.
+
+If an attack proceeds against a ruled province, the defender may need to choose a defending army. The chosen defenders become the province's defending army. If a fallback province is available, the defender may also need to choose where the army should flee or retreat if Shardok produces that outcome.
 
 ## Battle Creation
 
@@ -43,6 +58,8 @@ When Eagle creates a Shardok battle, it sends:
 
 Attackers in a normal province assault are trying to take the province. Defenders are trying to hold it or survive long enough for the attacker to fail.
 
+The battle food sent to Shardok is limited. Attackers bring up to one month of food consumption from their carried supplies. Defenders bring up to one month of food consumption from the province's food, and that food is removed from the province when the battle is created.
+
 ## Tactical Resolution
 
 The battle then runs in Shardok. Players place units, move, attack, use profession commands, spend Action Points, and try to satisfy their victory conditions.
@@ -53,22 +70,64 @@ See [Shardok battles](/concepts/shardok-battles/) for the tactical overview and
 
 ## Returning To Eagle
 
-When Shardok reports a result, Eagle applies it to the strategic world.
+When Shardok reports a result, Eagle applies battle consequences before deciding who owns the province.
 
-The result can change:
+The battle result can change:
 
-- Province ownership.
 - Hero locations and status.
 - Battalion size and survival.
 - Captured heroes and prisoners.
 - Supplies brought by attacking armies.
 - Province devastation.
 - Quest progress and battle history.
+- Prestige. Winners gain battle prestige; losers lose battle prestige.
+
+Battles add devastation to the battle province. Surviving units may return, flee, become outlaws, be secured, or be captured depending on the tactical result.
+
+Attackers' remaining gold and food are added to the battle province as part of battle resolution. If the defender holds the province, those supplies become part of the defended province. If an attacker later conquers it, the province changes hands with the supplies already present.
+
+## If The Defender Wins
+
+If the defending side wins, the province remains with its current ruler.
+
+Attackers who did not flee, become outlaws, or get otherwise secured may be captured by the defending faction. Captured attacker battalions can be destroyed. The defender receives a Province Held result and any captured heroes become prisoners in the province.
+
+## If One Attacker Wins
+
+If exactly one attacking faction wins, that faction conquers the province directly.
+
+Conquest does several things at once:
+
+- Sets the conquering faction as the province's ruler.
+- Removes the old ruling-faction heroes from the province.
+- Adds the surviving non-fled conquering heroes as the new ruling-faction heroes.
+- Replaces the province battalions with the surviving conquering battalions.
+- Clears the defending army.
+- Sets province support to 0.
+- Resets province orders to **Entrust**.
+- Captures non-fled defenders and former ruling heroes as prisoners.
+- Clears the old owner's focus province if this province was their focus.
+- Clears recon on the province for all factions.
+
+Prisoners already held in the conquered province can also be freed. Prisoners from the conquering faction join the new rulers at freed-prisoner loyalty. Prisoners from allied factions are sent toward the closest allied province when possible; if no allied province exists, they can become outlaws.
+
+## If Multiple Allied Attackers Win
+
+If multiple attacking factions win together, Eagle cannot automatically know who should keep the province. It creates a pending conquest decision for the surviving attacking claimants.
+
+During Battle Aftermath, each claimant may be asked to choose:
+
+- **Keep Province:** claim the province. Only one claimant can keep it.
+- **Withdraw:** leave for an adjacent province, taking up to the gold and food that claimant brought into the battle.
+
+If an ally has already claimed the province, the remaining claimants must withdraw. If only one undecided claimant remains and nobody has claimed the province, Eagle auto-resolves that claimant as keeping it.
+
+When aftermath finalizes, the keeper conquers the province through the same conquest rules as a single attacking winner. Withdrawing claimants become incoming armies to their chosen adjacent provinces, arriving next round with the gold and food they chose to take. These aftermath withdrawals do not apply shipment transit loss.
 
 ## Aftermath
 
-Some battle results need another Eagle decision before the round can continue.
+Some battle results need another Eagle decision before the round can continue. This happens mainly when multiple allied attackers win the same province or when captured heroes create follow-up handling decisions.
 
-If the defender wins, the province is held. If a single attacker wins, the province can be conquered directly. If multiple allied attackers win together, Eagle may ask who keeps the province and what happens to the remaining forces.
+Battle Aftermath happens after tactical results return but before the strategic round fully moves on. It is not a second Shardok battle; it is Eagle deciding ownership, withdrawals, supplies, and captured-hero consequences from the battle that already ended.
 
-Captured heroes can also create follow-up decisions. These happen in the Battle Aftermath phase, after the tactical result has returned but before the strategic round fully moves on.
+Captured heroes can create separate follow-up decisions after this. Those decisions determine what the capturing faction does with the hero now that the battle result has placed them in custody.