diff --git a/README.md b/README.md
index 9d9c471..b942f2a 100644
--- a/README.md
+++ b/README.md
@@ -48,6 +48,20 @@
 **Treee** is the smart contract layer of the *Treee tree-planting protocol*, enabling on-chain verification, organization management, and NFT issuance for planted trees.  
 It powers transparent and auditable sustainability tracking within the **Stability Nexus** ecosystem.
 
+## 📋 Table of Contents
+
+- [Tech Stack](#tech-stack)
+- [Architecture Overview](#architecture-overview)
+- [Getting Started](#getting-started)
+- [Developer Workflow](#developer-workflow)
+- [Testing](#testing)
+- [Deployment](#deployment)
+- [Common Commands](#common-commands)
+- [Project Structure](#project-structure)
+- [Security](#security)
+- [Contributing](#contributing)
+- [License](#license)
+
 ---
 
 ## Tech Stack
@@ -58,12 +72,50 @@ It powers transparent and auditable sustainability tracking within the **Stabili
 - **Foundry (forge, anvil, cast)** — Testing, simulation & deployment  
 - **OpenZeppelin Contracts** — Token standards and access control  
 
-### Contracts
+### Libraries & Dependencies
 
-- `TreeNft.sol` — NFT for planted trees  
-- `Organisation.sol` — Handles organization logic  
-- `OrganisationFactory.sol` — Deploys and tracks organizations  
-- `CareToken.sol`, `PlanterToken.sol`, `LegacyToken.sol` — Incentive ERC-20 tokens  
+- **foundry-devops** — Deployment utilities  
+- **forge-std** — Foundry standard library for testing  
+
+---
+
+## Architecture Overview
+
+### Core Contracts
+
+#### 🌳 TreeNft.sol
+The main NFT contract representing planted trees. Each NFT contains:
+- **Metadata** — Tree species, location, planting date
+- **Verification status** — On-chain proof of planting
+- **Organization tracking** — Links to the planting organization
+
+#### 🏢 Organisation.sol
+Manages individual organizations that plant trees:
+- **Role management** — Admin, verifier, and planter roles
+- **Tree tracking** — Records trees planted by the organization
+- **Token distribution** — Manages incentive token allocation
+
+#### 🏭 OrganisationFactory.sol
+Factory contract for deploying and managing organizations:
+- **Organization deployment** — Creates new organization contracts
+- **Registry** — Maintains a list of all active organizations
+- **Access control** — Manages who can create organizations
+
+### Token Contracts
+
+#### 💚 CareToken.sol
+ERC-20 token rewarding tree care and maintenance activities.
+
+#### 🌱 PlanterToken.sol
+ERC-20 token incentivizing tree planting activities.
+
+#### 🏆 LegacyToken.sol
+ERC-20 token for long-term sustainability contributions.
+
+### Utilities
+
+- **errors.sol** — Custom error definitions for gas-efficient reverts
+- **structs.sol** — Shared data structures across contracts
 
 ---
 
@@ -71,107 +123,384 @@ It powers transparent and auditable sustainability tracking within the **Stabili
 
 ### Prerequisites
 
-- [Foundry](https://book.getfoundry.sh/getting-started/installation)
-- Rust toolchain (`rustup`)  
-- Node.js (optional, for deployment scripting)
+Ensure you have the following installed:
 
----
+- **[Foundry](https://book.getfoundry.sh/getting-started/installation)** — Ethereum development toolkit
+  ```bash
+  curl -L https://foundry.paradigm.xyz | bash
+  foundryup
+  ```
+- **Git** — Version control
+- **Rust toolchain** — Required by Foundry (`rustup`)
+- **Node.js** (optional) — For additional tooling
 
-### Quickstart
+### Environment Setup
+
+Create a `.env` file in the root directory:
+Install dependencies
 
-#### 1. Clone the repository
 ```bash
-git clone https://github.com/StabilityNexus/Treee-Solidity.git
-cd Treee-Solidity
+forge install
 ```
 
-#### 2. Build contracts
+#### 3. Build contracts
 
 ```bash
 forge build
 ```
 
-#### 3. Run tests
+#### 4. Run tests
 
 ```bash
 forge test
 ```
 
-#### 4. Start a local node
+#### 5. Start a local node
 
 ```bash
 anvil
 ```
 
-#### 5. Deploy (example)
+#### 6. Deploy locally
 
 ```bash
-forge script script/Deploy.s.sol:DeployAllContractsAtOnce \
-  --rpc-url $SEPOLIA_RPC_URL \
-  --private-key $PRIVATE_KEY \
+# In a new terminal, deploy to local Anvil node
+forge script script/DeployAllContracts.s.sol:DeployAllContractsAtOnce \
+  --rpc-url http://127.0.0.1:8545 \
+  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+### Local Development
+
+#### Start local blockchain:
+
+```bash
+anvil
+```
+
+#### Test in watch mode:
+
+```bash
+forge test --watch
+```
+
+#### Run specific tests:
+
+```bash
+# Test a specific contract
+forge test --match-contract TreeNftTest
+
+# Test a specific function
+forge test --match-test testMintTree
+
+# Verbose output
+forge test -vvv
+```
+
+#### Gas reporting:
+
+```bash
+forge test --gas-report
+```
+
+#### Check test coverage:
+
+```bash
+forge coverage
+```
+
+### Interacting with Contracts
+
+#### Using Cast (Command Line):
+
+```bash
+# Call a view function
+cast call <CONTRACT_ADDRESS> "getOrganisationCount()(uint256)" --rpc-url http://127.0.0.1:8545
+
+# Send a transaction
+cast send <CONTRACT_ADDRESS> "mintTree(address,string)" <RECIPIENT> "ipfs://metadata" \
+  --private-key <YOUR_KEY> \
+  --rpc-url http://127.0.0.1:8545
+
+# Get contract balance
+cast balance <ADDRESS> --rpc-url http://127.0.0.1:8545
+```
+
+#### Using Forge Scripts:
+
+```bash
+# Deploy Organisation Factory
+forge script script/DeployOrganisationFactory.s.sol:DeployOrganisationFactory \
+  --rpc-url http://127.0.0.1:8545 \
+  --broadcast
+
+# Deploy TreeNft Contract
+forge script script/DeployTreeNftContract.s.sol:DeployTreeNft \
+  --rpc-url http://127.0.0.1:8545 \
   --broadcast
 ```
 
 ---
 
-## Developer Workflow
+## Project Structure
+
+```
+Treee-Solidity/
+├── 📁 src/                          # Smart contracts source code
+│   ├── 📄 Organisation.sol          # Organization management contract
+│   ├── 📄 OrganisationFactory.sol   # Factory for creating organizations
+│   ├── 📄 TreeNft.sol               # Tree NFT contract (ERC-721)
+│   ├── 📁 token-contracts/          # ERC-20 token implementations
+│   │   ├── 📄 CareToken.sol         # Care incentive token
+│   │   ├── 📄 PlanterToken.sol      # Planter reward token
+│   │   └── 📄 LegacyToken.sol       # Legacy contribution token
+│   └── 📁 utils/                    # Utility contracts
+│       ├── 📄 errors.sol            # Custom error definitions
+│       └── 📄 structs.sol           # Shared data structures
+│
+├── 📁 script/                       # Deployment & interaction scripts
+│   ├── 📄 DeployAllContracts.s.sol  # Deploy all contracts at once
+│   ├── 📄 DeployOrganisationFactory.s.sol
+│   └── 📄 DeployTreeNftContract.s.sol
+│
+├── 📁 test/                         # Test files (Foundry tests)
+│   ├── 📄 Organisation.t.sol        # Organisation contract tests
+│   ├── 📄 OrganisationFactory.t.sol # Factory contract tests
+│   └── 📄 TreeNft.t.sol             # TreeNft contract tests
+│
+├── 📁 lib/                          # External dependencies (Git submodules)
+│   ├── 📁 forge-std/                # Foundry standard library
+│   ├── 📁 foundry-devops/           # Deployment tools & utilities
+│   └── 📁 openzeppelin-contracts/   # OpenZeppelin security libraries
+│
+├── 📁 img/                          # Images & assets
+│
+├── 📄 foundry.toml                  # Foundry configuration
+├── 📄 remappings.txt                # Import path remappings
+├── 📄 makefile                      # Build automation
+├── 📄 package.json                  # Node.js package config
+└── 📄 README.md                     # This file
+```
+
+### Key Files Explained
+
+| File/Directory | Purpose |
+|----------------|---------|
+| `foundry.toml` | Foundry configuration including Solidity version, optimizer settings, and test paths |
+| `remappings.txt` | Maps import paths (e.g., `@openzeppelin/` → `lib/openzeppelin-contracts/`) |
+| `makefile` | Contains shortcuts for common build and deployment commands |
+| `lib/` | Contains all external dependencies installed via `forge install` |
+| `script/` | Deployment scripts using Foundry's scripting capabilities |
+| `test/` | Unit and integration tests using Foundry's testing framework |
+
+---
+
+## Testing
+
+### Test Structure
 
-Run a local node:
+```
+test/
+├── Organisation.t.sol       # Organisation contract tests
+├── OrganisationFactory.t.sol # Factory contract tests
+└── TreeNft.t.sol            # TreeNft contract tests
+```
+
+### Running Tests
 
 ```bash
-anvil
+# Run all tests
+forge test
+
+# Run with different verbosity levels
+forge test -v     # Show stack traces for failing tests
+forge test -vv    # Show stack traces for all tests
+forge test -vvv   # Show execution traces for failing tests
+forge test -vvvv  # Show execution traces for all tests
+forge test -vvvvv # Show execution and setup traces for all tests
+
+# Filter tests by name pattern
+forge test --match-test testMint
+
+# Filter tests by contract
+forge test --match-contract TreeNft
+
+# Run tests on specific file
+forge test --match-path test/TreeNft.t.sol
+
+# Generate gas snapshot
+forge snapshot
+
+# Compare gas usage
+forge snapshot --diff
+```
+
+---
+
+## Deployment
+
+### Testnet Deployment (Sepolia)
+
+#### 1. Configure environment variables in `.env`:
+
+```env
+SEPOLIA_RPC_URL=<your_rpc_url>
+PRIVATE_KEY=<your_private_key>
+ETHERSCAN_API_KEY=<your_api_key>
 ```
 
-Test in watch mode:
+#### 2. Deploy all contracts:
 
 ```bash
-forge test --watch
+forge script script/DeployAllContracts.s.sol:DeployAllContractsAtOnce \
+  --rpc-url $SEPOLIA_RPC_URL \
+  --private-key $PRIVATE_KEY \
+  --broadcast \
+  --verify \
+  --etherscan-api-key $ETHERSCAN_API_KEY
 ```
 
-Interact manually:
+#### 3. Deploy individual contracts:
 
 ```bash
-cast call <contract-address> "getOrganisationCount()()" --rpc-url http://127.0.0.1:8545
+# Deploy Organisation Factory
+forge script script/DeployOrganisationFactory.s.sol \
+  --rpc-url $SEPOLIA_RPC_URL \
+  --private-key $PRIVATE_KEY \
+  --broadcast \
+  --verify
+
+# Deploy TreeNft
+forge script script/DeployTreeNftContract.s.sol \
+  --rpc-url $SEPOLIA_RPC_URL \
+  --private-key $PRIVATE_KEY \
+  --broadcast \
+  --verify
 ```
 
----
+### Mainnet Deployment
 
-## Common Commands
+⚠️ **Critical**: Before mainnet deployment:
+
+1. ✅ Complete security audit
+2. ✅ Test extensively on testnet
+3. ✅ Verify all contract addresses
+4. ✅ Use hardware wallet or secure key management
+5. ✅ Double-check constructor parameters
+
+```bash
+forge script script/DeployAllContracts.s.sol:DeployAllContractsAtOnce \
+  --rpc-url $MAINNET_RPC_URL \
+  --private-key $PRIVATE_KEY \
+  --broadcast \
+  --verify \
+  --etherscan-api-key $ETHERSCAN_API_KEY
+```
+
+### Verify Contracts Manually
 
-| Command          | Description                 |
-| ---------------- | --------------------------- |
-| `forge build`    | Compile contracts           |
-| `forge test`     | Run tests                   |
-| `forge fmt`      | Format Solidity code        |
-| `forge snapshot` | Create gas usage reports    |
-| `anvil`          | Start local blockchain node |
+If automatic verification fails:
+
+```bash
+forge verify-contract <CONTRACT_ADDRESS> \
+  src/TreeNft.sol:TreeNft \
+  --chain-id 11155111 \
+  --etherscan-api-key $ETHERSCAN_API_KEY \
+  --constructor-args $(cast abi-encode "constructor(string,string)" "TreeNFT" "TREE")
+```
 
 ---
 
-## Contributing
+## Common Commands
+
+| Command                    | Description                              |
+| `forge build`              | Compile contracts                        |
+| `forge test`               | Run all tests                            |
+| `forge test -vvvv`         | Run tests with detailed traces           |
+| `forge fmt`                | Format Solidity code                     |
+| `forge clean`              | Remove build artifacts                   |
+| `forge snapshot`           | Create gas usage snapshot                |
+| `forge coverage`           | Generate test coverage report            |
+| `anvil`                    | Start local blockchain node              |
+| `cast call`                | Call a contract function (read-only)     |
+| `cast send`                | Send a transaction to a contract         |
+| `forge script <script>`    | Execute Whether it's bug fixes, new features, documentation improvements, or feedback.
 
-We welcome contributions of all kinds!
+### How to Contribute
 
-1. Fork the repo & create a feature branch:
+1. **Fork the repository** and create a feature branch:
 
    ```bash
    git checkout -b feature/AmazingFeature
    ```
-2. Commit your changes:
+
+2. **Make your changes** following our coding standards:
+   - Write clear, documented code
+   - Follow Solidity style guide
+   - Add tests for new functionality
+   - Update documentation as needed
+
+3. **Run all checks** before committing:
+
+   ```bash
+   forge build && forge test && forge fmt
+   ```
+
+4. **Commit your changes** with descriptive messages:
 
    ```bash
-   git commit -m "Add some AmazingFeature"
+   git commit -m "feat: Add tree verification mechanism"
    ```
-3. Run checks:
+
+5. **Push to your fork** and open a Pull Request:
 
    ```bash
-   forge build && forge test && forge fmt
+   git push origin feature/AmazingFeature
    ```
-4. Push & open a PR 
 
-For bugs, suggestions, or questions — open an issue or reach us on [Discord](https://discord.gg/YzDKeEfWtS).
+### Development Guidelines
+
+- ✅ Write tests for all new features
+- ✅ Maintain or improve test coverage
+- ✅ Follow existing code style and patterns
+- ✅ Add NatSpec comments to public functions
+- ✅ Update README if adding new features
+- ✅ Keep commits atomic and well-described
+
+### Getting Help
+
+- 💬 [Discord](https://discord.gg/YzDKeEfWtS) — Ask questions and get help
+- 🐛 [GitHub Issues](https://github.com/StabilityNexus/Treee-Solidity/issues) — Report bugs
+- 💡 [GitHub Discussions](https://github.com/StabilityNexus/Treee-Solidity/discussions) — Feature requests and ideas
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+---
+
+## Resources
+
+### Documentation
+
+- [Foundry Book](https://book.getfoundry.sh/) — Official Foundry documentation
+- [Solidity Docs](https://docs.soliditylang.org/) — Solidity language reference
+- [OpenZeppelin Docs](https://docs.openzeppelin.com/) — Smart contract libraries
+
+### Community
+
+- 🌐 [Website](https://treee.stability.nexus/)
+- 📰 [Blog](https://news.stability.nexus/)
+- 🐦 [Twitter/X](https://x.com/StabilityNexus)
+- 💼 [LinkedIn](https://linkedin.com/company/stability-nexus)
+- 📺 [YouTube](https://www.youtube.com/@StabilityNexus)
 
 ---
 
-© 2025 **Treee Project** · [Stability Nexus](https://stability.nexus/) ecosystem.
+<div align="center">
+
+**Built with 💚 by the Treee Team**
 
+© 2025 **Treee Project** · Part of the [Stability Nexus](https://stability.nexus/) ecosystem
+
+</div>