chore: add Makefile and restructure install.sh for /Applications install (#43)

- install.sh (default): builds .app bundle via build.sh, copies to
  /Applications, and launches. Permissions are granted directly to
  VocaMac — no terminal permission workarounds needed.
- install.sh --cli: keeps the old behavior — installs vocamac and
  vocamac-build CLI commands to ~/.local/bin
- Makefile: make install, make build, make install-cli, make test,
  make run, make clean, make help
- Updated README Quick Start: DMG as Option 1, make install as Option 2,
  make install-cli as Option 3
- Updated AGENTS.md and ARCHITECTURE.md build sections

Author: jatinkrmalik

AGENTS.md

@@ -48,7 +48,8 @@ VocaMac/
 │   └── Resources/        # Bundled resources (.gitkeep placeholder)
 ├── Tests/VocaMacTests/   # Unit tests
 ├── web/                  # Static website (HTML/CSS/JS, deployed to GitHub Pages)
-├── scripts/              # build.sh, install.sh
+├── Makefile              # make build, install, test, clean
+├── scripts/              # build.sh, install.sh, uninstall.sh
 ├── docs/                 # ARCHITECTURE.md, DATA_MODEL.md, PRD.md
 ├── Package.swift         # SPM manifest
 └── VocaMac.entitlements  # App sandbox entitlements
@@ -59,20 +60,28 @@ VocaMac/
 ## Build & Run
 
 ```bash
-# Build (debug)
-swift build
+# Build + install to /Applications (recommended)
+make install
 
-# Build (release)
-swift build -c release
+# Build .app bundle in repo root (fast dev iteration)
+make build
+
+# Install CLI commands to ~/.local/bin
+make install-cli
 
 # Run tests
-swift test
+make test
+
+# Clean build artifacts
+make clean
+```
 
-# Build app bundle (creates VocaMac.app)
-./scripts/build.sh
+Or use the scripts directly:
 
-# Install via script
-./scripts/install.sh
+```bash
+./scripts/build.sh              # Build .app bundle (dev)
+./scripts/install.sh            # Build + install to /Applications
+./scripts/install.sh --cli      # Install CLI commands
 ```
 
 The project builds on **macOS only** (requires AppKit, CoreML, AVFoundation). CI runs on `macos-15`.

Makefile

@@ -0,0 +1,46 @@
+# VocaMac — Makefile
+# Run `make help` for available commands.
+
+.PHONY: build install install-cli test clean run help
+
+## Build .app bundle in repo root (fast, for development)
+build:
+	@./scripts/build.sh
+
+## Build and install to /Applications (recommended for first-time setup)
+install:
+	@./scripts/install.sh
+
+## Install CLI commands (vocamac, vocamac-build) to ~/.local/bin
+install-cli:
+	@./scripts/install.sh --cli
+
+## Run tests
+test:
+	@swift test
+
+## Remove build artifacts
+clean:
+	@echo "🧹 Cleaning build artifacts..."
+	@swift package clean
+	@rm -rf VocaMac.app
+	@rm -rf .build
+	@echo "✅ Clean complete"
+
+## Launch the locally built .app (build first with `make build`)
+run:
+	@open VocaMac.app 2>/dev/null || (echo "❌ VocaMac.app not found. Run 'make build' first." && exit 1)
+
+## Show this help
+help:
+	@echo "VocaMac — Available Commands"
+	@echo ""
+	@echo "  make build        Build .app bundle (fast, for development)"
+	@echo "  make install      Build + install to /Applications (recommended)"
+	@echo "  make install-cli  Install CLI commands to ~/.local/bin"
+	@echo "  make test         Run tests"
+	@echo "  make run          Launch the locally built .app"
+	@echo "  make clean        Remove build artifacts"
+	@echo "  make help         Show this help"
+	@echo ""
+	@echo "Quick start:  make install"

README.md

@@ -134,34 +134,29 @@ VocaMac requires three macOS permissions:
 4. **Open** VocaMac from Applications (right-click → Open on first launch)
 5. **Grant permissions** — Microphone, Accessibility, and Input Monitoring when prompted
 
-### Option 2: Build from Source
+### Option 2: Build from Source (Recommended)
 
 ```bash
-# Clone the repository
 git clone https://github.com/jatinkrmalik/vocamac.git
 cd vocamac
-
-# Build the app bundle
-./scripts/build.sh
-
-# Launch VocaMac
-open VocaMac.app
+make install
 ```
 
-**Or use the install script** for a CLI-based workflow:
-
-```bash
-# Build + install `vocamac` command to ~/.local/bin
-./scripts/install.sh
+This builds VocaMac, installs it to `/Applications`, and launches it. Permissions are granted directly to VocaMac — just like the DMG method.
 
-# Launch in background
-vocamac &
+### Option 3: CLI Commands (For Developers)
 
-# Rebuild anytime after pulling updates
-vocamac-build
+```bash
+git clone https://github.com/jatinkrmalik/vocamac.git
+cd vocamac
+make install-cli
 ```
 
-> **Permissions note:** When running from terminal, macOS assigns permissions to your **terminal app** (Terminal, iTerm2, etc.) rather than VocaMac itself. Grant Microphone, Accessibility, and Input Monitoring to your terminal app instead.
+This installs two commands to `~/.local/bin`:
+- `vocamac &` — Launch VocaMac in background
+- `vocamac-build` — Rebuild from source after pulling updates
+
+> **Permissions note:** In CLI mode, macOS assigns permissions to your **terminal app** (Terminal, iTerm2, etc.) rather than VocaMac itself. Grant Microphone, Accessibility, and Input Monitoring to your terminal app instead.
 
 ### First Launch
 
@@ -291,9 +286,10 @@ VocaMac/
 │       └── Resources/
 ├── Tests/
 │   └── VocaMacTests/
+├── Makefile                        # make build, install, test, clean
 ├── scripts/
-│   ├── build.sh                    # Build .app bundle
-│   ├── install.sh                  # Install to ~/.local/bin
+│   ├── build.sh                    # Build .app bundle (dev)
+│   ├── install.sh                  # Install to /Applications or CLI
 │   └── uninstall.sh                # Full uninstall & cleanup
 ├── web/                            # Marketing website (vocamac.com)
 ├── docs/
@@ -306,23 +302,13 @@ VocaMac/
 ### Build Commands
 
 ```bash
-# Debug build
-swift build
-
-# 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
+make install        # Build + install to /Applications (recommended)
+make install-cli    # Install CLI commands to ~/.local/bin
+make build          # Build .app bundle in repo root (dev iteration)
+make test           # Run tests
+make run            # Launch the locally built .app
+make clean          # Remove build artifacts
+make help           # Show all commands
 ```
 
 ### Uninstall

docs/ARCHITECTURE.md

@@ -448,17 +448,23 @@ Package.swift
 ### 7.2 Build Commands
 
 ```bash
-# Debug build
-swift build
+# Build + install to /Applications (recommended)
+make install
 
-# Release build (optimized)
-swift build -c release
+# Build .app bundle in repo root (fast dev iteration)
+make build
+
+# Install CLI commands to ~/.local/bin
+make install-cli
 
-# Run
-swift run VocaMac
+# Run tests
+make test
 
-# Create app bundle (requires additional scripting)
-./scripts/build.sh
+# Debug build (SPM only, no .app bundle)
+swift build
+
+# Release build (SPM only, no .app bundle)
+swift build -c release
 ```
 
 ### 7.3 Distribution Strategy (MVP)