Simplify README and restructure documentation

AKS_DEPLOYMENT.md

@@ -0,0 +1,105 @@
+# Production AKS Deployment Guide
+
+> **⚠️ Notice:**  
+> The following production deployment instructions have **not been fully tested**.  
+> Please proceed with caution and verify each step in your environment.  
+> If you encounter issues, consult the script comments and configuration files for troubleshooting.
+
+Full production deployment of the **Buttercup CRS** on Azure Kubernetes Service with proper networking, monitoring, and scaling for the DARPA AIxCC competition.
+
+## Quick Setup (Recommended)
+
+Use our automated setup script:
+
+```bash
+make setup-azure
+```
+
+This script will check prerequisites, help create service principals, configure the environment, and validate your setup.
+
+## Manual Setup
+
+If you prefer to set up manually, follow these steps:
+
+### Prerequisites
+
+- Azure CLI installed and configured
+- Terraform installed
+- Active Azure subscription
+- Access to competition Tailscale tailnet
+
+### Azure Setup
+
+1. **Login to Azure:**
+
+```bash
+az login --tenant <your-tenant-here>
+```
+
+2. **Create Service Principal:**
+
+```bash
+# Get your subscription ID
+az account show --query "{SubscriptionID:id}" --output table
+
+# Create service principal (replace with your subscription ID)
+az ad sp create-for-rbac --name "ButtercupCRS" --role Contributor --scopes /subscriptions/<YOUR-SUBSCRIPTION-ID>
+```
+
+### Production Configuration
+
+1. **Configure environment file:**
+
+```bash
+cp deployment/env.template deployment/env
+```
+
+2. **Update `deployment/env` for production:**
+
+Look at the comments in the `deployment/env.template` for how to set variables.
+In particular, set `TF_VAR_*` variables, and `TAILSCALE_*` if used.
+
+## Deploy to AKS
+
+**Deploy the cluster and services:**
+
+```bash
+make deploy-azure
+```
+
+**Alternative manual command:**
+
+```bash
+cd deployment && make up
+```
+
+## Scaling and Management
+
+- **Scale nodes:** Update `TF_VAR_usr_node_count` in your env file and run `make up`
+- **View logs:** `kubectl logs -n crs <pod-name>`
+- **Monitor resources:** `kubectl top pods -A`
+
+## Additional Resources
+
+For detailed deployment instructions and advanced configuration options, see the [deployment README](deployment/README.md).
+
+## Troubleshooting
+
+### Azure Authentication Issues
+
+```bash
+az login --tenant <your-tenant>
+az account set --subscription <your-subscription-id>
+```
+
+### Cluster Management
+
+```bash
+# Get cluster credentials
+az aks get-credentials --name <cluster-name> --resource-group <resource-group>
+
+# View cluster info
+az aks show --name <cluster-name> --resource-group <resource-group>
+```
+
+For more troubleshooting information, see the main [Quick Reference Guide](QUICK_REFERENCE.md).

CONTRIBUTING.md

