From 26f3229b1eff1631a9e5ae43bfde8c0d88521eda Mon Sep 17 00:00:00 2001
From: Eric Ratliff <eric@nxlearn.net>
Date: Sun, 1 Feb 2026 20:56:52 -0600
Subject: [PATCH] docs: update README for v1.1.0 features

Document proxy support and Android Studio integration added in v1.1.0.

New sections:
- Proxy Support: --proxy and --no-proxy flags, HTTPS_PROXY env var
  auto-detection, air-gapped/offline installation workflows
- Android Studio Setup: complete guide including Shell Script plugin
  installation, opening projects, and using run configurations
- Troubleshooting: Android Studio plugin issues, proxy debugging

Updated sections:
- Quick Start: add weevil setup and weevil doctor as step 1
- Command Reference: environment commands (doctor, setup, uninstall),
  global proxy flags
- Features: highlight Android Studio integration and proxy support
- Project Status: current version 1.1.0, updated "What Works" list

Expanded troubleshooting for common issues: adb not found, proxy
connectivity, Android Studio run configuration errors.

All existing content preserved. Tone stays practical and student-focused.
---
 README.md | 277 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 252 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index 1afb9f2..e706268 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,8 @@ This approach works against standard software engineering practices and creates
 - ✅ Generate all build/deploy scripts automatically
 - ✅ Enable proper version control workflows
 - ✅ Are actually testable and maintainable
+- ✅ Work seamlessly with Android Studio
+- ✅ Support proxy/air-gapped environments
 
 Students focus on building robots, not navigating SDK internals.
 
@@ -39,6 +41,7 @@ my-robot/
 ├── src/
 │   ├── main/java/robot/     # Your robot code lives here
 │   └── test/java/robot/     # Unit tests (run on PC!)
+├── .idea/                   # Android Studio integration (auto-generated)
 ├── build.sh / build.bat     # One command to build
 ├── deploy.sh / deploy.bat   # One command to deploy
 └── .weevil.toml            # Project configuration
@@ -46,6 +49,9 @@ my-robot/
 
 ### 🚀 Simple Commands
 ```bash
+# Set up development environment
+weevil setup
+
 # Create a new robot project
 weevil new awesome-robot
 
@@ -60,6 +66,9 @@ cd awesome-robot
 
 ### 🔧 Project Management
 ```bash
+# Check system health
+weevil doctor
+
 # Upgrade project infrastructure
 weevil upgrade awesome-robot
 
@@ -69,8 +78,36 @@ weevil config awesome-robot --set-sdk /path/to/different/sdk
 
 # Check SDK status
 weevil sdk status
+
+# Remove installed components
+weevil uninstall --dry-run
+weevil uninstall
 ```
 
+### 🌐 Proxy Support (v1.1.0)
+Work behind corporate firewalls or in air-gapped environments:
+
+```bash
+# Use HTTP proxy for all downloads
+weevil --proxy http://proxy.company.com:8080 setup
+weevil --proxy http://proxy.company.com:8080 new my-robot
+
+# Bypass proxy (for local/direct connections)
+weevil --no-proxy setup
+
+# Proxy auto-detected from HTTPS_PROXY/HTTP_PROXY environment variables
+export HTTPS_PROXY=http://proxy:8080
+weevil setup  # Uses proxy automatically
+```
+
+### 💻 Android Studio Integration (v1.1.0)
+Projects work seamlessly with Android Studio:
+- **One-click deployment** - Run configurations appear automatically in the Run dropdown
+- **Clean file tree** - Internal directories hidden, only your code visible
+- **No configuration needed** - Just open the project and hit Run
+
+See [Android Studio Setup](#android-studio-setup) for details.
+
 ### ✨ Smart Features
 - **Per-project SDK configuration** - Different projects can use different SDK versions
 - **Automatic Gradle wrapper** - No manual setup required
@@ -78,6 +115,8 @@ weevil sdk status
 - **Zero SDK modification** - Your SDK stays pristine
 - **Git-ready** - Projects initialize with proper `.gitignore`
 - **Upgrade-safe** - Update build scripts without losing code
+- **System diagnostics** - `weevil doctor` checks your environment health
+- **Selective uninstall** - Remove specific components without nuking everything
 
 ---
 
@@ -96,30 +135,49 @@ export PATH="$PATH:$(pwd)/target/release"
 ```
 
 ### Prerequisites
-- Rust 1.70+ (for building)
+- Rust 1.70+ (for building Weevil)
 - Java 11+ (for running Gradle)
 - Android SDK with platform-tools (for deployment)
-- FTC SDK (Weevil can download it for you)
+- FTC SDK (Weevil can install it for you)
 
 ---
 
 ## Quick Start
 
