diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..ae6dd10
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Buttonwood Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index c622c5f..a7223aa 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,99 @@
-## Consol Protocol
+# Consol Protocol
 
-## Production Notes
-- Deployer should deposit at least $1 into USDX and then into Consol, and then transfer ownership to the contract to lock it in. This will help defend against donation attacks.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Solidity](https://img.shields.io/badge/Solidity-0.8.20-blue)](https://soliditylang.org/)
+[![Foundry](https://img.shields.io/badge/Built%20with-Foundry-FFDB1C)](https://book.getfoundry.sh/)
 
-## Documentation
+**Consol Protocol** is a decentralized mortgage lending platform developed by [Buttonwood Protocol](https://github.com/buttonwood-protocol). It enables on-chain mortgage origination, servicing, and conversion with features like origination pools, lender queues, and collateral management.
+
+## Features
+
+- **Mortgage Origination** - Create and manage on-chain mortgage positions with customizable terms
+- **Origination Pools** - Lender pools for deploying capital to mortgage origination with epoch-based lifecycle
+- **Multi-Token Vaults** - ERC4626-compliant vaults supporting multiple collateral types (USDX, SubConsol)
+- **Lender Queues** - Fair withdrawal queue system for lenders
+- **Conversion System** - Convert mortgage positions between collateral types
+- **Order Pool** - Matching system for mortgage orders
+- **Yield Strategies** - Pluggable yield strategies for collateral management
+
+## Architecture
+
+```
+src/
+├── Consol.sol              # Main vault for USDX deposits
+├── SubConsol.sol           # Collateral-specific sub-vaults
+├── LoanManager.sol         # Mortgage lifecycle management
+├── GeneralManager.sol      # Protocol configuration and settings
+├── OriginationPool.sol     # Epoch-based lending pools
+├── OriginationPoolScheduler.sol  # Pool deployment scheduling
+├── OrderPool.sol           # Order matching system
+├── LenderQueue.sol         # Withdrawal queue for lenders
+├── ConversionQueue.sol     # Collateral conversion queue
+├── MortgageNFT.sol         # NFT representation of mortgages
+└── USDX.sol                # Multi-collateral stablecoin
+```
+
+## Security
+
+Consol Protocol has been audited by Guardian. The audit report is available in the [`audits/`](audits/) directory.
+
+## Getting Started
+
+### Prerequisites
+
+- [Foundry](https://book.getfoundry.sh/getting-started/installation)
+- [Node.js](https://nodejs.org/) (v18+)
+- [pnpm](https://pnpm.io/)
 
-https://book.getfoundry.sh/
+### Installation
 
-## Usage
+```shell
+# Clone the repository
+git clone https://github.com/buttonwood-protocol/consol.git
+cd consol
+
+# Install dependencies
+pnpm install
+```
 
 ### Build
 
 ```shell
-$ forge build
+forge build
 ```
 
 ### Test
 
 ```shell
-$ forge test
+forge test
 ```
 
-### Format
+### Format & Lint
 
 ```shell
-$ forge fmt
-$ pnpm solhint
-$ lintspec src --compact
+forge fmt
+pnpm solhint
+lintspec src --compact
 ```
 
 ### Gas Snapshots
 
 ```shell
-$ forge snapshot
+forge snapshot
 ```
+
+## Production Notes
+
+> **Important:** Deployer should deposit at least $1 into USDX and then into Consol, and then transfer ownership to the contract to lock it in. This will help defend against donation attacks.
+
+## Documentation
+
+- [Foundry Book](https://book.getfoundry.sh/) - Development framework documentation
+
+## Contributing
+
+Contributions are welcome! Please see the [pull request template](pull_request_template.md) for guidelines.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.