diff --git a/README.md b/README.md
index 462e31e..8a6fe20 100644
--- a/README.md
+++ b/README.md
@@ -1,41 +1,124 @@
-# vite React TypeScript tailwindcss starter
+# Kleo Connect
 
-Template for vite, React + tailwindcss + TypeScript projects with some tools preconfigured.
+Kleo Connect is a Vite + React + TypeScript frontend for Kleo user onboarding, wallet/profile flows, and connected data cards. The app lets users sign up, connect supported web accounts, view their profile, and inspect their data dashboard.
 
-## About
+## Tech stack
 
-Template for vite, React + tailwindcss + TypeScript projects with some tools preconfigured.
+- React 18 + React Router 6
+- TypeScript 4.9
+- Vite 4
+- Tailwind CSS 3
+- Vitest
+- ESLint + Prettier + Husky + Commitlint
 
-![Screenshot](assets/screenshot.png)
+## Prerequisites
 
-### Libraries
+- Node.js 18.x (matches the CI workflow)
+- npm 9+ or Yarn
 
-- [React 18](https://reactjs.org/)
-- [React Router 6](https://reactrouter.com)
-- [tailwindcss 3](https://tailwindcss.com/)
-  - [tailwindcss forms plugin](https://tailwindcss-forms.vercel.app/)
-- [TypeScript 4.9.5](https://www.typescriptlang.org/)
-- [vite 4](https://vitejs.dev/)
-- [vitetest](https://vitest.dev/)
+## Local setup
 
-### Tools
+1. Install dependencies:
 
-- [commitlint 17](https://commitlint.js.org)
-- [Conventional Commits 1](https://www.conventionalcommits.org)
-- [editorconfig](https://editorconfig.org/)
-- [eslint 8](https://eslint.org/)
-- [husky 8](https://typicode.github.io/husky/#/)
-- [Prettier 2](https://prettier.io/)
-- [VS Code settings](https://code.visualstudio.com/)
+   ```bash
+   npm install
+   ```
 
-## Usage
+2. Create a local environment file:
 
-Create a new project from this template by clicking the "Use this template" button:
+   ```bash
+   cp .env.example .env
+   ```
 
-![](assets/template-usage.png)
+3. Fill the provider keys that your flow needs. The app can start with empty values, but OAuth, map, wallet, upload, and redirect flows need their corresponding `VITE_*` settings.
+
+4. Start the dev server:
+
+   ```bash
+   npm run dev
+   ```
+
+5. Open the URL printed by Vite, usually `http://localhost:5173`.
+
+## Environment variables
+
+The frontend reads configuration from `.env` through `import.meta.env`. Keep secrets out of Git and use `.env.example` only as a template.
+
+Common groups:
+
+- `VITE_GOOGLE_*` - Google OAuth configuration
+- `VITE_CALENDLY_*` - Calendly integration configuration
+- `VITE_INSTAGRAM_*`, `VITE_LINKEDIN_*`, `VITE_TWITTER_*`, `VITE_GITHUB_CLIENTID` - social connection keys
+- `VITE_GOOGLE_MAP_KEY` - map rendering
+- `VITE_RPC_URL` - blockchain RPC endpoint
+- `VITE_REDIRECTED_URL` - app redirect URL used after external auth flows
+- `VITE_KLEO_THIRDWEB_CLIENT_KEY`, `VITE_KLEO_THIRDWEB_SECRET` - Thirdweb configuration
+- `VITE_UPLOAD_API_DOMAIN` - decentralized upload API host
+
+## Project structure
+
+```text
+.
+├── assets/                 # README screenshots and static documentation assets
+├── src/
+│   ├── App.tsx             # Route definitions and top-level auth/profile state
+│   ├── main.tsx            # React root and BrowserRouter setup
+│   ├── common/
+│   │   ├── charts/         # Shared chart components
+│   │   ├── components/     # Shared UI components
+│   │   ├── constants/      # Static signup, event, URL, and website data
+│   │   ├── hooks/          # Reusable hooks for fetches, wallet, debounce, scroll
+│   │   ├── config.ts       # Environment-backed app configuration
+│   │   ├── interface.ts    # Shared TypeScript interfaces
+│   │   └── utils.ts        # Shared helper functions
+│   └── pages/
+│       ├── PrivacyPolicy/  # Privacy policy route
+│       ├── profile/        # Public profile and My Data screens
+│       └── signup/         # Multi-step signup/onboarding flow
+├── __tests__/              # Vitest tests
+├── .github/workflows/      # CI: lint, build, test
+├── tailwind.config.js      # Tailwind theme and plugin configuration
+└── vite.config.ts          # Vite and polyfill configuration
+```
+
+## Available scripts
 
 ```bash
-yarn
-yarn dev
-yarn test
+npm run dev      # Start Vite dev server
+npm run build    # Create production build in dist/
+npm run serve    # Preview the production build on port 3000
+npm run lint     # Run ESLint over JS/TS/TSX files
+npm run test     # Run Vitest
 ```
+
+## Routing overview
+
+- `/` redirects users to `/signup/0` unless an authenticated user token is present.
+- `/signup/:step` renders the onboarding flow.
+- `/profile/:address` renders a profile page for a wallet/address.
+- `/my-data/:address` renders the data dashboard for logged-in users.
+- `/privacy` renders the privacy policy.
+
+## Build, test, and deployment
+
+Before opening a pull request, run:
+
+```bash
+npm run lint
+npm run build
+npm run test
+```
+
+Deploy the generated `dist/` directory to any static hosting provider that supports single-page applications. Configure the host to serve `index.html` for unknown routes so React Router paths work after refresh.
+
+## Contributing
+
+1. Fork the repository and create a branch from `production`.
+2. Keep changes focused and small.
+3. Run lint, build, and tests locally.
+4. Open a pull request with a clear summary, validation notes, and screenshots for UI changes.
+5. Follow Conventional Commits for commit messages when possible, for example `docs: update project readme`.
+
+## License
+
+This project is licensed under the terms in [LICENSE](LICENSE).