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:

   docker build -f Dockerfile.test -t siter-solar-test .
   

2. Run tests inside Docker:

   docker run --rm siter-solar-test
   

3. Run analysis inside Docker:

   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:

# 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:

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