SITER-Solar/AGENTS.md

# SITER Solar Project - Agent Documentation

This document provides technical reference for AI agents working on this project.

## Software Development Lifecycle (SDLC)

### Host System: Git and Docker ONLY

**All work must be done inside Docker containers.** The host system is ONLY for:

1. **Git operations** - commit, push, pull, branch, etc.
2. **Docker operations** - build, run, exec, etc.

**Never run code, tests, or other tools directly on the host system.**

### Development Workflow

1. **Build Docker image:**
   ```bash
   docker build -f Dockerfile.test -t siter-solar-test .
   ```

2. **Run tests inside Docker:**
   ```bash
   docker run --rm siter-solar-test
   ```

3. **Run analysis inside Docker:**
   ```bash
   docker run --rm -e NREL_API_KEY=your_key siter-solar-test /app/solar-analysis/siter-solar-analysis.sh --scenarios
   ```

4. **Make atomic commits** using conventional commit format:
   - `feat:` - New feature
   - `fix:` - Bug fix
   - `docs:` - Documentation only
   - `test:` - Adding/updating tests
   - `refactor:` - Code refactoring
   - `chore:` - Maintenance tasks

### Code/Docs/Tests Synchronization

**Code, documentation, and tests MUST be kept in sync at all times.**

- When changing code, update tests and documentation in the same commit
- When changing documentation, verify code still matches
- When changing tests, ensure code passes new tests
- Pre-commit hooks enforce this synchronization

## Privacy Requirements

**CRITICAL: This is a public repository. All private data must be removed.**

### What MUST NOT be committed:
- Real addresses or locations (use "SITER" as placeholder)
- Account numbers, contract IDs, or meter numbers
- The `base-bill/` directory (contains personal billing data)
- `.env` file (contains real coordinates and API keys)

### What should be committed:
- `.env.example` - Template with placeholder values
- All code and documentation with "SITER" as location identifier
- SVG images and analysis scripts

### Location Data:
- Use configurable environment variables: `SITER_LAT`, `SITER_LON`
- Default to central Texas coordinates (30.44, -97.62)
- Never commit specific addresses

## File Structure

```
siter-solar/
├── AGENTS.md                 # This file
├── README.md                 # Project documentation
├── .env.example              # Environment template
├── .env                      # Gitignored - actual values
├── .gitignore                # Excludes private data
├── Dockerfile.test           # Test environment
├── v2-siter-solar-plan.md    # Main proposal document
├── images/                   # SVG diagrams for presentation
│   ├── v2-image-1.svg        # System architecture diagram
│   ├── v2-image-2.svg        # Monthly production chart
│   ├── v2-image-3.svg        # ROI/payback timeline
│   └── v2-image-4.svg        # System size comparison
└── solar-analysis/           # NREL PVWatts analysis tools
    ├── siter-solar-analysis.sh  # Main bash script (production)
    ├── tests/                # BATS test suite
    │   └── siter-solar-analysis.bats
    ├── solar_estimate.py     # DEPRECATED - kept for reference
    ├── solar_optimal.py      # DEPRECATED - kept for reference
    ├── solar_optimized.py    # DEPRECATED - kept for reference
    ├── Dockerfile            # Production image
    └── run-analysis.sh       # Docker wrapper
```

## Running NREL Analysis

### Using Bash Script (Recommended)

Inside Docker:
```bash
# Basic analysis
./siter-solar-analysis.sh

# With custom API key
./siter-solar-analysis.sh -k YOUR_API_KEY

# Compare system sizes
./siter-solar-analysis.sh --scenarios

# JSON output
./siter-solar-analysis.sh --json

# Custom configuration
./siter-solar-analysis.sh -p 20 -w 400 --lat 30.5 --lon -97.7
```

### Python Scripts (DEPRECATED)

The Python scripts are kept for reference only. Use the bash script instead.

## Key Parameters

| Parameter | Value | Notes |
|-----------|-------|-------|
| System Capacity | 4.0 kW DC | 16 × 250W panels |
| Array Type | Fixed Open Rack | Ground mount |
| Tilt | 30° | Optimal for latitude |
| Azimuth | 180° | South-facing |
| Losses | 14% (default) | Can optimize to 8% |

## Base Power Contract Details

- **Energy Rate:** $0.085/kWh (fixed through Oct 2028)
- **Solar Buyback:** $0.04/kWh (credits apply to entire bill)
- **Subscription Fee:** $10/month

## ROI Calculation Method

1. Annual production from NREL PVWatts (kWh/year)
2. Self-consumption: 60% × production × $0.085/kWh
3. Grid export: 40% × production × $0.04/kWh
4. Total annual value = self-consumption + export
5. Payback = Total investment / annual value

## Testing

Run tests inside Docker:
```bash
docker build -f Dockerfile.test -t siter-solar-test .
docker run --rm siter-solar-test
```

## Updating the Analysis

1. Modify `siter-solar-analysis.sh` as needed
2. Update tests in `tests/siter-solar-analysis.bats`
3. Run tests to verify changes
4. Update `v2-siter-solar-plan.md` with new estimates
5. Commit all changes together in atomic commit