-### 1. Create Your First Project
+### 1. Set Up Your Environment
+
+```bash
+# Check what's installed
+weevil doctor
+
+# Install everything automatically
+weevil setup
+
+# Or install to custom location
+weevil setup --ftc-sdk ~/my-sdks/ftc --android-sdk ~/my-sdks/android
+```
+
+Weevil will:
+- Download and install FTC SDK
+- Download and install Android SDK (if needed)
+- Set up Gradle wrapper
+- Verify all dependencies
+
+### 2. Create Your First Project
 
 ```bash
 weevil new my-robot
 cd my-robot
 ```
 
-Weevil will:
-- Download the FTC SDK if needed (or use existing)
-- Generate your project structure
-- Set up Gradle wrapper
-- Initialize git repository
-- Create example test files
+Weevil generates:
+- Clean project structure
+- Android Studio run configurations
+- Example test files
+- Build and deploy scripts
+- Git repository with `.gitignore`
 
-### 2. Write Some Code
+### 3. Write Some Code
 
 Create `src/main/java/robot/MyOpMode.java`:
 
@@ -146,7 +204,7 @@ public class MyOpMode extends LinearOpMode {
 }
 ```
 
-### 3. Test Locally (No Robot!)
+### 4. Test Locally (No Robot!)
 
 ```bash
 ./gradlew test
