Clarify faction relationships and destruction (#8416)

* Clarify faction relationships and destruction

* Document free hero recruitment states

* Clarify traveler and outlaw free heroes

* Clarify faction destruction criteria

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

@@ -5,23 +5,78 @@ description: Reference for Eagle factions, leaders, prestige, diplomacy, and pro
 
 Factions are the political actors in Eagle. They control provinces, command heroes and battalions, negotiate diplomacy, and compete for victory.
 
-The player-facing faction model is `FactionView`. It includes the faction id, head hero, leaders, name, prestige, relationships, incoming diplomacy offers, and optional focus province.
+<!-- Sources:
+- FactionView shape: src/main/protobuf/net/eagle0/eagle/views/faction_view.proto
+- Relationship levels: src/main/protobuf/net/eagle0/eagle/views/faction_relationship_view.proto
+- Trust storage: src/main/scala/net/eagle0/eagle/model/state/faction/FactionRelationship.scala
+- Swear Kinship availability: src/main/scala/net/eagle0/eagle/library/actions/availability/AvailableSwearBrotherhoodCommandFactory.scala
+- Swear Kinship effect: src/main/scala/net/eagle0/eagle/library/actions/impl/command/SwearBrotherhoodCommand.scala
+- Leadership and destruction: src/main/scala/net/eagle0/eagle/library/actions/impl/action/CheckForFactionChangesAction.scala
+- Free hero states and recruitment info: src/main/scala/net/eagle0/eagle/model/state/unaffiliated_hero/UnaffiliatedHeroT.scala
+- Recruitment availability and odds: src/main/scala/net/eagle0/eagle/library/actions/availability/AvailableRecruitHeroesCommandFactory.scala
+  and src/main/scala/net/eagle0/eagle/library/util/recruitment_odds/RecruitmentOdds.scala
+- Prestige calculation: src/main/scala/net/eagle0/eagle/library/util/faction_utils/FactionUtils.scala
+- Truce, alliance, break-alliance, ransom, and imprisonment effects:
+  src/main/scala/net/eagle0/eagle/library/actions/impl/action/diplomacy_helpers/
+- Trust constants: src/main/scala/net/eagle0/eagle/library/settings/BUILD.bazel
+-->
 
 ## Faction Head
 
-The faction head is the primary leader hero. The faction head usually defines the faction's identity and appears in diplomacy, story, and faction summaries.
+The faction head is the hero who represents the faction. In a normal game, this is usually your starting leader: the hero whose ideals, title, and story define what your faction is about.
+
+If the faction head is killed, another faction leader can take over as faction head. The faction may also be renamed around the new head if that hero has a faction name of their own.
 
 ## Leaders
 
-Factions can have multiple leader heroes. Leaders are tracked separately from ordinary vassals and can matter for succession, command availability, and political presentation.
+Faction leaders are the heroes you can command directly. They are different from vassals, who rule provinces for you and make their own choices.
+
+You can gain more faction leaders with **Swear Kinship**. The command is available when your faction head is in the province, your faction has fewer than 5 leaders, and another hero in the province has at least 95 loyalty. The new kinship hero becomes a faction leader.
+
+Faction leaders matter for succession. If the faction head dies, the next available faction leader becomes faction head. If no surviving leader is available to take over immediately, the strongest remaining vassal can rise to become a new faction leader and faction head.
 
 ## Prestige
 
-Prestige is a high-level measure of faction stature. It changes through major outcomes and is shown as part of the faction's public state.
+Prestige is a high-level measure of faction stature. It is also the main faction-wide factor in whether free heroes are willing to join you.
+
+You gain prestige by:
+
+- Controlling more provinces whose support is high enough for taxes. Each supported province is worth 10 prestige.
+- Winning battles.
+- Defeating beasts.
+
+Prestige is not the only recruitment factor. The faction head's charisma, the free hero's power and ambition, the hero's current state, and any personal bias toward or against your faction also matter. But when you want more heroes to take you seriously, prestige is the big strategic lever.
+
+## Free Heroes
+
+Free heroes are heroes in a province who do not currently belong to your faction's command structure. The Free Hero panel tells you what state they are in and whether they can be recruited, divined, or managed another way.
+
+The common states are:
+
+- **Resident:** A hero living in the province. Residents may be willing to join outright. If they are not ready, they may be divinable: use **Divine** to learn what would impress them, then fulfill that ask to make them recruitable.
+- **Traveler:** A hero passing through. You do not know whether a traveler would join you until a faction leader travels there and talks to them. Travelers are harder to recruit than residents, but they might still join if your prestige and other recruitment factors are strong enough. They are also likely to leave the province soon, so they are more time-sensitive than residents.
+- **Prisoner:** A captured hero. Prisoners start with a strong bias against the faction holding them, but desperation can build over time. Eventually a prisoner may become willing to join, especially if your prestige is high enough.
+- **Outlaw:** A hostile free hero in the province. Outlaws are not ordinary recruits and will not simply join from the Free Hero panel; you generally deal with them through commands such as **Apprehend Outlaw**.
+
+Some free heroes are effectively unavailable until circumstances change. For example, a province without one of your faction leaders cannot recruit from the Free Hero panel, and a hero may refuse forever if they have a permanent reason not to join your faction.
 
 ## Relationships
 
-Faction relationships describe the diplomatic state between factions. Diplomacy commands can propose truces, alliances, invitations, alliance breaks, ransoms, and other political outcomes.
+Faction relationships have a visible diplomatic state and an internal trust value.
+
+The visible relationship states are:
+
+- **Hostile:** The default enemy state. Hostile factions can fight each other.
+- **Truce:** A temporary peace. Truce offers set a reset date; when that date passes, the relationship returns to hostile. A truce or alliance also causes hostile armies between those factions to turn back during the truce turn-back phase.
+- **Alliance:** A stronger cooperative relationship. Alliances do not have a reset date. They last until they are broken.
+
+Trust is a hidden number used by AI diplomacy. Higher trust makes a faction more willing to accept diplomatic offers. Trust changes in a few ways:
+
+- Trust rises by 1 each new round between every pair of factions.
+- Accepting a ransom offer raises the offering faction's trust in the faction that accepted it by 25.
+- Rejecting a ransom offer lowers the offering faction's trust in the rejecting faction by 25.
+- Imprisoning another faction's ambassador is a major trust hit: the ambassador's faction loses 150 trust toward the imprisoning faction.
+- Other factions also notice ambassador imprisonment: each neutral faction loses 40 trust toward the imprisoning faction.
 
 ## Incoming Diplomacy Offers
 
@@ -31,10 +86,19 @@ Incoming offers are unresolved diplomatic proposals from other factions. They be
 
 A faction can have a focus province. The focus province helps direct command flow and AI attention toward a particular province.
 
-## Starting Factions
-
-Some heroes in `heroes.tsv` define a `faction_name`, which creates named factions at game setup. Examples include The Fracture Covenant, The King's Loyalists, The Reclamation, Builders of a Better World, and other hero-led factions.
-
 ## Faction Destruction
 
-When a faction loses its basis for continuing, the game can emit faction-destroyed results and remove faction references from the active state.
+A faction is destroyed if either of these is true:
+
+- It has no ruled provinces and no moving armies.
+- It has no faction leaders left.
+
+The leader case has one extra succession step. If a faction loses its available leaders but still has provinces or armies, the game first looks for the strongest surviving vassal and promotes that hero to faction leader and faction head. If no vassal can rise, the faction has no faction leaders left and is destroyed.
+
+When a faction is destroyed:
+
+- Its provinces lose their ruling faction.
+- Its incoming armies are removed, and their supplies are left in the province.
+- Its heroes lose their faction assignment.
+- Other factions lose relationships and incoming offers involving the destroyed faction.
+- If only one faction remains, the game ends and that faction wins. If no factions remain, the game ends with no winner.