docs: Update README with comprehensive installation, configuration, and usage instructions

Author: aronchick

README.md

@@ -6,37 +6,75 @@ Andaime (Poruguese for "scaffolding", pronounced An-Dye-Me) is a command-line to
 
 ## Prerequisites
 
-- Go 1.16 or later
-- AWS CLI configured with appropriate credentials
-- AWS SDK for Go
+- Go 1.21 or later
+- Cloud Provider CLI (AWS, GCP) configured with appropriate credentials
+- Just task runner (recommended)
 
 ## Installation and Building
 
-Clone the repository:
+### Prerequisites Installation
 
+1. Install Go (1.21+):
 ```bash
-git clone https://github.com/bacalhau-project/andaime.git
-cd andaime
+# macOS (using Homebrew)
+brew install go
+
+# Linux
+# Follow official Go installation guide: https://golang.org/doc/install
 ```
 
-You can build the project with the Go compiler:
+2. Install Just task runner:
 ```bash
-go build ./...
+# macOS
+brew install just
+
+# Linux
+# https://github.com/casey/just#installation
 ```
 
-or, using the `makefile`
+### Repository Setup
 
+Clone the repository:
 ```bash
-make build
+git clone https://github.com/bacalhau-project/andaime.git
+cd andaime
 ```
 
-If you wish to build for all supported platforms (Linux and macOS on `arm64` and `amd64` arch), you can run the following:
+### Building the Project
+
+You have multiple build options:
 
+#### Quick Build
 ```bash
-make release
+# Using Go directly
+go build ./cmd/andaime
+
+# Using Just (recommended)
+just build
 ```
 
-This will build and tarball Andaime for all of the aforementioned targets in a `./releases` directory with the filenames of `andaime-${OS}-${ARCHITECTURE}.tar.gz`.
+#### Multi-Platform Release Build
+```bash
+# Build release artifacts for Linux, macOS (Intel and Apple Silicon)
+just build-release
+```
+
+This will create platform-specific binaries in the `dist/` directory:
+- `andaime_linux_amd64`
+- `andaime_darwin_amd64`
+- `andaime_darwin_arm64`
+- `andaime_windows_amd64.exe`
+
+### Development Tools
+
+For development, install additional tools:
+```bash
+# Generate mocks
+just genmock
+
+# Generate cloud data
+just gencloud
+```
 
 ## Usage
 Commands
@@ -64,66 +102,124 @@ Options
 --verbose: Enable verbose logging.
 ```
 
-## Configuration
-You can configure the script using a config.json file in the root directory. The following parameters can be set:
+## Configuration and Customization
 
-```
-PROJECT_NAME
-TARGET_PLATFORM
-NUMBER_OF_ORCHESTRATOR_NODES
-NUMBER_OF_COMPUTE_NODES
+Andaime supports multiple configuration methods to suit different workflows:
 
-```
+### 1. Configuration File (config.json)
+Create a `config.json` in the project root:
 
-Example config.json:
 ```json
 {
-  "PROJECT_NAME": "bacalhau-by-andaime",
-  "TARGET_PLATFORM": "aws",
-  "NUMBER_OF_ORCHESTRATOR_NODES": 1,
-  "NUMBER_OF_COMPUTE_NODES": 2
+  "PROJECT_NAME": "bacalhau-cluster",
+  "TARGET_PLATFORM": ["aws", "gcp"],
+  "ORCHESTRATOR_NODES": {
+    "count": 1,
+    "instance_type": "t3.medium"
+  },
+  "COMPUTE_NODES": {
+    "count": 3,
+    "instance_type": "c5.large"
+  },
+  "REGIONS": ["us-east-1", "us-west-2", "eu-west-1"]
 }
 ```
-## Environment Variables
-You can also configure the script using environment variables:
 
-```
-PROJECT_NAME
-TARGET_PLATFORM
-NUMBER_OF_ORCHESTRATOR_NODES
-NUMBER_OF_COMPUTE_NODES
-AWS_ACCESS_KEY_ID
-AWS_SECRET_ACCESS_KEY
-```
-Example:
+### 2. Environment Variables
+Override or supplement configuration via environment variables:
 
 ```bash