@@ -154,7 +212,7 @@ public class MyOpMode extends LinearOpMode {
 
 Write unit tests in `src/test/java/robot/` that run on your PC. No need to deploy to a robot for every code change!
 
-### 4. Deploy to Robot
+### 5. Deploy to Robot
 
 ```bash
 # Build APK
@@ -172,8 +230,93 @@ Write unit tests in `src/test/java/robot/` that run on your PC. No need to deplo
 
 ---
 
+## Android Studio Setup
+
+### Opening a Weevil Project
+
+1. Launch Android Studio
+2. Choose **Open** (not "New Project")
+3. Navigate to your project directory (e.g., `my-robot`)
+4. Click OK
+
+Android Studio will index the project. After a few seconds, you'll see:
+- **Clean file tree** - Only `src/`, scripts, and essential files visible
+- **Run configurations** - Dropdown next to the green play button shows:
+  - **Build** - Builds APK without deploying
+  - **Deploy (auto)** - Auto-detects USB or WiFi
+  - **Deploy (USB)** - Forces USB connection
+  - **Deploy (WiFi)** - Forces WiFi connection
+  - **Test** - Runs unit tests
+
+### First-Time Setup: Shell Script Plugin
+
+**Important:** Android Studio requires the Shell Script plugin to run Weevil's deployment scripts.
+
+1. Go to **File → Settings** (or **Ctrl+Alt+S**)
+2. Navigate to **Plugins**
+3. Click the **Marketplace** tab
+4. Search for **"Shell Script"**
+5. Install the plugin (by JetBrains)
+6. Restart Android Studio
+
+After restart, the run configurations will work.
+
+### Running from Android Studio
+
+1. Select a configuration from the dropdown (e.g., "Deploy (auto)")
+2. Click the green play button (▶) or press **Shift+F10**
+3. Watch the output in the Run panel at the bottom
+
+**That's it!** Students can now build and deploy without leaving the IDE.
+
+### Platform Notes
+
+- **Linux/macOS:** Uses the Unix run configurations (`.sh` scripts)
+- **Windows:** Uses the Windows run configurations (`.bat` scripts)
+- Android Studio automatically hides the configurations for the other platform
+
+---
+
 ## Advanced Usage
 
+### Proxy Configuration
+
+#### Corporate Environments
+
+```bash
+# Set proxy for all Weevil operations
+weevil --proxy http://proxy.company.com:8080 setup
+weevil --proxy http://proxy.company.com:8080 new robot-project
+
+# Or use environment variables (auto-detected)
+export HTTPS_PROXY=http://proxy:8080
+export HTTP_PROXY=http://proxy:8080
+weevil setup  # Automatically uses proxy
+```
+
+#### Air-Gapped / Offline Installation
+
+If you're on an isolated network without internet:
+
+1. **Download SDKs manually on a connected machine:**
+   - FTC SDK: `git clone https://github.com/FIRST-Tech-Challenge/FtcRobotController.git`
+   - Android SDK: Download from https://developer.android.com/studio
+   - Gradle: Download distribution from https://gradle.org/releases/
+
+2. **Transfer to isolated machine via USB drive**
+
+3. **Install using local paths:**
+   ```bash
+   weevil setup --ftc-sdk /path/to/FtcRobotController --android-sdk /path/to/android-sdk
+   ```
+
+#### Bypass Proxy
+
+```bash
+# Force direct connection (ignore proxy environment variables)
+weevil --no-proxy setup
+```
+
 ### Multiple SDK Versions
 
 Working with multiple SDK versions? No problem:
@@ -203,10 +346,27 @@ This updates:
 - Build scripts
 - Deployment scripts
 - Gradle configuration
+- Android Studio run configurations
 - Project templates
 
 **Your code in `src/` is never touched.**
 
+### System Maintenance
+
+```bash
+# Check what's installed
+weevil doctor
+
+# See what can be uninstalled
+weevil uninstall --dry-run
+
+# Remove specific components
+weevil uninstall --only 1  # Removes FTC SDK only
+
+# Full uninstall (removes everything Weevil installed)
+weevil uninstall
+```
+
 ### Cross-Platform Development
 
 All scripts work on Windows, Linux, and macOS:
@@ -220,9 +380,11 @@ All scripts work on Windows, Linux, and macOS:
 **Windows:**
 ```cmd
 build.bat
-deploy.bat --wifi
+deploy.bat
 ```
 
+**Android Studio:** Works identically on all platforms
+
 ---
 
 ## Project Configuration
@@ -231,9 +393,10 @@ Each project has a `.weevil.toml` file:
 
 ```toml
 project_name = "my-robot"
-weevil_version = "1.0.0"
+weevil_version = "1.1.0"
 ftc_sdk_path = "/home/user/.weevil/ftc-sdk"
 ftc_sdk_version = "v10.1.1"
+android_sdk_path = "/home/user/.weevil/android-sdk"
 ```
 
 You can edit this manually or use:
@@ -273,6 +436,7 @@ git push
 1. **Unit Tests** - Test business logic on your PC
    ```bash
    ./gradlew test
+   # Or from Android Studio: select "Test" and click Run
    ```
 
 2. **Integration Tests** - Test on actual hardware
@@ -293,7 +457,7 @@ cd robot
 # Check SDK location
 weevil config .
 
-# Set SDK to local path
+# Set SDK to local path (if different from .weevil.toml)
 weevil config . --set-sdk ~/ftc-sdk
 
 # Build and deploy
@@ -301,15 +465,29 @@ weevil config . --set-sdk ~/ftc-sdk
 ./deploy.sh
 ```
 
+**Android Studio users:** Just open the project. The `.idea/` folder contains all run configurations.
+
 ---
 
 ## Command Reference
 
+### Environment Commands
+
+| Command | Description |
+|---------|-------------|
+| `weevil doctor` | Check system health and dependencies |
+| `weevil setup` | Install FTC SDK, Android SDK, and dependencies |
+| `weevil setup --ftc-sdk <path>` | Install to custom FTC SDK location |
+| `weevil uninstall` | Remove all Weevil-managed components |
+| `weevil uninstall --dry-run` | Show what would be removed |
+| `weevil uninstall --only <N>` | Remove specific component by index |
+
 ### Project Commands
 
 | Command | Description |
 |---------|-------------|
 | `weevil new <name>` | Create new FTC project |
+| `weevil new <name> --ftc-sdk <path>` | Create with specific SDK |
 | `weevil upgrade <path>` | Update project infrastructure |
 | `weevil config <path>` | View project configuration |
 | `weevil config <path> --set-sdk <sdk>` | Change FTC SDK path |
@@ -322,6 +500,13 @@ weevil config . --set-sdk ~/ftc-sdk
 | `weevil sdk install` | Download and install SDKs |
 | `weevil sdk update` | Update SDKs to latest versions |
 
+### Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--proxy <url>` | Use HTTP proxy for all network operations |
+| `--no-proxy` | Bypass proxy (ignore HTTPS_PROXY env vars) |
+
 ### Deployment Options
 
 **`deploy.sh` / `deploy.bat` flags:**
@@ -343,6 +528,7 @@ weevil config . --set-sdk ~/ftc-sdk
    - Creates standalone Java project structure
    - Generates Gradle build files that reference FTC SDK
    - Sets up deployment scripts
+   - Creates Android Studio run configurations
 
 2. **Build Process**
    - Runs `deployToSDK` Gradle task
@@ -355,12 +541,18 @@ weevil config . --set-sdk ~/ftc-sdk
    - Connects to Control Hub (USB or WiFi)
    - Installs APK using `adb`
 
+4. **Proxy Support**
+   - reqwest HTTP client respects `--proxy` flag and HTTPS_PROXY env vars
+   - git2/libgit2 gets temporary proxy env vars during clone/fetch
+   - Gradle wrapper reads HTTPS_PROXY natively
+
 ### Why This Approach?
 
 **Separation of Concerns:**
 - Your code: `my-robot/src/`
 - Build infrastructure: `my-robot/*.gradle.kts`
 - FTC SDK: System-level installation
+- IDE integration: Auto-generated, auto-upgraded
 
 **Benefits:**
 - Test code without SDK complications
@@ -368,6 +560,7 @@ weevil config . --set-sdk ~/ftc-sdk
 - SDK updates don't break your projects
 - Proper version control (no massive SDK in repo)
 - Industry-standard project structure
+- Students use familiar tools (Android Studio)
 
 ---
 
@@ -382,6 +575,7 @@ cargo test
 # Run specific test suites
 cargo test --test integration
 cargo test --test project_lifecycle
+cargo test --test proxy_integration
 cargo test config_tests
 ```
 
@@ -392,6 +586,8 @@ cargo test config_tests
 - ✅ Build script generation
 - ✅ Upgrade workflow
 - ✅ CLI commands
+- ✅ Proxy configuration and network operations
+- ✅ Environment setup and health checks
 
 ---
 
@@ -400,11 +596,11 @@ cargo test config_tests
 ### "FTC SDK not found"
 
 ```bash
-# Check SDK status
-weevil sdk status
+# Check system health
+weevil doctor
 
 # Install SDK
-weevil sdk install
+weevil setup
 
 # Or specify custom location
 weevil new my-robot --ftc-sdk /custom/path/to/sdk
@@ -416,6 +612,10 @@ Install Android platform-tools:
 
 **Linux:**
 ```bash
+# Weevil can install it for you
+weevil setup
+
+# Or install manually
 sudo apt install android-tools-adb
 ```
 
@@ -425,7 +625,7 @@ brew install android-platform-tools
 ```
 
 **Windows:**
-Download Android SDK Platform Tools from Google.
+Download Android SDK Platform Tools from Google or run `weevil setup`.
 
 ### "Build failed"
 
@@ -437,6 +637,9 @@ cd my-robot
 
 # Check SDK path
 weevil config .
+
+# Verify system health
+weevil doctor
 ```
 
 ### "Deploy failed - No devices"
@@ -451,6 +654,24 @@ weevil config .
 2. Find Control Hub IP (usually 192.168.43.1 or 192.168.49.1)
 3. Try `./deploy.sh -i <ip>`
 
+### Android Studio: "Unknown run configuration type ShellScript"
+
+The Shell Script plugin is not installed. See [Android Studio Setup](#android-studio-setup) for installation instructions.
+
+### Proxy Issues
+
+```bash
+# Test proxy connectivity
+weevil --proxy http://proxy:8080 sdk status
+
+# Bypass proxy if it's causing issues
+weevil --no-proxy setup
+
+# Check environment variables
+echo $HTTPS_PROXY
+echo $HTTP_PROXY
+```
+
 ---
 
 ## Contributing
@@ -490,6 +711,7 @@ Like the boll weevil that bores through complex cotton bolls to reach the valuab
 3. **Testability** - Enable TDD and proper testing workflows  
 4. **Simplicity** - One command should do one obvious thing
 5. **Transparency** - Students should understand what's happening
+6. **Tool compatibility** - Work with tools students already know
 
 ---
 
@@ -511,28 +733,33 @@ Built with frustration at unnecessarily complex robotics frameworks, and hope th
 
 ## Project Status
 
-**Current Version:** 1.0.0
+**Current Version:** 1.1.0
 
 **What Works:**
 - ✅ Project generation
 - ✅ Cross-platform build/deploy
-- ✅ SDK management
+- ✅ SDK management and auto-install
 - ✅ Configuration management
 - ✅ Project upgrades
-- ✅ Local testing
+- ✅ Local unit testing
+- ✅ System diagnostics (`weevil doctor`)
+- ✅ Selective uninstall
+- ✅ Proxy support for corporate/air-gapped environments
+- ✅ Android Studio integration with one-click deployment
 
 **Roadmap:**
 - 📋 Package management for FTC libraries
 - 📋 Template system for common robot configurations
-- 📋 IDE integration (VS Code, IntelliJ)
+- 📋 VS Code integration
 - 📋 Team collaboration features
 - 📋 Automated testing on robot hardware
+- 📋 Multi-robot support (manage multiple Control Hubs)
 
 ---
 
 **Questions? Issues? Suggestions?**
 
-📧 Email: [eric@nxlearn.net](mailto:eric@nxlearn.net)
+📧 Email: [eric@nxlearn.net](mailto:eric@nxlearn.net)  
 🐛 Issues: Open an issue on the repository
 
-Building better tools so you can build better robots. 🤖
+Building better tools so you can build better robots. 🤖
\ No newline at end of file