Add Eagle0pedia concept reference pages (#8399)

* Add Eagle0pedia concept reference pages

* Expand Eagle0pedia profession reference

* Document faction leader mechanics

* Document hero battle capability thresholds

* Call out profession-restricted commands

docs/eagle0pedia/astro.config.mjs

@@ -16,6 +16,10 @@ export default defineConfig({
           items: [
             { label: "Eagle0pedia", slug: "" },
             { label: "Eagle Commands", slug: "commands" },
+            { label: "Shardok Commands", slug: "shardok-commands" },
+            { label: "Heroes", slug: "heroes" },
+            { label: "Factions", slug: "factions" },
+            { label: "Provinces", slug: "provinces" },
           ],
         },
       ],

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

@@ -56,6 +56,8 @@ Most commands belong to the province currently acting this turn. Some are reacti
 
 Give food from the acting province as charity. The province spends food and gains support, capped at 100. The acting hero spends vigor and gains charisma XP; Paladins create more support per food than other heroes.
 
+Profession note: Paladins are not required, but they generate more support per food.
+
 Selection: choose an amount of food and the acting hero.
 
 ## Apprehend Outlaw
@@ -80,6 +82,8 @@ Selection: choose one available attack decision.
 
 Use a hero to change weather in a target province. Available options can start or end blizzards and droughts. The target province receives a deferred weather change, and the acting hero records a weather backstory event, spends or gains the configured vigor delta, and gains wisdom XP.
 
+Requires: Mage with enough vigor.
+
 Selection: choose the weather control type, target province, and acting hero.
 
 ## Decline Quest
@@ -152,6 +156,8 @@ Selection: choose the recipient hero and amount.
 
 Improve a province using one of the available improvement types. Economy, agriculture, and infrastructure rise toward 100; devastation repair reduces all three devastation tracks. The acting hero spends vigor and gains strength/agility XP. Engineers add an improvement bonus, and the improvement can optionally be locked as the province's preferred type.
 
+Profession note: Engineers are not required, but they add an improvement bonus and are recommended when available.
+
 Selection: choose the improvement type, acting hero, and whether to lock the type.
 
 ## Issue Orders
@@ -188,6 +194,8 @@ Selection: choose the province, hero, and whether to accept.
 
 Send a hero to scout another province. The command lists available target provinces and eligible heroes.
 
+Requires: Ranger with enough vigor.
+
 Selection: choose the acting hero and target province.
 
 ## Recruit Heroes
@@ -254,12 +262,16 @@ Selection: choose gold, food, acting hero, and destination province.
 
 Use a hero to start an epidemic in an eligible target province.
 
+Requires: Necromancer with enough vigor.
+
 Selection: choose the target province and acting hero.
 
 ## Suppress Beasts
 
 Send a hero, optionally with a battalion, to suppress beasts in the acting province. The fight rolls beast power, applies casualties to the battalion and/or hero, removes the beast event on success or failure, and creates a story notification. Success can award gold, food, support, hero XP, and battalion backstory; failure can kill the hero and destroy the battalion.
 
+Profession note: no specific profession is required, but heroes with any profession get a power bonus over heroes with no profession.
+
 Selection: choose the hero and optional battalion.
 
 ## Swear Brotherhood
@@ -278,6 +290,8 @@ Selection: choose buy or sell and the amount of food.
 
 Train battalions with a hero in the acting province. The acting hero spends vigor and gains charisma, strength, and agility XP. Trainable battalions gain training based on the hero's strength and charisma, scaled by total troop count and battalion training difficulty. Champions add a training bonus.
 
+Profession note: Champions are not required, but they add a training bonus and are recommended when available.
+
 Selection: choose the acting hero.
 
 ## Travel

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

@@ -0,0 +1,42 @@
+---
+title: Factions
+description: Reference for Eagle factions, leaders, prestige, diplomacy, and province focus.
+---
+
+# Factions
+
+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.
+
+## 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.
+
+## Leaders
+
+Factions can have multiple leader heroes. Leaders are tracked separately from ordinary vassals and can matter for succession, command availability, and political presentation.
+
+## 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.
+
+## Relationships
+
+Faction relationships describe the diplomatic state between factions. Diplomacy commands can propose truces, alliances, invitations, alliance breaks, ransoms, and other political outcomes.
+
+## Incoming Diplomacy Offers
+
+Incoming offers are unresolved diplomatic proposals from other factions. They become reaction commands such as resolving truce offers, alliance offers, invitations, ransom offers, or alliance breaks.
+
+## Focus Province
+
+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.

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

@@ -0,0 +1,212 @@
+---
+title: Heroes
+description: Reference for Eagle heroes, stats, professions, and battlefield roles.
+---
+
+# Heroes
+
+Heroes are named characters who lead factions, rule provinces, command troops, perform strategic commands, and appear as units in Shardok battles.
+
+The player-facing hero model is `HeroView`. It includes identity, faction membership, profession, core stats, personality stats, vigor, loyalty, abilities, portrait path, and backstory text.
+
+## Core Stats
+
+- **Strength** affects physical power and contributes to combat-oriented commands.
+- **Agility** affects mobility, scouting-style competence, and some profession eligibility.
+- **Constitution** sets a hero's endurance profile and is closely tied to vigor.
+- **Charisma** affects leadership, loyalty, diplomacy-flavored actions, and some profession eligibility.
+- **Wisdom** affects knowledge, magic-flavored actions, and some profession eligibility.
+
+Stats can also have XP values. Strategic commands often spend vigor and grant XP in the stats connected to that action.
+
+## Personality Stats
+
+- **Integrity** represents trustworthiness and moral reliability.
+- **Ambition** represents appetite for power or advancement.
+- **Gregariousness** represents sociability and ease with other heroes.
+- **Bravery** represents willingness to face danger.
+
+These values help drive hero flavor, AI decisions, and story generation.
+
+## Vigor
+
+Vigor is a hero's current energy. Many commands require an acting hero and spend vigor. Resting restores vigor up to the hero's constitution.
+
+## Loyalty
+
+Loyalty measures a hero's attachment to their faction. Feasts, events, captures, faction bias, and story consequences can move loyalty over time.
+
+## Professions
+
+Professions give heroes special command access, bonuses, and tactical identity. Some effects are Eagle strategic effects, while others apply only when the hero is attached to a Shardok battle unit.
+
+Several Shardok profession commands also depend on the attached battalion type. For example, many magic commands require a battalion type that allows casting, and stealth commands require a battalion type that allows stealth.
+
+### Mage
+
+Eagle effects:
+
+- Unlocks **Control Weather** for a mage in the acting province with enough vigor.
+- Can start or end blizzards and droughts in the acting province or a neighboring province.
+- Counts as a profession for general hero power and riot-crackdown hero power.
+- Makes the hero naturally capable of starting fires.
+
+Shardok effects:
+
+- Unlocks **Lightning Bolt** when attached to a casting-capable unit.
+- Unlocks the multi-round **Meteor** command chain: start, target, cast, and cancel.
+- Unlocks **Freeze Water** on adjacent water when attached to a casting-capable unit.
+- Improves **Start Fire** odds when the unit can start fires.
+- Changes hero melee damage from physical damage to magical damage: lightning, cold, fire, and aether essence.
+- Can influence AI water-crossing evaluation because Mage can freeze water.
+
+Profession gain:
+
+- Wisdom is the qualifying stat for Mage.
+
+### Necromancer
+
+Eagle effects:
+
+- Unlocks **Start Epidemic** for a necromancer in the acting province with enough vigor.
+- Epidemics can target the acting province or neighboring provinces, excluding friendly provinces that already have an epidemic.
+- Counts as a profession for general hero power and riot-crackdown hero power.
+
+Shardok effects:
+
+- Unlocks **Raise Dead** when attached to a casting-capable unit and not already controlling a unit.
+- Unlocks **Fear** against eligible enemy units when attached to a casting-capable unit.
+- Raised dead and fear use the hero's charisma and wisdom in their odds.
+
+Profession gain:
+
+- Charisma is one qualifying stat for Necromancer.
+
+### Engineer
+
+Eagle effects:
+
+- Is recommended first for **Improve** when an engineer is available.
+- Adds the configured engineer bonus to province improvements and devastation repair.
+- Counts as a profession for general hero power and riot-crackdown hero power.
+
+Shardok effects:
+
+- Unlocks **Build Bridge** from non-water terrain onto adjacent water.
+- Unlocks **Repair** for damaged bridges and castles.
+- Unlocks **Blow Bridge** while standing on a bridge.
+- Unlocks **Reduce** from a castle or fortified position against enemy units or castles.
+- Unlocks **Fortify** on fortifiable terrain.
+- Can influence AI water-crossing evaluation because engineers can create and destroy bridge access.
+
+Profession gain:
+
+- Agility is one qualifying stat for Engineer.
+
+### Paladin
+
+Eagle effects:
+
+- Improves **Alms** by multiplying the support gained per food given.
+- Is sorted first in the **Alms** hero list when eligible.
+- Counts as a profession for general hero power and riot-crackdown hero power.
+
+Shardok effects:
+
+- Unlocks **Holy Wave** when the paladin has enough action points.
+
+Profession gain:
+
+- Charisma is one qualifying stat for Paladin.
+
+### Ranger
+
+Eagle effects:
+
+- Unlocks **Recon** for a ranger in the acting province with enough vigor.
+- Recon can target provinces not ruled by the acting faction, as long as that faction does not already have a pending recon there.
+- Counts as a profession for general hero power and riot-crackdown hero power.
+
+Shardok effects:
+
+- Unlocks **Scout** when attached to a stealth-capable unit.
+- Unlocks **Hide** when attached to a stealth-capable unit, outside enemy zone of control, and with multiple hideable positions.
+- Allows defending rangers with stealth-capable units to use hidden placement during setup.
+- Gives a bonus to **Brave Water** odds when the unit can brave water.
+- Reveals adjacent hidden enemies while moving.
+- Prevents adjacent enemies from hiding or remaining hidden when the ranger has enough knowledge to be identified.
+
+Profession gain:
+
+- Agility is one qualifying stat for Ranger.
+
+### Champion
+
+Eagle effects:
+
+- Is recommended first for **Train** when a champion is available.
+- Adds the configured champion bonus to training gained by trainable battalions.
+- Counts as a profession for general hero power and riot-crackdown hero power.
+
+Shardok effects:
+
+- Unlocks **Challenge Duel** against adjacent enemy heroes outside castles.
+- The target must have an attached hero and must either have enough known vigor to accept or be insufficiently known to rule that out.
+
+Profession gain:
+
+- Strength is the qualifying stat for Champion.
+
+### Warden
+
+Eagle effects:
+
+- Improves prisoner recruitment over time. At new round processing, prisoners in a province with a ruling-faction Warden gain additional faction bias toward that province's ruler.
+- Counts as a profession for general hero power and riot-crackdown hero power.
+
+Shardok effects:
+
+- Unlocks **Evacuate Prisoners** when the warden's unit can flee, has enough action points, and hostile captured hero units are present.
+
+Profession gain:
+
+- Constitution is the qualifying stat for Warden.
+
+### NoProfession
+
+Heroes with no profession have no profession-specific command unlocks. They can still lead, fight, train, improve, march, use many normal strategic commands, and gain a profession later.
+
+## Profession Gain
+
+Only heroes with **NoProfession** can gain a profession. At the end of a round, heroes with enough XP can gain stats. If a no-profession hero gains one or more stats, the game checks for profession gain:
+
+- The hero gets one profession-gain roll for each stat that increased.
+- Eligible professions are based on all post-gain stats at or above the configured prime-stat threshold.
+- Strength qualifies **Champion**.
+- Agility qualifies **Engineer** and **Ranger**.
+- Wisdom qualifies **Mage**.
+- Charisma qualifies **Necromancer** and **Paladin**.
+- Constitution qualifies **Warden**.
+
+## Faction Leaders
+
+Every faction starts with a **faction head**. The faction head is the hero who defines what the faction represents: its political identity, its public story, and the starting point for its leadership.
+
+Factions can gain additional faction leaders through **Swear Kinship** with another hero. The candidate must already belong to the faction, must have at least 95 loyalty, and must be in a province with the faction head. When the command succeeds, that hero becomes one of the faction's leaders.
+
+Faction leaders are directly commandable. Vassals, by contrast, lead provinces and make their own choices when their province acts. Promoting a loyal vassal into leadership gives the player more direct control over that hero.
+
+Faction leaders also provide succession. If the faction head is killed, another available faction leader can take over as the new faction head.
+
+## Unaffiliated Heroes
+
+Unaffiliated heroes can appear in provinces before joining a faction. Their province entry includes name, profession, status, leader flag, and recruitment information.
+
+Common interactions include recruiting them, divining more information about them, declining their quests, or responding when they ask to join.
+
+## Battle Capabilities
+
+Hero views expose whether a hero is archery-capable or start-fire-capable. Those capabilities affect Shardok command availability when the hero is represented in battle.
+
+- **Archery-capable**: the hero needs at least 75 agility.
+- **Start-fire-capable**: the hero is always capable if they are a Mage. Otherwise, they need at least 70 agility and at least 70 wisdom.

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

@@ -12,6 +12,10 @@ This Starlight site lives close to the game data and can be reviewed with code c
 ## Sections
 
 - [Eagle commands](commands/)
+- [Shardok commands](shardok-commands/)
+- [Heroes](heroes/)
+- [Factions](factions/)
+- [Provinces](provinces/)
 
 ## Link Targets
 
@@ -20,5 +24,8 @@ Unity info buttons should link to stable concept URLs. For the command panel, st
 - `https://pedia.eagle0.net/commands/#train`
 - `https://pedia.eagle0.net/commands/#march`
 - `https://pedia.eagle0.net/commands/#diplomacy`
+- `https://pedia.eagle0.net/shardok-commands/#melee`
+- `https://pedia.eagle0.net/heroes/#professions`
+- `https://pedia.eagle0.net/provinces/#province-stats`
 
 When individual command pages are split out, keep redirects or aliases for these anchors so older clients still land somewhere useful.

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

@@ -0,0 +1,62 @@
+---
+title: Provinces
+description: Reference for Eagle provinces, resources, infrastructure, orders, and tactical maps.
+---
+
+# Provinces
+
+Provinces are the strategic map locations in Eagle. They hold resources, heroes, battalions, province orders, incoming armies, local events, and the Shardok map used when battles occur there.
+
+The player-facing province model is `ProvinceView`. Public information includes id, name, ruling faction, known events, known incoming armies, and an `as_of` date. When the player has full information, `FullProvinceInfo` adds the detailed local state.
+
+## Province Stats
+
+- **Economy** affects gold production and the province's economic strength.
+- **Agriculture** affects food production and the province's ability to sustain armies and heroes.
+- **Infrastructure** affects development quality and can cap certain troop improvements.
+- **Economy devastation**, **agriculture devastation**, and **infrastructure devastation** track war damage or disaster damage to those systems.
+- **Support** represents local backing for the ruling faction.
+
+## Supplies
+
+Provinces store gold and food. They also have gold and food caps. Commands such as feast, alms, trade, organize troops, send supplies, and march all interact with province supplies.
+
+## Price Index
+
+The price index reflects local price pressure. Spending-heavy commands can move it, and costs can scale by it.
+
+## Ruling Faction and Ruling Hero
+
+A province can have a ruling faction and a ruling hero. Full province info also tracks the ordered list of ruling-faction heroes currently in the province.
+
+## Battalions and Defenders
+
+Provinces contain battalions and may have a defending army. Organize, train, arm, march, defend, and attack-related commands all depend on province military state.
+
+## Incoming Armies
+
+Incoming armies represent forces that are moving toward the province but have not arrived or resolved yet. They can trigger defense choices, battles, or other strategic consequences.
+
+## Province Orders
+
+Province orders are standing instructions for the province. The `Issue Orders` command changes them and can also change the faction's focus province.
+
+## Tactical Map
+
+Each province has a `hex_map_name`. When a battle occurs there, Eagle uses that name to connect the strategic province to the Shardok tactical map.
+
+## Castles
+
+`castle_count` records the province's fortification count. Castles matter for defensive strength and battle setup.
+
+## Hero Cap
+
+`hero_cap` limits how many ruling-faction heroes the province can comfortably hold.
+
+## Unaffiliated Heroes
+
+Unaffiliated heroes in a province are potential recruits, quest-givers, outlaws, or heroes asking to join. Province info exposes their basics and recruitment information when known.
+
+## Province Map Data
+
+`province_map.tsv` defines province ids, names, neighbor ids, neighbor positions, tactical map names, neighbor names, and castle counts. This is the source for strategic map adjacency and province identity.

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

@@ -0,0 +1,204 @@
+---
+title: Shardok Commands
+description: Tactical command reference for Shardok battles.
+---
+
+# Shardok Commands
+
+Shardok commands are the tactical actions available during a battle. The tactical engine advertises them as `CommandDescriptor` values with a command type, acting unit, target hex or unit, path, odds, and any follow-up command types.
+
+Commands shown in `current_command` can be posted now. Commands shown in `preview_command` are useful for the UI, but are not currently postable.
+
+## Command List
+
+- [Melee](#melee)
+- [Archery](#archery)
+- [Charge](#charge)
+- [Move](#move)
+- [Lightning Bolt](#lightning-bolt)
+- [Meteor](#meteor)
+- [Start Fire](#start-fire)
+- [Extinguish Fire](#extinguish-fire)
+- [Freeze Water](#freeze-water)
+- [Build Bridge](#build-bridge)
+- [Blow Bridge](#blow-bridge)
+- [Placement](#placement)
+- [Scout](#scout)
+- [Raise Dead](#raise-dead)
+- [Dismiss Unit](#dismiss-unit)
+- [Holy Wave](#holy-wave)
+- [Stop and Rest](#stop-and-rest)
+- [Challenge Duel](#challenge-duel)
+- [Fear](#fear)
+- [Repair](#repair)
+- [Reduce](#reduce)
+- [Flee and Retreat](#flee-and-retreat)
+- [Control](#control)
+- [Reinforce](#reinforce)
+- [Brave Water](#brave-water)
+- [Release Unit](#release-unit)
+- [End Turn and Setup](#end-turn-and-setup)
+- [Hide](#hide)
+- [Fortify](#fortify)
+- [Become Outlaw](#become-outlaw)
+- [Evacuate Prisoners](#evacuate-prisoners)
+
+## Melee
+
+Attack an adjacent enemy unit in close combat. The command descriptor identifies the acting unit, target unit or hex, action-point cost, and combat odds when available.
+
+## Archery
+
+Make a ranged attack with an archery-capable unit. Archery commands usually target a unit at range instead of requiring adjacency.
+
+## Charge
+
+Move into an attack as one action. Charge is a tactical attack command with movement built into the command path.
+
+## Move
+
+Move a unit across one or more hexes. Multi-step movement uses the descriptor `path` field to list every traversed hex in order.
+
+## Lightning Bolt
+
+Cast a lightning attack at a target. This is a magic command and may include odds or roll information when the client can display expected results.
+
+Requires: Mage attached to a casting-capable unit.
+
+## Meteor
+
+Meteor is represented as several command types: start, target, cast, and cancel. The start and target steps establish the spell, while cast resolves it and cancel backs out of the pending meteor.
+
+Requires: Mage attached to a casting-capable unit, with enough vigor to start the spell.
+
+## Start Fire
+
+Set a target hex on fire when the acting unit has access to the command.
+
+Profession note: Mage is not required, but mages improve the start-fire odds.
+
+## Extinguish Fire
+
+Remove or reduce fire on a target hex.
+
+## Freeze Water
+
+Turn water into traversable frozen terrain where the command is valid.
+
+Requires: Mage attached to a casting-capable unit.
+
+## Build Bridge
+
+Create a bridge across a valid water or gap target.
+
+Requires: Engineer.
+
+## Blow Bridge
+
+Destroy an existing bridge target.
+
+Requires: Engineer standing on a bridge.
+
+## Placement
+
+Place units during battle setup. Shardok distinguishes visible placement and hidden placement with `PLACE_UNIT_COMMAND` and `PLACE_HIDDEN_UNIT_COMMAND`.
+
+Profession note: normal placement is not profession-restricted. Hidden placement requires a defending Ranger attached to a stealth-capable unit.
+
+## Scout
+
+Reveal information using a scouting unit. Scout commands can be advertised as previews when the UI needs to show setup or hidden-unit possibilities.
+
+Requires: Ranger attached to a stealth-capable unit.
+
+## Raise Dead
+
+Create or restore undead forces through necromantic action.
+
+Requires: Necromancer attached to a casting-capable unit, and the hero must not already control a unit.
+
+## Dismiss Unit
+
+Remove a unit from the tactical battle when dismissal is allowed.
+
+## Holy Wave
+
+Use a holy-area effect from a capable unit.
+
+Requires: Paladin.
+
+## Stop and Rest
+
+`UNIT_STOP_COMMAND` stops a unit. `UNIT_REST_COMMAND` has a unit spend its action resting instead of acting aggressively.
+
+## Challenge Duel
+
+Challenge an opposing unit to a duel. The tactical action emits accepted or declined outcomes directly.
+
+Requires: Champion.
+
+## Fear
+
+Use a fear effect against an eligible target.
+
+Requires: Necromancer attached to a casting-capable unit.
+
+## Repair
+
+Repair a damaged unit or battlefield object when an engineer-style action is available.
+
+Requires: Engineer.
+
+## Reduce
+
+Reduce a target, generally used for siege-like or structure-focused tactical effects.
+
+Requires: Engineer in a castle or fortified position.
+
+## Flee and Retreat
+
+`FLEE_COMMAND` handles immediate flight from a tactical situation. `RETREAT_COMMAND` handles a more formal withdrawal command.
+
+## Control
+
+Take control of a target when the command is available.
+
+## Reinforce
+
+Bring reinforcements into the battle.
+
+## Brave Water
+
+Move through water despite the usual danger or restriction.
+
+Profession note: Ranger is not required, but rangers get a brave-water odds bonus.
+
+## Release Unit
+
+Release a controlled, held, or otherwise constrained unit.
+
+## End Turn and Setup
+
+`END_TURN_COMMAND` ends the active tactical turn. `END_PLAYER_SETUP_COMMAND` ends that player's setup phase.
+
+## Hide
+
+Hide a unit when it can enter or remain in hidden status.
+
+Requires: Ranger attached to a stealth-capable unit.
+
+## Fortify
+
+Have a unit fortify its current position.
+
+Requires: Engineer.
+
+## Become Outlaw
+
+Mark a unit or hero as becoming an outlaw as a battle consequence.
+
+## Evacuate Prisoners
+
+Move prisoners out of danger when the battlefield state allows prisoner evacuation.
+
+Requires: Warden on a unit that can flee.