From be7d27f66323778539b2a52238c5e1c2cd81a893 Mon Sep 17 00:00:00 2001 From: oho Date: Tue, 13 Jan 2026 08:17:35 +0100 Subject: [PATCH] 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) --- QUICKSTART.md | 67 ++++----------------------------- docs/USER_MANUAL.md | 90 +++++++++++++++++++++++++++++++-------------- docs/index.md | 7 +++- 3 files changed, 76 insertions(+), 88 deletions(-) diff --git a/QUICKSTART.md b/QUICKSTART.md index 874c445..1c9f7c7 100644 --- 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.** --- diff --git a/docs/USER_MANUAL.md b/docs/USER_MANUAL.md index 04d7767..9b82c07 100644 --- 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 ``` diff --git a/docs/index.md b/docs/index.md index f0d7a6c..5137654 100644 --- 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