diff --git a/contracts/README.md b/contracts/README.md
new file mode 100644
index 00000000..8e0a92c5
--- /dev/null
+++ b/contracts/README.md
@@ -0,0 +1,41 @@
+# Contracts
+
+This directory contains all smart contracts for the Pinto Protocol.
+
+## Overview
+
+Pinto is a low-volatility money protocol with a $1 price target, built using the EIP-2535 Diamond pattern for modular upgradability.
+
+## Directory Structure
+
+| Directory | Description |
+|-----------|-------------|
+| `beanstalk/` | Core protocol contracts including Diamond, facets, storage, and initializers |
+| `ecosystem/` | Peripheral contracts for oracles, price feeds, and integrations |
+| `interfaces/` | Solidity interfaces for all protocol contracts |
+| `libraries/` | Shared libraries for math, storage, and utility functions |
+| `mocks/` | Mock contracts used for testing |
+| `pipeline/` | Pipeline contracts for composing protocol interactions |
+| `tokens/` | Token contracts including the Bean ERC20 token |
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `C.sol` | Protocol constants and configuration values |
+
+## Architecture
+
+The protocol uses EIP-2535 (Diamond Standard) which allows:
+- **Modular Upgrades**: Individual facets can be upgraded without redeploying the entire contract
+- **Unlimited Contract Size**: Circumvents the 24KB contract size limit
+- **Shared Storage**: All facets share common storage through `AppStorage`
+
+## Getting Started
+
+See the [main README](../README.md) for build and test instructions.
+
+## Documentation
+
+- [Pinto Docs](https://docs.pinto.money)
+- [EIP-2535 Diamond Standard](https://eips.ethereum.org/EIPS/eip-2535)
diff --git a/contracts/beanstalk/README.md b/contracts/beanstalk/README.md
new file mode 100644
index 00000000..1ff969e8
--- /dev/null
+++ b/contracts/beanstalk/README.md
@@ -0,0 +1,43 @@
+# Beanstalk Core
+
+This directory contains the core protocol contracts implementing the Pinto Diamond.
+
+## Overview
+
+Pinto inherits its architecture from Beanstalk and uses the EIP-2535 Diamond pattern. The Diamond serves as the main entry point, delegating calls to various facets based on function selectors.
+
+## Directory Structure
+
+| Directory | Description |
+|-----------|-------------|
+| `facets/` | Modular contract facets implementing protocol functionality |
+| `init/` | Initialization contracts for protocol upgrades |
+| `storage/` | Storage layout contracts defining `AppStorage` |
+
+## Key Contracts
+
+| Contract | Description |
+|----------|-------------|
+| `Diamond.sol` | Main Diamond proxy contract, entry point for all protocol interactions |
+| `Invariable.sol` | Invariant checks to ensure protocol safety |
+| `ReentrancyGuard.sol` | Reentrancy protection for protocol functions |
+
+## Facets
+
+Facets are organized by functionality:
+
+- **diamond/**: Core Diamond operations (DiamondCut, DiamondLoupe, Ownership)
+- **farm/**: Token operations, Depot, Farm actions, Tractor automation
+- **field/**: Field mechanics for sowing and harvesting Pods
+- **market/**: Pod Marketplace for trading Pods
+- **metadata/**: NFT metadata for deposit tokens
+- **silo/**: Silo deposits, withdrawals, conversions, and rewards
+- **sun/**: Season advancement, gauges, oracles, and incentives
+
+## Storage
+
+The protocol uses a single `AppStorage` struct shared across all facets, ensuring consistent state management.
+
+## Initialization
+
+`init/` contracts handle state migrations during protocol upgrades (e.g., `InitPI1.sol` through `InitPI13.sol` for Protocol Improvements).
diff --git a/contracts/beanstalk/facets/README.md b/contracts/beanstalk/facets/README.md
new file mode 100644
index 00000000..ffde9f8a
--- /dev/null
+++ b/contracts/beanstalk/facets/README.md
@@ -0,0 +1,74 @@
+# Facets
+
+This directory contains all Diamond facets implementing Pinto Protocol functionality.
+
+## Overview
+
+Facets are modular contracts that provide specific functionality to the Diamond. Each facet is a separate contract that can be added, replaced, or removed through the DiamondCut mechanism.
+
+## Directory Structure
+
+| Directory | Description |
+|-----------|-------------|
+| `diamond/` | Core Diamond management facets |
+| `farm/` | Token and farming operation facets |
+| `field/` | Pod Field mechanics |
+| `market/` | Pod Marketplace |
+| `metadata/` | NFT metadata generation |
+| `silo/` | Silo deposits and yield distribution |
+| `sun/` | Season advancement and gauges |
+
+## Diamond Facets
+
+| Facet | Description |
+|-------|-------------|
+| `DiamondCutFacet` | Add, replace, or remove facet functions |
+| `DiamondLoupeFacet` | Introspection functions to view facet information |
+| `OwnershipFacet` | Contract ownership management |
+
+## Farm Facets
+
+| Facet | Description |
+|-------|-------------|
+| `DepotFacet` | Pipeline integration for external protocol calls |
+| `FarmFacet` | Composable farming operations |
+| `TokenFacet` | Internal token balance management |
+| `TokenSupportFacet` | Token whitelisting and support |
+| `TractorFacet` | Automated action execution (Tractor) |
+
+## Field Facets
+
+| Facet | Description |
+|-------|-------------|
+| `FieldFacet` | Sowing Beans for Pods, harvesting mature Pods |
+
+## Market Facets
+
+| Facet | Description |
+|-------|-------------|
+| `MarketplaceFacet` | Pod listing, ordering, and trading |
+
+## Silo Facets
+
+| Facet | Description |
+|-------|-------------|
+| `SiloFacet` | Deposit, withdraw, and transfer Silo assets |
+| `SiloGettersFacet` | View functions for Silo state |
+| `ConvertFacet` | Convert between whitelisted Silo assets |
+| `ConvertGettersFacet` | View functions for conversions |
+| `PipelineConvertFacet` | Pipeline-based conversions |
+| `ClaimFacet` | Claim Silo rewards and Earned Beans |
+| `ApprovalFacet` | Deposit approval management |
+| `BDVFacet` | Bean Denominated Value calculations |
+| `WhitelistFacet` | Silo asset whitelisting |
+
+## Sun Facets
+
+| Facet | Description |
+|-------|-------------|
+| `SeasonFacet` | Advance the Season (sunrise) |
+| `SeasonGettersFacet` | View functions for Season state |
+| `GaugeFacet` | Gauge system for directing incentives |
+| `GaugeGettersFacet` | View functions for gauge state |
+| `OracleFacet` | Price oracle integration |
+| `LiquidityWeightFacet` | Liquidity weight calculations |
diff --git a/contracts/ecosystem/README.md b/contracts/ecosystem/README.md
new file mode 100644
index 00000000..b9c0d539
--- /dev/null
+++ b/contracts/ecosystem/README.md
@@ -0,0 +1,44 @@
+# Ecosystem
+
+This directory contains peripheral ecosystem contracts that support the Pinto Protocol.
+
+## Overview
+
+Ecosystem contracts provide supporting infrastructure for the core protocol, including price oracles, gauge point calculations, and external integrations.
+
+## Directory Structure
+
+| Directory | Description |
+|-----------|-------------|
+| `gaugePoints/` | Gauge point calculation contracts |
+| `junction/` | Junction contracts for multi-protocol integration |
+| `oracles/` | Oracle implementations for price feeds |
+| `price/` | Price calculation contracts |
+| `tractor/` | Tractor automation utilities |
+
+## Key Contracts
+
+| Contract | Description |
+|----------|-------------|
+| `ShipmentPlanner.sol` | Plans and coordinates shipments of newly minted Beans |
+
+## Price Contracts
+
+The `price/` directory contains contracts for calculating Bean price across liquidity pools:
+- `BeanstalkPrice.sol`: Main price aggregation contract
+- `WellPrice.sol`: Price calculations for Well liquidity pools
+
+## Oracles
+
+Oracle contracts provide manipulation-resistant price data for protocol operations including:
+- Minting calculations
+- Silo reward distribution
+- Gauge weight adjustments
+
+## Gauge Points
+
+Gauge point contracts calculate the distribution of incentives across different Silo assets based on protocol-defined criteria.
+
+## Tractor
+
+Tractor utilities enable automated operations like recurring deposits, conversions, and other protocol interactions.
diff --git a/contracts/libraries/README.md b/contracts/libraries/README.md
new file mode 100644
index 00000000..40bb63aa
--- /dev/null
+++ b/contracts/libraries/README.md
@@ -0,0 +1,81 @@
+# Libraries
+
+This directory contains shared libraries used across the Pinto Protocol.
+
+## Overview
+
+Libraries provide reusable logic for mathematical operations, storage management, and protocol-specific calculations. They are designed to be stateless and called via `delegatecall` or as internal functions.
+
+## Categories
+
+### Storage Libraries
+
+| Library | Description |
+|---------|-------------|
+| `LibAppStorage` | Access to the shared `AppStorage` struct |
+| `LibDiamond` | Diamond storage and facet management |
+
+### Math Libraries
+
+Located in `Math/`:
+- `LibRedundantMath256` - Safe math operations
+- Various mathematical utilities for precision calculations
+
+### Protocol Libraries
+
+| Library | Description |
+|---------|-------------|
+| `LibDibbler` | Field sowing mechanics |
+| `LibEvaluate` | Evaluation functions for protocol state |
+| `LibGauge` | Gauge system calculations |
+| `LibGaugeHelpers` | Helper functions for gauge operations |
+
+### Silo Libraries
+
+Located in `Silo/`:
+- Deposit and withdrawal logic
+- Stalk and Seed calculations
+- Germination mechanics
+
+### Convert Libraries
+
+Located in `Convert/`:
+- Conversion calculations between Silo assets
+- Lambda convert functions
+
+### Token Libraries
+
+| Library | Description |
+|---------|-------------|
+| `LibBytes` | Byte manipulation utilities |
+| `LibBytes64` | 64-bit byte operations |
+| `Token/` | Token transfer and balance utilities |
+
+### Oracle Libraries
+
+Located in `Oracle/`:
+- Price oracle integrations
+- TWAP calculations
+
+### Utility Libraries
+
+| Library | Description |
+|---------|-------------|
+| `LibClipboard` | Data encoding for Farm calls |
+| `LibFarm` | Farm operation utilities |
+| `LibFunction` | Function selector utilities |
+| `LibCases` | Protocol case handling |
+
+## Usage
+
+Libraries are typically imported and used in facets:
+
+```solidity
+import {LibSilo} from "contracts/libraries/Silo/LibSilo.sol";
+
+contract SiloFacet {
+    function deposit(address token, uint256 amount) external {
+        LibSilo._deposit(msg.sender, token, amount);
+    }
+}
+```
diff --git a/contracts/pipeline/README.md b/contracts/pipeline/README.md
new file mode 100644
index 00000000..3529eecc
--- /dev/null
+++ b/contracts/pipeline/README.md
@@ -0,0 +1,41 @@
+# Pipeline
+
+This directory contains Pipeline contracts for composable protocol interactions.
+
+## Overview
+
+Pipeline is a utility contract that enables chaining multiple protocol calls in a single transaction. It allows users to compose complex operations by "piping" data between calls.
+
+## Key Features
+
+- **Call Composition**: Chain multiple contract calls together
+- **Data Passing**: Pass output from one call as input to the next
+- **Gas Efficiency**: Execute multiple operations in a single transaction
+- **Flexibility**: Interact with any external protocol
+
+## Usage
+
+Pipeline integrates with the protocol through the `DepotFacet`, allowing users to:
+
+1. Execute external calls to other protocols
+2. Compose Pinto operations with DeFi integrations
+3. Build complex farming strategies
+
+## Integration
+
+Pipeline is commonly used with:
+- **Farm**: Combine Farm operations with external calls
+- **Tractor**: Automate complex multi-step operations
+- **Conversions**: Execute conversions through external DEXs
+
+## Example
+
+```solidity
+// Compose a swap and deposit in one transaction
+depot.pipe([
+    // Swap ETH for Bean on an external DEX
+    encodeSwap(ETH, BEAN, amount),
+    // Deposit the received Beans into the Silo
+    encodeDeposit(BEAN, receivedAmount)
+]);
+```
diff --git a/contracts/tokens/README.md b/contracts/tokens/README.md
new file mode 100644
index 00000000..1b186a3b
--- /dev/null
+++ b/contracts/tokens/README.md
@@ -0,0 +1,30 @@
+# Tokens
+
+This directory contains token contracts for the Pinto Protocol.
+
+## Overview
+
+Pinto's primary token is Bean (PINTO), a low-volatility ERC20 token with a $1 price target.
+
+## Directory Structure
+
+| Directory/File | Description |
+|----------------|-------------|
+| `Bean.sol` | Main Bean token contract |
+| `ERC20/` | ERC20 base implementations and extensions |
+
+## Bean Token
+
+The Bean token (`Bean.sol`) is the core stablecoin of the Pinto Protocol. Key features:
+
+- **Price Target**: $1 USD
+- **Low Volatility**: Peg stability through credit-based mechanisms
+- **Minting**: Controlled by the protocol during Seasons
+- **Burning**: Occurs during certain protocol operations
+
+## ERC20 Extensions
+
+The `ERC20/` directory contains ERC20 implementations with additional features required by the protocol:
+- Permit functionality (EIP-2612)
+- Protocol-specific access controls
+- Integration with the Diamond architecture