Merge pull request #20 from jatinkrmalik/docs/fix-readme

chore: v0.1.0 alpha release preparation

Author: jatinkrmalik

.github/workflows/ci.yml

@@ -6,17 +6,40 @@ on:
   pull_request:
     branches: [main]
 
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build-and-test:
     name: Build & Test
     runs-on: macos-15
+    timeout-minutes: 30
 
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Build
+      - name: Cache SPM dependencies
+        uses: actions/cache@v4
+        with:
+          path: .build
+          key: spm-${{ runner.os }}-${{ hashFiles('Package.resolved') }}
+          restore-keys: |
+            spm-${{ runner.os }}-
+
+      - name: Build (Debug)
         run: swift build
 
       - name: Test
         run: swift test
+
+      - name: Build (Release)
+        run: swift build -c release
+
+      - name: Verify app bundle
+        run: |
+          ./scripts/build.sh release
+          test -d VocaMac.app || exit 1
+          codesign -v VocaMac.app
+          echo "App bundle verified"

.github/workflows/release.yml

@@ -0,0 +1,90 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-release:
+    name: Build & Release
+    runs-on: macos-15
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Update version in build script
+        run: |
+          sed -i '' "s/CFBundleVersion.*/<key>CFBundleVersion<\/key>/" scripts/build.sh || true
+          echo "Building version: ${{ steps.version.outputs.VERSION }}"
+
+      - name: Build release app bundle
+        run: ./scripts/build.sh release
+
+      - name: Verify code signature
+        run: codesign -v --deep --strict VocaMac.app
+
+      - name: Run tests
+        run: swift test
+
+      - name: Create DMG
+        run: |
+          mkdir -p dmg-staging
+          cp -R VocaMac.app dmg-staging/
+          ln -s /Applications dmg-staging/Applications
+
+          hdiutil create -volname "VocaMac" \
+            -srcfolder dmg-staging \
+            -ov -format UDZO \
+            "VocaMac-${{ steps.version.outputs.VERSION }}-arm64.dmg"
+
+          echo "DMG created:"
+          ls -lh VocaMac-*.dmg
+
+      - name: Create ZIP archive
+        run: |
+          ditto -c -k --sequesterRsrc --keepParent VocaMac.app \
+            "VocaMac-${{ steps.version.outputs.VERSION }}-arm64.zip"
+
+          echo "ZIP created:"
+          ls -lh VocaMac-*.zip
+
+      - name: Generate checksums
+        run: |
+          shasum -a 256 VocaMac-*.dmg VocaMac-*.zip > checksums.txt
+          cat checksums.txt
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          draft: true
+          files: |
+            VocaMac-*.dmg
+            VocaMac-*.zip
+            checksums.txt
+          body: |
+            ## VocaMac ${{ steps.version.outputs.VERSION }}
+
+            ### Installation
+
+            1. Download `VocaMac-${{ steps.version.outputs.VERSION }}-arm64.dmg`
+            2. Open the DMG and drag VocaMac to Applications
+            3. Open VocaMac from Applications
+            4. Grant Microphone, Accessibility, and Input Monitoring permissions when prompted
+
+            ### Checksums (SHA-256)
+            See `checksums.txt` for verification.
+
+            ### Requirements
+            - macOS 13 (Ventura) or later
+            - Apple Silicon (arm64)

README.md

@@ -4,27 +4,27 @@
 
 <h1 align="center">VocaMac</h1>
 
