docs: layered information architecture (#140) (#163)

docs/technical/tokenomics.md

@@ -0,0 +1,60 @@
+# Tokenomics
+
+## KRK Token
+
+- **Standard**: ERC20 on Base (Ethereum L2)
+- **Supply**: Dynamic (minted on buys, burned on sells)
+- **Backing**: Every KRK token is backed by ETH in the trading vault
+
+## ETH Reserve & Floor Price
+
+The protocol maintains an ETH reserve in a Uniswap V3 concentrated liquidity position. This creates a floor price:
+
+```
+floor_price = ETH_reserve / total_KRK_supply
+```
+
+**Key property**: The floor price can only go up (in ETH terms) because:
+- Buys add ETH to the reserve and mint KRK at market price (above floor)
+- Sells remove KRK from supply and return ETH at market price
+- Trading fees from the pool add to the reserve without minting new tokens
+
+## Supply Mechanics
+
+### Minting (on buy)
+When someone buys KRK on Uniswap:
+1. ETH enters the pool
+2. KRK is minted at market price
+3. 20% of new tokens go to the staking pool (for stakers)
+4. 80% goes to the buyer
+
+### Burning (on sell)
+When someone sells KRK:
+1. KRK is burned
+2. ETH leaves the pool at market price
+3. The staking pool burns proportionally
+
+## Liquidity Management
+
+The LiquidityManager positions liquidity in a concentrated range around the current price:
+
+### Modes
+- **Scarcity** (bearish signal): Wide range, conservative positioning
+- **Abundance** (bullish signal): Narrow range, aggressive fee capture
+
+### Signals
+The optimizer reads staking activity as a sentiment indicator:
+- High staking ratio + low tax rates = genuine confidence → Bull mode
+- Dropping staking or rising tax rates = uncertainty → Bear mode
+
+### VWAP Tracking
+The system tracks a volume-weighted average price (VWAP) to set liquidity ranges. This creates a "mirror floor" — a second price support level based on recent trading history.
+
+## Fee Generation
+
+Trading activity generates fees from the Uniswap V3 position. These fees accrue to the ETH reserve, increasing the floor price for all holders.
+
+The fee rate depends on:
+- Trading volume
+- Liquidity concentration (narrower range = more fees per trade)
+- Pool fee tier (1% on the KRK/WETH pair)