docs: Add README documentation for missing contract directories

contracts/contracts/automation/README.md

@@ -0,0 +1,45 @@
+# Automation
+
+This directory contains Safe Module contracts for automating protocol operations.
+
+## Overview
+
+Automation modules extend Gnosis Safe functionality to enable operators to execute specific, pre-approved actions without requiring full multisig approval for each transaction.
+
+## Contracts
+
+### Base Contracts
+
+| Contract | Description |
+|----------|-------------|
+| `AbstractSafeModule.sol` | Base contract for all Safe modules with operator role management |
+
+### Bridge Helpers
+
+| Contract | Description |
+|----------|-------------|
+| `AbstractCCIPBridgeHelperModule.sol` | Base for Chainlink CCIP bridge operations |
+| `AbstractLZBridgeHelperModule.sol` | Base for LayerZero bridge operations |
+| `BaseBridgeHelperModule.sol` | Common bridge helper functionality |
+| `EthereumBridgeHelperModule.sol` | Ethereum mainnet bridge operations |
+| `PlumeBridgeHelperModule.sol` | Plume network bridge operations |
+
+### Operational Modules
+
+| Contract | Description |
+|----------|-------------|
+| `ClaimBribesSafeModule.sol` | Automate claiming of bribe rewards |
+| `ClaimStrategyRewardsSafeModule.sol` | Automate claiming strategy rewards |
+| `CollectXOGNRewardsModule.sol` | Automate collection of xOGN rewards |
+| `CurvePoolBoosterBribesModule.sol` | Automate Curve pool booster bribes |
+
+## Architecture
+
+All modules inherit from `AbstractSafeModule` which provides:
+- **Operator Role**: Designated addresses can trigger module actions
+- **Safe Integration**: Modules execute transactions through the Safe contract
+- **Access Control**: OpenZeppelin's `AccessControlEnumerable` for role management
+
+## Usage
+
+Modules are registered with a Gnosis Safe and can then be triggered by operators to execute pre-defined actions safely.

contracts/contracts/beacon/README.md

@@ -0,0 +1,30 @@
+# Beacon
+
+This directory contains contracts for Ethereum Beacon Chain proof verification.
+
+## Overview
+
+These contracts enable verification of Beacon Chain data through Merkle proofs, which is essential for OETH's native staking functionality. They verify validator states, withdrawal credentials, and other beacon chain data.
+
+## Contracts
+
+| Contract | Description |
+|----------|-------------|
+| `BeaconProofs.sol` | Main contract for verifying beacon chain Merkle proofs |
+| `BeaconProofsLib.sol` | Library implementation of proof verification logic |
+| `BeaconConsolidation.sol` | Handles validator consolidation proofs |
+| `BeaconRoots.sol` | Access to beacon block roots (EIP-4788) |
+| `Merkle.sol` | Merkle tree utilities for proof verification |
+| `Endian.sol` | Endianness conversion utilities |
+| `PartialWithdrawal.sol` | Handles partial withdrawal proofs |
+
+## Use Cases
+
+- **Validator Verification**: Verify validator public keys and indices
+- **Withdrawal Credentials**: Confirm validators point to correct withdrawal addresses
+- **Withdrawal Proofs**: Verify partial and full validator withdrawals
+- **Consolidation**: Handle validator consolidation operations
+
+## Integration
+
+These contracts are used by the Native Staking strategy (`strategies/NativeStaking/`) to verify on-chain that validators are correctly configured and to process withdrawals trustlessly.

contracts/contracts/bridges/README.md

@@ -0,0 +1,30 @@
+# Bridges
+
+This directory contains contracts for cross-chain token bridging using omnichain standards.
+
+## Overview
+
+Bridge adapters enable OETH and other Origin tokens to be bridged across multiple chains using LayerZero's Omnichain Fungible Token (OFT) standard.
+
+## Contracts
+
+| Contract | Description |
+|----------|-------------|
+| `OmnichainL2Adapter.sol` | LayerZero OFT adapter for L2 chains (mint/burn mechanism) |
+| `OmnichainMainnetAdapter.sol` | LayerZero OFT adapter for Ethereum mainnet (lock/unlock mechanism) |
+
+## Architecture
+
+### Mainnet (Lock/Unlock)
+On Ethereum mainnet, the adapter locks tokens when bridging out and unlocks when receiving from L2s.
+
+### L2 (Mint/Burn)
+On L2 chains, the adapter mints tokens when receiving from mainnet and burns when bridging back.
+
+## Integration
+
+These adapters integrate with LayerZero's messaging infrastructure to enable secure cross-chain token transfers while maintaining a unified token supply across all chains.
+
+## Related
+
+- See `automation/` for bridge helper modules that assist with cross-chain operations

contracts/contracts/buyback/README.md

