docs: consolidate documentation and fix redundancies

- Add MACOS_APP_MANUAL.md reference to docs/index.md - Streamline QUICKSTART.md macOS section (reference full manual) - Update USER_MANUAL.md Quick Start to use ./alpha workflow - Clarify that python cli.py is for advanced usage - Fix venv naming consistency (.venv throughout)
2026-05-14 20:37:51 +00:00 · 2026-01-13 08:17:35 +01:00 · 2026-01-13 08:17:35 +01:00 · be7d27f663
commit be7d27f663
parent 1c66f3b254
3 changed files with 76 additions and 88 deletions
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@ -99,69 +99,18 @@ ALPHA_HOST=0.0.0.0 ./alpha start

 For a native macOS experience, use the menu bar app instead of terminal commands.

-### Requirements
- macOS 13.0 or later
- Xcode 15.0+ (for building from source)
-
-### Build & Install
-
 ```bash
-# Build the app
-cd macos-app
-./build.sh
-
-# Or build and install to /Applications
-./build.sh install
+# Build and install to /Applications
+cd macos-app && ./build.sh install
 ```

-### Open in Xcode (for development)
-```bash
-open macos-app/AlphaArena.xcodeproj
-```
+**Features:**
+- One-click start/stop from menu bar
+- Real-time P&L updates via WebSocket
+- Native macOS notifications
+- Network mode toggle (localhost/LAN)

-### Features
- Native SwiftUI menu bar app
- Status icon in menu bar (green=running, gray=stopped)
- Start/Stop server with one click
- Real-time P&L and position updates via WebSocket
- Network mode toggle (localhost vs LAN-accessible)
- Rich notifications with action buttons
- Open Dashboard, View Logs, Copy URL shortcuts
- Preferences window for configuration
-
-### Menu Bar Controls
-```
-┌────────────────────────────────────────┐
-│ ● Server Running                       │
-│   http://127.0.0.1:8000                │
-├────────────────────────────────────────┤
-│ P&L: +$127.45 | 5 positions            │
-│ Trading: Active (simulation)           │
-├────────────────────────────────────────┤
-│ Stop Server                   ⌘⇧S      │
-│ Open Dashboard                ⌘D       │
-│ Copy Server URL               ⌘C       │
-│ View Logs                     ⌘L       │
-├────────────────────────────────────────┤
-│ Network Mode                        ▶  │
-│   ✓ Localhost Only (127.0.0.1)        │
-│     LAN Access (0.0.0.0)              │
-├────────────────────────────────────────┤
-│ Preferences...                ⌘,       │
-│ Quit Alpha Arena              ⌘Q       │
-└────────────────────────────────────────┘
-```
-
-### Keyboard Shortcuts
-| Shortcut | Action |
-|----------|--------|
-| ⌘S | Start Server |
-| ⌘⇧S | Stop Server |
-| ⌘D | Open Dashboard |
-| ⌘C | Copy Server URL |
-| ⌘L | View Logs |
-| ⌘, | Preferences |
-| ⌘Q | Quit |
+**See [docs/MACOS_APP_MANUAL.md](docs/MACOS_APP_MANUAL.md) for full documentation.**

 ---

--- a/docs/USER_MANUAL.md
+++ b/docs/USER_MANUAL.md
@ -108,39 +108,55 @@ Alpha Arena is a world-class autonomous trading harness for Polymarket predictio
 # 1. Clone and enter directory
 cd alpha-arena

-# 2. Create virtual environment
-python -m venv venv
-source venv/bin/activate
+# 2. Start (auto-runs setup if needed)
+./alpha start

-# 3. Install dependencies
-pip install -r requirements.txt
+# 3. Configure credentials
+nano .env  # Add your API keys

-# 4. Configure credentials
-cp .env.example .env
-# Edit .env with your API keys
+# 4. Restart to apply changes
+./alpha restart

-# 5. Verify setup
-python cli.py providers
-
-# 6. Start simulation
-python cli.py run --simulation
+# 5. Open web UI
+./alpha open
 ```

+The `./alpha start` command automatically:
+- Creates the virtual environment (`.venv`)
+- Installs all dependencies
+- Creates `.env` from template if missing
+- Starts the server on port 8000
+
 ### 2.2 First Live Trade

+1. Open the web dashboard: `./alpha open`
+2. Navigate to **Trading** page
+3. Configure your settings
+4. Start in **simulation mode** first
+5. When ready, switch to **live mode**
+
+### 2.3 Advanced CLI (python cli.py)
+
+For advanced operations, you can use the Python CLI directly:
+
 ```bash
