diff --git a/.env.example b/.env.example
index dfca079..f574b7c 100644
--- a/.env.example
+++ b/.env.example
@@ -1,26 +1,32 @@
-# Environment Configuration
+# Application Configuration
 # Copy this file to .env and fill in your actual values
-# DO NOT commit .env to version control
+# The .env file is in .gitignore and should never be committed
 
-# API Configuration
-API_BASE_URL_DEV=https://api-dev.example.com
-API_BASE_URL_PROD=https://api.example.com
+# App Name (displayed in app launcher and settings)
+# This is a reference value - you'll also need to update:
+# - Android: android/app/src/main/AndroidManifest.xml (android:label)
+# - macOS: macos/Runner/Configs/AppInfo.xcconfig (PRODUCT_NAME)
+# - pubspec.yaml (name field - used for package name)
+APP_NAME=app_boilerplate
 
 # Immich Configuration
 IMMICH_BASE_URL=https://photos.satoshinakamoto.win
 IMMICH_API_KEY_DEV=your-dev-api-key-here
 IMMICH_API_KEY_PROD=your-prod-api-key-here
 
-# Nostr Relays (comma-separated)
+# Nostr Relays (comma-separated list)
 NOSTR_RELAYS_DEV=wss://nostrum.satoshinakamoto.win,wss://nos.lol
 NOSTR_RELAYS_PROD=wss://relay.damus.io
 
+# API Configuration
+API_BASE_URL_DEV=https://api-dev.example.com
+API_BASE_URL_PROD=https://api.example.com
+
 # Logging
 ENABLE_LOGGING_DEV=true
 ENABLE_LOGGING_PROD=false
 
-# Firebase Configuration (Optional)
-# Set to 'true' to enable Firebase services
+# Firebase Configuration (optional)
 FIREBASE_ENABLED=false
 FIREBASE_FIRESTORE_ENABLED=true
 FIREBASE_STORAGE_ENABLED=true
diff --git a/README.md b/README.md
index ace645a..e65f5d5 100644
--- a/README.md
+++ b/README.md
@@ -211,18 +211,43 @@ flutter test test/ui/navigation/main_navigation_scaffold_test.dart
 
 ### Setup .env File
 
-1. Copy `.env.example` to `.env` in the project root:
+1. Create `.env.example` file in the project root with the following template:
+   ```bash
+   # Application Configuration
+   APP_NAME=app_boilerplate
+   
+   # Immich Configuration
+   IMMICH_BASE_URL=https://photos.satoshinakamoto.win
+   IMMICH_API_KEY_DEV=your-dev-api-key-here
+   IMMICH_API_KEY_PROD=your-prod-api-key-here
+   
+   # Nostr Relays (comma-separated list)
+   NOSTR_RELAYS_DEV=wss://nostrum.satoshinakamoto.win,wss://nos.lol
+   NOSTR_RELAYS_PROD=wss://relay.damus.io
+   
+   # API Configuration
+   API_BASE_URL_DEV=https://api-dev.example.com
+   API_BASE_URL_PROD=https://api.example.com
+   
+   # Logging
+   ENABLE_LOGGING_DEV=true
+   ENABLE_LOGGING_PROD=false
+   
+   # Firebase Configuration (optional)
+   FIREBASE_ENABLED=false
+   FIREBASE_FIRESTORE_ENABLED=true
+   FIREBASE_STORAGE_ENABLED=true
+   FIREBASE_AUTH_ENABLED=true
+   FIREBASE_MESSAGING_ENABLED=true
+   FIREBASE_ANALYTICS_ENABLED=true
+   ```
+
+3. Copy `.env.example` to `.env` and fill in your actual values:
    ```bash
    cp .env.example .env
    ```
 
-2. Edit `.env` and fill in your actual values:
-   - `IMMICH_BASE_URL` - Your Immich server URL
-   - `IMMICH_API_KEY_DEV` - Your development Immich API key
-   - `IMMICH_API_KEY_PROD` - Your production Immich API key
-   - `NOSTR_RELAYS_DEV` - Comma-separated Nostr relay URLs for dev
-   - `NOSTR_RELAYS_PROD` - Comma-separated Nostr relay URLs for prod
-   - Other configuration values as needed
+4. Edit `.env` with your actual configuration values.
 
 **Important:** The `.env` file is in `.gitignore` and should never be committed to version control. Only commit `.env.example` as a template.
 
