diff --git a/README.md b/README.md
index 285952e..5b18a57 100644
--- a/README.md
+++ b/README.md
@@ -1,45 +1,132 @@
-# car64
+<p align="center">
+  <img src="assets/icon/app_icon.png" alt="car64 logo" width="120" />
+</p>
 
-car64 is a Flutter + Supabase die-cast collector app with a fast scanning workflow, private photo storage, collaborative collections, and community-based catalog validation.
+<h1 align="center">car64</h1>
 
-## Core Features
+<p align="center">
+  A modern Flutter + Supabase app for tracking and managing die-cast car collections.
+</p>
 
-- Lightning add flow with barcode/OCR scanning and active collection selection.
-- Global catalog (`global_cars`) + personal entries (`hotwheels`) architecture.
-- Private storage (`car-images`) with signed URL rendering for collection members.
-- In-app photo compression pipeline (target max 1080px and <500 KB uploads).
-- Collaborative garages via `collections` + `collection_members`.
-- Community validation with `car_votes`, `confirmation_count`, and verification state.
+---
 
-## Local Development
+## Overview
 
-1. Install Flutter (stable) and run `flutter doctor`.
-2. Configure Supabase values via build-time variables (`--dart-define`) — required (no fallback is embedded), for example:
+car64 helps collectors scan model IDs, organize personal and shared collections, and keep a clean catalog with community validation/reporting flows.
 
-	```bash
-	flutter run \
-	  --dart-define=SUPABASE_URL=https://your-project.supabase.co \
-	  --dart-define=SUPABASE_ANON_KEY=your_anon_key \
-	  --dart-define=SUPABASE_USE_PKCE=true
-	```
-3. Install dependencies:
+## Features
 
-	```bash
-	flutter pub get
-	```
+- Fast scan workflow (camera OCR + manual entry fallback)
+- Multi-collection support with member roles (owner/member/viewer)
+- Private image storage with signed URL access
+- Collection collaboration and member management
+- Community validation and issue reporting for catalog entries
+- Profile/settings flows including password updates and report tracking
 
-4. Run the app:
+## Tech Stack
 
-	```bash
-	flutter run
-	```
+- Flutter (Material 3)
+- Supabase (Auth, PostgREST, Storage, RPC)
+- Shared Preferences (local settings)
+- Google ML Kit Text Recognition (scanner)
 
-## Quality Check
+## Prerequisites
+
+- Flutter SDK (stable)
+- A Supabase project
+- For iOS builds: macOS + Xcode
+
+## Configuration
+
+Supabase config is required at runtime/build time (no embedded fallback values).
+
+### Option A: local defines file (recommended)
+
+Use:
+
+- `.env/flutter_defines.json` (local, ignored by git)
+- `.env/flutter_defines.example.json` (tracked template)
+
+Expected shape:
+
+```json
+{
+  "SUPABASE_URL": "https://your-project.supabase.co",
+  "SUPABASE_ANON_KEY": "your_anon_key",
+  "SUPABASE_USE_PKCE": "true"
+}
+```
+
+### Option B: direct dart-define flags
+
+```bash
+flutter run \
+  --dart-define=SUPABASE_URL=https://your-project.supabase.co \
+  --dart-define=SUPABASE_ANON_KEY=your_anon_key \
+  --dart-define=SUPABASE_USE_PKCE=true
+```
+
+## Getting Started
+
+1. Install dependencies
+
+```bash
+flutter pub get
+```
+
+2. Run analyze
 
 ```bash
 flutter analyze
 ```
 
+3. Launch app
+
+```bash
+flutter run
+```
+
+## VS Code Workflows
+
+### Run / Debug (`launch.json`)
+
+Use **Run and Debug** with:
+
+- `Flutter (Supabase Local - Debug)`
+- `Flutter (Supabase Local - Profile)`
+- `Flutter (Supabase Local - Release)`
+
+These configurations read:
+
+`--dart-define-from-file=.env/flutter_defines.json`
+
+### Build Tasks (`tasks.json`)
+
+Use **Terminal → Run Task**:
+
+- `Flutter Build APK (Release)`
+- `Flutter Build App Bundle (Release)`
+- `Flutter Build iOS IPA (Release)`
+
+## Project Structure (high level)
+
+- `lib/screens/` UI screens and flows
+- `lib/services/` Supabase integration/services
+- `lib/widgets/` reusable UI components
+- `lib/utils/` helpers and formatting utilities
+- `lib/theme/` app theme and colors
+
+## Security Notes
+
+- Supabase anon keys are intentionally client-side, but RLS and RPC permissions must be strict.
+- Sensitive local config files are git-ignored.
+- User-facing errors are sanitized and shown via global overlays.
+
+## License
+
+License file is not included in this repository yet.
+Add your preferred license in the GitHub repo when ready.
+
 ## Reference
 
-- Product and backend requirements: `TPB.md`
+- Product/backend notes: `TPB.md`