# Webber Monorepo - Agent Instructions

> **Start every session by reading this file.**
> This file contains everything you need to work with this codebase efficiently.

## Quick Reference

| Action | Command |
|--------|---------|
| Start API server | `cd webber-api && ./wakeup.sh` |
| View API logs | `tail -f webber-api/logs/server.log` |
| Run API tests | `cd webber-api && .venv/bin/python -m pytest tests/ -v` |
| Check CLI status | `cd webber-cli && .venv/bin/webber-cli status` |
| Load sandbox | `./sandbox.sh load calculator-cli` |
| Explore sandbox | `cd webber-cli && .venv/bin/webber-cli explore "query" -d ../webber-sandbox` |

---

## Repository Structure

```
webber/
├── webber-api/          # FastAPI backend server
│   ├── src/             # API source code
│   ├── tests/           # API tests (pytest)
│   ├── docs/            # Architecture docs, COVERAGE.md
│   ├── logs/            # Runtime logs (server.log)
│   ├── .venv/           # API virtual environment
│   ├── wakeup.sh        # Dev server startup script
│   └── AGENTS.md        # API-specific development guide
│
├── webber-cli/          # CLI client
│   ├── webber_cli/      # Python package (underscore!)
│   ├── .venv/           # CLI virtual environment
│   └── README.md        # CLI usage guide
│
├── webber-sandbox/      # Active test project (contents swappable)
│   ├── src/             # Current project source
│   ├── tests/           # Current project tests
│   ├── .venv/           # Sandbox virtual environment
│   └── TASKS.md         # Tasks for Webber to complete
│
├── sandbox-templates/   # Template storage
│   ├── calculator-cli/  # Simple CLI with intentional bugs
│   └── empty/           # Blank starter project
│
├── sandbox.sh           # Sandbox management script
└── AGENTS.md            # THIS FILE
```

---

## Development Workflow

### 1. Start the API Server

```bash
cd webber-api
./wakeup.sh
```

- **Port:** 8095 (dev), 8086 (production Docker)
- **Logs:** `webber-api/logs/server.log`
- **Health check:** `curl http://localhost:8095/health`
- **API docs:** http://localhost:8095/docs

To stop: `Ctrl+C` or `pkill -f "uvicorn src.main:app"`

### 2. Run Tests

```bash
# API tests (39 tests)
cd webber-api
.venv/bin/python -m pytest tests/ -v

# With coverage
.venv/bin/python -m pytest tests/ --cov=src

# Single test file
.venv/bin/python -m pytest tests/test_tools.py -v
```

### 3. Use the CLI

```bash
cd webber-cli

# Check API connection
.venv/bin/webber-cli status

# Explore a directory
.venv/bin/webber-cli explore "find all python files" -d ../webber-sandbox

# Interactive chat mode
.venv/bin/webber-cli chat -d ../webber-sandbox
```

**Note:** The API server must be running for CLI commands to work.

---

## Sandbox Management

The sandbox is a swappable test project for functional testing.

### Available Templates

| Template | Description |
|----------|-------------|
| `calculator-cli` | Python CLI with intentional bugs (div-by-zero, missing tests) |
| `empty` | Blank starter project |

### Commands

```bash
# List available templates
./sandbox.sh list

# Load a template (clears sandbox, preserves .venv)
./sandbox.sh load calculator-cli

# Reset to last loaded template
./sandbox.sh reset

# Save current sandbox as new template
./sandbox.sh save my-template

# Check current status
./sandbox.sh status
```

### After Loading a Template

```bash
cd webber-sandbox
source .venv/bin/activate  # Create .venv first if missing
pip install -r requirements.txt

# Read the tasks
cat TASKS.md

# Run the project's tests
pytest tests/ -v
```

---

## Testing Webber's Capabilities

### Scenario: Find bugs in calculator-cli

```bash
# 1. Load the template
./sandbox.sh load calculator-cli

# 2. Have Webber explore it
cd webber-cli
.venv/bin/webber-cli explore "find all bugs in the code" -d ../webber-sandbox

# 3. Check TASKS.md for expected bugs
cat ../webber-sandbox/TASKS.md
```

### Known bugs in calculator-cli:
- Division by zero not handled (`operations.py:divide`)
- Invalid operation causes KeyError (`main.py:get_operation`)
- Power function broken for fractional exponents
- Missing tests for divide and power functions

---

## Key Files for Debugging

| File | Purpose |
|------|---------|
| `webber-api/logs/server.log` | API server logs |
| `webber-api/src/domains/agents/explore/prompts.py` | Explore agent system prompts |
| `webber-api/src/domains/agents/explore/agent.py` | Explore agent implementation |
| `webber-api/src/ollama/provider.py` | Ollama integration (sanitizes content:null) |
| `webber-api/docs/COVERAGE.md` | Feature coverage and known issues |

---

## Versioning & Releases

Uses prefixed tags:
- `api/vX.Y.Z` → Triggers API Docker build
- `cli/vX.Y.Z` → Triggers CLI build (future)

### MANDATORY Release Procedure

**NEVER push a tag before updating version files.** Follow this exact order:

```bash
# 1. Update version in pyproject.toml
# 2. Update CHANGELOG.md with release notes
# 3. Commit the version bump
git add -A && git commit -m "chore: release api vX.Y.Z"

# 4. Create the tag (AFTER the commit)
git tag api/vX.Y.Z

# 5. Push everything together
git push origin main --tags
```

**Why this matters:** Pushing a tag before the version commit requires deleting and recreating the tag, which can trigger CI/CD pipelines prematurely and cause deployment issues.

---

## Troubleshooting

### API server won't start
```bash
# Check if port is in use
lsof -i :8095

# Kill stuck process
pkill -f "uvicorn src.main:app"
```

### CLI can't connect
```bash
# Check API is running
curl http://localhost:8095/health

# Check CLI config
echo $WEBBER_API_URL  # Should be http://localhost:8095
```

### Ollama errors
```bash
# Check Ollama is running
curl http://192.168.86.149:11434/api/tags

# Check model is available
curl http://192.168.86.149:11434/api/tags | grep mistral-nemo
```

### Tests failing
```bash
# Run with verbose output
cd webber-api
.venv/bin/python -m pytest tests/ -v --tb=short
```

---

## Known Limitations

1. **Model hallucination** - Mistral Nemo sometimes makes up file contents instead of using tool results
2. **No conversation memory** - CLI chat mode doesn't persist between sessions
3. **No streaming** - Responses appear all at once

See `webber-api/docs/COVERAGE.md` for full feature coverage status.