diff --git a/README.md b/README.md
index 8817d6ab..3b675074 100644
--- a/README.md
+++ b/README.md
@@ -1,66 +1,66 @@
-## Foundry
+# Aavegotchi Geist Contracts
 
-**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
+Canonical contracts and upgrade scripts for Aavegotchi on Base.
 
-Foundry consists of:
+As of July 25, 2025, Aavegotchi's canonical home chain is Base (`8453`). This repository is the main source for active smart contract development, deployments, and upgrade tooling.
 
-- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
-- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
-- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
-- **Chisel**: Fast, utilitarian, and verbose solidity REPL.
+Legacy Polygon/Ethereum contracts are maintained in [`aavegotchi/aavegotchi-contracts`](https://github.com/aavegotchi/aavegotchi-contracts).
 
-## Documentation
+## Canonical Base Addresses
 
-https://book.getfoundry.sh/
+The addresses below are sourced from `helpers/constants.ts` (`networkAddresses[8453]`).
 
-## Usage
+| Component | Address |
+| --- | --- |
+| GHST (Base) | [`0xcd2f22236dd9dfe2356d7c543161d4d260fd9bcb`](https://basescan.org/address/0xcd2f22236dd9dfe2356d7c543161d4d260fd9bcb) |
+| AavegotchiDiamond | [`0xA99c4B08201F2913Db8D28e71d020c4298F29dBF`](https://basescan.org/address/0xA99c4B08201F2913Db8D28e71d020c4298F29dBF) |
+| WearableDiamond | [`0x052e6c114a166B0e91C2340370d72D4C33752B4b`](https://basescan.org/address/0x052e6c114a166B0e91C2340370d72D4C33752B4b) |
+| ForgeDiamond | [`0x50aF2d63b839aA32b4166FD1Cb247129b715186C`](https://basescan.org/address/0x50aF2d63b839aA32b4166FD1Cb247129b715186C) |
+| RarityFarming | [`0x8c8E076Cd7D2A17Ba2a5e5AF7036c2b2B7F790f6`](https://basescan.org/address/0x8c8E076Cd7D2A17Ba2a5e5AF7036c2b2B7F790f6) |
 
-### Build
+For the full address map (including Base Sepolia and legacy networks), see [`helpers/constants.ts`](./helpers/constants.ts).
 
-```shell
-$ forge build
-```
+## Supported Networks
 
-### Test
+| Network | Chain ID | Status |
+| --- | --- | --- |
+| Base Mainnet | `8453` | Canonical production |
+| Base Sepolia | `84532` | Testnet |
+| Polygon | `137` | Legacy/reference scripts |
 
-```shell
-$ forge test
-```
+## Quick Start
 
-### Format
+### 1) Install
 
-```shell
-$ forge fmt
+```bash
+npm install
 ```
 
-### Gas Snapshots
+### 2) Configure environment
 
-```shell
-$ forge snapshot
-```
+Set required variables in `.env`:
 
-### Anvil
+- `BASE_RPC_URL`
+- `BASE_SEPOLIA_RPC_URL`
+- `SECRET`
 
-```shell
-$ anvil
-```
+Optional for legacy scripts:
 
-### Deploy
+- `MATIC_URL`
+- `AMOY_URL`
 
-```shell
-$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
-```
-
-### Cast
+### 3) Compile and test
 
-```shell
-$ cast <subcommand>
+```bash
+npx hardhat compile
+npx hardhat test
+forge build
+forge test
 ```
 
-### Help
+## Related Docs
 
-```shell
-$ forge --help
-$ anvil --help
-$ cast --help
-```
+- Swap + buy flow integration: [`SWAP_AND_BUY_INTEGRATION.md`](./SWAP_AND_BUY_INTEGRATION.md)
+- Aavegotchi docs: [https://docs.aavegotchi.com](https://docs.aavegotchi.com)
+- Wiki migration reference: [https://wiki.aavegotchi.com/base-migration](https://wiki.aavegotchi.com/base-migration)
+- Migration announcement: [https://blog.aavegotchi.com/aavegotchi-has-migrated-to-base/](https://blog.aavegotchi.com/aavegotchi-has-migrated-to-base/)