@@ -0,0 +1,165 @@
+# Contributing to Buttercup CRS
+
+Thank you for your interest in contributing to the Buttercup Cyber Reasoning System! This guide will help you get started with development and understand our workflows.
+
+## Development Setup
+
+Before contributing, set up your local development environment:
+
+```bash
+# Clone with submodules
+git clone --recurse-submodules https://github.com/trailofbits/buttercup.git
+
+# Quick setup (recommended)
+make setup-local
+
+# Start development environment
+make deploy-local
+```
+
+## Development Workflow
+
+### Using Makefile Shortcuts
+
+The **Buttercup CRS** project includes a Makefile with convenient shortcuts for common tasks:
+
+```bash
+# View all available commands
+make help
+
+# Setup
+make setup-local          # Automated local development setup
+make setup-azure          # Automated production AKS setup
+make validate             # Validate current setup and configuration
+
+# Deployment
+make deploy               # Deploy to current environment (local or azure)
+make deploy-local         # Deploy to local Minikube environment
+make deploy-azure         # Deploy to production AKS environment
+
+# Status
+make status               # Check the status of the deployment
+
+# Testing
+make send-libpng-task          # Run libpng test task
+
+# Development
+make lint                 # Lint all Python code
+make lint-component COMPONENT=orchestrator  # Lint specific component
+
+# Cleanup
+make undeploy             # Remove deployment and clean up resources
+make clean-local          # Delete Minikube cluster and remove local config
+```
+
+### Code Quality Standards
+
+All Python components use consistent formatting and linting standards:
+
+- **Formatter:** `ruff format`
+- **Linter:** `ruff check`
+- **Type Checker:** `mypy` (for common, patcher, and program-model components)
+
+### Running Tests
+
+```bash
+# Lint all Python code
+make lint
+
+# Lint specific component
+make lint-component COMPONENT=orchestrator
+
+# Run test task
+make send-libpng-task
+```
+
+
+### Development Tools
+
+
+#### Kubernetes Development
+
+```bash
+# Port forward for local access  
+kubectl port-forward -n crs service/buttercup-competition-api 31323:1323
+
+# View logs
+kubectl logs -n crs -l app=scheduler --tail=-1 --prefix
+
+# Debug pods
+kubectl exec -it -n crs <pod-name> -- /bin/bash
+```
+
+## Component Architecture
+
+The system consists of several key components:
+
+- **Common** (`/common/`): Shared utilities, protobuf definitions, Redis queue management, telemetry
+- **Orchestrator** (`/orchestrator/`): Central coordination, task server, scheduler, competition API client
+- **Fuzzer** (`/fuzzer/`): Automated vulnerability discovery (build-bot, fuzzer-bot, coverage-bot, tracer-bot)
+- **Program Model** (`/program-model/`): Semantic code analysis using CodeQuery and Tree-sitter
+- **Patcher** (`/patcher/`): LLM-powered automated patch generation
+- **Seed Generation** (`/seed-gen/`): Intelligent input generation
+
+## Contribution Guidelines
+
+### Code Style
+
+- Follow existing code patterns and conventions in each component
+- Use structured logging via the common logging module
+- Implement proper error handling with circuit breakers for external service calls
+- Use Pydantic models for data validation
+- Write comprehensive tests for new functionality
+
+### Testing
+
+Each component should include:
+
+- Unit tests using pytest
+- Mock external dependencies (Redis, LLM APIs, file system)
+- Integration tests using Docker containers
+- Test data stored in `<component>/tests/data/`
+
+### Security Considerations
+
+- All untrusted code execution must happen in isolated Docker containers
+- Never expose or log secrets and keys
+- Never commit secrets or keys to the repository
+
+### Submitting Changes
+
+1. **Create a feature branch** from the main branch
+2. **Make your changes** following the code style guidelines
+3. **Test your changes** using the appropriate test commands
+4. **Lint your code** using `make lint` or component-specific linting
+5. **Create a pull request** with a clear description of your changes
+
+
+### Python Package Management
+
+Each component uses `uv` for dependency management:
+
+```bash
+# Install dependencies
+cd <component> && uv sync
+
+# Install with dev dependencies
+cd <component> && uv sync --all-extras
+
+# Add new dependency
+cd <component> && uv add <package>
+
+# Update dependencies
+cd <component> && uv lock --upgrade
+```
+
+## Getting Help
+
+- **Validate your setup:** `make validate` - Check if your environment is ready
+- Check the [Quick Reference Guide](QUICK_REFERENCE.md) for common commands and troubleshooting
+- Check the [deployment README](deployment/README.md) for detailed deployment information
+- Check logs: `kubectl logs -n crs <pod-name>`
+
+## Questions?
+
+If you have questions about contributing, please feel free to open an issue or reach out to the development team.

MANUAL_SETUP.md

@@ -0,0 +1,118 @@
+# Manual Setup Guide
+
+This guide provides detailed manual setup instructions for the Buttercup CRS system. If you prefer automated setup, use `make setup-local` instead.
+
+## Prerequisites
+
+Before starting manual setup, ensure you have the following dependencies installed:
+
+### System Packages
+
+```bash
+# Ubuntu/Debian
+sudo apt-get update
+sudo apt-get install -y make curl git
+
+# RHEL/CentOS/Fedora  
+sudo yum install -y make curl git
+# or
+sudo dnf install -y make curl git
+
+# MacOS
+brew install make curl git
+```
+
+### Docker
+
+```bash
+curl -fsSL https://get.docker.com | sh
+sudo usermod -aG docker $USER
+# Log out and back in for group changes to take effect
+```
+
+### kubectl
+
+```bash
+curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
+sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
+```
+
+### Helm
+
+```bash
+curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+```
+
+### Minikube
+
+```bash
+curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
+sudo install minikube-linux-amd64 /usr/local/bin/minikube
+```
+
+### Git LFS (for some tests)
+
+```bash
+sudo apt-get install git-lfs
+git lfs install
+```
+
+## Manual Configuration
+
+1. **Create configuration file:**
+
+```bash
+cp deployment/env.template deployment/env
+```
+
+2. **Configure the environment file** (`deployment/env`):
+
+Look at the comments in the `deployment/env.template` for how to set variables.
+
+## Start Services Manually
+
+```bash
+# Start services manually
+cd deployment && make up
+
+# Port forward manually
+kubectl port-forward -n crs service/buttercup-ui 31323:1323
+
+# Test manually
+./orchestrator/scripts/task_crs.sh
+```
+
+## Verification
+
+After setup, verify your installation by running:
+
+```bash
+make status
+```
+
+## Troubleshooting
+
+### Common Manual Setup Issues
+
+1. **Docker permission issues:**
+
+```bash
+sudo usermod -aG docker $USER
+# Log out and back in
+```
+
+2. **Minikube won't start:**
+
+```bash
+minikube delete
+minikube start --driver=docker
+```
+
+3. **Helm chart issues:**
+
+```bash
+helm repo update
+helm dependency update deployment/k8s/
+```
+
+For additional troubleshooting, see the [Quick Reference Guide](QUICK_REFERENCE.md).