-# Ensure .env has WALLET_PRIVATE_KEY and Polymarket credentials
+# Activate environment first
+source .venv/bin/activate

-# Check market status
-python cli.py markets
-
-# Start with enhanced multi-agent mode (recommended)
+# Start enhanced multi-agent mode
 python cli.py run-enhanced --dry-run  # Preview only

 # When ready for live trading
 python cli.py run-enhanced
+
+# Other useful commands
+python cli.py markets     # List markets
+python cli.py providers   # Check LLM status
+python cli.py backtest    # Run backtest
 ```

+> **Note:** The `./alpha` script is recommended for daily operations. The `python cli.py` commands provide additional features for advanced users.
+
 ---

 ## 3. Installation & Setup
@ -157,17 +173,17 @@ python cli.py run-enhanced

 ### 3.2 Python Environment

+The recommended way is to use `./alpha start` which handles setup automatically.
+
+For manual setup:
+
 ```bash
-# Create isolated environment
-python -m venv venv
+# Run the setup script (creates .venv)
+./scripts/setup.sh

-# Activate (macOS/Linux)
-source venv/bin/activate
-
-# Activate (Windows)
-.\venv\Scripts\activate
-
-# Install dependencies
+# Or manually:
+python -m venv .venv
+source .venv/bin/activate
 pip install -r requirements.txt

 # Verify installation
@ -176,6 +192,8 @@ python -c "from src.agents import AgentCoordinator; print('Agents OK')"
 python -c "from src.broker import PolymarketBroker; print('Broker OK')"
 ```

+> **Note:** The project uses `.venv` (with dot) as the virtual environment directory.
+
 ### 3.3 Wallet Setup

 1. **Create Polygon Wallet**: Use MetaMask or any Polygon-compatible wallet
@ -363,9 +381,25 @@ AGENT_LOOP_INTERVAL_SECONDS=60

 ## 5. CLI Commands

-### 5.1 Command Overview
+### 5.0 Daily Commands (./alpha)
+
+For daily operations, use the `./alpha` script:

 ```bash
+./alpha start    # Start server (auto-setup)
+./alpha stop     # Stop server
+./alpha status   # Check status
+./alpha logs     # Watch logs
+./alpha open     # Open web UI
+./alpha test     # Run tests
+```
+
+### 5.1 Advanced CLI (python cli.py)
+
+For advanced operations, activate the venv and use `python cli.py`:
+
+```bash
+source .venv/bin/activate
 python cli.py --help
 ```

--- a/docs/index.md
+++ b/docs/index.md
@ -12,6 +12,9 @@ Welcome to Alpha Arena. This guide helps you find the right documentation for yo
 ### Using the web interface?
 **[WEB_APP_MANUAL.md](WEB_APP_MANUAL.md)** - Complete web UI guide with screenshots and workflows

+### Using the macOS menu bar app?
+**[MACOS_APP_MANUAL.md](MACOS_APP_MANUAL.md)** - Native SwiftUI app for menu bar control
+
 ### Need the full reference?
 **[USER_MANUAL.md](USER_MANUAL.md)** - CLI commands, multi-agent system, strategies, API reference

@ -29,6 +32,7 @@ Welcome to Alpha Arena. This guide helps you find the right documentation for yo
 |----------|----------|---------|
 | [QUICKSTART.md](../QUICKSTART.md) | Everyone | 5-minute guide, daily commands |
 | [WEB_APP_MANUAL.md](WEB_APP_MANUAL.md) | Operators | Web interface, dashboards, controls |
+| [MACOS_APP_MANUAL.md](MACOS_APP_MANUAL.md) | macOS users | Native menu bar app |
 | [USER_MANUAL.md](USER_MANUAL.md) | Developers | Full CLI, agents, strategies, API |
 | [OPERATIONAL_MANUAL.md](OPERATIONAL_MANUAL.md) | DevOps | Deployment, monitoring, security |
 | [TESTING.md](TESTING.md) | Developers | Test suite, fixtures, patterns |
@ -40,7 +44,8 @@ Welcome to Alpha Arena. This guide helps you find the right documentation for yo
 ### Beginner
 1. Read [../QUICKSTART.md](../QUICKSTART.md) - Get running
 2. Explore [WEB_APP_MANUAL.md](WEB_APP_MANUAL.md) - Use the web UI
-3. Try simulation mode before live trading
+3. Or try [MACOS_APP_MANUAL.md](MACOS_APP_MANUAL.md) - Native menu bar app
+4. Try simulation mode before live trading

 ### Intermediate
 1. Study [USER_MANUAL.md](USER_MANUAL.md) Sections 6-10 - Agents, strategies, risk