docs: establish official design documentation

docs/COMBAT.md

@@ -0,0 +1,229 @@
+# Combat
+
+This document defines the intended combat model for the simulation.
+
+Combat is primarily a local-space activity. It is how factions, pirates, and defenders contest access, claims, stations, and logistics.
+
+## Design Goals
+
+The combat model should support:
+
+- local-space tactical fights
+- piracy and harassment
+- claim destruction and station contestation
+- station defense
+- commander-driven engagement behavior
+- policy-aware hostility and access denial
+
+## Core Principles
+
+- combat happens in `local-space`
+- claims and structures are physically contestable
+- piracy should target valuable traffic and vulnerable infrastructure
+- stations should be defensible but not magically safe
+- combat behavior should come from commanders and policy, not only from raw proximity
+
+## Combat Space
+
+Combat belongs in `local-space`.
+
+This is where entities can:
+
+- maneuver with thrusters
+- approach targets
+- engage with weapons
+- defend stations and claims
+- intercept miners, haulers, and construction support
+
+Ships in `system-space` warp transit are not in normal tactical combat.
+
+This keeps tactical fighting distinct from travel.
+
+## Combat Actors
+
+The main combat actors are:
+
+- combat ships
+- escorts
+- station defenses
+- pirates
+- claim objects
+- vulnerable civilian or industrial ships
+
+Combat should matter not only for fleet battle, but also for logistics disruption and territorial contest.
+
+## Claims As Combat Targets
+
+Claims at Lagrange points should be valid combat targets.
+
+That means:
+
+- enemies may destroy a claim before it matures
+- pirates may harass or destroy claims
+- destroying a claim reopens the location for future contest
+
+Claims should not be protected by abstract immunity.
+
+They are real objects in the world.
+
+## Construction As A Vulnerable Phase
+
+Station founding and expansion should be dangerous.
+
+Vulnerable targets include:
+
+- claim objects
+- construction storage
+- constructor ships
+- supplying haulers
+
+This makes station growth something that may require escort and local protection rather than being a purely economic background action.
+
+## Station Defense
+
+Stations should be able to defend themselves through modules and local defenders.
+
+Station defense may come from:
+
+- defense modules
+- docked or assigned defenders
+- nearby fleet response
+- friendly system presence
+
+Station safety should depend on actual defensive capacity, not only ownership flags.
+
+## Piracy
+
+Pirates should be a meaningful local-space threat.
+
+They should favor:
+
+- industrial ships
+- haulers
+- construction traffic
+- station approaches
+- valuable logistics lanes
+
+Piracy is especially important because it creates pressure on:
+
+- escorts
+- trade profitability
+- claim security
+- station recovery
+
+Pirates should not behave like generic random attackers if the game can instead make them economically disruptive predators.
+
+## Hostility And Access
+
+Combat should interact with policy and diplomacy, but not be replaced by them.
+
+Examples:
+
+- a hostile faction may be denied docking and attacked on approach
+- a neutral faction may be tolerated in-system but not allowed to build
+- pirates may ignore policy altogether and simply attack vulnerable targets
+
+See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) for the access side of this relationship.
+
+## Commander Role In Combat
+
+Commanders should determine combat behavior.
+
+Examples:
+
+- faction commanders set threat posture
+- station commanders request local defense
+- ship commanders choose whether to attack, escort, retreat, or hold
+
+Combat should therefore depend on:
+
+- commander doctrine
+- assigned role
+- local threat level
+- policy and hostility state
+
+This is better than a purely reflexive “closest target” model.
+
+## Engagement Rules
+
+Commanders should eventually carry engagement rules such as:
+
+- attack hostiles on sight
+- defend only if attacked
+- prioritize claims and stations
+- prioritize civilian protection
+- avoid battle unless escorted
+
+These rules can begin simple, but they are important for faction identity.
+
+## Civilian And Industrial Vulnerability
+
+Non-combat ships should not be expected to behave like warships.
+
+Industrial or civilian commanders should prefer:
+
+- fleeing
+- docking
+- requesting escort
+- rerouting
+- abandoning low-value trade under danger
+
+This gives escorts and station defense real purpose.
+
+## Claim And Station Contest
+
+A system can be contested without full conquest mechanics.
+
+Useful examples:
+
+- destroy the enemy claim before activation
+- raid construction storage
+- kill the constructor ship
+- deny safe trade to a vulnerable station
+- force expensive escort commitments
+
+This creates strategic conflict even before fully mature station warfare exists.
+
+## Destruction And Recovery
+
+Combat should create lasting economic consequences.
+
+Examples:
+
+- destroyed claims delay expansion
+- destroyed haulers create shortages
+- destroyed defenders weaken a system
+- damaged or powerless stations need recovery support
+
+This is one of the main ways combat feeds back into the economy.
+
+See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the combat and claim-related event families.
+
+## Minimum Rules
+
+The following rules should remain true unless deliberately revised:
+
+- combat is primarily a local-space activity
+- claims are destructible and contestable
+- station construction is a vulnerable phase
+- piracy should prefer valuable and vulnerable traffic
+- station defense depends on real assets
+- commander doctrine should influence combat behavior
+- combat outcomes should affect logistics and expansion
+
+## Relationship To Other Documents
+
+- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
+  - defines where combat is allowed
+
+- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
+  - defines access and hostility context
+
+- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
+  - defines who decides engagement behavior
+
+- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
+  - defines vulnerable stations, claims, and local defense context
+
+- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
+  - defines the economic consequences of combat disruption