diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2415537
--- /dev/null
+++ b/README.md
@@ -0,0 +1,25 @@
+# TurboLong
+
+TurboLong is a multi-module Stellar project that combines a Soroban leverage strategy, alerting infrastructure, CLI utilities, and a Vite front end.
+
+## Module Docs
+
+| Directory | README | Purpose |
+| --- | --- | --- |
+| `contracts/` | [contracts/README.md](contracts/README.md) | Soroban strategy contract for the leveraged Blend vault. |
+| `alerts/` | [alerts/README.md](alerts/README.md) | Cloudflare Worker that sends APY alerts and manages subscriptions. |
+| `scripts/` | [scripts/README.md](scripts/README.md) | Helper scripts for debugging, deployment, oracle lookups, and simulations. |
+| `src/` | [src/README.md](src/README.md) | Rust CLI binaries for simulations, rate calculations, and execution flows. |
+| `frontend/` | [frontend/README.md](frontend/README.md) | Browser UI for interacting with the leveraged strategy. |
+
+## Quick Start
+
+1. Open the README for the area you want to work on.
+2. Install the dependencies for that module.
+3. Run the module-specific command listed in its README.
+
+If you are exploring the project for the first time, start with:
+
+- [contracts/README.md](contracts/README.md)
+- [frontend/README.md](frontend/README.md)
+- [src/README.md](src/README.md)
diff --git a/alerts/README.md b/alerts/README.md
new file mode 100644
index 0000000..0bb98ce
--- /dev/null
+++ b/alerts/README.md
@@ -0,0 +1,50 @@
+# Alerts
+
+This module is a Cloudflare Worker that lets users subscribe to APY alerts for supported pools and leverage brackets.
+
+## Purpose
+
+`alerts/` stores the worker that:
+
+- accepts subscription requests,
+- sends email verification and unsubscribe flows,
+- checks pool rates on a schedule, and
+- emails subscribers when the calculated net APY turns negative.
+
+## How To Run
+
+From the repository root:
+
+```bash
+cd alerts
+npm install
+npm run dev
+```
+
+Useful worker commands:
+
+```bash
+npm run db:create
+npm run db:migrate
+npm run deploy
+```
+
+Notes:
+
+- `npm run dev` starts the worker locally with Wrangler.
+- `npm run db:create` creates the D1 database entry expected by `wrangler.toml`.
+- `npm run db:migrate` applies the schema from `src/schema.sql`.
+- `npm run deploy` publishes the worker to Cloudflare.
+
+## File Map
+
+| File | Role |
+| --- | --- |
+| `package.json` | Local scripts and Wrangler tooling. |
+| `wrangler.toml` | Worker config, cron schedule, D1 binding, and env vars. |
+| `src/index.ts` | HTTP routes, cron handler, validation, and alert orchestration. |
+| `src/email.ts` | Email composition and delivery helpers. |
+| `src/schema.sql` | D1 schema for subscription storage. |
+| `src/stellar.ts` | Pool metadata, rate fetching, and APY math. |
+| `src/xdr.ts` | XDR helpers used by the worker. |
+
diff --git a/contracts/README.md b/contracts/README.md
new file mode 100644
index 0000000..2f9945d
--- /dev/null
+++ b/contracts/README.md
@@ -0,0 +1,39 @@
+# Contracts
+
+This directory contains the Soroban smart contract that powers the leveraged Blend strategy used by TurboLong.
+
+## Purpose
+
+The contract under `contracts/strategies/blend_leverage/` manages leveraged deposits, harvests BLND emissions, tracks strategy accounting, and coordinates safety checks against the Blend pool.
+
+## How To Run
+
+From the repository root:
+
+```bash
+cd contracts/strategies/blend_leverage
+cargo test
+cargo build --target wasm32-unknown-unknown --release
+```
+
+Notes:
+
+- `cargo test` runs the contract unit and integration tests.
+- `cargo build --target wasm32-unknown-unknown --release` builds the WASM artifact for deployment.
+- The contract depends on Soroban SDK crates and the Blend contract SDK, so first builds may take a little longer.
+
+## File Map
+
+| File | Role |
+| --- | --- |
+| `Cargo.toml` | Contract crate manifest and release settings. |
+| `src/lib.rs` | Contract entry point, constructor, strategy trait implementation, and public methods. |
+| `src/blend_pool.rs` | Blend pool interaction helpers. |
+| `src/constants.rs` | Shared constants and scaling values. |
+| `src/leverage.rs` | Leverage math, health factor checks, and safety helpers. |
+| `src/reserves.rs` | Reserve accounting and share conversion logic. |
+| `src/soroswap.rs` | Swap helpers for moving BLND into the underlying asset. |
+| `src/storage.rs` | Persistent config, keeper, and TTL management. |
+| `src/test_leverage.rs` | Leverage-focused tests. |
+| `src/test_integration.rs` | End-to-end contract tests. |
+
diff --git a/frontend/README.md b/frontend/README.md
new file mode 100644
index 0000000..6780f74
--- /dev/null
+++ b/frontend/README.md
@@ -0,0 +1,48 @@
+# Frontend
+
+This directory contains the Vite front end for TurboLong's leveraged strategy dashboard.
+
+## Purpose
+
+The app connects to Stellar wallets, switches between supported networks, shows pool and vault state, and builds the transactions needed for deposits, withdrawals, swaps, and leverage actions.
+
+## How To Run
+
+From the repository root:
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Useful commands:
+
+```bash
+npm run build
+npm run test
+npm run preview
+```
+
+Notes:
+
+- `npm run dev` starts the Vite development server.
+- `npm run build` produces a production bundle.
+- `npm run test` runs the parity test suite.
+
+## File Map
+
+| File | Role |
+| --- | --- |
+| `index.html` | Vite entry HTML. |
+| `package.json` | Front-end scripts and dependencies. |
+| `vite.config.ts` | Vite configuration. |
+| `public/favicon.svg` | Browser favicon. |
+| `public/logo.svg` | Project logo asset. |
+| `public/_redirects` | Deployment routing rules. |
+| `src/main.ts` | Application bootstrap, wallet integration, and UI orchestration. |
+| `src/blend.ts` | Blend pool data fetching, math, and transaction builders. |
+| `src/defindex.ts` | DeFindex vault helpers and transaction builders. |
+| `src/style.css` | App styling. |
+| `test/parity.test.ts` | Rate parity test between the TypeScript and Rust calculators. |
+
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..d83aecc
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,54 @@
+# Scripts
+
+This directory contains utility scripts for debugging, deployment, oracle inspection, token discovery, and leverage simulations.
+
+## Purpose
+
+The scripts here are intended for local operator workflows. They are not the user-facing app, but they are useful for inspecting on-chain state, testing strategy behavior, and preparing deployments.
+
+## How To Run
+
+From the repository root:
+
+```bash
+cd scripts
+npm install
+npm run testnet-loop
+```
+
+You can also run any individual TypeScript helper directly:
+
+```bash
+npx tsx test_strategy.ts
+npx tsx debug_pool.ts
+```
+
+Notes:
+
+- `npm run testnet-loop` is the main packaged entry point in `package.json`.
+- The other `.ts` files are runnable with `tsx` as ad hoc utilities.
+- `gen_thumbnail.py` is a Python helper and should be run with your local Python interpreter.
+
+## File Map
+
+| File | Role |
+| --- | --- |
+| `package.json` | Script entry points and runtime dependencies. |
+| `.npmrc` | npm configuration for the scripts workspace. |
+| `debug_blnd.ts` | Debug helper for BLND-related calculations. |
+| `debug_pool.ts` | Debug helper for pool state and rates. |
+| `deploy_strategy.ts` | Deployment helper for strategy contracts. |
+| `discover_pools.ts` | Pool discovery and inspection utility. |
+| `gen_thumbnail.py` | Python helper for asset or report thumbnail generation. |
+| `get_oracle.ts` | Oracle lookup helper. |
+| `get_oracle2.ts` | Alternate oracle lookup helper. |
+| `identify_tokens.ts` | Token identification helper. |
+| `mainnet_loop.ts` | Mainnet loop runner and strategy exercise script. |
+| `oracle_deep.ts` | Deep oracle inspection script. |
+| `oracle_deep2.ts` | Alternate deep oracle inspection script. |
+| `oracle_deep3.ts` | Alternate deep oracle inspection script. |
+| `oracle_deep4.ts` | Alternate deep oracle inspection script. |
+| `query_oracle.ts` | Oracle query helper. |
+| `testnet_loop.ts` | Testnet loop runner used by the npm script. |
+| `test_strategy.ts` | Strategy test harness. |
+
diff --git a/src/README.md b/src/README.md
new file mode 100644
index 0000000..f53a833
--- /dev/null
+++ b/src/README.md
@@ -0,0 +1,39 @@
+# src
+
+This directory contains the Rust command-line binaries used to simulate, calculate, and execute TurboLong leverage flows.
+
+## Purpose
+
+The binaries here mirror the on-chain Blend math and transaction flow so you can inspect rates, simulate loops, or prepare an execution run before touching a wallet.
+
+## How To Run
+
+From the repository root:
+
+```bash
+cargo test
+cargo run --bin rate_calc < tests/fixtures/rates.json
+cargo run --bin simulate -- --loops 20
+```
+
+For the execution helper, provide a secret key file and run from the repo root:
+
+```bash
+cargo run --bin execute_loop -- --key-file /path/to/keyfile --loops 13 --initial 1000
+```
+
+Notes:
+
+- `cargo test` runs the Rust test suite, including the leverage simulation test under `tests/`.
+- `rate_calc` reads JSON fixtures from stdin and prints projected rates.
+- `simulate` reads live pool data and prints a leverage table.
+- `execute_loop` submits or simulates the atomic leverage transaction flow.
+
+## File Map
+
+| File | Role |
+| --- | --- |
+| `bin/execute_loop.rs` | CLI for building and submitting the leverage execution flow. |
+| `bin/rate_calc.rs` | Fixture-driven rate projection tool used by parity tests. |
+| `bin/simulate.rs` | Live mainnet simulation and reporting tool. |
+