docs: add comprehensive build instructions for all platforms

Add detailed build instructions for web, desktop (Electron), and mobile
(Capacitor) platforms. Include prerequisites, setup steps, and platform-specific
build commands. Add sections for testing, linting, and development workflows.
Document build output directories and PWA features.

BUILDING.md

@@ -0,0 +1,159 @@
+# Building TimeSafari
+
+This guide explains how to build TimeSafari for different platforms.
+
+## Prerequisites
+
+- Node.js (LTS version recommended)
+- npm (comes with Node.js)
+- Git
+- For iOS builds: macOS with Xcode installed
+- For Android builds: Android Studio with SDK installed
+- For desktop builds: Additional build tools based on your OS
+
+## Initial Setup
+
+1. Clone the repository:
+   ```bash
+   git clone [repository-url]
+   cd TimeSafari
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+## Web Build
+
+To build for web deployment:
+
+1. Run the production build:
+   ```bash
+   npm run build
+   ```
+
+2. The built files will be in the `dist` directory.
+
+3. To test the production build locally:
+   ```bash
+   npm run serve
+   ```
+
+## Desktop Build (Electron)
+
+To build the desktop application:
+
+1. Run the Electron build:
+   ```bash
+   npm run build -- --mode electron
+   ```
+
+2. The built files will be in `dist-electron`.
+
+3. To create installable packages:
+   ```bash
+   npm run electron:build
+   ```
+
+This will create platform-specific installers in `dist-electron-build`:
+- Windows: `.exe` installer
+- macOS: `.dmg` file
+- Linux: `.AppImage` file
+
+## Mobile Builds (Capacitor)
+
+### iOS Build
+
+Prerequisites: macOS with Xcode installed
+
+1. Build the web assets:
+   ```bash
+   npm run build -- --mode capacitor
+   ```
+
+2. Add iOS platform if not already added:
+   ```bash
+   npx cap add ios
+   ```
+
+3. Update iOS project with latest build:
+   ```bash
+   npx cap sync ios
+   ```
+
+4. Open the project in Xcode:
+   ```bash
+   npx cap open ios
+   ```
+
+5. Use Xcode to build and run on simulator or device.
+
+### Android Build
+
+Prerequisites: Android Studio with SDK installed
+
+1. Build the web assets:
+   ```bash
+   npm run build -- --mode capacitor
+   ```
+
+2. Add Android platform if not already added:
+   ```bash
+   npx cap add android
+   ```
+
+3. Update Android project with latest build:
+   ```bash
+   npx cap sync android
+   ```
+
+4. Open the project in Android Studio:
+   ```bash
+   npx cap open android
+   ```
+
+5. Use Android Studio to build and run on emulator or device.
+
+## Development
+
+To run the application in development mode:
+
+1. Start the development server:
+   ```bash
+   npm run dev
+   ```
+
+## Testing
+
+Run local tests:
+```bash
+npm run test-local
+```
+
+Run all tests (includes building):
+```bash
+npm run test-all
+```
+
+## Linting
+
+Check code style:
+```bash
+npm run lint
+```
+
+Fix code style issues:
+```bash
+npm run lint-fix
+```
+
+## Notes
+
+- The application uses PWA (Progressive Web App) features for web builds
+- Electron builds disable PWA features automatically
+- Build output directories:
+  - Web: `dist/`
+  - Electron: `dist-electron/`
+  - Capacitor: `dist-capacitor/`
+