-export PROJECT_NAME="bacalhau-by-andaime"
-export TARGET_PLATFORM="aws"
-export NUMBER_OF_ORCHESTRATOR_NODES=1
-export NUMBER_OF_COMPUTE_NODES=2
+# Cloud Provider Credentials
+export AWS_ACCESS_KEY_ID=your_aws_key
+export AWS_SECRET_ACCESS_KEY=your_aws_secret
+export GCP_PROJECT_ID=your_gcp_project
+
+# Cluster Configuration
+export ANDAIME_PROJECT_NAME="my-bacalhau-cluster"
+export ANDAIME_TARGET_PLATFORM="aws"
+export ANDAIME_ORCHESTRATOR_NODES=1
+export ANDAIME_COMPUTE_NODES=3
 ```
 
-## Examples
+### 3. CLI Flags
+Direct CLI configuration for maximum flexibility:
 
-#### Create Resources
 ```bash
-# Create a new network
-./andaime create --target-regions "us-east-1,us-west-2" --compute-nodes 3 --orchestrator-nodes=1
+# Specify configuration directly
+andaime create \
+  --project-name "bacalhau-cluster" \
+  --target-platform aws \
+  --orchestrator-nodes 1 \
+  --compute-nodes 3 \
+  --instance-type t3.medium \
+  --target-regions us-east-1,us-west-2
+```
 
-# Create nodes and add them to an existing orchestrator
-./andaime create --aws-profile="expanso" --target-regions="us-east-1,us-west-2,eu-west-1,eu-west-2,eu-west-3,ap-southeast-1,ap-southeast-2,sa-east-1,ca-central-1,eu-north-1" --compute-nodes=20 --orchestrator-ip=<ORCHESTRATOR_IP_ADDRESS>
+### Configuration Precedence
+Andaime resolves configuration in this order:
+1. CLI Flags (Highest Priority)
+2. Environment Variables
+3. Configuration File
+4. Default Values
+
+### Supported Cloud Providers
+- AWS (Primary)
+- GCP (Beta)
+- More providers planned
+
+## Workflow Examples
+
+### 1. Basic AWS Cluster Creation
+```bash
+# Create a simple Bacalhau cluster in us-east-1
+andaime create \
+  --target-platform aws \
+  --target-regions us-east-1 \
+  --compute-nodes 3 \
+  --orchestrator-nodes 1
+```
 
-# Create a single node of a specific type, and add them to an orchestrator using environment variables to authenticate with AWS
-AWS_ACCESS_KEY_ID=<YOUR_KEY_ID> AWS_SECRET_ACCESS_KEY=<YOUR_ACCESS_KEY> ./andaime --target-regions="us-east-1" --compute-nodes=1 --instance-type="t2.large" --orchestrator-ip=<ORCHESTRATOR_IP_ADDRESS>
+### 2. Multi-Region GCP Deployment
+```bash
+# Deploy a cluster across multiple GCP regions
+andaime create \
+  --target-platform gcp \
+  --target-regions us-central1,us-west1,europe-west3 \
+  --compute-nodes 5 \
+  --orchestrator-nodes 2 \
+  --instance-type n2-standard-4
+```
 
+### 3. Existing Orchestrator Expansion
+```bash
+# Add compute nodes to an existing orchestrator
+andaime create \
+  --orchestrator-ip 203.0.113.10 \
+  --compute-nodes 10 \
+  --target-regions us-east-1,us-west-2
 ```
 
-#### List Resources
+### 4. Resource Management
 ```bash
-./andaime list
+# List current Andaime-managed resources
+andaime list
+
+# Destroy all resources for the current project
+andaime destroy
 ```
-#### Destroy Resources
+
+### 5. Advanced Configuration
 ```bash
-./andaime destroy
-```
+# Use a specific AWS profile and custom configuration
+AWS_PROFILE=my-bacalhau-profile \
+andaime create \
+  --config-file custom_config.json \
+  --verbose
+```
+
+## Troubleshooting
+
+- Ensure cloud provider credentials are correctly configured
+- Check network connectivity and firewall rules
+- Use `--verbose` flag for detailed logging
+- Consult documentation for provider-specific requirements