-[![Build & Test](https://github.com/jatinkrmalik/vocamac/actions/workflows/ci.yml/badge.svg)](https://github.com/jatinkrmalik/vocamac/actions/workflows/ci.yml) [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) [![Platform: macOS](https://img.shields.io/badge/Platform-macOS%2013%2B-lightgrey.svg)](https://github.com/jatinkrmalik/vocamac) [![Swift 5.9+](https://img.shields.io/badge/Swift-5.9%2B-orange.svg)](https://swift.org) [![Website](https://img.shields.io/badge/Web-vocamac.com-007AFF.svg)](https://vocamac.com) [![GitHub stars](https://img.shields.io/github/stars/jatinkrmalik/vocamac?style=social)](https://github.com/jatinkrmalik/vocamac/stargazers)
+[![Build & Test](https://github.com/jatinkrmalik/vocamac/actions/workflows/ci.yml/badge.svg)](https://github.com/jatinkrmalik/vocamac/actions/workflows/ci.yml) [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) [![Platform: macOS](https://img.shields.io/badge/Platform-macOS%2013%2B-lightgrey.svg)](https://github.com/jatinkrmalik/vocamac) [![Swift 5.9+](https://img.shields.io/badge/Swift-5.9%2B-orange.svg)](https://swift.org)
 
 
-**Local voice-to-text for macOS — powered by [WhisperKit](https://github.com/argmaxinc/WhisperKit)**
+**Local voice-to-text for macOS - powered by [WhisperKit](https://github.com/argmaxinc/WhisperKit)**
 
 VocaMac is a native macOS menu bar application that transcribes your voice to text locally on your machine. No cloud, no subscriptions, no data leaves your device. Just hold a hotkey, speak, and your words appear wherever your cursor is.
 
-🌐 [vocamac.com](https://vocamac.com) · 🐧 [VocaLinux](https://github.com/jatinkrmalik/vocalinux) · 🪟 VocaWin *(coming soon)*
+ [VocaLinux](https://github.com/jatinkrmalik/vocalinux) ·  **VocaMac** · 🪟 VocaWin *(coming soon)* · 🌐 [vocamac.com](https://vocamac.com)
 
 ---
 
 ## ✨ Features
 
-- **🔒 100% Local** — All audio processing happens on your machine. No internet required (except for one-time model downloads).
-- **⌨️ System-Wide Text Injection** — Transcribed text is typed wherever your cursor is: browsers, Slack, VS Code, spreadsheets, terminals — everywhere.
-- **🎯 Push-to-Talk** — Hold a hotkey (default: Right Option) to record. Release to transcribe.
-- **👆 Double-Tap Toggle** — Double-tap the hotkey to start/stop recording.
-- **🧠 Smart Model Selection** — Auto-detects your hardware (Apple Silicon/Intel, RAM) and recommends the best whisper model via WhisperKit.
-- **⚡ Native Apple Acceleration** — CoreML + Metal + Neural Engine acceleration on Apple Silicon. No manual setup.
-- **📊 Visual Feedback** — Menu bar icon changes color during recording and processing. Audio level indicator shows input.
-- **⚙️ Configurable** — Choose hotkeys, models, languages, silence detection thresholds, and more.
+- **🔒 100% Local** - All audio processing happens on your machine. No internet required (except for one-time model downloads).
+- **⌨️ System-Wide Text Injection** - Transcribed text is typed wherever your cursor is: browsers, Slack, VS Code, spreadsheets, terminals - everywhere.
+- **🎯 Push-to-Talk** - Hold a hotkey (default: Right Option) to record. Release to transcribe.
+- **👆 Double-Tap Toggle** - Double-tap the hotkey to start/stop recording.
+- **🧠 Smart Model Selection** - Auto-detects your hardware (Apple Silicon/Intel, RAM) and recommends the best whisper model via WhisperKit.
+- **⚡ Native Apple Acceleration** - CoreML + Metal + Neural Engine acceleration on Apple Silicon. No manual setup.
+- **📊 Visual Feedback** - Menu bar icon changes color during recording and processing. Audio level indicator shows input.
+- **⚙️ Configurable** - Choose hotkeys, models, languages, silence detection thresholds, and more.
 
 ---
 
@@ -50,8 +50,8 @@ Same accuracy, dramatically better Apple platform integration.
 
 - **macOS 13 (Ventura)** or later
 - **Xcode 15+** or Swift 5.9+ (for building)
-- **Microphone permission** — For audio capture
-- **Accessibility permission** — For global hotkeys and text injection
+- **Microphone permission** - For audio capture
+- **Accessibility permission** - For global hotkeys and text injection
 
 ---
 
@@ -64,7 +64,7 @@ Same accuracy, dramatically better Apple platform integration.
 git clone https://github.com/jatinkrmalik/vocamac.git
 cd vocamac
 
-# Build (first build downloads WhisperKit dependency — ~1 min)
+# Build (first build downloads WhisperKit dependency - ~1 min)
 swift build -c release
 
 # Run VocaMac
@@ -75,9 +75,9 @@ swift run -c release VocaMac
 
 1. **VocaMac appears in your menu bar** (microphone icon, no Dock icon)
 2. **Grant Microphone permission** when prompted
-3. **Grant Accessibility permission** — VocaMac will guide you to System Settings → Privacy & Security → Accessibility
-4. **First model download** — WhisperKit automatically downloads the recommended model for your device (~40-500MB depending on hardware)
-5. **Start dictating** — Hold the **Right Option** key, speak, and release. Your words appear at the cursor!
+3. **Grant Accessibility permission** - VocaMac will guide you to System Settings → Privacy & Security → Accessibility
+4. **First model download** - WhisperKit automatically downloads the recommended model for your device (~40-500MB depending on hardware)
+5. **Start dictating** - Hold the **Right Option** key, speak, and release. Your words appear at the cursor!
 
 ---
 
@@ -124,15 +124,16 @@ Models are downloaded automatically from [HuggingFace](https://huggingface.co/ar
 Open Settings from the menu bar popover or with **⌘,**
 
 ### General
-- **Activation mode** — Push-to-Talk or Double-Tap Toggle
-- **Hotkey** — Choose from Right Option, Right Command, Fn, function keys, etc.
-- **Language** — Auto-detect or specify (English, Spanish, French, German, Chinese, Japanese, and more)
+- **Activation mode** - Push-to-Talk or Double-Tap Toggle
+- **Hotkey** - Choose from Right Option, Right Command, Fn, function keys, etc.
+- **Language** - Auto-detect or specify (English, Spanish, French, German, Chinese, Japanese, and more)
 - **Launch at login**
 
 ### Audio
-- **Max recording duration** — 30s, 60s, 120s, or 300s
-- **Silence detection** — Auto-stop recording after configurable silence
-- **Input device** — Select which microphone to use
+- **Max recording duration** - 30s, 60s, 120s, or 300s
+- **Silence detection** - Auto-stop recording after configurable silence
+- **Sound effects** - Toggle audio feedback for recording start/stop
+- **Input device** - Select which microphone to use
 
 ### Models
 - View system info and WhisperKit's hardware recommendation
@@ -147,21 +148,21 @@ VocaMac is built with a clean, modular architecture using native Swift and Swift
 
 ```
 VocaMacApp (SwiftUI MenuBarExtra)
-├── AppState          — Central observable state
-├── HotKeyManager     — CGEventTap global hotkey listener
-├── AudioEngine       — AVAudioEngine mic capture (16kHz, mono, Float32)
-├── WhisperService    — WhisperKit async transcription wrapper
-│   └── ModelManager  — Model download, storage, device recommendations
-│       └── SystemInfo — Hardware detection & model recommendation
-├── TextInjector      — Clipboard + Cmd+V text injection
-├── MenuBarView       — Status popover UI
-└── SettingsView      — Configuration tabs (General, Models, Audio, About)
+├── AppState          - Central observable state
+├── HotKeyManager     - CGEventTap global hotkey listener
+├── AudioEngine       - AVAudioEngine mic capture (16kHz, mono, Float32)
+├── WhisperService    - WhisperKit async transcription wrapper
+│   └── ModelManager  - Model download, storage, device recommendations
+│       └── SystemInfo - Hardware detection & model recommendation
+├── SoundManager      - Audio feedback (start/stop recording cues)
+├── TextInjector      - Clipboard + Cmd+V text injection
+├── MenuBarView       - Status popover UI
+└── SettingsView      - Configuration tabs (General, Models, Audio, About)
 ```
 
 For detailed documentation, see:
-- [`docs/PRD.md`](docs/PRD.md) — Product Requirements Document
-- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — Technical Architecture
-- [`docs/DATA_MODEL.md`](docs/DATA_MODEL.md) — Data Model & Entity Relationships
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) - Technical Architecture
+- [`docs/DATA_MODEL.md`](docs/DATA_MODEL.md) - Data Model & Entity Relationships
 
 ---
 
@@ -189,6 +190,7 @@ VocaMac/
 │       │   ├── HotKeyManager.swift # CGEventTap global hotkeys
 │       │   ├── WhisperService.swift# WhisperKit transcription wrapper
 │       │   ├── ModelManager.swift  # Model download & management
+│       │   ├── SoundManager.swift  # Audio feedback for recording
 │       │   ├── TextInjector.swift  # Clipboard-based text injection
 │       │   └── SystemInfo.swift    # Hardware detection
 │       ├── Models/
@@ -198,10 +200,14 @@ VocaMac/
 │       └── Resources/
 ├── Tests/
 │   └── VocaMacTests/
+├── scripts/
+│   ├── build.sh                    # Build .app bundle
+│   ├── install.sh                  # Install to ~/.local/bin
+│   └── uninstall.sh                # Full uninstall & cleanup
+├── web/                            # Marketing website (vocamac.com)
 ├── docs/
-│   ├── PRD.md                      # Product Requirements Document
 │   ├── ARCHITECTURE.md             # Technical Architecture
-│   └── DATA_MODEL.md               # Data Model & ERD
+│   └── DATA_MODEL.md               # Data Model & Entity Relationships
 ├── LICENSE                         # AGPL-3.0 License
 └── .gitignore
 ```
@@ -212,56 +218,73 @@ VocaMac/
 # Debug build
 swift build
 
-# Release build (optimized — recommended for actual use)
+# Release build (optimized)
 swift build -c release
 
 # Run
 swift run VocaMac
 
 # Run tests (requires Xcode)
 swift test
+
+# Build .app bundle
+./scripts/build.sh
+
+# Install launcher scripts to ~/.local/bin
+./scripts/install.sh
 ```
 
----
+### Uninstall
+
+To completely remove VocaMac and all its data (downloaded models, preferences, caches):
 
-## 🗺️ Roadmap
+```bash
+./scripts/uninstall.sh
+```
 
-- [x] **v0.1.0** — MVP: Menu bar app, push-to-talk, double-tap toggle, WhisperKit integration, text injection, settings
-- [ ] **v0.2.0** — Onboarding flow, transcription history, audio feedback sounds
-- [ ] **v0.3.0** — Custom prompts, real-time streaming transcription, word-level timestamps
-- [ ] **v0.4.0** — Auto-updates via Sparkle, code signing, DMG distribution
-- [ ] **v1.0.0** — Homebrew Cask, polished UI, performance tuning
+Use `--keep-build` to preserve build artifacts:
+
+```bash
+./scripts/uninstall.sh --keep-build
+```
 
 ---
 
+
 ## 🌐 Cross-Platform
 
 VocaMac is the macOS member of the Voca family:
 
 | Platform | Project | Status |
 |----------|---------|--------|
-| 🐧 Linux | [VocaLinux](https://github.com/jatinkrmalik/vocalinux) | ✅ Available |
-| 🍎 macOS | **VocaMac** (this project) | 🚧 MVP |
-| 🪟 Windows | VocaWin ([vocawin.com](https://vocawin.com)) | 📋 Planned |
+|  Linux | [VocaLinux](https://github.com/jatinkrmalik/vocalinux) | ✅ Available |
+|  macOS | [VocaMac](https://github.com/jatinkrmalik/vocamac) | 🚧 Alpha |
+| 🪟 Windows | [VocaWin](https://vocawin.com) | 📋 Planned |
 
 Each platform uses native technologies for the best possible integration, while sharing the same UX patterns and Whisper model family.
 
 ---
 
 ## 🤝 Related Projects
 
-- [WhisperKit](https://github.com/argmaxinc/WhisperKit) — Swift native on-device speech recognition
-- [VocaLinux](https://github.com/jatinkrmalik/vocalinux) — Voice-to-text for Linux
-- [OpenAI Whisper](https://github.com/openai/whisper) — Original Whisper model
+- [WhisperKit](https://github.com/argmaxinc/WhisperKit) - Swift native on-device speech recognition
+- [VocaLinux](https://github.com/jatinkrmalik/vocalinux) - Voice-to-text for Linux
+- [OpenAI Whisper](https://github.com/openai/whisper) - Original Whisper model
 
 ---
 
-## 📄 License
+## ⚠️ Known Limitations
 
-AGPL-3.0 License — see [LICENSE](LICENSE) for details.
+- **Ad-hoc code signing** - Accessibility and Input Monitoring permissions reset on every rebuild. Re-grant them after each build.
+- **First launch requires internet** - WhisperKit downloads the speech recognition model on first run. All subsequent launches work fully offline.
+- **macOS only** - Requires macOS 13 (Ventura) or later.
 
 ---
 
-## 👨‍💻 Author
+## 📄 License
+
+AGPL-3.0 License - see [LICENSE](LICENSE) for details.
+
+---
 
-**Jatin Kumar Malik** · [GitHub](https://github.com/jatinkrmalik) · [vocamac.com](https://vocamac.com)
+Made with ❤️ for the macOS community!