@@ -0,0 +1,35 @@
+# Buyback
+
+This directory contains contracts for protocol buyback mechanisms.
+
+## Overview
+
+Buyback contracts swap protocol yield (OUSD/OETH) for governance tokens (OGN) and CVX, supporting token value and protocol governance power.
+
+## Contracts
+
+| Contract | Description |
+|----------|-------------|
+| `AbstractBuyback.sol` | Base buyback implementation with common logic |
+| `OUSDBuyback.sol` | OUSD-specific buyback contract |
+| `OETHBuyback.sol` | OETH-specific buyback contract |
+| `ARMBuyback.sol` | ARM (Automated Redemption Manager) buyback contract |
+
+## Mechanism
+
+1. **Yield Collection**: Protocol yield is collected from strategies
+2. **Swap Execution**: Yield tokens are swapped via 1inch or other DEX aggregators
+3. **Token Distribution**: 
+   - OGN is sent to treasury or staking
+   - CVX is locked in vlCVX for voting power
+
+## Configuration
+
+- **CVX Share BPS**: Configurable percentage split between OGN and CVX
+- **Rewards Source**: Address that receives buyback proceeds
+- **Treasury Manager**: Address managing treasury operations
+- **Swap Router**: DEX aggregator for executing swaps
+
+## Access Control
+
+Buyback operations are restricted to the Strategist role, ensuring controlled execution of swaps with appropriate slippage parameters.

contracts/contracts/poolBooster/README.md

@@ -0,0 +1,49 @@
+# Pool Booster
+
+This directory contains contracts for boosting liquidity pool incentives.
+
+## Overview
+
+Pool Booster contracts distribute Origin token rewards to liquidity providers through various incentive distribution platforms like Merkl and Metropolis.
+
+## Contracts
+
+### Core
+
+| Contract | Description |
+|----------|-------------|
+| `PoolBoostCentralRegistry.sol` | Central registry tracking all pool boosters |
+| `AbstractPoolBoosterFactory.sol` | Base factory for deploying pool boosters |
+
+### Merkl Integration
+
+| Contract | Description |
+|----------|-------------|
+| `PoolBoosterMerkl.sol` | Pool booster using Merkl distribution |
+| `PoolBoosterFactoryMerkl.sol` | Factory for deploying Merkl boosters |
+
+### Metropolis Integration
+
+| Contract | Description |
+|----------|-------------|
+| `PoolBoosterMetropolis.sol` | Pool booster using Metropolis distribution |
+| `PoolBoosterFactoryMetropolis.sol` | Factory for deploying Metropolis boosters |
+
+### Swapx Integration
+
+| Contract | Description |
+|----------|-------------|
+| `PoolBoosterSwapxSingle.sol` | Single-token Swapx pool booster |
+| `PoolBoosterSwapxDouble.sol` | Dual-token Swapx pool booster |
+| `PoolBoosterFactorySwapxSingle.sol` | Factory for single-token Swapx boosters |
+| `PoolBoosterFactorySwapxDouble.sol` | Factory for dual-token Swapx boosters |
+
+## Architecture
+
+1. **Registry**: Tracks all deployed pool boosters
+2. **Factories**: Deploy new pool boosters with consistent configuration
+3. **Boosters**: Distribute rewards to target liquidity pools
+
+## Usage
+
+Pool boosters are funded with Origin tokens (OS) and create incentive campaigns on the respective platforms to attract liquidity to OETH/OUSD pools.

contracts/contracts/zapper/README.md

@@ -0,0 +1,35 @@
+# Zapper
+
+This directory contains zapper contracts for simplified token operations.
+
+## Overview
+
+Zappers provide one-transaction convenience functions that combine multiple operations, such as wrapping and bridging in a single call.
+
+## Contracts
+
+| Contract | Description |
+|----------|-------------|
+| `WOETHCCIPZapper.sol` | Zap ETH on mainnet directly to WOETH on L2 chains |
+
+## WOETHCCIPZapper
+
+The WOETH CCIP Zapper enables users to convert ETH on Ethereum mainnet directly into Wrapped OETH (WOETH) on supported L2 chains in a single transaction.
+
+### Flow
+
+1. User sends ETH to the zapper
+2. Zapper converts ETH to OETH via the OETH Zapper
+3. OETH is wrapped to WOETH
+4. WOETH is bridged to the destination chain via Chainlink CCIP
+5. WOETH arrives at the recipient address on L2
+
+### Benefits
+
+- **Gas Efficient**: Single transaction instead of multiple
+- **User Friendly**: No need to manage intermediate tokens
+- **Cross-Chain**: Direct mainnet ETH to L2 WOETH
+
+## Events
+
+- `Zap`: Emitted on each successful zap with message ID, sender, recipient, and amount