@@ -244,6 +269,111 @@ If `.env` file is not found or variables are missing, the app uses default value
 - `dev` - Development (default): Logging enabled, dev API URL
 - `prod` - Production: Logging disabled, production API URL
 
+## App Name Configuration
+
+# 1. Set APP_NAME in your .env file
+# 2. Run the script
+./scripts/set_app_name.sh
+
+To make this easier, you can use the provided script that reads `APP_NAME` from `.env` and automatically updates all platform files:
+
+```bash
+# Make sure APP_NAME is set in your .env file first
+./scripts/set_app_name.sh
+```
+
+This script will:
+1. Read `APP_NAME` from your `.env` file
+2. Update `android/app/src/main/AndroidManifest.xml`
+3. Update `macos/Runner/Configs/AppInfo.xcconfig`
+
+**Manual Setup:** If you prefer to set it manually, just update the files listed above directly.
+
+## App Icon Configuration
+
+App icons are platform-specific and must be placed in the correct directories with the correct formats.
+
+### Android Icons
+
+**Location:** `android/app/src/main/res/mipmap-*/`
+
+**Format:** PNG files
+
+**Required Sizes:**
+- `mipmap-mdpi/ic_launcher.png` - 48x48 px
+- `mipmap-hdpi/ic_launcher.png` - 72x72 px
+- `mipmap-xhdpi/ic_launcher.png` - 96x96 px
+- `mipmap-xxhdpi/ic_launcher.png` - 144x144 px
+- `mipmap-xxxhdpi/ic_launcher.png` - 192x192 px
+
+**Instructions:**
+1. Create your app icon as a square image (recommended: 1024x1024 px source)
+2. Generate all required sizes using an icon generator tool (e.g., [App Icon Generator](https://www.appicon.co/))
+3. Replace the existing `ic_launcher.png` files in each `mipmap-*` directory
+4. The icon is referenced in `AndroidManifest.xml` as `@mipmap/ic_launcher`
+
+**Best Practices:**
+- Use PNG format (no transparency for launcher icons on some Android versions)
+- Keep icon simple and recognizable at small sizes
+- Follow Material Design guidelines for Android icons
+- Ensure icon works on both light and dark backgrounds
+
+### macOS Icons
+
+**Location:** `macos/Runner/Assets.xcassets/AppIcon.appiconset/`
+
+**Format:** PNG files
+
+**Required Sizes:**
+- `app_icon_16.png` - 16x16 px
+- `app_icon_32.png` - 32x32 px
+- `app_icon_64.png` - 64x64 px
+- `app_icon_128.png` - 128x128 px
+- `app_icon_256.png` - 256x256 px
+- `app_icon_512.png` - 512x512 px
+- `app_icon_1024.png` - 1024x1024 px
+
+**Instructions:**
+1. Create your app icon as a square image (recommended: 1024x1024 px source)
+2. Generate all required sizes
+3. Replace the existing PNG files in `AppIcon.appiconset/` directory
+4. The `Contents.json` file defines which sizes map to which files - update if needed
+
+**Best Practices:**
+- Use PNG format
+- macOS icons can have transparency
+- Follow macOS Human Interface Guidelines
+- Icon should be recognizable at 16x16 size
+
+### iOS Icons (if adding iOS support)
+
+**Location:** `ios/Runner/Assets.xcassets/AppIcon.appiconset/`
+
+**Format:** PNG files (no transparency for some sizes)
+
+**Required Sizes:** iOS requires many sizes. Use Xcode's App Icon set or a tool like [App Icon Generator](https://www.appicon.co/) to generate all required sizes automatically.
+
+**Best Practices:**
+- Use PNG format
+- Some sizes require no transparency (check iOS guidelines)
+- Follow iOS Human Interface Guidelines
+- Generate all sizes from a 1024x1024 px source
+
+### Icon Generation Tools
+
+Recommended tools for generating all required icon sizes:
+- [AppIcon.co](https://www.appicon.co/) - Online tool, supports multiple platforms
+- [IconKitchen](https://icon.kitchen/) - Google's icon generator
+- [MakeAppIcon](https://makeappicon.com/) - Generates all sizes from one image
+- Xcode (for macOS/iOS) - Built-in asset catalog editor
+
+### Quick Setup
+
+1. **Prepare your icon:** Create a 1024x1024 px square PNG image
+2. **Generate sizes:** Use one of the tools above to generate all required sizes
+3. **Replace files:** Copy generated icons to the appropriate directories
+4. **Test:** Run the app and verify icons appear correctly
+
 ## Running the App
 
 ### Android Emulator