Add uv-based installation system

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cubny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -18,80 +18,116 @@ The system includes professional audio processing to enhance the listening exper
 - **Stereo Widening**: M/S processing for a wider, more immersive soundstage
 - **Safety Limiter**: True Peak limiting prevents digital clipping and ensures consistent volume
 
-## Prerequisites
-- Python 3.12+
-- pip package manager
-- Google Gemini API key (free from [AI Studio](https://aistudio.google.com/))
+## Installation
 
-## Setup
+### Quick Install (Recommended)
+
+Run the installer script to automatically set up Focus Music and its dependencies:
 
 ```bash
-# Install with pip (Python 3.12+ required)
-pip install -e ".[dev]"
+curl -LsSf https://raw.githubusercontent.com/cubny/focus/main/install.sh | bash
+```
+
+This will:
+- Install [uv](https://docs.astral.sh/uv/) (fast Python package manager)
+- Install PortAudio (audio library) if needed
+- Install Focus Music globally
 
-# Set your Google API key
-export GOOGLE_API_KEY="your-api-key-from-aistudio"
+After installation, set your API key and start a session:
+
+```bash
+export GOOGLE_API_KEY="your-api-key"  # Get one at https://aistudio.google.com/
+focus start --profile deep-work
 ```
 
-<details>
-<summary>Troubleshooting the setup</summary>
+### Manual Installation with uv
 
-### "externally-managed-environment" Error
+If you prefer to install manually:
 
-If you see an error message like this:
+```bash
+# 1. Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 2. Install focus as a CLI tool
+uv tool install focus-music
 
+# 3. Set your API key and run
+export GOOGLE_API_KEY="your-api-key"
+focus start --profile deep-work
 ```
-error: externally-managed-environment
-...
+
+### One-liner (Try without installing)
+
+```bash
+# Run focus directly without permanent installation
+uvx focus-music start --profile deep-work
 ```
 
-It means that your Python installation is managed by a system package manager (like Homebrew on macOS). To avoid conflicts, `pip` prevents you from installing packages system-wide.
+<details>
+<summary>🛠️ Developer Setup</summary>
 
-**Solution: Use a Virtual Environment**
+For development, clone the repository and use `uv sync`:
 
-The recommended solution is to create a virtual environment. This creates an isolated space for your project's dependencies.
+```bash
+git clone https://github.com/cubny/focus.git
+cd focus
 
-1.  **Create the virtual environment:**
-    ```bash
-    python3 -m venv .venv
-    ```
+# Install uv if needed
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
-2.  **Activate it:**
-    ```bash
-    source .venv/bin/activate
-    ```
+# Install dependencies and create virtual environment
+uv sync
 
-3.  **Install the package:**
-    ```bash
-    pip install -e ".[dev]"
-    ```
+# Run the CLI
+uv run focus start --profile deep-work
 
-### "File setup.py not found" Error
+# Or activate the virtual environment
+source .venv/bin/activate
+focus start --profile deep-work
+```
 
-If you see an error like this:
+### Running Tests
+
+```bash
+uv run pytest
 ```
-ERROR: File "setup.py" not found. Directory cannot be installed in editable mode...
+
+### Code Formatting
+
+```bash
+uv run ruff format src/ tests/
+uv run ruff check --fix src/ tests/
 ```
 
-This usually means you are using an old version of `pip` or `python`. This project requires Python 3.12+ and a modern version of `pip`.
+</details>
 
-**Solution: Update Python and `pip`**
+<details>
+<summary>📦 Alternative: pip installation</summary>
 
-1.  **Check your Python version:**
-    ```bash
-    python3 --version
-    ```
-    If it's not 3.12 or higher, you'll need to upgrade your Python installation.
+If you prefer using pip directly:
 
-2.  **Use `python3 -m pip`:**
-    Instead of just `pip`, use `python3 -m pip` to ensure you're using the `pip` associated with your Python 3 installation.
+```bash
+# Create a virtual environment (recommended)
+python3 -m venv .venv
+source .venv/bin/activate
 
-    ```bash
-    python3 -m pip install -e ".[dev]"
-    ```
+# Install from PyPI (when published)
+pip install focus-music
+
+# Or install from source
+git clone https://github.com/cubny/focus.git
+cd focus
+pip install -e ".[dev]"
+```
 
 </details>
 
+### Prerequisites
+
+- **macOS** or **Linux** (Windows via WSL)
+- **Google Gemini API key** (free from [AI Studio](https://aistudio.google.com/))
+- Python 3.12+ (automatically installed by uv if missing)
+
 ## Usage
 
 ```bash
@@ -192,11 +228,11 @@ Warm, positive motivation.
 
 ```bash
 # Run tests
-pytest
+uv run pytest
 
 # Format code
-ruff format src/ tests/
-ruff check --fix src/ tests/
+uv run ruff format src/ tests/
+uv run ruff check --fix src/ tests/
 ```
 
 ## Verification