# inBOXER Agent Guidance

## Reference Documents
- **Master specification**: `PROJECT_PLAN.md` (phases, architecture, guardrails)
- **Live secrets**: `.env` contains API keys & Git credentials – never commit

## Repository Setup
- Use Git credentials from `.env` (`GIT_*` variables) to create remote repository
- Create exact directory hierarchy per `PROJECT_PLAN.md` section 2
- Binary builds to `bin/inboxer`, config to `bin/config.yaml`, prompt to `bin/prompt.txt` (or `bin/classify_prompt.txt` – see `PROJECT_PLAN.md` for clarification)
- Prompt file loaded at runtime – users can modify without recompiling

## Development Phases
- Follow phased plan (Phase 1–4) with version tags `2026-04.1` etc.
- After each phase: update `docs/CHANGELOG.md`, commit, push
- Version increment pattern: `2026-04.{phase}`

## Dependencies & Commands
```bash
go mod init
# Key dependencies: go-imap, gorm, sqlite, slog
go test ./...          # Each function has its own *_test.go
```

## Build & Run
- Create `Makefile` with targets: `build`, `run`, `test` (Phase 4.3)
- Final binary placed in `bin/` for distribution

## Architecture Notes
- **Modular packages**: `auth`, `imap`, `ai`, `db`, `worker` with focused interfaces
- **Main package**: orchestrator only (reads config, starts server/worker)
- **Frontend**: mobile‑first responsive design (Go templates + CSS)
- **Database**: SQLite single file with GORM
- **Authentication**: Email + OTP (6-digit, 10-min expiry, bcrypt storage)

## Operational Guardrails
- **Never delete emails** – only move between IMAP folders
- **AI failures**: keep email in `INBOX`, log error, retry later
- **OTP security**: TLS SMTP, bcrypt storage, 10-minute expiry
- **Session cookies**: `HttpOnly`, `Secure`, appropriate expiry
- **Test mode**: Frontend toggle logs AI decisions without moving emails
- **Never terminate sessions or kill processes** – do not run `kill`, `killall`, `pkill`, `tmux kill-session`, `exit`, or any command that would terminate the agent's own shell, tmux session, or running processes. The agent runs **inside** a tmux session and killing it disrupts ongoing work. Use `nohup`, `disown`, or `setsid` if a process needs to outlive the session.

## Testing & Quality
- Each modular function has its own `*_test.go` file
- Tests can target any package in isolation
- Frontend must be usable on mobile devices

## What's Not Here
- Generic Go advice, exhaustive file trees, speculative claims
- Content already covered by `PROJECT_PLAN.md`